Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: verify checkout archives with bounded resource use (#13438)

picodot0fbefda4a085
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index c9424f1039..345d5f408a 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -68,6 +68,55 @@ immediately before removal; if that recheck refuses, the original lock is
restored. A retired row leaves the inventory and appears under *Recently
retired* with its archive path; only the next sweep can report convergence.
+### Held archive work budgets
+
+Patch capture preserves original Git output bytes, including non-UTF-8 content. Metadata names and symlink targets must round-trip losslessly through UTF-8; unsupported encodings refuse preservation before removal.
+
+Held archives use resource contract `1`, recorded as `resourceContract` in the
+manifest. File count is not admission policy: every ignored/untracked content
+file and worktree-private Git file remains included. Hashing and copying use
+64 KiB chunks, with one copy at a time and at most two concurrent snapshot
+file streams. Git snapshot queries keep their existing finite fan-out: seven
+content queries plus the private Git directory lookup. A source growing during a copy aborts rather than expanding disk use.
+
+The existing limits remain 25 MiB per raw file, 250 MiB combined content and
+private administration, 16 MiB serialized manifest, and the existing Git output
+buffer of `64 * 1024 * 1024` JavaScript code units. Git output overflow and command timeout retain measured usage and recovery guidance, without changing either existing limit. Patch verification bounds its
+raw byte representation at three bytes per decoded code unit (192 MiB), preserving older multibyte
+patch admission. Metadata is charged incrementally against the same 16 MiB ceiling,
+including file entries, symlink targets and gitlinks; this also bounds
+zero-byte-file trees. Transient sorted directory names have a separate 16 MiB
+scan budget, so directory traversal cannot allocate unbounded name lists. These
+byte ceilings retain the prior safety envelope instead of estimating work from a count. A snapshot, archive write (both source
+passes included), or independent verification has a ten-minute elapsed work
+budget. This is a conservative ceiling of twenty existing 30-second Git command
+timeouts; it allows ordinary many-small-file archives while bounding repeated
+filesystem work. Checks run between filesystem operations and 64 KiB chunks;
+a running Git command retains its existing 30-second timeout. Kernel I/O may
+finish before cancellation is observed. No new global setting is written.
+
+Internal callers may pass an `AbortSignal` as `opts.signal`. Cancellation or a
+resource refusal keeps the original checkout, ref and outstanding obligations;
+partial archives and temporary bundle refs are cleaned up. A new attempt starts
+from fresh snapshots rather than treating partial work as preservation evidence.
+After a process crash, an archive without a complete manifest cannot prove
+preservation; an existing completed archive still needs the full independent
+hash and isolated Git object proof. No historical receipt is synthesized.
+
+Capacity responses include measured bytes, Git output code units, or elapsed
+milliseconds. Recover by
+freeing resources or preserving large outputs separately, then retrying the exact
+checkout with fresh evidence; do not remove it or raise global limits to clear a
+refusal. Existing unversioned archives follow an explicit compatibility path
+through the same bounded verification and complete content/private-Git proof.
+Unknown contract versions fail closed. The real-Git benchmark at `d200ec77d2`
+measured 16.9–20.9 seconds for cancellation/cleanup/retry and 20.2 seconds for
+the 1,100-plus-file restore. Integration fixture construction, retirement or
+confirmation, and independent proof retain separate existing 30-second phase
+budgets; cumulative case duration includes its hooks. Existing tests retain their
+default timeout. This does not change initialized-checkout archives or their
+separate operational budgets.
+
Historical held-checkout archives must also prove that their staged patch
reconstructs the preserved private index. Verification imports the bundle into
a fresh, isolated Git repository, starts from the recorded HEAD, applies
diff --git a/server/lib/execGit.js b/server/lib/execGit.js
index dc00eba5f2..2ae78f538d 100644
--- a/server/lib/execGit.js
+++ b/server/lib/execGit.js
@@ -5,6 +5,7 @@
import { spawn } from './childProcess.js';
import { AsyncLocalStorage } from 'node:async_hooks';
+import { StringDecoder } from 'node:string_decoder';
const mutationLifetime = new AsyncLocalStorage();
/** Admission owners retain their durable permit when Git/helper exit is uncertain. */
@@ -16,11 +17,12 @@ export const withGitMutationLifetime = (work, onUncertain) => mutationLifetime.r
* @param {string} cwd - Working directory (required — an absent cwd would
* silently resolve to process.cwd(), i.e. PortOS's own checkout)
* @param {object} options - Additional options
- * @param {number} [options.maxBuffer] - Max output buffer size in bytes (default 10 MB)
+ * @param {number} [options.maxBuffer] - Max combined output in JavaScript code units (default 10 * 1024 * 1024)
+ * @param {boolean} [options.bufferOutput] - Return original output bytes; the same decoded code-unit limit applies
* @param {number} [options.timeout] - Timeout in ms (default 30s)
* @param {boolean} [options.ignoreExitCode] - Resolve instead of reject on non-zero exit
* @param {object} [options.env] - Explicit child environment; omitted inherits normally
- * @returns {Promise<{stdout: string, stderr: string, exitCode: number|null, signal?: string, terminated?: boolean}>}
+ * @returns {Promise<{stdout: string|Buffer, stderr: string|Buffer, exitCode: number|null, signal?: string, terminated?: boolean}>}
*/
export function execGit(args, cwd, options = {}) {
return new Promise((resolve, reject) => {
@@ -46,6 +48,19 @@ export function execGit(args, cwd, options = {}) {
const onUncertain = mutationLifetime.getStore();
let stdout = '';
let stderr = '';
+ let outputUnits = 0;
+ const stdoutChunks = [];
+ const stderrChunks = [];
+ const collect = (data, decoder, chunks, channel) => {
+ const bytes = typeof data === 'string' ? Buffer.from(data) : data;
+ const decoded = decoder.write(bytes);
+ outputUnits += decoded.length;
+ if (options.bufferOutput) chunks.push(bytes);
+ else if (channel === 'stdout') stdout += decoded;
+ else stderr += decoded;
+ };
+ const stdoutDecoder = new StringDecoder('utf8');
+ const stderrDecoder = new StringDecoder('utf8');
let killed = false;
let failure = null;
let escalation = null;
@@ -65,36 +80,56 @@ export function execGit(args, cwd, options = {}) {
}, 5000);
};
+ const started = performance.now();
const timer = setTimeout(() => {
if (!killed) {
- terminate(new Error(`git command timed out after ${timeout / 1000}s: git ${args.join(' ')}`));
+ terminate(Object.assign(new Error(`git command timed out after ${timeout / 1000}s: git ${args.join(' ')}`), {
+ code: 'GIT_TIMEOUT', limitMs: timeout, observedMs: Math.ceil(performance.now() - started),
+ }));
}
}, timeout);
- // Both streams share one overflow guard against the combined byte count so
+ // Both streams share one overflow guard against the combined code-unit count so
// a runaway command can't blow past maxBuffer on either channel.
+ const outputLimitError = () => Object.assign(new Error(`git output exceeded maxBuffer (${maxBuffer} code units)`), {
+ code: 'GIT_OUTPUT_LIMIT', limitCodeUnits: maxBuffer, observedCodeUnits: outputUnits,
+ });
const guardOverflow = () => {
- if (stdout.length + stderr.length > maxBuffer && !killed) {
+ if (outputUnits > maxBuffer && !killed) {
clearTimeout(timer);
- terminate(new Error(`git output exceeded maxBuffer (${maxBuffer} bytes)`));
+ terminate(outputLimitError());
}
};
child.stdout.on('data', (data) => {
if (killed) return;
- stdout += data.toString();
+ collect(data, stdoutDecoder, stdoutChunks, 'stdout');
guardOverflow();
});
child.stderr.on('data', (data) => {
if (killed) return;
- stderr += data.toString();
+ collect(data, stderrDecoder, stderrChunks, 'stderr');
guardOverflow();
});
child.on('close', (code, signal) => {
clearTimeout(timer);
clearTimeout(escalation);
+ const stdoutTail = stdoutDecoder.end();
+ const stderrTail = stderrDecoder.end();
+ outputUnits += stdoutTail.length + stderrTail.length;
+ if (options.bufferOutput) {
+ stdout = Buffer.concat(stdoutChunks);
+ stderr = Buffer.concat(stderrChunks);
+ } else {
+ stdout += stdoutTail;
+ stderr += stderrTail;
+ }
+ if (!failure && outputUnits > maxBuffer) {
+ markUncertain();
+ failure = outputLimitError();
+ }
if (failure) { reject(failure); return; }
if (code === null && signal) {
markUncertain();
@@ -106,7 +141,7 @@ export function execGit(args, cwd, options = {}) {
}));
}
} else if (code !== 0 && !options.ignoreExitCode) {
- reject(new Error(stderr || `git exited with code ${code}`));
+ reject(new Error(stderr.length ? stderr.toString() : `git exited with code ${code}`));
} else {
resolve({ stdout, stderr, exitCode: code });
}
diff --git a/server/lib/execGit.test.js b/server/lib/execGit.test.js
index 787a1a111e..ab71d9abe4 100644
--- a/server/lib/execGit.test.js
+++ b/server/lib/execGit.test.js
@@ -63,6 +63,47 @@ describe('execGit', () => {
});
});
+ it('preserves UTF-8 characters split across stdout and stderr chunks, including an incomplete final character', async () => {
+ const child = makeChild();
+ spawn.mockReturnValue(child);
+ const promise = execGit(['diff'], '/repo');
+ const stdout = 'staged:界😀';
+ const stderr = 'diagnostic:é界';
+ for (const byte of Buffer.from(stdout)) child.stdout.emit('data', Buffer.from([byte]));
+ for (const byte of Buffer.from(stderr)) child.stderr.emit('data', Buffer.from([byte]));
+ child.stdout.emit('data', Buffer.from([0xe7]));
+ child.emit('close', 0);
+ await expect(promise).resolves.toEqual({ stdout: `${stdout}\uFFFD`, stderr, exitCode: 0 });
+ });
+
+ it('enforces the output limit when decoder flush completes the final character', async () => {
+ const child = makeChild();
+ spawn.mockReturnValue(child);
+ const promise = execGit(['show'], '/repo', { maxBuffer: 1 });
+ child.stdout.emit('data', Buffer.from([0x61, 0xe7]));
+ child.emit('close', 0);
+ await expect(promise).rejects.toThrow(/maxBuffer/);
+ expect(child.kill).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('returns opaque output bytes while retaining the decoded output budget', async () => {
+ const child = makeChild();
+ spawn.mockReturnValue(child);
+ const promise = execGit(['diff'], '/repo', { bufferOutput: true, maxBuffer: 2 });
+ const bytes = Buffer.from([0xe7, 0x95, 0x8c, 0xff]);
+ for (const byte of bytes) child.stdout.emit('data', Buffer.from([byte]));
+ child.emit('close', 0);
+ await expect(promise).resolves.toEqual({ stdout: bytes, stderr: Buffer.alloc(0), exitCode: 0 });
+
+ const overflowing = makeChild();
+ spawn.mockReturnValue(overflowing);
+ const limited = execGit(['diff'], '/repo', { bufferOutput: true, maxBuffer: 2 });
+ overflowing.stdout.emit('data', Buffer.from('abc'));
+ overflowing.emit('close', null, 'SIGTERM');
+ await expect(limited).rejects.toMatchObject({ code: 'GIT_OUTPUT_LIMIT', limitCodeUnits: 2, observedCodeUnits: 3 });
+ });
+
it('rejects with stderr on a non-zero exit', async () => {
const child = makeChild();
spawn.mockReturnValue(child);
@@ -113,7 +154,8 @@ describe('execGit', () => {
const promise = execGit(['fetch'], '/repo', { timeout: 500 });
vi.advanceTimersByTime(500);
child.emit('close', null, 'SIGTERM');
- await expect(promise).rejects.toThrow(/timed out after 0\.5s/);
+ await expect(promise).rejects.toMatchObject({ code: 'GIT_TIMEOUT', limitMs: 500, observedMs: expect.any(Number),
+ message: expect.stringMatching(/timed out after 0\.5s/) });
expect(child.kill).toHaveBeenCalled();
});
diff --git a/server/routes/cosScheduleRoutes.js b/server/routes/cosScheduleRoutes.js
index 69ed6708a6..8167893b3d 100644
--- a/server/routes/cosScheduleRoutes.js
+++ b/server/routes/cosScheduleRoutes.js
@@ -302,7 +302,7 @@ router.post('/schedule/branch-reconcile/checkouts/review', asyncHandler(async (r
const { prepareInventoriedCheckoutRetirement } = await import('../services/heldCheckoutRecovery.js');
const result = await prepareInventoriedCheckoutRetirement({ appId, release, prUrl });
if (!result.ok) throw new ServerError(`Checkout review refused: ${result.reason}`, {
- status: 409, code: 'CHECKOUT_REVIEW_REFUSED', context: { reason: result.reason, ...(result.archiveLimit && { archiveLimit: result.archiveLimit }) },
+ status: 409, code: 'CHECKOUT_REVIEW_REFUSED', context: { reason: result.reason, ...(result.archiveLimit && { archiveLimit: result.archiveLimit }), ...(result.nextAction && { nextAction: result.nextAction }) },
});
res.json(result);
}));
@@ -315,7 +315,7 @@ router.post('/schedule/branch-reconcile/checkouts/retire', asyncHandler(async (r
const result = await retireInventoriedCheckout({ appId, release, review });
if (!result.ok) {
throw new ServerError(`Checkout kept: ${result.reason}${result.detail ? ` (${result.detail})` : ''}`, {
- status: result.reason === 'app-not-found' ? 404 : 409, code: 'CHECKOUT_RETIREMENT_REFUSED', context: { reason: result.reason, ...(result.archiveLimit && { archiveLimit: result.archiveLimit }) },
+ status: result.reason === 'app-not-found' ? 404 : 409, code: 'CHECKOUT_RETIREMENT_REFUSED', context: { reason: result.reason, ...(result.archiveLimit && { archiveLimit: result.archiveLimit }), ...(result.nextAction && { nextAction: result.nextAction }) },
});
}
res.json(result);
diff --git a/server/routes/cosScheduleRoutes.test.js b/server/routes/cosScheduleRoutes.test.js
index 435532779f..b14b6d179a 100644
--- a/server/routes/cosScheduleRoutes.test.js
+++ b/server/routes/cosScheduleRoutes.test.js
@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
import { request } from '../lib/testHelper.js';
import scheduleRoutes from './cosScheduleRoutes.js';
+import { errorMiddleware } from '../lib/errorHandler.js';
const recordUserAction = vi.hoisted(() => vi.fn(async () => ({ id: 'evt' })));
vi.mock('../services/userActions.js', () => ({ recordUserAction }));
@@ -100,6 +101,22 @@ describe('CoS Schedule Routes', () => {
if (operation === 'review') expect(recovery.retireInventoriedCheckout).not.toHaveBeenCalled();
});
+ it.each(['review', 'retire'])('returns measured archive capacity and recovery guidance from checkout %s', async operation => {
+ const tuple = { path: '/synthetic/checkout', head: 'a'.repeat(40), branch: 'feature/bounded', locked: false, lockReason: null };
+ const prUrl = 'https://github.com/example/repo/pull/42';
+ const result = { ok: false, reason: 'retirement-archive-work-limit-exceeded',
+ archiveLimit: { scope: 'verification', kind: 'time', limitMs: 600000, observedMs: 600001 },
+ nextAction: 'Keep the checkout and ref; free resources and retry with fresh evidence.' };
+ const method = operation === 'review' ? recovery.prepareInventoriedCheckoutRetirement : recovery.retireInventoriedCheckout;
+ method.mockResolvedValue(result);
+ app.use(errorMiddleware);
+ const body = operation === 'review' ? { appId: 'app-1', ...tuple, prUrl }
+ : { appId: 'app-1', ...tuple, review: { prUrl, digest: 'b'.repeat(64), acceptSuperseded: false } };
+ const response = await request(app).post(`/api/cos/schedule/branch-reconcile/checkouts/${operation}`).send(body);
+ expect(response.status).toBe(409);
+ expect(response.body.context).toEqual({ reason: result.reason, archiveLimit: result.archiveLimit, nextAction: result.nextAction });
+ });
+
it('requires exact review and journal proofs for explicit initialized checkout operations', async () => {
const base = '/api/cos/schedule/branch-reconcile/initialized-checkouts';
const tuple = { path: '/synthetic/checkout', head: 'a'.repeat(40), branch: 'claim/42', locked: false, lockReason: null };
diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.js
index 83eddeac25..ac099d6d44 100644
--- a/server/services/heldCheckoutRecovery.js
+++ b/server/services/heldCheckoutRecovery.js
@@ -20,13 +20,14 @@ import { readRetirementCheckoutIdentity } from '../lib/retirementCheckoutObserva
*/
import { findGoneInventoryRows } from './branchReconcileInventoryPrune.js';
-import { createReadStream, realpathSync } from 'node:fs';
-import { lstat, stat, readlink, readdir, readFile, chmod, open, mkdtemp } from 'node:fs/promises';
+import { realpathSync, constants } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { lstat, stat, readlink, readdir, opendir, readFile, chmod, open, mkdtemp } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { createHash, randomUUID } from 'node:crypto';
import { basename, dirname, isAbsolute, join, resolve, relative, sep } from 'node:path';
import { sameRetirementCheckout, unresolvedRetirements } from '../lib/reconcileRetirementEvidence.js';
-import { atomicWrite, copyFileGuarded, ensureDir, PATHS, rmGuarded, sha256File, writeFileGuarded } from '../lib/fileUtils.js';
+import { atomicWrite, createWriteStreamGuarded, ensureDir, PATHS, rmGuarded, writeFileGuarded } from '../lib/fileUtils.js';
import { execGit } from '../lib/execGit.js';
import { PROTECTED_BRANCHES } from '../lib/gitArgs.js';
import { claimCheckoutOwnerReason } from '../lib/claimContinuation.js';
@@ -38,15 +39,99 @@ import { withClaimOwnershipLock, readClaimOwnershipAgents, retireWithUnlockedArc
export const heldCheckoutArchiveRoot = (cosDir = PATHS.cos) => join(cosDir, 'held-checkout-archives');
const evidenceHash = value => createHash('sha256').update(value).digest('hex');
-const MAX_ARCHIVE_FILES = 1000;
const MAX_MANIFEST_BYTES = 16 * 1024 * 1024;
function checkArchiveBudget(content, administration) {
- if (content.files.length + administration.files.length > MAX_ARCHIVE_FILES) throw new Error('archive-file-budget-exceeded');
// Creation and recovery share one byte budget across both snapshots.
- const total = [...content.files, ...administration.files].reduce((bytes, file) => bytes + file.bytes, 0);
+ let total = 0;
+ for (const snapshot of [content, administration]) for (const file of snapshot.files) {
+ if (!Number.isSafeInteger(file.bytes) || file.bytes < 0) throw new Error('archive-file-proof-invalid');
+ checkArchiveSize('combined', file.bytes, total += file.bytes);
+ }
checkArchiveSize('combined', 0, total);
}
+// Metadata is retained for exact fingerprints and final rechecks. Bound its
+// encoded bytes as it is collected, including zero-byte files and links.
+const ARCHIVE_WORK_MS = 10 * 60 * 1000;
+function archiveWork(signal, started = performance.now()) {
+ const usage = { metadata: 0, directory: 0 };
+ const check = () => {
+ if (signal?.aborted) throw new Error('retirement-archive-cancelled');
+ const elapsed = Math.ceil(performance.now() - started);
+ if (elapsed > ARCHIVE_WORK_MS) throw Object.assign(new Error('retirement-archive-work-limit-exceeded'), {
+ archiveLimit: { scope: 'verification', kind: 'time', limitMs: ARCHIVE_WORK_MS, observedMs: elapsed },
+ });
+ };
+ return { check, renew: () => archiveWork(signal), metadataScope: () => archiveWork(signal, started), add(value, scope = 'metadata') {
+ check();
+ usage[scope] += Buffer.byteLength(JSON.stringify(value));
+ if (usage[scope] > MAX_MANIFEST_BYTES) throw Object.assign(new Error('archive-manifest-budget-exceeded'), {
+ archiveLimit: { scope, kind: 'total', limitBytes: MAX_MANIFEST_BYTES, observedBytes: usage[scope] },
+ });
+ } };
+}
+
+async function archiveSource(path) {
+ const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+ try {
+ const info = await handle.stat();
+ if (!info.isFile()) throw new Error('archive-file-invalid');
+ return { stream: handle.createReadStream({ highWaterMark: 64 * 1024 }), mode: info.mode & 0o7777 };
+ } catch (error) { await handle.close(); throw error; }
+}
+
+async function archiveHash(path, work, limitBytes = MAX_FILE_BYTES) {
+ work.check();
+ let bytes = 0;
+ const hash = createHash('sha256');
+ const { stream } = await archiveSource(path);
+ for await (const chunk of stream) {
+ work.check();
+ bytes += chunk.length;
+ if (bytes > limitBytes) throw Object.assign(new Error('retirement-archive-limit-exceeded'), {
+ archiveLimit: { scope: 'file-read', kind: 'file', limitBytes, observedBytes: bytes },
+ });
+ hash.update(chunk);
+ }
+ work.check();
+ return hash.digest('hex');
+}
+
+async function archiveCopy(source, destination, expectedBytes, work) {
+ let bytes = 0;
+ const { stream: input, mode } = await archiveSource(source);
+ let output;
+ try { output = await createWriteStreamGuarded(destination, { flags: 'wx', mode: 0o600 }); }
+ catch (error) { input.destroy(); throw error; }
+ await pipeline(
+ input,
+ async function* (chunks) {
+ for await (const chunk of chunks) {
+ work.check();
+ checkArchiveSize('file-copy', bytes += chunk.length, 0);
+ if (bytes > expectedBytes) throw new Error('checkout-content-changed');
+ yield chunk;
+ }
+ if (bytes !== expectedBytes) throw new Error('checkout-content-changed');
+ },
+ output,
+ );
+ await chmod(destination, mode);
+}
+
+function validateArchiveEntries(snapshot, work, accountMetadata = true) {
+ const paths = new Set();
+ for (const entries of [snapshot.files, snapshot.symlinks, snapshot.gitlinks || []]) for (const entry of entries) {
+ if (accountMetadata) work.add(entry);
+ else work.check();
+ if (typeof entry.path !== 'string' || !entry.path || (sep === '\\' && entry.path.includes('\\')) || isAbsolute(entry.path)
+ || entry.path.split('/').some(part => !part || part === '.' || part === '..') || paths.has(entry.path)) {
+ throw new Error('archive-file-proof-invalid');
+ }
+ paths.add(entry.path);
+ }
+}
+
const historicalNextAction = 'Locate a complete archive for this exact historical checkout and retry branch reconciliation; if none exists, recover the original data from backup. Checkout or ref absence is not preservation evidence.';
/** Never follow an archive link, including an intermediate directory link. */
@@ -64,27 +149,44 @@ async function archiveFile(root, path) {
return path;
}
-async function archiveManifest(dir) {
+async function archiveBytes(path, work, limitBytes, reason = 'retirement-archive-limit-exceeded') {
+ const chunks = [];
+ let size = 0;
+ const { stream } = await archiveSource(path);
+ for await (const chunk of stream) {
+ work.check();
+ if ((size += chunk.length) > limitBytes) throw Object.assign(new Error(reason), {
+ archiveLimit: { scope: 'metadata-read', kind: 'file', limitBytes, observedBytes: size },
+ });
+ chunks.push(chunk);
+ }
+ return Buffer.concat(chunks);
+}
+
+async function archiveManifest(dir, work = archiveWork()) {
const path = await archiveFile(dir, join(dir, 'manifest.json'));
- if ((await lstat(path)).size > MAX_MANIFEST_BYTES) throw new Error('archive-manifest-budget-exceeded');
- const bytes = await readFile(path);
+ const bytes = await archiveBytes(path, work, MAX_MANIFEST_BYTES, 'archive-manifest-budget-exceeded');
return { manifest: JSON.parse(bytes), digest: evidenceHash(bytes) };
}
/** Reuses recorded byte hashes and independently reconstructs the private index.
* Older dirty archives without patch hashes cannot prove completeness later.
*/
-async function verifyHeldArchive(repoPath, dir, release) {
- const { manifest: saved, digest } = await archiveManifest(dir);
+async function verifyHeldArchive(repoPath, dir, release, work = archiveWork()) {
+ work.check();
+ const { manifest: saved, digest } = await archiveManifest(dir, work);
if (saved.repoPath !== repoPath || !sameRetirementCheckout(saved, release)
|| (saved.release ? !sameRelease(saved.release, release) : release.locked !== false || release.lockReason !== null)) throw new Error('archive-identity-mismatch');
if (!(Date.parse(saved.archivedAt) >= Date.parse(release.createdAt)) || Date.parse(saved.archivedAt) > Date.now()) throw new Error('archive-generation-mismatch');
+ if (saved.resourceContract !== undefined && saved.resourceContract !== 1) throw new Error('archive-contract-unsupported');
const captured = saved.captured;
if (captured?.commitBundle !== true || captured.missingCheckout || !Array.isArray(captured.files)
|| !Array.isArray(captured.symlinks) || !Array.isArray(captured.gitlinks)
|| !Array.isArray(saved.administration?.files) || !Array.isArray(saved.administration?.symlinks)
|| !saved.administration.files.some(file => file.path === 'gitdir/HEAD')
|| !saved.administration.files.some(file => file.path === 'git-indirection')) throw new Error('archive-preservation-incomplete');
+ validateArchiveEntries(captured, work);
+ validateArchiveEntries(saved.administration, work);
checkArchiveBudget(captured, saved.administration);
const stamps = [];
const stamp = async path => {
@@ -94,15 +196,17 @@ async function verifyHeldArchive(repoPath, dir, release) {
};
const remember = async path => { stamps.push([path, await stamp(path)]); };
await remember(join(dir, 'manifest.json'));
+ work.check();
let total = 0;
for (const [prefix, files] of [['files', captured.files], ['administration', saved.administration.files]]) {
for (const file of files) {
+ work.check();
if (typeof file.path !== 'string' || !/^[a-f0-9]{64}$/.test(file.sha256 || '')) throw new Error('archive-file-proof-invalid');
const path = await archiveFile(dir, join(dir, prefix, file.path));
await remember(path);
const info = await lstat(path);
if (info.size !== file.bytes || info.size > MAX_FILE_BYTES || (total += info.size) > MAX_TOTAL_BYTES
- || await sha256File(path) !== file.sha256) throw new Error('archive-file-changed');
+ || await archiveHash(path, work) !== file.sha256) throw new Error('archive-file-changed');
}
}
const administrationFingerprint = evidenceHash(JSON.stringify({
@@ -116,7 +220,7 @@ async function verifyHeldArchive(repoPath, dir, release) {
if (!/^[a-f0-9]{64}$/.test(expected || '')) throw new Error('archive-patch-proof-unavailable');
const path = await archiveFile(dir, join(dir, `${name}.diff`));
await remember(path);
- if (await sha256File(path) !== expected) throw new Error('archive-patch-changed');
+ if (await archiveHash(path, work, MAX_PATCH_BYTES) !== expected) throw new Error('archive-patch-changed');
}
const bundle = await archiveFile(dir, join(dir, 'commits.bundle'));
await remember(bundle);
@@ -130,11 +234,13 @@ async function verifyHeldArchive(repoPath, dir, release) {
header = buffer.subarray(0, bytesRead).toString('latin1').split('\n\n')[0];
if (!buffer.subarray(0, bytesRead).includes(Buffer.from('\n\n')) || /^-/m.test(header)) throw new Error('archive-bundle-incomplete');
} finally { await handle.close(); }
+ work.check();
await git(['bundle', 'verify', bundle], repoPath);
+ work.check();
const heads = new Set((await git(['bundle', 'list-heads', bundle], repoPath)).trim().split('\n').map(line => line.split(' ')[0]));
if (!Array.isArray(captured.recoveryHeads) || !captured.recoveryHeads.includes(release.head)
|| captured.recoveryHeads.some(head => !heads.has(head))) throw new Error('archive-bundle-head-mismatch');
- const bundleHash = await sha256File(bundle);
+ const bundleHash = await archiveHash(bundle, work, Infinity);
if (saved.bundleSha256 && bundleHash !== saved.bundleSha256) throw new Error('archive-bundle-changed');
// Bundle verify/list-heads validate headers, not packed object integrity. Prove
// the complete closure without borrowing any object from the live repository.
@@ -143,22 +249,28 @@ async function verifyHeldArchive(repoPath, dir, release) {
// (\\.\nul) is not the Git configuration-file contract.
const env = { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_'))),
GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1', GIT_TERMINAL_PROMPT: '0' };
- const prove = (args, index = null) => execGit(['--no-optional-locks', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', ...args], scratch,
- { env: { ...env, ...(index && { GIT_INDEX_FILE: join(scratch, index) }) }, maxBuffer: GIT_OUTPUT_BYTES });
+ const prove = (args, index = null) => {
+ work.check();
+ return execGit(['--no-optional-locks', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', ...args], scratch,
+ { env: { ...env, ...(index && { GIT_INDEX_FILE: join(scratch, index) }) }, maxBuffer: GIT_OUTPUT_BYTES });
+ };
try {
try {
await prove(['init', '--bare', `--object-format=${release.head.length === 64 ? 'sha256' : 'sha1'}`, '.']);
await prove(['bundle', 'unbundle', bundle]);
await prove(['fsck', '--full', '--strict', '--no-reflogs', '--no-dangling', ...captured.recoveryHeads]);
- } catch { throw new Error('archive-bundle-object-proof-failed'); }
+ } catch (error) {
+ if (archiveLimitRefusal(error)) throw error;
+ throw new Error('archive-bundle-object-proof-failed');
+ }
try {
// Copy only validated index bytes into our own Git directory. Never run
// Git against archived config, commondir, gitdir pointers or object stores.
if (!saved.administration.files.some(file => file.path === 'gitdir/index')) throw new Error('missing archived index');
for (const file of saved.administration.files.filter(file => file.path === 'gitdir/index'
|| /^gitdir\/sharedindex\.[a-f0-9]+$/.test(file.path))) {
- await copyFileGuarded(await archiveFile(dir, join(dir, 'administration', file.path)),
- join(scratch, file.path === 'gitdir/index' ? 'archived-index' : basename(file.path)));
+ await archiveCopy(await archiveFile(dir, join(dir, 'administration', file.path)),
+ join(scratch, file.path === 'gitdir/index' ? 'archived-index' : basename(file.path)), file.bytes, work);
}
// Quoted paths make this comparison ASCII and lossless even for opaque
// filename bytes. --stage includes modes, object IDs and conflict stages.
@@ -168,11 +280,18 @@ async function verifyHeldArchive(repoPath, dir, release) {
if (captured.indexDiff) await prove(['apply', '--cached', '--binary', join(dir, 'index.diff')]);
const restored = await prove(entries);
if (restored.stdout !== expected.stdout) throw new Error('index entries differ');
- } catch { throw new Error('archive-index-reconstruction-failed'); }
+ } catch (error) {
+ if (archiveLimitRefusal(error)) throw error;
+ throw new Error('archive-index-reconstruction-failed');
+ }
} finally { await rmGuarded(scratch, { recursive: true, force: true }); }
- if ((await archiveManifest(dir)).digest !== digest) throw new Error('archive-manifest-changed');
+ work.check();
+ if ((await archiveManifest(dir, work)).digest !== digest) throw new Error('archive-manifest-changed');
+
const recheck = async () => {
+ const recheckWork = work.renew();
for (const [path, original] of stamps) {
+ recheckWork.check();
if (await stamp(await archiveFile(dir, path)) !== original) return false;
}
return true;
@@ -207,7 +326,7 @@ export async function findMissingCheckoutPreservation({ repoPath, release }, opt
let selected = null;
for (const entry of entries) {
if (!entry.isDirectory()) continue;
- const proof = await verifyHeldArchive(repoPath, join(root, entry.name), release).catch(() => null);
+ const proof = await verifyHeldArchive(repoPath, join(root, entry.name), release, archiveWork(opts.signal)).catch(() => null);
if (!proof) continue;
// Multiple valid snapshots cannot identify the original private contents.
if (selected) return null;
@@ -253,13 +372,16 @@ export async function recoverMissingCheckoutPreservations({ appId, repoPath, out
&& candidate.dir === release.preservationReceipt.archiveDir) : candidates;
for (const candidate of scopedCandidates) {
try {
- proof = candidate.kind === 'held' ? await verifyHeldArchive(repoPath, candidate.dir, release)
+ proof = candidate.kind === 'held' ? await verifyHeldArchive(repoPath, candidate.dir, release, archiveWork(opts.signal))
: await (await import('./initializedCheckoutRecovery.js')).verifyMissingInitializedCheckoutPreservation({ appId, repoPath, release, archiveDir: candidate.dir });
if (proof.releaseFence) evidenceFences.push(proof.releaseFence);
evidence.push({ archiveDir: candidate.dir, reason: 'preservation-verified' });
break;
} catch (error) {
- evidence.push({ archiveDir: candidate.dir, reason: /^[a-z][a-z-]+$/.test(error.message) ? error.message : 'archive-unverifiable' });
+ const refusal = archiveLimitRefusal(error);
+ evidence.push({ archiveDir: candidate.dir, ...(refusal ? { reason: refusal.reason,
+ ...(refusal.archiveLimit && { archiveLimit: refusal.archiveLimit }), nextAction: refusal.nextAction,
+ } : { reason: /^[a-z][a-z-]+$/.test(error.message) ? error.message : 'archive-unverifiable' }) });
}
}
observations.push({ release, proof, evidence, reason: discoveryReason || (candidates.length ? 'archive-evidence-unverified' : 'archive-evidence-missing'), nextAction: historicalNextAction });
@@ -292,6 +414,9 @@ export async function recoverMissingCheckoutPreservations({ appId, repoPath, out
const MAX_FILE_BYTES = 25 * 1024 * 1024;
const MAX_TOTAL_BYTES = 250 * 1024 * 1024;
const GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+// execGit bounds JS string length. Three UTF-8 bytes per code unit is its
+// maximum encoded size; retain admission for older multibyte patches too.
+const MAX_PATCH_BYTES = 3 * GIT_OUTPUT_BYTES;
function checkArchiveSize(scope, fileBytes, totalBytes) {
if (fileBytes <= MAX_FILE_BYTES && totalBytes <= MAX_TOTAL_BYTES) return;
@@ -302,36 +427,63 @@ function checkArchiveSize(scope, fileBytes, totalBytes) {
} });
}
-const archiveLimitRefusal = error => error.message === 'archive-manifest-budget-exceeded'
- ? { ok: false, reason: 'retirement-archive-manifest-limit-exceeded' }
- : error.message === 'archive-file-budget-exceeded'
- ? { ok: false, reason: 'retirement-archive-file-limit-exceeded' }
- : error.message === 'retirement-archive-limit-exceeded'
- ? { ok: false, reason: error.message, archiveLimit: error.archiveLimit } : null;
+const archiveRecoveryAction = 'Keep the checkout and ref; free resources or preserve large outputs separately, then retry this exact checkout with fresh evidence.';
+const archiveLimitRefusal = error => {
+ const gitLimit = error.code === 'GIT_OUTPUT_LIMIT'
+ ? { scope: 'git-output', kind: 'output', limitCodeUnits: error.limitCodeUnits, observedCodeUnits: error.observedCodeUnits }
+ : error.code === 'GIT_TIMEOUT'
+ ? { scope: 'git-command', kind: 'time', limitMs: error.limitMs, observedMs: error.observedMs } : null;
+ const reason = error.code === 'GIT_TIMEOUT' ? 'retirement-archive-work-limit-exceeded'
+ : error.code === 'GIT_OUTPUT_LIMIT' ? 'retirement-archive-limit-exceeded'
+ : error.message === 'archive-manifest-budget-exceeded' ? 'retirement-archive-manifest-limit-exceeded'
+ : ['retirement-archive-cancelled', 'retirement-archive-work-limit-exceeded', 'retirement-archive-limit-exceeded'].includes(error.message)
+ ? error.message : null;
+ return reason ? { ok: false, reason, ...((gitLimit || error.archiveLimit) && { archiveLimit: gitLimit || error.archiveLimit }), nextAction: archiveRecoveryAction } : null;
+};
const shortBranch = (ref) => (ref ? String(ref).replace(/^refs\/heads\//, '') : null);
const zLines = (stdout) => (stdout || '').split('\0').filter(Boolean);
-const git = (args, cwd) => execGit(args, cwd, { maxBuffer: GIT_OUTPUT_BYTES }).then(r => r.stdout || '');
+const archiveText = bytes => {
+ const text = bytes.toString('utf8');
+ if (!Buffer.from(text, 'utf8').equals(bytes)) throw new Error('archive metadata is not lossless UTF-8');
+ return text;
+};
+const git = (args, cwd, raw = false) => execGit(args, cwd, { maxBuffer: GIT_OUTPUT_BYTES, bufferOutput: true })
+ .then(r => raw ? r.stdout : archiveText(r.stdout));
/** Preserve worktree-private Git evidence, never follow its links into the
* common repository. The lock is archived but matched separately by release.
*/
-async function snapshotAdministration(path, missingRoot = null) {
+async function snapshotAdministration(path, missingRoot = null, work = archiveWork()) {
const root = missingRoot || (await git(['rev-parse', '--absolute-git-dir'], path)).trim();
const files = [];
const symlinks = [];
let bytes = 0;
const visit = async (source, rel) => {
+ work.check();
const info = await lstat(source);
- if (info.isSymbolicLink()) { symlinks.push({ path: rel, target: await readlink(source) }); return; }
+ if (info.isSymbolicLink()) {
+ const link = { path: rel, target: archiveText(await readlink(source, { encoding: 'buffer' })) };
+ work.add(link);
+ symlinks.push(link);
+ return;
+ }
if (info.isDirectory()) {
- for (const name of (await readdir(source)).sort()) await visit(join(source, name), rel ? `${rel}/${name}` : name);
+ const names = [];
+ for await (const entry of await opendir(source, { encoding: 'buffer' })) {
+ const name = archiveText(entry.name);
+ work.add(name, 'directory');
+ names.push(name);
+ }
+ for (const name of names.sort()) await visit(join(source, name), rel ? `${rel}/${name}` : name);
return;
}
if (!info.isFile()) throw new Error('administration cannot be archived');
bytes += info.size;
checkArchiveSize('administration', info.size, bytes);
- files.push({ path: rel, source, bytes: info.size, sha256: await sha256File(source) });
+ const file = { path: rel, bytes: info.size, sha256: await archiveHash(source, work) };
+ work.add(file);
+ files.push({ ...file, source });
};
await visit(root, 'gitdir');
const pointer = join(path, '.git');
@@ -405,7 +557,7 @@ async function reviewCurrentCheckout({ repoPath, release, prUrl, unlocked = fals
if (!identity) return { ok: false, reason: 'retirement-local-objects-missing' };
const policy = await retirementPolicy(repoPath, release.branch, opts, identity);
if (policy.reason) return { ok: false, reason: policy.reason };
- return archiveSnapshots(matched.tree, repoPath)
+ return archiveSnapshots(matched.tree, repoPath, null, archiveWork(opts.signal))
.then(([content, administration]) => buildCheckoutRetirementReview({ repoPath, release, prUrl,
contentFingerprint: content.fingerprint, administrationFingerprint: administration.fingerprint, policy }, { ...opts, readForge: async () => forge }))
.then(review => ({ ok: true, review }), error => archiveLimitRefusal(error) || ({ ok: false,
@@ -434,9 +586,17 @@ export async function prepareInventoriedCheckoutRetirement({ appId, release, prU
}
/** Git's object id for raw bytes, with no clean filter or line-ending conversion. */
-async function rawBlobId(source, size, format) {
+async function rawBlobId(source, size, format, work) {
const hash = createHash(format).update(`blob ${size}\0`);
- for await (const chunk of createReadStream(source)) hash.update(chunk);
+ let bytes = 0;
+ const { stream } = await archiveSource(source);
+ for await (const chunk of stream) {
+ work.check();
+ // Clean tracked files are not raw archive inputs; a growing read still
+ // cannot consume unbounded work before the next metadata check.
+ if ((bytes += chunk.length) > size) throw new Error('checkout-content-changed');
+ hash.update(chunk);
+ }
return hash.digest('hex');
}
@@ -449,7 +609,8 @@ async function rawBlobId(source, size, format) {
* on anything that cannot be archived faithfully, before any copy is made.
* The fingerprint is compared again immediately before removal.
*/
-async function snapshotContent(path) {
+async function snapshotContent(path, work = archiveWork()) {
+ work.check();
// These reads are independent and each Git spawn is mostly launch latency, so
// they run together; every destructive boundary re-reads this snapshot anyway.
const [unmerged, stageOut, tagged, indexDiff, worktreeDiff, objectFormat, others] = await Promise.all([
@@ -460,8 +621,8 @@ async function snapshotContent(path) {
// diff's stat-cache refresh too: an otherwise read-only diff can rewrite
// the index and race the concurrent administration snapshot. Git's
// --no-optional-locks alone does not disable diff.autoRefreshIndex.
- git(['-c', 'diff.autoRefreshIndex=false', 'diff', '--cached', '--binary', '--no-textconv', '--no-ext-diff'], path),
- git(['-c', 'diff.autoRefreshIndex=false', 'diff', '--binary', '--no-textconv', '--no-ext-diff'], path),
+ git(['-c', 'diff.autoRefreshIndex=false', 'diff', '--cached', '--binary', '--no-textconv', '--no-ext-diff'], path, true),
+ git(['-c', 'diff.autoRefreshIndex=false', 'diff', '--binary', '--no-textconv', '--no-ext-diff'], path, true),
git(['rev-parse', '--show-object-format'], path),
git(['ls-files', '--others', '-z'], path),
]);
@@ -474,7 +635,9 @@ async function snapshotContent(path) {
const rel = line.slice(tab + 1);
const info = await lstat(join(path, rel)).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
if (info && (!info.isDirectory() || (await readdir(join(path, rel))).length)) throw new Error('retirement-submodule-not-uninitialized');
- gitlinks.push({ path: rel, commit: header.split(' ')[1], state: info ? 'empty' : 'missing' });
+ const link = { path: rel, commit: header.split(' ')[1], state: info ? 'empty' : 'missing' };
+ work.add(link);
+ gitlinks.push(link);
}
// Assume-unchanged (lowercase tag) and skip-worktree (S) entries hide edits from diff.
const hidden = zLines(tagged).find(line => /^[a-zS]/.test(line));
@@ -485,10 +648,13 @@ async function snapshotContent(path) {
const addFile = async (rel, info, extra = {}) => {
total += info.size;
checkArchiveSize('content', info.size, total);
- files.push({ path: rel, bytes: info.size, sha256: await sha256File(join(path, rel)), ...extra });
+ const file = { path: rel, bytes: info.size, sha256: await archiveHash(join(path, rel), work), ...extra };
+ work.add(file);
+ files.push(file);
};
const format = objectFormat.trim() || 'sha1';
for (const line of stage) {
+ work.check();
const tab = line.indexOf('\t');
const [mode, blob] = line.slice(0, tab).split(' ');
const rel = line.slice(tab + 1);
@@ -496,14 +662,19 @@ async function snapshotContent(path) {
if (mode !== '100644' && mode !== '100755') continue;
const info = await lstat(join(path, rel)).catch(err => (err.code === 'ENOENT' ? null : Promise.reject(err)));
if (!info?.isFile()) continue;
- if (await rawBlobId(join(path, rel), info.size, format) !== blob) await addFile(rel, info, { tracked: true });
+ if (await rawBlobId(join(path, rel), info.size, format, work) !== blob) await addFile(rel, info, { tracked: true });
}
const symlinks = [];
for (const rel of zLines(others)) {
+ work.check();
// `ls-files --others` names a nested repository as `dir/` without its files.
if (rel.endsWith('/')) throw new Error(`nested repository at ${rel} cannot be archived`);
const info = await lstat(join(path, rel));
- if (info.isSymbolicLink()) symlinks.push({ path: rel, target: await readlink(join(path, rel)) });
+ if (info.isSymbolicLink()) {
+ const link = { path: rel, target: archiveText(await readlink(join(path, rel), { encoding: 'buffer' })) };
+ work.add(link);
+ symlinks.push(link);
+ }
else if (info.isFile()) await addFile(rel, info);
else throw new Error(`${rel} is not a regular file`);
}
@@ -571,9 +742,13 @@ async function missingCheckoutAdministration(repoPath, path) {
return roots[0];
}
-async function archiveSnapshots(tree, repoPath, missingRoot) {
+async function archiveSnapshots(tree, repoPath, missingRoot, work = archiveWork()) {
+ work = work.metadataScope();
if (!missingRoot) {
- const snapshots = await Promise.all([snapshotContent(tree.path), snapshotAdministration(tree.path)]);
+ const snapshots = await Promise.all([snapshotContent(tree.path, work), snapshotAdministration(tree.path, null, work)]);
+ work.check();
+ // Capture already charged metadata; apply the reader's layout checks too.
+ for (const snapshot of snapshots) validateArchiveEntries(snapshot, work, false);
checkArchiveBudget(...snapshots);
return snapshots;
}
@@ -581,10 +756,11 @@ async function archiveSnapshots(tree, repoPath, missingRoot) {
if (present) throw new Error('missing-checkout-reappeared');
const prefix = ['--git-dir', missingRoot, '--work-tree', tree.path];
if ((await git([...prefix, 'ls-files', '-u', '-z'], repoPath)).length) throw new Error('unmerged index entries cannot be archived');
- const indexDiff = await git([...prefix, 'diff', '--cached', '--binary', '--no-textconv', '--no-ext-diff'], repoPath);
- const content = { indexDiff, worktreeDiff: '', files: [], symlinks: [], gitlinks: [], missingCheckout: true,
+ const indexDiff = await git([...prefix, 'diff', '--cached', '--binary', '--no-textconv', '--no-ext-diff'], repoPath, true);
+ const content = { indexDiff, worktreeDiff: Buffer.alloc(0), files: [], symlinks: [], gitlinks: [], missingCheckout: true,
fingerprint: createHash('sha256').update('missing-checkout\0').update(indexDiff).digest('hex') };
- const administration = await snapshotAdministration(tree.path, missingRoot);
+ const administration = await snapshotAdministration(tree.path, missingRoot, work);
+ validateArchiveEntries(administration, work, false);
checkArchiveBudget(content, administration);
return [content, administration];
}
@@ -593,16 +769,16 @@ async function archiveSnapshots(tree, repoPath, missingRoot) {
* is removed. The caller owns the live ownership fence and merge proof; this
* guard verifies that every preserved byte still matches immediately at removal.
*/
-export async function preserveMergedCheckout(repoPath, tree, defaultBranch, { cosDir } = {}) {
+export async function preserveMergedCheckout(repoPath, tree, defaultBranch, { cosDir, signal } = {}) {
if (!tree?.head || (!tree.branch && tree.detached !== true) || tree.locked) throw new Error('checkout-identity-unavailable');
const branch = shortBranch(tree.branch);
const missingRoot = await missingCheckoutAdministration(repoPath, tree.path);
- const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, cosDir, missingRoot });
+ const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, cosDir, missingRoot, work: archiveWork(signal) });
return {
archiveDir: archive.dir,
async verify(holder) {
if (!holder || holder.head !== tree.head || holder.branch !== tree.branch || Boolean(holder.detached) !== Boolean(tree.detached)) return 'worktree-holder-changed';
- const [content, administration] = await archiveSnapshots(tree, repoPath, missingRoot);
+ const [content, administration] = await archiveSnapshots(tree, repoPath, missingRoot, archiveWork(signal));
return content.fingerprint === archive.fingerprint && administration.fingerprint === archive.administrationFingerprint
? null : 'checkout-content-changed';
},
@@ -629,11 +805,12 @@ function recoveryReferenceKind(path) {
return /^[A-Z][A-Z0-9_]*$/.test(relative) ? 'ref' : null;
}
-async function recoveryObjectHeads(administration, { repoPath, tree, missingRoot }) {
+async function recoveryObjectHeads(administration, { repoPath, tree, missingRoot }, work) {
const heads = new Set([tree.head]);
const oid = new RegExp(`^[a-f0-9]{${tree.head.length}}$`, 'i');
const invalid = () => { throw new Error('unrecognized private recovery reference'); };
const add = (value, allowZero = false) => {
+ work.check();
if (!oid.test(value)) invalid();
if (/^0+$/.test(value)) { if (allowZero) return; invalid(); }
heads.add(value.toLowerCase());
@@ -643,10 +820,11 @@ async function recoveryObjectHeads(administration, { repoPath, tree, missingRoot
if (recoveryReferenceKind(link.path)) throw new Error('unsupported linked recovery reference');
}
for (const file of administration.files) {
+ work.check();
const kind = recoveryReferenceKind(file.path);
if (!kind) continue;
if (kind === 'unsafe') throw new Error('retirement-operation-active');
- const contents = await readFile(file.source, 'utf8');
+ const contents = (await archiveBytes(file.source, work, MAX_FILE_BYTES)).toString('utf8');
const lines = contents.split(/\r?\n/);
if (lines.at(-1) === '') lines.pop();
if (kind === 'ref') {
@@ -654,13 +832,16 @@ async function recoveryObjectHeads(administration, { repoPath, tree, missingRoot
const symbolic = /^ref: (\S+)$/.exec(lines[0]);
if (symbolic) {
const prefix = missingRoot ? ['--git-dir', missingRoot, '--work-tree', tree.path] : [];
+ work.check();
await git([...prefix, 'check-ref-format', '--allow-onelevel', symbolic[1]], missingRoot ? repoPath : tree.path);
+ work.check();
add((await git([...prefix, 'rev-parse', '--verify', '--end-of-options', symbolic[1]], missingRoot ? repoPath : tree.path)).trim());
} else add(lines[0]);
continue;
}
if (kind === 'objects' && !lines.length) invalid();
for (const line of lines) {
+ work.check();
if (kind === 'reflog') {
const fields = /^([a-f0-9]+) ([a-f0-9]+) [^\t]+(?:\t.*)?$/i.exec(line);
if (!fields) invalid();
@@ -745,9 +926,10 @@ export async function preserveSupersededCheckout({ appId, repoPath, tree, defaul
};
}
-async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, release, review, missingRoot = null }) {
- const [snapshot, administration] = await archiveSnapshots(tree, repoPath, missingRoot);
- const recoveryHeads = await recoveryObjectHeads(administration, { repoPath, tree, missingRoot });
+async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, release, review, missingRoot = null, work = archiveWork() }) {
+ work.check();
+ const [snapshot, administration] = await archiveSnapshots(tree, repoPath, missingRoot, work);
+ const recoveryHeads = await recoveryObjectHeads(administration, { repoPath, tree, missingRoot }, work);
await ensureDir(dir);
await chmod(dir, 0o700);
@@ -762,13 +944,17 @@ async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, releas
const namespace = `refs/portos/archive/${randomUUID()}`;
try {
for (const head of recoveryHeads) {
+ work.check();
const type = (await git(['cat-file', '-t', head], repoPath)).trim();
if (!['commit', 'tree', 'blob', 'tag'].includes(type)) throw new Error('private recovery object has an unsupported type');
+ work.check();
const ref = `${namespace}/${head}`;
await git(['update-ref', ref, head, ''], repoPath);
recoveryRefs.push({ ref, head });
}
+ work.check();
await git([...(missingRoot ? ['--git-dir', missingRoot, '--work-tree', tree.path] : []), 'bundle', 'create', bundle, 'HEAD', ...recoveryRefs.map(entry => entry.ref)], missingRoot ? repoPath : tree.path);
+ work.check();
const [, heads] = await Promise.all([git(['bundle', 'verify', bundle], repoPath), git(['bundle', 'list-heads', bundle], repoPath)]);
const bundled = new Set(heads.trim().split('\n').map(line => line.split(' ')[0]));
if ([...recoveryHeads].some(head => !bundled.has(head))) throw new Error('bundle recovery head mismatch');
@@ -779,39 +965,42 @@ async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, releas
}
await chmod(bundle, 0o600);
for (const file of administration.files) {
+ work.check();
const destination = join(dir, 'administration', file.path);
await ensureDir(dirname(destination));
- await copyFileGuarded(file.source, destination);
+ await archiveCopy(file.source, destination, file.bytes, work);
await chmod(destination, 0o600);
- if (await sha256File(destination) !== file.sha256) throw new Error('administration archive mismatch');
+ if (await archiveHash(destination, work) !== file.sha256) throw new Error('administration archive mismatch');
}
- if (snapshot.indexDiff) await writeFileGuarded(join(dir, 'index.diff'), snapshot.indexDiff);
- if (snapshot.worktreeDiff) await writeFileGuarded(join(dir, 'worktree.diff'), snapshot.worktreeDiff);
+ if (snapshot.indexDiff.length) await writeFileGuarded(join(dir, 'index.diff'), snapshot.indexDiff);
+ if (snapshot.worktreeDiff.length) await writeFileGuarded(join(dir, 'worktree.diff'), snapshot.worktreeDiff);
const { files, symlinks } = snapshot;
for (const file of files) {
+ work.check();
const destination = join(dir, 'files', file.path);
await ensureDir(dirname(destination));
- await copyFileGuarded(join(tree.path, file.path), destination);
- if (await sha256File(destination) !== file.sha256) throw new Error(`archived copy of ${file.path} does not match`);
+ await archiveCopy(join(tree.path, file.path), destination, file.bytes, work);
+ if (await archiveHash(destination, work) !== file.sha256) throw new Error(`archived copy of ${file.path} does not match`);
}
// Re-read after every copy so the check covers the whole archive window.
- const [after, administrationAfter] = await archiveSnapshots(tree, repoPath, missingRoot);
+ const [after, administrationAfter] = await archiveSnapshots(tree, repoPath, missingRoot, work);
if (administrationAfter.fingerprint !== administration.fingerprint) throw new Error('administration changed while archiving');
if (after.fingerprint !== snapshot.fingerprint) throw new Error('checkout content changed while archiving');
const manifest = {
+ resourceContract: 1,
repoPath, defaultBranch, path: tree.path, head: tree.head, branch,
release, review, administration: { ...administration, files: administration.files.map(({ source: _source, ...file }) => file) }, archivedAt: new Date().toISOString(),
- bundleSha256: await sha256File(bundle),
+ bundleSha256: await archiveHash(bundle, work, Infinity),
patchHashes: { index: evidenceHash(snapshot.indexDiff), worktree: evidenceHash(snapshot.worktreeDiff) },
- captured: { commitBundle: true, recoveryHeads: [...recoveryHeads], ...(snapshot.missingCheckout ? { missingCheckout: true } : {}), gitlinks: snapshot.gitlinks, indexDiff: Boolean(snapshot.indexDiff), worktreeDiff: Boolean(snapshot.worktreeDiff), files, symlinks },
+ captured: { commitBundle: true, recoveryHeads: [...recoveryHeads], ...(snapshot.missingCheckout ? { missingCheckout: true } : {}), gitlinks: snapshot.gitlinks, indexDiff: Boolean(snapshot.indexDiff.length), worktreeDiff: Boolean(snapshot.worktreeDiff.length), files, symlinks },
restore: [
'git -C <repo> fetch commits.bundle HEAD:refs/heads/<restored-branch>',
'git -C <repo> fetch commits.bundle "+refs/portos/archive/*:refs/portos/recovered/*"',
`git -C <repo> worktree add <checkout> ${tree.head}`,
- snapshot.indexDiff ? 'git -C <checkout> apply --index index.diff' : null,
- snapshot.worktreeDiff ? 'git -C <checkout> apply worktree.diff' : null,
+ snapshot.indexDiff.length ? 'git -C <checkout> apply --index index.diff' : null,
+ snapshot.worktreeDiff.length ? 'git -C <checkout> apply worktree.diff' : null,
// Last, so raw tracked bytes replace the filtered form the diffs restore.
files.length ? 'cp -R files/. <checkout>/' : null,
symlinks.length ? 'recreate manifest.captured.symlinks with ln -s' : null,
@@ -820,7 +1009,11 @@ async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, releas
// Check the exact payload atomicWrite receives: escaped review text can make
// the manifest larger than its individually bounded Git diff inputs.
const serialized = JSON.stringify(manifest, null, 2);
- if (Buffer.byteLength(serialized) > MAX_MANIFEST_BYTES) throw new Error('archive-manifest-budget-exceeded');
+ const manifestBytes = Buffer.byteLength(serialized);
+ if (manifestBytes > MAX_MANIFEST_BYTES) throw Object.assign(new Error('archive-manifest-budget-exceeded'), {
+ archiveLimit: { scope: 'manifest', kind: 'total', limitBytes: MAX_MANIFEST_BYTES, observedBytes: manifestBytes },
+ });
+ work.check();
await atomicWrite(join(dir, 'manifest.json'), serialized);
await chmod(join(dir, 'manifest.json'), 0o600);
return { dir, fingerprint: snapshot.fingerprint, administrationFingerprint: administration.fingerprint };
@@ -920,7 +1113,7 @@ async function retireHeldCheckout({ repoPath, release, review }, opts = {}) {
// Every ownership check queues behind the claim-ownership lock with a short
// budget, so the archive runs between two critical sections (#12682).
- const refuse = (reason, archiveLimit) => ({ result: { ok: false, reason, ...(archiveLimit && { archiveLimit }) } });
+ const refuse = (reason, archiveLimit, nextAction) => ({ result: { ok: false, reason, ...(archiveLimit && { archiveLimit }), ...(nextAction && { nextAction }) } });
return retireWithUnlockedArchive({
busy: () => ({ ok: false, reason: 'checkout-retirement-reserved' }),
admit: async () => {
@@ -936,14 +1129,14 @@ async function retireHeldCheckout({ repoPath, release, review }, opts = {}) {
: await isAncestor(repoPath, tree.head, defaultBranch);
if (!merged && !review) return refuse('not-merged-on-recheck');
const reviewed = review ? await reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl }, opts) : null;
- if (reviewed && (!reviewed.ok || reviewed.review.digest !== review.digest)) return refuse(reviewed.reason || 'retirement-review-changed', reviewed.archiveLimit);
+ if (reviewed && (!reviewed.ok || reviewed.review.digest !== review.digest)) return refuse(reviewed.reason || 'retirement-review-changed', reviewed.archiveLimit, reviewed.nextAction);
if (reviewed?.review.comparison.disposition === 'review-supersession' && review.acceptSuperseded !== true) return refuse('retirement-supersession-not-accepted');
const owner = await ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review), mergedObligationSettled });
if (owner) return refuse(owner);
return { fence: { repoPath, path: tree.path, branch }, tree, reviewed, checkoutIdentity };
},
archive: async ({ tree, reviewed }) => {
- const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, release, cosDir, review: reviewed?.review })
+ const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, release, cosDir, review: reviewed?.review, work: archiveWork(opts.signal) })
.catch(error => ({ error }));
if (!archive.error) return { archive };
const capacityRefusal = archiveLimitRefusal(archive.error);
@@ -962,6 +1155,7 @@ async function retireHeldCheckout({ repoPath, release, review }, opts = {}) {
async function finishHeldCheckoutRetirement({ repoPath, release, review, reviewed, tree, branch, archive, checkoutIdentity, mergedObligationSettled = false }, opts) {
const { readAgents = readClaimOwnershipAgents } = opts;
// Archiving takes time; never unlock a lock that changed hands meanwhile.
+ if (opts.signal?.aborted) return { ok: false, reason: 'retirement-archive-cancelled', archiveDir: archive.dir };
const second = await matchRelease(repoPath, release);
if (!second.tree) return { ok: false, reason: second.reason, archiveDir: archive.dir };
if (await readRetirementCheckoutIdentity(tree.path) !== checkoutIdentity) return { ok: false, reason: 'checkout-identity-changed', archiveDir: archive.dir };
@@ -970,7 +1164,9 @@ async function finishHeldCheckoutRetirement({ repoPath, release, review, reviewe
const unlocked = await execGit(['worktree', 'unlock', tree.path], repoPath).then(() => true, () => false);
if (!unlocked) return { ok: false, reason: 'worktree-unlock-failed', archiveDir: archive.dir };
}
+ let capacityRefusal;
const verifyRemoval = async (holder) => {
+ if (opts.signal?.aborted) return 'retirement-archive-cancelled';
if (!holder || holder.head !== tree.head || shortBranch(holder.branch) !== branch) return 'worktree-holder-changed';
if (!await matchesObservedCheckoutIncarnation(repoPath, release)) return 'checkout-identity-changed';
if (await readRetirementCheckoutIdentity(tree.path) !== checkoutIdentity) return 'checkout-identity-changed';
@@ -979,11 +1175,15 @@ async function finishHeldCheckoutRetirement({ repoPath, release, review, reviewe
ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review), mergedObligationSettled }),
review ? reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl, unlocked: release.locked }, opts) : null,
]);
- if (fresh && (!fresh.ok || fresh.review.digest !== review.digest)) return fresh.reason || 'retirement-review-changed';
+ if (fresh && !fresh.ok) { capacityRefusal = fresh; return fresh.reason; }
+ if (fresh && fresh.review.digest !== review.digest) return 'retirement-review-changed';
// The byte comparisons stay last so nothing else ages between them and removal.
- const [administration, current] = await Promise.all([snapshotAdministration(tree.path), snapshotContent(tree.path).catch(() => null)]);
+ const [current, administration] = await archiveSnapshots(tree, repoPath, null, archiveWork(opts.signal))
+ .catch(error => { capacityRefusal = archiveLimitRefusal(error); return []; });
+ if (!administration || !current) return capacityRefusal?.reason || 'checkout-content-changed';
if (administration.fingerprint !== archive.administrationFingerprint) return 'checkout-administration-changed';
if (reason) return reason;
+ if (opts.signal?.aborted) return 'retirement-archive-cancelled';
return current?.fingerprint === archive.fingerprint ? null : 'checkout-content-changed';
};
const removal = await forceRemoveWorktreeDir(repoPath, tree.path, {
@@ -996,7 +1196,7 @@ async function finishHeldCheckoutRetirement({ repoPath, release, review, reviewe
const args = ['worktree', 'lock', ...(release.lockReason != null ? ['--reason', release.lockReason] : []), tree.path];
await execGit(args, repoPath).catch(err => console.warn(`⚠️ held-checkout recovery: could not restore lock on ${tree.path}: ${err.message}`));
}
- return { ok: false, reason: removal.reason || 'worktree-remove-failed', archiveDir: archive.dir };
+ return { ...(capacityRefusal || { ok: false, reason: removal.reason || 'worktree-remove-failed' }), archiveDir: archive.dir };
}
console.log(`🧹 held-checkout recovery: retired ${tree.path} (archive: ${archive.dir})`);
if (!branch) return { ok: true, archiveDir: archive.dir, branchDeleted: false };
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
index 3621ba5234..6a65c8b95f 100644
--- a/server/services/heldCheckoutRecovery.test.js
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -5,7 +5,7 @@
* its lock and its branch as found.
*/
import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from 'vitest';
-import { cp, mkdtemp, mkdir, rm, rename, writeFile, readFile, readdir, symlink, utimes, truncate } from 'fs/promises';
+import { cp, mkdtemp, mkdir, rm, rename, writeFile, readFile, readdir, readlink, symlink, utimes, truncate, chmod, stat } from 'fs/promises';
import { existsSync, realpathSync } from 'fs';
import { tmpdir } from 'os';
import { promisify } from 'node:util';
@@ -24,7 +24,7 @@ afterAll(cleanupTempDataRoots);
const SYMLINKS = process.platform !== 'win32';
const retirementFaults = vi.hoisted(() => ({ onRemove: null, onBranchDelete: null, scheduleWrites: 0, failScheduleWrite: null }));
-const injected = vi.hoisted(() => ({ policies: [], schedule: null, app: null, fetchRemote: null, fetches: [], onBundle: null, onEvidence: null, proofFailures: [] }));
+const injected = vi.hoisted(() => ({ policies: [], schedule: null, app: null, fetchRemote: null, fetches: [], onBundle: null, onArchiveRef: null, onEvidence: null, onProof: null, proofFailures: [] }));
vi.mock('../lib/execGit.js', async importOriginal => {
const actual = await importOriginal();
@@ -38,7 +38,12 @@ vi.mock('../lib/execGit.js', async importOriginal => {
injected.fetches.push({ args, options });
if (injected.fetchRemote) args = args.map(arg => arg === 'https://github.com/example/repo.git' ? injected.fetchRemote : arg);
}
- try { return await actual.execGit(args, cwd, options); }
+ try {
+ const result = await actual.execGit(args, cwd, options);
+ if (injected.onArchiveRef && args[0] === 'update-ref' && args[1]?.startsWith('refs/portos/archive/')) await injected.onArchiveRef();
+ if (injected.onProof && args.includes('--bare') && options?.env?.GIT_NO_REPLACE_OBJECTS === '1') await injected.onProof();
+ return result;
+ }
catch (error) {
const phase = args.includes('unbundle') ? 'unbundle' : args.includes('fsck') ? 'fsck' : args.includes('--bare') ? 'init' : null;
if (phase && options?.env?.GIT_NO_REPLACE_OBJECTS === '1') {
@@ -85,7 +90,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
beforeEach(async () => {
Object.assign(retirementFaults, { onRemove: null, onBranchDelete: null, scheduleWrites: 0, failScheduleWrite: null });
- Object.assign(injected, { policies: [], schedule: { tasks: {}, executions: {} }, app: { id: 'app-1', repoPath: null }, fetchRemote: null, fetches: [], onBundle: null, onEvidence: null, proofFailures: [] });
+ Object.assign(injected, { policies: [], schedule: { tasks: {}, executions: {} }, app: { id: 'app-1', repoPath: null }, fetchRemote: null, fetches: [], onBundle: null, onArchiveRef: null, onEvidence: null, onProof: null, proofFailures: [] });
scratch = realpathSync(await mkdtemp(join(tmpdir(), 'portos-held-checkout-')));
const safeRepo = join(scratch, 'repo');
await mkdir(safeRepo);
@@ -386,6 +391,34 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(recreated.retirementObligations[0].preservationEvidence.archives).toContainEqual({ archiveDir: saved.archiveDir, reason: 'archive-generation-mismatch' });
});
+ it.each(['cancel', 'time', 'git-output', 'git-time'])('retains the %s diagnosis when isolated Git proof is interrupted without settling preservation', async mode => {
+ const { saved } = await historicalArchive();
+ const outcome = await getBranchReconcileOutcome('app-1');
+ const controller = new AbortController();
+ let clock;
+ injected.onProof = () => {
+ if (mode === 'cancel') controller.abort();
+ else if (mode === 'time') clock = vi.spyOn(performance, 'now').mockReturnValue(performance.now() + 11 * 60 * 1000);
+ else throw Object.assign(new Error('synthetic Git resource exhaustion'), mode === 'git-output'
+ ? { code: 'GIT_OUTPUT_LIMIT', limitCodeUnits: 64 * 1024 * 1024, observedCodeUnits: 64 * 1024 * 1024 + 1 }
+ : { code: 'GIT_TIMEOUT', limitMs: 30000, observedMs: 30001 });
+ };
+ try {
+ const result = await recoverMissingCheckoutPreservations({ appId: 'app-1', repoPath: repo, outcome }, { signal: controller.signal });
+ expect(result.recoveredPreservations || []).toEqual([]);
+ expect(result.retirementObligations).toHaveLength(1);
+ const evidence = result.retirementObligations[0].preservationEvidence.archives.find(row => row.archiveDir === saved.archiveDir);
+ expect(evidence).toMatchObject({ reason: mode === 'cancel' ? 'retirement-archive-cancelled'
+ : mode === 'git-output' ? 'retirement-archive-limit-exceeded' : 'retirement-archive-work-limit-exceeded', nextAction: expect.any(String) });
+ if (mode === 'git-output') expect(evidence.archiveLimit).toEqual({ scope: 'git-output', kind: 'output',
+ limitCodeUnits: 64 * 1024 * 1024, observedCodeUnits: 64 * 1024 * 1024 + 1 });
+ if (mode === 'git-time') expect(evidence.archiveLimit).toEqual({ scope: 'git-command', kind: 'time', limitMs: 30000, observedMs: 30001 });
+ if (mode === 'time') expect(evidence.archiveLimit).toMatchObject({ scope: 'verification', kind: 'time', limitMs: 600000, observedMs: expect.any(Number) });
+ expect(result.retired).toBeUndefined();
+ expect(existsSync(saved.archiveDir)).toBe(true);
+ } finally { clock?.mockRestore(); }
+ });
+
it('recognizes an absent completion archive without a schedule obligation and rejects changed or older evidence', async () => {
const { release, saved } = await historicalArchive();
const outcome = await getBranchReconcileOutcome('app-1');
@@ -393,12 +426,15 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
injected.schedule = { executions: {} };
const withoutObligation = await getBranchReconcileOutcome('app-1');
await execGit(['branch', '-d', release.branch], repo);
- const proof = await findMissingCheckoutPreservation({ repoPath: repo, release: original });
+ const controller = new AbortController();
+ const proof = await findMissingCheckoutPreservation({ repoPath: repo, release: original }, { signal: controller.signal });
expect(proof).toMatchObject({ archiveDir: saved.archiveDir, evidenceDigest: expect.stringMatching(/^[a-f0-9]{64}$/) });
expect(await proof.recheck()).toBe(true);
await mkdir(release.path);
expect(await proof.recheck()).toBe(false);
await rm(release.path, { recursive: true });
+ controller.abort();
+ await expect(proof.recheck()).rejects.toThrow('retirement-archive-cancelled');
const manifest = JSON.parse(await readFile(join(saved.archiveDir, 'manifest.json'), 'utf8'));
expect(await findMissingCheckoutPreservation({ repoPath: repo, release: { ...original, createdAt: new Date(Date.parse(manifest.archivedAt) + 1).toISOString() } })).toBeNull();
await writeFile(join(saved.archiveDir, 'files', 'private.txt'), 'corrupt archived evidence');
@@ -739,8 +775,9 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
await writeFile(join(tree, 'eol.txt'), 'one\r\ntwo\r\n');
} });
// Only the index holds this file once its working copy is gone.
- await writeFile(join(path, 'staged-only.txt'), 'staged work\n');
+ await writeFile(join(path, 'staged-only.txt'), Buffer.concat([Buffer.from(`staged work\n${'界'.repeat(100000)}\n`), Buffer.from([0xff, 10])]));
await execGit(['add', 'staged-only.txt'], path);
+ const stagedBlob = (await execGit(['rev-parse', ':staged-only.txt'], path)).stdout.trim();
await rm(join(path, 'staged-only.txt'));
// Make an unchanged tracked file's stat cache stale. Git diff normally
@@ -763,6 +800,13 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await readFile(join(result.archiveDir, 'files', 'ignored.txt'), 'utf8')).toBe('ignored work\n');
expect(await readFile(join(result.archiveDir, 'worktree.diff'), 'utf8')).toContain('+tracked edit');
expect(await readFile(join(result.archiveDir, 'index.diff'), 'utf8')).toContain('+staged work');
+ const restored = join(scratch, 'unicode-staged-restore');
+ await mkdir(restored);
+ await execGit(['init'], restored);
+ await execGit(['fetch', join(result.archiveDir, 'commits.bundle'), 'HEAD'], restored);
+ await execGit(['checkout', '--detach', 'FETCH_HEAD'], restored);
+ await execGit(['apply', '--index', join(result.archiveDir, 'index.diff')], restored);
+ expect((await execGit(['rev-parse', ':staged-only.txt'], restored)).stdout.trim()).toBe(stagedBlob);
});
it('bundles a squash-merged branch, retires it with its branch, and drops it from the persisted inventory', async () => {
@@ -975,6 +1019,19 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await archives()).toEqual([]);
});
+ it.skipIf(!SYMLINKS)('preserves the checkout when a link target cannot be represented losslessly in archive metadata', async () => {
+ const { path, release } = await heldCheckout('opaque-link', { branch: 'feature/opaque-link' });
+ const target = Buffer.from([0xff]);
+ await symlink(target, join(path, 'opaque-link'));
+
+ expect(await retire(release)).toMatchObject({ ok: false, reason: 'archive-failed' });
+ expect(await readlink(join(path, 'opaque-link'), { encoding: 'buffer' })).toEqual(target);
+ expect(await lockText(path)).toBe('synthetic external owner');
+ expect(await registered(path)).toBe(true);
+ expect(await archives()).toEqual([]);
+ expect((await execGit(['rev-parse', release.branch], repo)).stdout.trim()).toBe(release.head);
+ });
+
// #12682: archive I/O ran inside the shared ownership lock and starved every
// claim-ownership check behind its 15 s queue budget for minutes.
it('archives with the ownership queue free while fencing only the checkout being retired', async () => {
@@ -1108,7 +1165,8 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(Buffer.byteLength(prepared.review.comparison.difference)).toBeLessThan(4 * 1024 * 1024);
const before = await getBranchReconcileOutcome('app-1');
const original = await sha256File(join(c.path, 'tabs.txt'));
- expect(await c.confirm(prepared.review)).toEqual({ ok: false, reason: 'retirement-archive-manifest-limit-exceeded' });
+ expect(await c.confirm(prepared.review)).toMatchObject({ ok: false, reason: 'retirement-archive-manifest-limit-exceeded',
+ archiveLimit: { scope: 'manifest', limitBytes: 16 * 1024 * 1024, observedBytes: expect.any(Number) } });
expect(await sha256File(join(c.path, 'tabs.txt'))).toBe(original);
expect(await registered(c.path)).toBe(true);
expect(await lockText(c.path)).toBe(c.release.lockReason);
@@ -1117,31 +1175,57 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
});
- it('refuses file-count overflow before preview, reviewed retirement or unattended archive publication', async () => {
- const c = await reviewedCheckout('file-count-overflow', { normalMerge: true });
+ // Each case includes a failed archive, cleanup, complete retry and repeat request.
+ // At d200ec77d2, measured 16.9–20.9 seconds; the many-file restore took 20.2 seconds.
+ it.each([
+ { mode: 'cancel', phase: 'recovery refs' }, { mode: 'time', phase: 'recovery refs' },
+ { mode: 'cancel', phase: 'bundle' }, { mode: 'time', phase: 'bundle' },
+ ])('preserves originals and can restart after $mode interrupts $phase', async ({ mode, phase }) => {
+ const c = await reviewedCheckout('bounded-interruption', { normalMerge: true });
const prepared = await c.prepare();
expect(prepared.ok).toBe(true);
- await writeFile(join(c.path, '.gitignore'), 'ignored.txt\nlinked\nprivate-files/\n');
- const directory = join(c.path, 'private-files');
- await mkdir(directory);
- // Content alone stays below 1000; its private Git administration crosses the shared limit.
- const files = Array.from({ length: 995 }, (_, i) => join(directory, `item-${i}`));
- await Promise.all(files.map(file => writeFile(file, 'preserve every tiny file\n')));
- const hashes = await Promise.all(files.map(sha256File));
const before = await getBranchReconcileOutcome('app-1');
- const refusal = { ok: false, reason: 'retirement-archive-file-limit-exceeded' };
- expect(await c.prepare()).toEqual(refusal);
- expect(await c.confirm(prepared.review)).toEqual(refusal);
- expect(await retireInventoriedCheckout({ appId: 'app-1', release: c.release }, {
- ...c.opts, settleMergedReviewObligation: true,
- })).toEqual(refusal);
- expect(await Promise.all(files.map(sha256File))).toEqual(hashes);
+ const controller = new AbortController();
+ let clock;
+ const interrupt = () => {
+ if (mode === 'cancel') controller.abort();
+ else clock = vi.spyOn(performance, 'now').mockReturnValue(performance.now() + 11 * 60 * 1000);
+ };
+ let recoveryRefs = 0;
+ let bundles = 0;
+ injected.onArchiveRef = () => {
+ if (++recoveryRefs === 1 && phase === 'recovery refs') interrupt();
+ };
+ injected.onBundle = () => {
+ bundles++;
+ if (phase === 'bundle') interrupt();
+ };
+ try {
+ const result = await c.confirm(prepared.review, { signal: controller.signal });
+ expect(result).toMatchObject({ ok: false, reason: mode === 'cancel'
+ ? 'retirement-archive-cancelled' : 'retirement-archive-work-limit-exceeded' });
+ if (mode === 'time') expect(result.archiveLimit).toMatchObject({ kind: 'time', limitMs: 600000,
+ observedMs: expect.any(Number) });
+ } finally { clock?.mockRestore(); }
+ if (phase === 'recovery refs') {
+ expect(recoveryRefs).toBe(1);
+ expect(bundles).toBe(0);
+ } else expect(bundles).toBe(1);
+ expect(await readFile(join(c.path, 'ignored.txt'), 'utf8')).toBe('ignored work\n');
expect(await registered(c.path)).toBe(true);
expect(await lockText(c.path)).toBe(c.release.lockReason);
expect((await execGit(['rev-parse', c.release.branch], repo)).stdout.trim()).toBe(c.release.head);
+ expect((await execGit(['for-each-ref', '--format=%(refname)', 'refs/portos/archive/'], repo)).stdout.trim()).toBe('');
expect(await archives()).toEqual([]);
expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
- });
+ // A new attempt takes fresh snapshots; no partial checkpoint grants removal.
+ injected.onArchiveRef = null;
+ injected.onBundle = null;
+ expect(await c.confirm(prepared.review)).toMatchObject({ ok: true, branchDeleted: true });
+ const repeated = await c.confirm(prepared.review);
+ expect(repeated.ok).toBe(false);
+ expect((await archives()).length).toBe(1);
+ }, 30_000);
it('refuses combined content and administration bytes before preview or teardown while each snapshot fits', async () => {
const c = await reviewedCheckout('combined-byte-limit', { normalMerge: true });
@@ -1162,7 +1246,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
}
const hashes = await Promise.all(files.map(sha256File));
const before = await getBranchReconcileOutcome('app-1');
- const refusal = { ok: false, reason: 'retirement-archive-limit-exceeded', archiveLimit: {
+ const refusal = { ok: false, reason: 'retirement-archive-limit-exceeded', nextAction: expect.any(String), archiveLimit: {
scope: 'combined', kind: 'total', limitBytes: 250 * 1024 * 1024, observedBytes: expect.any(Number),
} };
const preview = await c.prepare();
@@ -1181,19 +1265,23 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
});
- describe('near-boundary file-count preservation', () => {
+ describe('many-file resource-bounded preservation', () => {
let c;
let createdAt;
let prepared;
let retired;
- // Bound fixture preparation, retirement and independent proof separately;
- // none of these real-I/O phases may borrow another phase's 30-second budget.
+ // Retain main's separate fixture/retirement/proof phases and their existing
+ // 30-second budgets while exercising more than 1,000 files in both snapshots.
beforeEach(async () => {
c = await reviewedCheckout('file-count-admitted', { normalMerge: true });
await writeFile(join(c.path, '.gitignore'), 'ignored.txt\nlinked\nprivate-files/\n');
const directory = join(c.path, 'private-files');
await mkdir(directory);
- await Promise.all(Array.from({ length: 980 }, (_, i) => writeFile(join(directory, `item-${i}`), 'retained ignored bytes\n')));
+ await Promise.all(Array.from({ length: 1050 }, (_, i) => writeFile(join(directory, `item-${i}`), 'retained ignored bytes\n')));
+ if (process.platform !== 'win32') await chmod(join(directory, 'item-1049'), 0o755);
+ const privateDir = join(c.admin, 'private-files');
+ await mkdir(privateDir);
+ await Promise.all(Array.from({ length: 60 }, (_, i) => writeFile(join(privateDir, `item-${i}`), 'private recovery bytes\n')));
createdAt = new Date().toISOString();
prepared = await c.prepare();
expect(prepared.ok).toBe(true);
@@ -1204,20 +1292,55 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(retired).toMatchObject({ ok: true, branchDeleted: true });
});
- it('admits an archive that the missing-checkout verifier can independently recover', async () => {
+ it('retires and independently restores more than 1000 content and private Git files under the resource contract', async () => {
const manifest = JSON.parse(await readFile(join(retired.archiveDir, 'manifest.json'), 'utf8'));
const capturedCount = manifest.captured.files.length + manifest.administration.files.length;
- expect(capturedCount).toBeGreaterThanOrEqual(990);
- expect(capturedCount).toBeLessThanOrEqual(1000);
+ expect(capturedCount).toBeGreaterThan(1100);
+ expect(manifest.resourceContract).toBe(1);
+ expect(await readFile(join(retired.archiveDir, 'files/private-files/item-1049'), 'utf8')).toBe('retained ignored bytes\n');
+ expect(await readFile(join(retired.archiveDir, 'administration/gitdir/private-files/item-59'), 'utf8')).toBe('private recovery bytes\n');
const before = await getBranchReconcileOutcome('app-1');
const proof = await findMissingCheckoutPreservation({ repoPath: repo, release: { ...c.release, createdAt } }, { cosDir });
expect(proof, `Standalone archive proof failures: ${JSON.stringify(injected.proofFailures)}`)
.toMatchObject({ archiveDir: retired.archiveDir, evidenceDigest: expect.stringMatching(/^[a-f0-9]{64}$/) });
expect(await proof.recheck()).toBe(true);
expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
- });
+ const restore = join(scratch, 'independent-restore');
+ await mkdir(restore);
+ await execGit(['init'], restore);
+ await execGit(['fetch', join(retired.archiveDir, 'commits.bundle'), 'HEAD'], restore);
+ await execGit(['checkout', '--detach', 'FETCH_HEAD'], restore);
+ await cp(join(retired.archiveDir, 'files'), restore, { recursive: true });
+ expect(await readFile(join(restore, 'private-files/item-1049'), 'utf8')).toBe('retained ignored bytes\n');
+ if (process.platform !== 'win32') expect((await stat(join(restore, 'private-files/item-1049'))).mode & 0o777).toBe(0o755);
+ const manifestPath = join(retired.archiveDir, 'manifest.json');
+ const original = await readFile(manifestPath, 'utf8');
+ const find = () => findMissingCheckoutPreservation({ repoPath: repo, release: { ...c.release, createdAt } }, { cosDir });
+ // Historical unversioned archives use the same full proof, never a count exemption.
+ delete manifest.resourceContract;
+ await writeFile(manifestPath, JSON.stringify(manifest));
+ expect(await find()).toMatchObject({ archiveDir: retired.archiveDir });
+ for (const mutate of [
+ saved => { saved.resourceContract = 999; },
+ saved => { saved.captured.files[0].bytes = -1; },
+ saved => { saved.captured.files.push(saved.captured.files[0]); },
+ saved => { saved.captured.files[0].path = '../administration/gitdir/HEAD'; },
+ saved => { saved.captured.files[0].path = 'x'.repeat(16 * 1024 * 1024); },
+ ]) {
+ const altered = JSON.parse(original);
+ mutate(altered);
+ await writeFile(manifestPath, JSON.stringify(altered));
+ expect(await find()).toBe(null);
+ }
+ await writeFile(manifestPath, original);
+ expect(await find()).toMatchObject({ archiveDir: retired.archiveDir });
+ await writeFile(join(retired.archiveDir, 'administration/gitdir/private-files/item-59'), 'changed private bytes');
+ expect(await find()).toBe(null);
+ expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
+ }, 30_000);
});
+
it.each([
{ scope: 'content', kind: 'file', count: 1, bytes: 25 * 1024 * 1024 + 1 },
{ scope: 'content', kind: 'total', count: 11, bytes: 24 * 1024 * 1024 },
@@ -1236,7 +1359,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
const hashes = await Promise.all(files.map(sha256File));
const before = await getBranchReconcileOutcome('app-1');
const result = await c.prepare();
- expect(result).toEqual({ ok: false, reason: 'retirement-archive-limit-exceeded', archiveLimit: {
+ expect(result).toEqual({ ok: false, reason: 'retirement-archive-limit-exceeded', nextAction: expect.any(String), archiveLimit: {
scope, kind, limitBytes: (kind === 'file' ? 25 : 250) * 1024 * 1024, observedBytes: expect.any(Number),
} });
expect(Number.isSafeInteger(result.archiveLimit.observedBytes)).toBe(true);
@@ -1272,7 +1395,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
const before = await getBranchReconcileOutcome('app-1');
const result = mode === 'reviewed' ? await c.confirm(prepared.review)
: await retireInventoriedCheckout({ appId: 'app-1', release: c.release }, { ...c.opts, settleMergedReviewObligation: true });
- expect(result).toEqual({ ok: false, reason: 'retirement-archive-limit-exceeded', archiveLimit: {
+ expect(result).toEqual({ ok: false, reason: 'retirement-archive-limit-exceeded', nextAction: expect.any(String), archiveLimit: {
scope: 'content', kind: 'file', limitBytes: bytes - 1, observedBytes: bytes,
} });
expect(await sha256File(file)).toBe(hash);
@@ -1283,6 +1406,32 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
});
+ it('retains measured capacity and the exact lock when the final refreshed review exceeds its budget', async () => {
+ const c = await reviewedCheckout('final-review-capacity', { normalMerge: true });
+ const prepared = await c.prepare();
+ expect(prepared.ok).toBe(true);
+ const before = await getBranchReconcileOutcome('app-1');
+ const file = join(c.path, 'ignored.txt');
+ const bytes = 25 * 1024 * 1024 + 1;
+ let mutations = 0;
+ let changedHash;
+ const result = await c.confirm(prepared.review, { beforeMutation: async () => {
+ if (++mutations === 2) {
+ await truncate(file, bytes);
+ changedHash = await sha256File(file);
+ }
+ } });
+ expect(result).toMatchObject({ ok: false, reason: 'retirement-archive-limit-exceeded', nextAction: expect.any(String),
+ archiveDir: expect.any(String), archiveLimit: { scope: 'content', kind: 'file', limitBytes: bytes - 1, observedBytes: bytes } });
+ expect(changedHash).toBeTruthy();
+ expect(await sha256File(file)).toBe(changedHash);
+ expect(await registered(c.path)).toBe(true);
+ expect(await lockText(c.path)).toBe(c.release.lockReason);
+ expect((await execGit(['rev-parse', c.release.branch], repo)).stdout.trim()).toBe(c.release.head);
+ expect(await readFile(join(result.archiveDir, 'files/ignored.txt'), 'utf8')).toBe('ignored work\n');
+ expect(await getBranchReconcileOutcome('app-1')).toEqual(before);
+ });
+
it('retires a merged receipt checkout without an inventory grant, preserving ignored bytes and original commits', async () => {
const c = await receiptCheckout('receipt', { gitlink: true });
const result = await c.retireReceipt();
@@ -1406,13 +1555,19 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await readFile(join(result.archiveDir, 'files/ignored.txt'), 'utf8')).toBe('ignored work\n');
});
- it('reviews original changes after an ancestral merged tip is later changed', async () => {
+ it('requires supersession acceptance after an ancestral merged tip is later changed', async () => {
const c = await reviewedCheckout('ancestral', { normalMerge: true, superseded: true });
const prepared = await c.prepare();
expect(prepared.ok).toBe(true);
expect(prepared.review.comparison.disposition).toBe('review-supersession');
expect(prepared.review.comparison.localPatch).toContain('+original feature');
expect(prepared.review.comparison.difference).toContain('+strengthened replacement');
+ expect(await retireInventoriedCheckout({ appId: 'app-1', release: c.release,
+ review: { prUrl: c.forge.prUrl, digest: prepared.review.digest, acceptSuperseded: false } }, c.opts))
+ .toMatchObject({ ok: false, reason: 'retirement-supersession-not-accepted' });
+ expect(await registered(c.path)).toBe(true);
+ expect(await lockText(c.path)).toBe(c.release.lockReason);
+ expect(await archives()).toEqual([]);
});
it('compares pathspec glob filenames literally', async () => {
@@ -1444,9 +1599,6 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
const prepared = await c.prepare();
expect(prepared.ok).toBe(true);
expect(prepared.review.comparison.disposition).toBe(superseded ? 'review-supersession' : 'integrated');
- if (superseded) expect(await retireInventoriedCheckout({ appId: 'app-1', release: c.release,
- review: { prUrl: c.forge.prUrl, digest: prepared.review.digest, acceptSuperseded: false } }, c.opts))
- .toMatchObject({ ok: false, reason: 'retirement-supersession-not-accepted' });
const result = await c.confirm(prepared.review);
expect(result).toMatchObject({ ok: true, branchDeleted: true });
const manifest = JSON.parse(await readFile(join(result.archiveDir, 'manifest.json'), 'utf8'));
@@ -1702,29 +1854,39 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(after.retirementObligations).toEqual(before.retirementObligations);
});
- it.each(['content', 'index', 'administration', 'default', 'pr-head', 'forge', 'policy', 'unreadable-policy', 'submodule', 'inventory'])('refuses changed %s evidence between review and confirmation', async change => {
- const c = await reviewedCheckout('changed-review', { gitlink: true });
- const prepared = await c.prepare();
- expect(prepared.ok).toBe(true);
- if (change === 'content') await writeFile(join(c.path, 'ignored.txt'), 'new evidence');
- if (change === 'index') { await writeFile(join(c.path, 'staged.txt'), 'new index'); await execGit(['add', 'staged.txt'], c.path); }
- if (change === 'administration') await writeFile(join(c.admin, 'portos-review-status'), 'new review');
- if (change === 'default') {
- await writeFile(join(repo, 'later.txt'), 'later default');
- await execGit(['add', 'later.txt'], repo); await execGit(['commit', '-m', 'later default'], repo);
- c.forge.defaultHead = (await execGit(['rev-parse', 'HEAD'], repo)).stdout.trim();
- }
- if (change === 'pr-head') c.forge.prHead = c.forge.defaultHead;
- if (change === 'unreadable-policy') injected.policies = null;
- if (change === 'forge') c.forge.remoteHead = c.release.head;
- if (change === 'policy') injected.policies[0].metadata.prCompletionPolicy = 'leave-open';
- if (change === 'submodule') await writeFile(join(c.path, 'vendor', 'unique.txt'), 'submodule work');
- if (change === 'inventory') injected.schedule.executions = {};
- const result = await c.confirm(prepared.review);
- expect(result.ok).toBe(false);
- expect(await registered(c.release.path)).toBe(true);
- expect(await lockText(c.release.path)).toBe(c.release.lockReason);
- expect(await archives()).toEqual([]);
+ describe.each(['content', 'index', 'administration', 'default', 'pr-head', 'forge', 'policy', 'unreadable-policy', 'submodule', 'inventory'])('changed %s evidence between review and confirmation', change => {
+ let c;
+ let prepared;
+ // Fixture construction, preview and confirmation are distinct real-Git
+ // workflows; each retains the existing 30-second phase budget.
+ beforeEach(async () => {
+ c = await reviewedCheckout('changed-review', { gitlink: true });
+ });
+ beforeEach(async () => {
+ prepared = await c.prepare();
+ expect(prepared.ok).toBe(true);
+ });
+ it('refuses confirmation and retains the checkout, lock and archive state', async () => {
+ if (change === 'content') await writeFile(join(c.path, 'ignored.txt'), 'new evidence');
+ if (change === 'index') { await writeFile(join(c.path, 'staged.txt'), 'new index'); await execGit(['add', 'staged.txt'], c.path); }
+ if (change === 'administration') await writeFile(join(c.admin, 'portos-review-status'), 'new review');
+ if (change === 'default') {
+ await writeFile(join(repo, 'later.txt'), 'later default');
+ await execGit(['add', 'later.txt'], repo); await execGit(['commit', '-m', 'later default'], repo);
+ c.forge.defaultHead = (await execGit(['rev-parse', 'HEAD'], repo)).stdout.trim();
+ }
+ if (change === 'pr-head') c.forge.prHead = c.forge.defaultHead;
+ if (change === 'unreadable-policy') injected.policies = null;
+ if (change === 'forge') c.forge.remoteHead = c.release.head;
+ if (change === 'policy') injected.policies[0].metadata.prCompletionPolicy = 'leave-open';
+ if (change === 'submodule') await writeFile(join(c.path, 'vendor', 'unique.txt'), 'submodule work');
+ if (change === 'inventory') injected.schedule.executions = {};
+ const result = await c.confirm(prepared.review);
+ expect(result.ok).toBe(false);
+ expect(await registered(c.release.path)).toBe(true);
+ expect(await lockText(c.release.path)).toBe(c.release.lockReason);
+ expect(await archives()).toEqual([]);
+ });
});
it.each(['running', 'paused'])('refuses a %s owner that arrives after preparation', async status => {
diff --git a/server/services/worktreeReap.test.js b/server/services/worktreeReap.test.js
index 4766fff3fe..98b70a2be2 100644
--- a/server/services/worktreeReap.test.js
+++ b/server/services/worktreeReap.test.js
@@ -801,7 +801,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('reapMergedWorktrees', () => {
// list and drop it, so a clean merged checkout was archived and removed.
// The disposable sibling is the same shape on an unprotected name, so a
// sweep that protected every branch would fail here too.
- it('holds a merged + clean gh-pages worktree in both reapers', async () => {
+ it('holds a merged + clean gh-pages worktree in local reaping', async () => {
const pagesPath = await addWorktree(dir, 'pages', 'gh-pages');
const disposablePath = await addWorktree(dir, 'disposable', 'disposable-br');
await execGit(['merge', '--no-ff', 'gh-pages', '--no-edit'], dir);
@@ -813,7 +813,11 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('reapMergedWorktrees', () => {
expect(existsSync(pagesPath)).toBe(true);
expect(reaped.reaped.map(r => r.branch)).toContain('disposable-br');
expect(existsSync(disposablePath)).toBe(false);
+ });
+ // Keep the two public cleanup boundaries independently bounded without
+ // combining both real-Git workflows under one test's 30-second budget.
+ it('holds a merged + clean gh-pages worktree in external cleanup', async () => {
// cleanupExternalRepoWorktrees only admits agent-* dirs under the shared
// worktrees root, and that root must be the temp one both PATHS see.
expect(PATHS.worktrees).toContain('portos-reap-archives-');