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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { matchingRetirementReceipts } from '../lib/reconcileRetirementEvidence.js';
import { readRetirementCheckoutIdentity } from '../lib/retirementCheckoutObservation.js';
/**
* Operator-scoped retirement of a merged checkout that branch reconciliation
* reported but cannot retire on its own (#12002): one outside the managed
* worktree roots, or one behind a `git worktree lock`.
*
* Authority is a scoped release, never an inference. The operator names the
* exact inventory row they saw — checkout path, HEAD, branch and lock state —
* and that release only applies while a fresh read of the repository still
* matches it. A lock's age, an absent process or its prose never establish
* release: a changed lock, HEAD or branch is an ownership change and refuses.
*
* A merged, clean checkout is removed in place. Dirty, unmerged, protected,
* and live-owner checkouts stay where they are. Retirement does not copy the
* checkout, its ignored files, or its commit history.
*/
import { findGoneInventoryRows } from './branchReconcileInventoryPrune.js';
import { realpathSync, constants } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { lstat, stat, realpath, 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, 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';
import { backupSlug } from './supersededBackup.js';
import { listWorktrees, forceRemoveWorktreeDir, deleteCompletedLocalBranch, classifyWorktreeDirt } from './worktreeManager.js';
import { getDefaultBranch, hasBranchMergeEvidence } from './git.js';
import { withClaimOwnershipLock, readClaimOwnershipAgents, retireWithUnlockedArchive } from './cosClaimOwnership.js';
/** Unlocked recheck between ownership sections. Does not copy the checkout. */
export async function releaseCheckoutWithoutArchive(_context, prepare) {
return prepare();
}
export const heldCheckoutArchiveRoot = (cosDir = PATHS.cos) => join(cosDir, 'held-checkout-archives');
const evidenceHash = value => createHash('sha256').update(value).digest('hex');
const MAX_MANIFEST_BYTES = 16 * 1024 * 1024;
function checkArchiveBudget(content, administration) {
// Creation and recovery share one byte budget across both snapshots.
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. */
async function archiveFile(root, path) {
const rel = relative(root, path);
if (!rel || isAbsolute(rel) || rel.split(sep).includes('..')) throw new Error('archive-path-invalid');
const parts = rel.split(sep);
let current = root;
if (!(await lstat(root)).isDirectory()) throw new Error('archive-directory-invalid');
for (const [index, part] of parts.entries()) {
current = join(current, part);
const info = await lstat(current);
if (info.isSymbolicLink() || (index < parts.length - 1 ? !info.isDirectory() : !info.isFile())) throw new Error('archive-file-invalid');
}
return path;
}
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();
work.read?.(chunk.length);
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'));
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, 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 => {
const info = await lstat(path, { bigint: true });
if (!info.isFile()) throw new Error('archive-file-invalid');
return [info.dev, info.ino, info.size, info.mtimeNs, info.ctimeNs].map(String).join(':');
};
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 archiveHash(path, work) !== file.sha256) throw new Error('archive-file-changed');
}
}
const administrationFingerprint = evidenceHash(JSON.stringify({
files: saved.administration.files.filter(file => file.path !== 'gitdir/locked'), symlinks: saved.administration.symlinks,
}));
if (administrationFingerprint !== saved.administration.fingerprint) throw new Error('archive-administration-changed');
for (const name of ['index', 'worktree']) {
if (typeof captured[`${name}Diff`] !== 'boolean') throw new Error('archive-patch-proof-invalid');
if (!captured[`${name}Diff`]) continue;
const expected = saved.patchHashes?.[name];
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 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);
// A thin bundle verifies against the current repository but is not a complete
// restore point. Inspect only its bounded textual header, never fetch it.
const handle = await open(bundle, 'r');
let header;
try {
const buffer = Buffer.alloc(256 * 1024);
const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
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 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.
const scratch = await mkdtemp(join(tmpdir(), 'portos-retirement-proof-'));
// Git's null path also works on Windows; Node's device-namespace spelling
// (\\.\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) => {
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 (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 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.
const entries = ['-c', 'core.quotePath=true', 'ls-files', '--stage'];
const expected = await prove(entries, 'archived-index');
await prove(['read-tree', release.head]);
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 (error) {
if (archiveLimitRefusal(error)) throw error;
throw new Error('archive-index-reconstruction-failed');
}
} finally { await rmGuarded(scratch, { recursive: true, force: true }); }
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;
};
if (!await recheck()) throw new Error('archive-changed-during-verification');
return { repoPath, archiveDir: dir, archivedAt: saved.archivedAt, evidenceDigest: evidenceHash(digest + bundleHash), kind: 'held', recheck };
}
async function historicalCheckoutAbsent(release, trees) {
const present = await lstat(release.path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
return !present && trees.length > 0 && !trees.some(tree => tree.path === release.path || (release.branch && shortBranch(tree.branch) === release.branch));
}
/** Read existing no-archive service receipts, scoped to the original repository
* and physical checkout generation. Never infer removal from absence alone. */
async function completedServiceRetirement(repoPath, release) {
if (!/^[a-f0-9]{64}$/.test(release.checkoutIdentity || '')) return null;
const [{ loadSchedule }, { getAppById }] = await Promise.all([
import('./taskScheduleStore.js'), import('./apps.js'),
]);
const schedule = await loadSchedule();
const root = await realpath(repoPath).catch(() => null);
if (!root) return null;
const found = new Map();
for (const [appId, record] of Object.entries(schedule.executions?.['task:branch-reconcile']?.perApp || {})) {
const receipts = matchingRetirementReceipts(record.branchReconcileOutcome, release).filter(row => row.archiveDir == null
&& row.checkoutIdentity === release.checkoutIdentity && Date.parse(row.retiredAt) >= Date.parse(release.createdAt));
if (!receipts.length) continue;
const app = await getAppById(appId);
if (!app?.repoPath || await realpath(app.repoPath).catch(() => null) !== root) continue;
for (const row of receipts) {
const key = JSON.stringify([row.branch, row.path, row.head, row.checkoutIdentity, row.retiredAt, row.branchDeleted]);
found.set(key, row);
}
}
if (found.size !== 1) return null;
const [key, receipt] = [...found][0];
return { kind: 'service-retirement-receipt', archiveDir: null, receipt,
evidenceDigest: createHash('sha256').update(key).digest('hex') };
}
/** Completion audits have a server-captured checkout generation, but may never
* have entered the scheduled retirement queue. Reuse its archive verifier
* without creating an obligation or inventing a branch-deletion receipt.
*/
export async function findMissingCheckoutPreservation({ repoPath, release }, opts = {}) {
if (!Number.isFinite(Date.parse(release?.createdAt)) || Date.parse(release.createdAt) > Date.now()
|| !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(release?.head || '')) return null;
const absent = async () => {
const trees = await listWorktrees(repoPath);
const ref = await execGit(['rev-parse', '--verify', '--quiet', `refs/heads/${release.branch}`], repoPath, { ignoreExitCode: true });
return ref.exitCode === 1 && await historicalCheckoutAbsent(release, trees);
};
if (!await absent()) return null;
const receipt = await completedServiceRetirement(repoPath, release).catch(() => null);
if (receipt) return { ...receipt, recheck: async () => {
if (!await absent()) return false;
const fresh = await completedServiceRetirement(repoPath, release).catch(() => null);
return fresh?.evidenceDigest === receipt.evidenceDigest;
} };
const root = heldCheckoutArchiveRoot(opts.cosDir);
const info = await lstat(root).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
if (!info?.isDirectory()) return null;
const entries = await readdir(root, { withFileTypes: true });
if (entries.length > 1000) return null;
let selected = null;
for (const entry of entries) {
if (!entry.isDirectory()) continue;
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;
selected = proof;
}
if (!selected) return null;
const proof = selected;
return { ...proof, recheck: async () => await absent() && await proof.recheck() };
}
const RECOVERY_DETAIL_LIMIT = 20;
const DISCOVERY_BYTE_LIMIT = 64 * 1024 * 1024;
const archiveIdentityKey = row => row && [row.repoPath, row.path, row.head].every(value => typeof value === 'string')
&& (typeof row.branch === 'string' || row.branch === null)
? JSON.stringify([row.repoPath, row.branch, row.path, row.head]) : null;
/** Metadata only selects work; every selected archive is independently verified. */
async function discoverRecoveryArchives(cosDir, signal) {
const roots = [heldCheckoutArchiveRoot(cosDir), join(cosDir || PATHS.cos, 'initialized-checkout-retirements')];
const index = new Map();
const byDirectory = new Map();
const coverage = { entriesRead: 0, candidates: 0, indexed: 0, metadataBytes: 0, missingRoots: 0,
errors: 0, details: [], detailsOmitted: 0, complete: true, truncated: false };
const diagnose = (archiveDir, error) => {
coverage.complete = false;
coverage.errors++;
const refusal = archiveLimitRefusal(error);
const detail = { archiveDir, ...(refusal || { reason: /^[a-z][a-z-]+$/.test(error.message) ? error.message : 'archive-discovery-unavailable' }) };
if (coverage.details.length < RECOVERY_DETAIL_LIMIT) coverage.details.push(detail);
else coverage.detailsOmitted++;
};
const work = { ...archiveWork(signal), read: bytes => {
// Account before parsing, including partial, malformed and oversized reads.
coverage.metadataBytes += bytes;
if (coverage.metadataBytes > DISCOVERY_BYTE_LIMIT) throw new Error('archive-discovery-budget-exceeded');
} };
for (const root of roots) {
try {
const info = await lstat(root).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
if (!info) { coverage.missingRoots++; continue; }
if (!info.isDirectory()) throw new Error('archive-directory-invalid');
const directory = await opendir(root);
for await (const entry of directory) {
if (coverage.entriesRead >= 1000 || coverage.metadataBytes >= DISCOVERY_BYTE_LIMIT) {
coverage.truncated = true;
diagnose(root, new Error('archive-discovery-budget-exceeded'));
break;
}
coverage.entriesRead++;
if (!entry.isDirectory()) continue;
const candidate = { dir: join(root, entry.name), kind: root === roots[0] ? 'held' : 'initialized' };
coverage.candidates++;
byDirectory.set(candidate.dir, candidate);
try {
const { manifest } = await archiveManifest(candidate.dir, work);
const identity = candidate.kind === 'held' ? manifest : { repoPath: manifest.facts?.repoPath, ...manifest.facts?.release };
const key = archiveIdentityKey(identity);
if (!key) throw new Error('archive-identity-unreadable');
if (!index.has(key)) index.set(key, []);
index.get(key).push(candidate);
coverage.indexed++;
} catch (error) {
diagnose(candidate.dir, error);
}
}
} catch (error) { diagnose(root, error); }
}
return { index, byDirectory, coverage };
}
/** Read existing archives only. Verification stays outside both writer locks;
* the final ownership/absence recheck and schedule compare-and-set are fenced.
*/
export async function recoverMissingCheckoutPreservations({ appId, repoPath, outcome }, opts = {}) {
const expected = structuredClone(outcome);
const obligations = unresolvedRetirements(expected);
if (!obligations.length) return outcome;
const trees = await listWorktrees(repoPath).catch(() => null);
if (!trees?.length) return outcome;
const { index, byDirectory, coverage } = await discoverRecoveryArchives(opts.cosDir, opts.signal);
const observations = [];
const evidenceFences = [];
let details = 0;
const addEvidence = (row, detail) => {
if (details < RECOVERY_DETAIL_LIMIT) { row.evidence.push(detail); details++; }
else row.coverage.detailsOmitted++;
};
try {
for (const release of obligations) {
if (!await historicalCheckoutAbsent(release, trees).catch(() => false)) continue;
let proof = null;
let verified = 0;
const matching = index.get(archiveIdentityKey({ ...release, repoPath })) || [];
const scopedCandidates = Object.hasOwn(release, 'preservationReceipt')
? [byDirectory.get(release.preservationReceipt?.archiveDir)].filter(candidate => candidate && release.preservationReceipt?.status === 'preserved'
&& JSON.stringify(release.preservationReceipt.incarnation) === JSON.stringify(release.checkoutIncarnation)
&& candidate.dir === release.preservationReceipt.archiveDir) : matching;
const row = { release, proof: null, evidence: [], coverage: { matching: scopedCandidates.length,
unrelated: coverage.indexed - matching.length, attempted: 0, detailsOmitted: 0 },
reason: !coverage.complete ? 'archive-discovery-incomplete' : coverage.candidates ? 'archive-evidence-unverified' : 'archive-evidence-missing', nextAction: historicalNextAction };
for (const candidate of scopedCandidates) {
row.coverage.attempted++;
try {
const verifiedProof = 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 (verifiedProof.releaseFence) evidenceFences.push(verifiedProof.releaseFence);
verified++;
proof = verifiedProof;
addEvidence(row, { archiveDir: candidate.dir, reason: 'preservation-verified' });
} catch (error) {
const refusal = archiveLimitRefusal(error);
addEvidence(row, { 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' }) });
}
}
row.proof = verified === 1 && (coverage.complete || Object.hasOwn(release, 'preservationReceipt')) ? proof : null;
if (verified > 1) row.reason = 'archive-preservation-ambiguous';
observations.push(row);
}
if (!observations.length) return outcome;
const { recordRecoveredCheckoutPreservations } = await import('./taskSchedule.js');
return await withClaimOwnershipLock(() => recordRecoveredCheckoutPreservations(appId, expected, observations, async () => {
const { getAppById } = await import('./apps.js');
if ((await getAppById(appId))?.repoPath !== repoPath) return false;
const currentTrees = await listWorktrees(repoPath);
for (const row of observations) {
if (!await historicalCheckoutAbsent(row.release, currentTrees)) return false;
if (row.proof?.recheck && !await row.proof.recheck().catch(() => false)) {
addEvidence(row, { archiveDir: row.proof.archiveDir, reason: 'archive-changed-during-verification' });
row.proof = null;
row.reason = 'archive-changed-during-verification';
}
}
return true;
}, coverage));
} finally {
for (const releaseFence of evidenceFences) await releaseFence();
}
}
// Refuse rather than archive a subset: a partial archive followed by removal
// would delete the rest. Larger than the superseded reap's caps because this is
// an explicit operator action, but still bounded so a build tree cannot fill
// the disk.
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;
const kind = fileBytes > MAX_FILE_BYTES ? 'file' : 'total';
throw Object.assign(new Error('retirement-archive-limit-exceeded'), { archiveLimit: {
scope, kind, limitBytes: kind === 'file' ? MAX_FILE_BYTES : MAX_TOTAL_BYTES,
observedBytes: Math.min(kind === 'file' ? fileBytes : totalBytes, Number.MAX_SAFE_INTEGER),
} });
}
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 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, 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()) {
const link = { path: rel, target: archiveText(await readlink(source, { encoding: 'buffer' })) };
work.add(link);
symlinks.push(link);
return;
}
if (info.isDirectory()) {
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);
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');
if (!missingRoot) {
if (!(await lstat(pointer)).isFile()) throw new Error('checkout git indirection is not a file');
await visit(pointer, 'git-indirection');
}
const fingerprint = createHash('sha256').update(JSON.stringify({
files: files.filter(file => file.path !== 'gitdir/locked').map(({ source: _source, ...file }) => file), symlinks,
})).digest('hex');
return { files, symlinks, fingerprint };
}
async function retirementPolicy(repoPath, branch, opts, reviewIdentity = {}) {
const { readBranchCompletionPolicies, reviewedRetirementPolicy, mergedReceiptRetirementPolicy } = await import('./branchCompletionPolicy.js');
const policies = await (opts.readPolicies || (() => readBranchCompletionPolicies({ repairIndex: false })))().catch(() => null);
if (opts.mergedReceipt) return mergedReceiptRetirementPolicy({ repoPath, branch, agents: policies,
tip: opts.mergedReceipt.expectedHeadSha });
const checkoutIdentities = {};
if (reviewIdentity.verifiedPrHead === reviewIdentity.tip && reviewIdentity.tip && Array.isArray(policies)) {
const paths = new Set([reviewIdentity.checkoutPath, repoPath]);
for (const agent of policies) {
const meta = agent?.metadata || {};
const scopes = [meta.worktreeBranch, meta.jiraBranch, meta.claimBranch, meta.branchCompletionPolicy?.branch,
...(Array.isArray(meta.claimBranches) ? meta.claimBranches : []),
...(Array.isArray(meta.claimReleasedBranches) ? meta.claimReleasedBranches : [])];
if (scopes.includes(branch)) {
if (isAbsolute(meta.workspacePath || '')) paths.add(meta.workspacePath);
// Receipt capture canonicalizes filesystem names. Windows short names
// and other existing aliases need the same server-observed identity
// comparison as the current checkout, never textual guessing.
for (const row of Array.isArray(meta.completedCheckouts) ? meta.completedCheckouts : []) {
if (row?.version !== 2 || row.branch !== branch) continue;
for (const path of [row.repoPath, row.path]) if (isAbsolute(path || '')) paths.add(path);
}
}
}
// A failed identity read or excessive history cannot prove distinctness.
// Missing paths resolve through their existing canonical ancestor, the same
// identity rule used to locate missing checkout administration below.
if (paths.size <= 1000) {
const entries = [...paths];
for (let offset = 0; offset < entries.length; offset += 25) {
await Promise.all(entries.slice(offset, offset + 25).map(async path => {
const facts = await missingPathIdentity(path).catch(() => null);
if (facts) checkoutIdentities[path] = JSON.stringify({ dev: facts.dev, ino: facts.ino, tail: facts.tail });
}));
}
}
}
const initial = reviewedRetirementPolicy({ repoPath, branch, agents: policies, ...reviewIdentity, checkoutIdentities });
if (initial.reason !== 'retirement-policy-not-legacy-completed' || !reviewIdentity.retirementForge) return initial;
let identity = reviewIdentity;
if (!identity.checkoutIncarnation) {
const { readCompletedCheckoutIdentity } = await import('./completedCheckoutEvidence.js');
// The caller has already checked the released lock and registration. This
// fact-read grants no unlock authority; ordinary matching policies avoid it.
const generation = await readCompletedCheckoutIdentity({ repoPath, branch, path: identity.checkoutPath,
head: identity.tip, allowLocked: true }).catch(() => null);
if (!generation) return initial;
identity = { ...identity, checkoutIncarnation: generation.incarnation };
}
const { readCheckoutDeliveryContinuations } = await import('./checkoutDeliveryContinuation.js');
const deliveryContinuations = await readCheckoutDeliveryContinuations({ repoPath, branch, ...identity }, policies, opts);
return deliveryContinuations.length
? reviewedRetirementPolicy({ repoPath, branch, agents: policies, ...identity, checkoutIdentities, deliveryContinuations }) : initial;
}
const policyReviewIdentity = (release, prUrl, forge) => ({
checkoutPath: release.path, tip: release.head, prUrl,
verifiedPrHead: forge?.prUrl === prUrl ? forge.prHead : null,
});
async function integratedPolicyReviewIdentity(repoPath, release, prUrl, forge, archivedIncarnation = null) {
if (!forge || !await execGit(['cat-file', '-e', `${forge.defaultHead}^{commit}`], repoPath).then(() => true, () => false)) return null;
// Only the post-removal caller supplies a generation already bound into the
// verified archive/review. A recreated path is never an absent original.
const absent = archivedIncarnation && await lstat(release.path).then(() => false, error => error.code === 'ENOENT');
const checkoutIncarnation = absent ? archivedIncarnation : null;
return { ...policyReviewIdentity(release, prUrl, forge), retirementForge: forge,
...(checkoutIncarnation && { checkoutIncarnation }),
// Older pinned claims missed completion capture. Fresh inclusion of every
// commit settles cleanup-only outcomes without manufacturing receipts.
integratedCleanupHead: forge?.prHead === release.head && await isAncestor(repoPath, release.head, forge.defaultHead)
? forge.defaultHead : null };
}
const reviewForgeOptions = (release, kind, opts) => ({ forgeAccount: opts.forgeAccount,
...(!release.branch && { exactAliasHead: release.head }),
...(kind === 'source-supersession' && { sourceSupersessionHead: release.head }) });
async function matchReviewTarget({ repoPath, release, kind, unlocked = false }, opts) {
if (kind && kind !== 'source-supersession') return { ok: false, reason: 'retirement-review-kind-unavailable' };
if (kind && !release.branch) return { ok: false, reason: 'retirement-source-branch-required' };
if (PROTECTED_BRANCHES.includes(release.branch)) return { ok: false, reason: 'protected-branch' };
const matched = await matchRelease(repoPath, unlocked ? { ...release, locked: false, lockReason: null } : release);
if (!matched.tree) return { ok: false, reason: matched.reason };
const owner = await ownerReason({ repoPath, tree: matched.tree, branch: release.branch,
readAgents: opts.readAgents || readClaimOwnershipAgents, reviewed: true });
if (owner) return { ok: false, reason: owner };
return { ok: true, tree: matched.tree };
}
async function readCheckoutReviewPrerequisites(input, opts) {
const { repoPath, release, prUrl, kind } = input;
const matched = await matchReviewTarget(input, opts);
if (!matched.ok) return matched;
const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
const forge = await (opts.readForge || readRetirementForgeEvidence)(repoPath, release.branch, prUrl, reviewForgeOptions(release, kind, opts))
.catch(error => ({ error }));
if (forge?.error) return { ok: false, reason: /^retirement-[a-z-]+$/.test(forge.error.message) ? forge.error.message : 'retirement-forge-unavailable' };
if (kind && forge?.sourceSupersessionHead !== release.head) return { ok: false, reason: 'retirement-source-head-unverified' };
if (!release.branch && (forge?.prHead !== release.head || !forge.publishedBranch)) return { ok: false, reason: 'retirement-detached-head-unverified' };
const policyBranch = release.branch || forge.publishedBranch;
const namedOwner = !release.branch && await ownerReason({ repoPath, tree: matched.tree, branch: policyBranch,
readAgents: opts.readAgents || readClaimOwnershipAgents, reviewed: true });
if (namedOwner) return { ok: false, reason: namedOwner };
const identity = await integratedPolicyReviewIdentity(repoPath, release, prUrl, forge);
if (!identity) return { ok: false, reason: 'retirement-local-objects-missing' };
if (!release.branch) {
identity.detachedCheckoutIdentity = await readRetirementCheckoutIdentity(release.path);
if (!identity.detachedCheckoutIdentity) return { ok: false, reason: 'checkout-identity-changed' };
}
const policy = await retirementPolicy(repoPath, policyBranch, opts, identity);
if (policy.reason) return { ok: false, reason: policy.reason };
return { ok: true, tree: matched.tree, forge, policy };
}
async function buildCurrentCheckoutReview({ repoPath, release, prUrl, kind }, { tree, forge, policy }, opts) {
const { buildCheckoutRetirementReview } = await import('./heldCheckoutReview.js');
return archiveSnapshots(tree, repoPath, null, archiveWork(opts.signal))
.then(([content, administration]) => buildCheckoutRetirementReview({ repoPath, release, prUrl, kind,
contentFingerprint: content.fingerprint, administrationFingerprint: administration.fingerprint, policy }, { ...opts, readForge: async () => forge }))
.then(review => ({ ok: true, review }), error => archiveLimitRefusal(error) || ({ ok: false,
reason: /^retirement-[a-z-]+$/.test(error.message) ? error.message : 'retirement-local-evidence-unavailable' }));
}
async function reviewCurrentCheckout(input, opts = {}) {
const prerequisites = await readCheckoutReviewPrerequisites(input, opts);
return prerequisites.ok ? buildCurrentCheckoutReview(input, prerequisites, opts) : prerequisites;
}
async function previewCheckoutIdentity(path) {
const pointer = await readRetirementCheckoutIdentity(path);
if (!pointer) return null;
const gitdir = await realpath((await execGit(['rev-parse', '--absolute-git-dir'], path)).stdout.trim());
const info = await lstat(gitdir, { bigint: true });
if (!info.isDirectory() || await readRetirementCheckoutIdentity(path) !== pointer) return null;
return JSON.stringify([pointer, gitdir, String(info.dev), String(info.ino), String(info.birthtimeNs)]);
}
/** Preview is evidence, never a retirement reservation or mutation grant. Keep
* forge calls, hashing and diff construction outside the process-wide queue. */
async function previewCurrentCheckout(input, opts) {
const matched = await withClaimOwnershipLock(() => matchReviewTarget(input, opts));
if (!matched.ok) return matched;
const { repoPath, release, prUrl, kind } = input;
const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
const forge = await (opts.readForge || readRetirementForgeEvidence)(repoPath, release.branch, prUrl,
reviewForgeOptions(release, kind, opts)).catch(error => ({ error }));
const localOptions = { ...opts, readForge: async () => forge };
const captured = await withClaimOwnershipLock(async () => {
const prerequisites = await readCheckoutReviewPrerequisites(input, localOptions);
if (!prerequisites.ok) return prerequisites;
const identity = await previewCheckoutIdentity(release.path).catch(() => null);
return identity && (!release.checkoutIdentity || await readRetirementCheckoutIdentity(release.path) === release.checkoutIdentity)
? { ...prerequisites, identity }
: { ok: false, reason: 'checkout-identity-changed' };
});
if (!captured.ok) return captured;
const prepared = await buildCurrentCheckoutReview(input, captured, localOptions);
if (!prepared.ok) return prepared;
return withClaimOwnershipLock(async () => {
// Bind even legacy inventory rows to the generation captured before hashing.
const current = await readCheckoutReviewPrerequisites(input, localOptions);
if (!current.ok) return current;
if (await previewCheckoutIdentity(release.path).catch(() => null) !== captured.identity) {
return { ok: false, reason: 'checkout-identity-changed' };
}
if (JSON.stringify(current.policy) !== JSON.stringify(captured.policy)) {
return { ok: false, reason: 'retirement-review-changed' };
}
return prepared;
});
}
/** Host-control-gated preview of one inventory row; may fetch missing proof objects. */
export async function prepareInventoriedCheckoutRetirement({ appId, release, prUrl, kind }, opts = {}) {
const [{ getAppById }, { getBranchReconcileOutcome }] = await Promise.all([import('./apps.js'), import('./taskSchedule.js')]);
const app = await getAppById(appId);
if (!app?.repoPath) return { ok: false, reason: 'app-not-found' };
const outcome = await getBranchReconcileOutcome(appId);
release = bindInventoriedRelease(outcome, release);
if (!release) return { ok: false, reason: 'release-not-in-inventory' };
const reviewOptions = { ...opts, forgeAccount: app.forgeAccount ?? null };
const review = () => previewCurrentCheckout({ repoPath: app.repoPath, release, prUrl, kind }, reviewOptions);
let prepared = await review();
if (prepared.reason === 'retirement-local-objects-missing') {
// A remote default may advance while local refs stay put. Acquire only its
// validated proof objects; then repeat every owner/policy/content check.
const fetched = await fetchRetirementProofObjects(app.repoPath, release, prUrl, null, { ...reviewOptions, ...reviewForgeOptions(release, kind, reviewOptions) });
if (!fetched.ok) return fetched;
prepared = await review();
}
if (!kind && release.branch && prepared.reason === 'retirement-policy-not-legacy-completed') {
// Recover only a previously registered physical generation after fresh
// merged exact-head proof. Never promote an orphan's execution to success.
const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
const forge = await (opts.readForge || readRetirementForgeEvidence)(app.repoPath, release.branch, prUrl,
{ forgeAccount: app.forgeAccount ?? null }).catch(() => null);
if (forge?.prUrl === prUrl && forge.prHead === release.head) {
const [repoPath, checkoutPath] = await Promise.all([
realpath(app.repoPath).catch(() => null), realpath(release.path).catch(() => null),
]);
if (!repoPath || !checkoutPath) return prepared;
const { readBranchCompletionPolicies } = await import('./branchCompletionPolicy.js');
const policies = await (opts.readPolicies || (() => readBranchCompletionPolicies({ repairIndex: false })))().catch(() => null);
const retry = opts.recoverCheckoutCapture || (await import('./cosAgentLifecycle.js')).retryCompletionCheckoutCapture;
let recovered = false;
for (const agent of Array.isArray(policies) ? policies : []) {
const meta = agent.metadata || {};
const knownPr = meta.branchCompletionPolicy?.prUrl || meta.reviewLoopMergeTarget?.url;
if (agent.status !== 'completed' || agent.result?.orphaned !== true || agent.result.validationPassed === false
|| knownPr !== prUrl || meta.checkoutCapture?.status !== 'captured' || meta.completedCheckouts?.length !== 0
|| !meta.checkoutSeeds?.some(seed => seed.repoPath === repoPath && seed.branch === release.branch && seed.path === checkoutPath)) continue;
recovered = await retry(agent.id || agent.agentId, { retirement: { ...release, repoPath, path: checkoutPath } }).catch(() => false) || recovered;
}
if (recovered) prepared = await review();
}
}
return prepared;
}
/** Git's object id for raw bytes, with no clean filter or line-ending conversion. */
async function rawBlobId(source, size, format, work) {
const hash = createHash(format).update(`blob ${size}\0`);
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');
}
/**
* Everything the archive must preserve, read in one pass: the staged and
* unstaged diffs (separately, so a staged blob whose working copy is gone
* survives), raw copies of tracked files whose bytes differ from their index
* blob (a clean filter or line-ending conversion hides those from diff), and
* every untracked or ignored file by content hash, symlinks by target. Throws
* on anything that cannot be archived faithfully, before any copy is made.
* The fingerprint is compared again immediately before removal.
*/
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([
git(['ls-files', '-u', '-z'], path),
git(['ls-files', '--stage', '-z'], path),
git(['ls-files', '-v', '-z'], path),
// A textconv or external diff driver can drop bytes from a patch. Disable
// 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, 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),
]);
if (unmerged.length) throw new Error('unmerged index entries cannot be archived');
const stage = zLines(stageOut);
const gitlinks = [];
for (const line of stage.filter(row => row.startsWith('160000 '))) {
const tab = line.indexOf('\t');
const header = line.slice(0, tab);
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');
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));
if (hidden) throw new Error(`${hidden.slice(2)} hides working-tree changes from Git`);
const files = [];
let total = 0;
const addFile = async (rel, info, extra = {}) => {
total += info.size;
checkArchiveSize('content', info.size, total);
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);
// Symlink blobs are not filtered; deletions and type changes are in the diff.
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, 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()) {
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`);
}
const fingerprint = createHash('sha256').update(indexDiff).update('\0').update(worktreeDiff).update('\0')
.update(JSON.stringify({ files, symlinks, gitlinks })).digest('hex');
return { indexDiff, worktreeDiff, files, symlinks, gitlinks, fingerprint };
}
/**
* Write and verify the archive. Throws on anything that would leave it
* incomplete; the caller then retires nothing.
*/
async function archiveCheckout(input) {
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
const dir = join(heldCheckoutArchiveRoot(input.cosDir), `${backupSlug(input.branch || `detached-${input.tree.head}`)}-${stamp}-${randomUUID()}`);
// An incomplete archive must not read as a restore point.
return writeArchive(dir, input).catch(async (error) => {
await rmGuarded(dir, { recursive: true, force: true }).catch(() => {});
throw error;
});
}
// A missing tail has no filesystem identity yet. Match its exact spelling under
// the deepest existing directory's identity, so Git's expanded Windows 8.3
// names and directory aliases agree without case-folding nonexistent names.
async function missingPathIdentity(path) {
let ancestor = resolve(path);
const tail = [];
for (;;) {
const info = await lstat(ancestor).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
if (info) {
// Native realpath expands Windows short names; JavaScript realpath may
// retain them. Existing dangling links/errors must hold, never walk past.
const canonical = realpathSync.native(ancestor);
const identity = await stat(canonical, { bigint: true });
if ((!identity.isDirectory() && tail.length) || identity.ino === 0n) throw new Error('missing-checkout-ancestor-unverified');
return { ancestor: canonical, dev: String(identity.dev), ino: String(identity.ino), tail };
}
const parent = dirname(ancestor);
if (parent === ancestor) throw new Error('missing-checkout-ancestor-unverified');
tail.unshift(basename(ancestor));
ancestor = parent;
}
}
// A vanished checkout can still own a staged index and private recovery files.
// Locate its exact registration without recreating the missing working tree.
async function missingCheckoutAdministration(repoPath, path) {
const present = await lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
if (present) return null;
const common = resolve(repoPath, (await git(['rev-parse', '--git-common-dir'], repoPath)).trim());
const roots = [];
const target = await missingPathIdentity(join(path, '.git'));
const mismatches = [];
for (const name of await readdir(join(common, 'worktrees'))) {
const root = join(common, 'worktrees', name);
if (!(await lstat(root)).isDirectory()) continue;
const pointer = await readFile(join(root, 'gitdir'), 'utf8').catch(() => null);
if (!pointer?.trim()) continue;
const candidate = await missingPathIdentity(resolve(root, pointer.trim()));
if (candidate.dev === target.dev && candidate.ino === target.ino && JSON.stringify(candidate.tail) === JSON.stringify(target.tail)) roots.push(root);
else if (mismatches.length < 4) mismatches.push({ registration: name, pointer: pointer.trim().slice(0, 1024), identity: candidate });
}
if (roots.length !== 1) throw new Error(`missing-checkout-administration-unverified: ${JSON.stringify({ target, matches: roots.length, mismatches })}`);
return roots[0];
}
async function archiveSnapshots(tree, repoPath, missingRoot, work = archiveWork()) {
work = work.metadataScope();
if (!missingRoot) {
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;
}
const present = await lstat(tree.path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
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, 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, work);
validateArchiveEntries(administration, work, false);
checkArchiveBudget(content, administration);
return [content, administration];
}
/** Preserve ignored content and recovery evidence before a clean merged tree
* 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, signal } = {}) {
if (!tree?.head || (!tree.branch && tree.detached !== true) || tree.locked) throw new Error('checkout-identity-unavailable');
const checkoutIdentity = await readRetirementCheckoutIdentity(tree.path);
const branch = shortBranch(tree.branch);
const missingRoot = await missingCheckoutAdministration(repoPath, tree.path);
const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, cosDir, missingRoot, work: archiveWork(signal) });
return {
archiveDir: archive.dir,
checkoutIdentity,
async verify(holder) {
if (!holder || holder.head !== tree.head || holder.branch !== tree.branch || Boolean(holder.detached) !== Boolean(tree.detached)) return 'worktree-holder-changed';
// Missing-root recovery archives Git administration without a live pointer.
if (checkoutIdentity && await readRetirementCheckoutIdentity(tree.path) !== checkoutIdentity) return 'checkout-identity-changed';
const [content, administration] = await archiveSnapshots(tree, repoPath, missingRoot, archiveWork(signal));
return content.fingerprint === archive.fingerprint && administration.fingerprint === archive.administrationFingerprint
? null : 'checkout-content-changed';
},
};
}
// All administration bytes are preserved separately. Only Git's reference
// formats establish object dependencies; messages and application JSON do not.
function recoveryReferenceKind(path) {
const relative = path.replace(/^gitdir\//, '');
if (/^(rebase-merge|rebase-apply|sequencer|reftable)(\/|$)/.test(relative)
|| /\.lock$/.test(relative) || (/^BISECT_/.test(relative) && relative !== 'BISECT_HEAD')) return 'unsafe';
if (/^logs(?:\/|$)/.test(relative)) return 'reflog';
if (/^refs(?:\/|$)/.test(relative)) return 'ref';
if (relative === 'packed-refs') return 'packed';
if (relative === 'FETCH_HEAD') return 'fetch';
// HEAD resolves to tree.head, which is already a recovery root; skipping it
// saves two Git spawns per retirement (#13154 spawn ceiling).
if (relative === 'HEAD') return null;
if (relative === 'MERGE_HEAD' || relative === 'shallow') return 'objects';
if (['COMMIT_EDITMSG', 'MERGE_MSG', 'MERGE_MODE', 'MERGE_RR', 'SQUASH_MSG', 'TAG_EDITMSG', 'NOTES_EDITMSG'].includes(relative)) return null;
// Worktree-private root refs use uppercase names. Unknown operation formats
// must hold rather than silently omit recovery objects introduced by Git.
return /^[A-Z][A-Z0-9_]*$/.test(relative) ? 'ref' : null;
}
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());
if (heads.size > 1024) throw new Error('too many private recovery objects');
};
for (const link of administration.symlinks) {
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 archiveBytes(file.source, work, MAX_FILE_BYTES)).toString('utf8');
const lines = contents.split(/\r?\n/);
if (lines.at(-1) === '') lines.pop();
if (kind === 'ref') {
if (lines.length !== 1) invalid();
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();
add(fields[1], true);
add(fields[2], true);
} else if (kind === 'fetch') {
const fields = /^([a-f0-9]+)\t(?:not-for-merge)?\t.*$/i.exec(line);
if (!fields) invalid();
add(fields[1]);
} else if (kind === 'packed') {
if (line.startsWith('#')) continue;
const fields = /^(?:([a-f0-9]+) refs\/\S+|\^([a-f0-9]+))$/i.exec(line);
if (!fields) invalid();
add(fields[1] || fields[2]);
} else add(line);
}
}
return heads;
}
/** Shared app-scoped preservation for merged and superseded checkouts.
* Persist the original generation before archiving, then its exact preservation
* receipt before the caller can remove anything under the retirement fence.
*/
export async function preserveSupersededCheckout({ appId, repoPath, tree, defaultBranch, cosDir }) {
const [{ getAppById }, schedule] = await Promise.all([import('./apps.js'), import('./taskSchedule.js')]);
const app = appId && await getAppById(appId);
if (!app?.repoPath || resolve(app.repoPath) !== resolve(repoPath)) throw new Error('retirement-receipt-scope-unavailable');
if (!tree?.path || !tree.branch || tree.locked) throw new Error('retirement-checkout-unavailable');
const release = { path: tree.path, branch: shortBranch(tree.branch), head: tree.head, locked: false, lockReason: null };
const { readCompletedCheckoutIdentity } = await import('./completedCheckoutEvidence.js');
const target = { repoPath, branch: release.branch, path: release.path, head: release.head };
const identity = await readCompletedCheckoutIdentity(target);
if (!identity) throw new Error('checkout-incarnation-unavailable');
const checkoutIdentity = await readRetirementCheckoutIdentity(tree.path);
if (!checkoutIdentity) throw new Error('checkout-incarnation-unavailable');
const previous = await schedule.getBranchReconcileOutcome(appId);
if (unresolvedRetirements(previous).some(row => sameRelease(row, release)
&& JSON.stringify(row.checkoutIncarnation) !== JSON.stringify(identity.incarnation))) {
throw new Error('retirement-checkout-generation-unverified');
}
const identityCurrent = async () => JSON.stringify(await readCompletedCheckoutIdentity(target)) === JSON.stringify(identity);
const pending = await schedule.recordBranchReconcileOutcome(appId, {
status: 'incomplete', reason: 'retirement-receipt-unverified',
retirementObligations: [{ ...release, checkoutIdentity, checkoutIncarnation: identity.incarnation, reason: 'retirement-review-pending' }],
nextAction: 'Require complete preservation and an exact retirement receipt for the checkout.',
});
const obligation = pending?.retirementObligations?.find(row => sameRelease(row, release));
if (!Number.isFinite(Date.parse(obligation?.createdAt))) throw new Error('retirement-obligation-unavailable');
if (JSON.stringify(obligation.checkoutIncarnation) !== JSON.stringify(identity.incarnation)) throw new Error('retirement-checkout-generation-unverified');
// Invalidate any earlier attempt's prepared receipt without dropping its
// obligation. A crash must never let an older snapshot stand in for this one.
await schedule.recordHeldCheckoutPreservation(appId, { ...release, createdAt: obligation.createdAt, archiveDir: null, incarnation: identity.incarnation });
const archive = await preserveMergedCheckout(repoPath, tree, defaultBranch, { cosDir });
if (!await identityCurrent()) throw new Error('checkout-incarnation-changed');
await schedule.recordHeldCheckoutPreservation(appId, { ...release, createdAt: obligation.createdAt, archiveDir: archive.archiveDir, incarnation: identity.incarnation });
const receiptCurrent = async () => {
const currentApp = await getAppById(appId);
if (!currentApp?.repoPath || resolve(currentApp.repoPath) !== resolve(repoPath)) return false;
const current = await schedule.getBranchReconcileOutcome(appId);
return current?.retirementObligations?.some(row => sameRelease(row, release)
&& row.createdAt === obligation.createdAt && row.preservationReceipt?.status === 'preserved'
&& row.preservationReceipt.archiveDir === archive.archiveDir
&& JSON.stringify(row.preservationReceipt.incarnation) === JSON.stringify(identity.incarnation)
&& JSON.stringify(row.checkoutIncarnation) === JSON.stringify(identity.incarnation)) === true;
};
if (!await receiptCurrent()) throw new Error('retirement-preservation-receipt-unverified');
return {
archiveDir: archive.archiveDir,
verify: async holder => !await receiptCurrent() ? 'retirement-preservation-receipt-changed'
: !await identityCurrent() ? 'checkout-incarnation-changed' : archive.verify(holder),
async recordRetirement() {
if (!await receiptCurrent()) throw new Error('retirement-preservation-receipt-changed');
const ref = await execGit(['rev-parse', '--verify', '--quiet', `refs/heads/${release.branch}`], repoPath, { ignoreExitCode: true });
if (ref.exitCode !== 1 || !await historicalCheckoutAbsent(release, await listWorktrees(repoPath))) throw new Error('retirement-checkout-recreated');
const outcome = await schedule.recordHeldCheckoutRetirement(appId, { ...release, checkoutIdentity, branchDeleted: true, archiveDir: archive.archiveDir });
if (!outcome?.retired?.some(row => sameRelease(row, release) && row.branchDeleted === true
&& row.archiveDir === archive.archiveDir && Date.parse(row.retiredAt) >= Date.parse(obligation.createdAt))) {
throw new Error('retirement-receipt-unverified');
}
},
};
}
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);
// A bundle keeps the original commit objects, merges included, which a
// squash-merged branch would otherwise lose to garbage collection.
const bundle = join(dir, 'commits.bundle');
// Private refs and operation files can name any Git object: ort's AUTO_MERGE
// names a tree containing conflict-resolution evidence, not a commit.
// Named bundle roots preserve their reachable objects too. Unknown/missing
// recovery objects still hold the checkout.
const recoveryRefs = [];
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');
} finally {
// These are private temporary refs, never branch refs. The checkout and its
// original reflog remain intact unless the entire archive later verifies.
for (const { ref, head } of recoveryRefs) await git(['update-ref', '-d', ref, head], repoPath);
}
await chmod(bundle, 0o600);
for (const file of administration.files) {
work.check();
const destination = join(dir, 'administration', file.path);
await ensureDir(dirname(destination));
await archiveCopy(file.source, destination, file.bytes, work);
await chmod(destination, 0o600);
if (await archiveHash(destination, work) !== file.sha256) throw new Error('administration archive mismatch');
}
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 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, 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 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.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.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,
].filter(Boolean),
};
// 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);
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 };
}
const isAncestor = (repoPath, sha, ref) => execGit(['merge-base', '--is-ancestor', sha, ref], repoPath, { ignoreExitCode: true })
.then(r => r.exitCode === 0, () => false);
async function ownerReason({ repoPath, tree, branch, readAgents, reviewed = false, mergedObligationSettled = false }) {
const agents = await readAgents().catch(() => null);
if (!Array.isArray(agents)) return 'claim-ownership-unreadable';
const claim = claimCheckoutOwnerReason({ branchName: branch || 'HEAD', holderPath: tree.path, sourceWorkspace: repoPath, agents });
if (claim) return claim;
const [{ buildActiveOwnerIds, resolveLiveOwnerReason }, { getActiveAgentIds }] = await Promise.all([
import('./branchReconcile.js'), import('./agentState.js'),
]);
// The released lock is excluded here on purpose: it was matched against the
// release above, and a NEW lock is caught by the registration recheck.
const live = resolveLiveOwnerReason({ branch, path: tree.path, locked: false, activeAgentIds: buildActiveOwnerIds(new Set(getActiveAgentIds()), agents) });
if (live) return live;
if (!branch || reviewed) return null;
const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
const hold = await readBranchCompletionHold({ repoPath, branch, retirement: true }).catch(() => 'pr-completion-policy-unavailable');
// A review obligation is moot once every commit is already on the default
// branch (re-proven under the fence). Human handoffs and unreadable policy stay held.
return mergedObligationSettled && hold === 'pr-completion-review-required' ? null : hold;
}
/** Optional server inventory identity binds private administration as well as
* the pointer file. Callers have already checked the exact released lock under
* the retirement fence; allowing a fact-read does not authorize unlocking it. */
async function matchesObservedCheckoutIncarnation(repoPath, release, worktrees = null) {
if (!release.checkoutIncarnation) return true;
const { readCompletedCheckoutIdentity } = await import('./completedCheckoutEvidence.js');
const current = await readCompletedCheckoutIdentity({ repoPath, ...release, worktrees,
allowLocked: release.locked === true }).catch(() => null);
return current && JSON.stringify(current.incarnation) === JSON.stringify(release.checkoutIncarnation);
}
/** Fresh registration that still matches the release, or the reason it does not. */
async function matchRelease(repoPath, release) {
const trees = await listWorktrees(repoPath).catch(() => null);
if (!trees?.length) return { reason: 'worktree-ownership-unreadable' };
const index = trees.findIndex(tree => resolve(tree.path) === resolve(release.path));
if (index === -1) return { reason: 'checkout-not-found' };
const tree = trees[index];
// Lexical equality alone can collapse '..' across a symlink. Different
// spellings must also resolve to the same existing filesystem checkout.
if (tree.path !== release.path) {
try { if (realpathSync.native(tree.path) !== realpathSync.native(release.path)) return { reason: 'checkout-identity-changed' }; }
catch { return { reason: 'checkout-identity-changed' }; }
}
if (index === 0 || tree.bare) return { reason: 'checkout-primary' };
if (tree.prunable) return { reason: 'worktree-prunable' };
if (tree.head !== release.head) return { reason: 'checkout-head-changed' };
if (shortBranch(tree.branch) !== (release.branch ?? null)) return { reason: 'checkout-branch-changed' };
if (Boolean(tree.locked) !== release.locked || (tree.lockReason ?? null) !== (release.lockReason ?? null)) {
return { reason: 'checkout-lock-changed' };
}
if (!await matchesObservedCheckoutIncarnation(repoPath, release, trees)) return { reason: 'checkout-identity-changed' };
// Carry the persisted release spelling through archive/receipt publication.
// Native lexical resolution above proves it names this registration; fresh
// head, lock and incarnation checks still bind the filesystem generation.
return { tree: { ...tree, path: release.path } };
}
/** Shared live policy/owner check for the explicit whole-checkout transaction.
* It does not archive, unlock or infer integration.
*/
export async function inspectCheckoutRetirementOwnership({ repoPath, release, registration = true, reviewIdentity = {}, forgeAccount = null }, opts = {}) {
if (!release.branch || PROTECTED_BRANCHES.includes(release.branch)) return { ok: false, reason: 'protected-branch' };
const matched = registration ? await matchRelease(repoPath, release) : { tree: release };
if (!matched.tree) return { ok: false, reason: matched.reason };
const reason = await ownerReason({ repoPath, tree: matched.tree, branch: release.branch,
readAgents: opts.readAgents || readClaimOwnershipAgents, reviewed: true });
if (reason) return { ok: false, reason };
const policy = await retirementPolicy(repoPath, release.branch, { ...opts, forgeAccount: opts.forgeAccount ?? forgeAccount }, reviewIdentity);
return policy.reason ? { ok: false, reason: policy.reason } : { ok: true, tree: matched.tree, policy };
}
/**
* Remove one held checkout under an operator's scoped release. Nothing is copied.
*
* @param {{ repoPath: string, release: { path: string, head: string, branch: string|null, locked: boolean, lockReason: string|null } }} input
* @param {{ cosDir?: string, readAgents?: () => Promise<object[]|null> }} [opts]
* @returns {Promise<{ ok: true, branchDeleted: boolean, checkoutIdentity?: string, branchRetainedReason?: string } | { ok: false, reason: string, detail?: string }>}
*/
async function retireHeldCheckout({ repoPath, release, review }, opts = {}) {
const { readAgents = readClaimOwnershipAgents } = opts;
// Only the unattended merged-retirement caller sets this, and only without a review.
const mergedObligationSettled = !review && opts.settleMergedReviewObligation === true;
const branch = release.branch ?? null;
if (branch && PROTECTED_BRANCHES.includes(branch)) return { ok: false, reason: 'protected-branch' };
const defaultBranch = await getDefaultBranch(repoPath, { allowRemote: false, strict: true }).catch(() => null);
if (!defaultBranch) return { ok: false, reason: 'default-branch-unavailable' };
if (branch === defaultBranch) return { ok: false, reason: 'protected-branch' };
// 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, nextAction) => ({ result: { ok: false, reason, ...(archiveLimit && { archiveLimit }), ...(nextAction && { nextAction }) } });
return retireWithUnlockedArchive({
busy: () => ({ ok: false, reason: 'checkout-retirement-reserved' }),
admit: async () => {
if (opts.inventoryCurrent && !await opts.inventoryCurrent()) return refuse('release-not-in-inventory');
await opts.beforeMutation?.();
const first = await matchRelease(repoPath, release);
if (!first.tree) return refuse(first.reason);
const { tree } = first;
const checkoutIdentity = await readRetirementCheckoutIdentity(tree.path);
if (!checkoutIdentity || (release.checkoutIdentity && release.checkoutIdentity !== checkoutIdentity)) return refuse('checkout-identity-changed');
// A reviewed checkout can be integrated on the forge while local main still
// lags (squash, or a reset default). Local ancestry remains the proof when
// no review was supplied. Supersession acceptance never covers that lag.
const locallyMerged = branch
? await hasBranchMergeEvidence(repoPath, branch, defaultBranch).catch(() => false)
: await isAncestor(repoPath, tree.head, defaultBranch);
if (!locallyMerged && !review) return refuse('not-merged-on-recheck');
const porcelain = await execGit(['status', '--porcelain'], tree.path).then(r => r.stdout, () => null);
if (porcelain === null) return refuse('worktree-status-unavailable');
if (!classifyWorktreeDirt(porcelain).clean) return refuse('worktree-dirty');
const reviewed = review ? await reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl, kind: review.kind }, opts) : null;
if (reviewed && (!reviewed.ok || reviewed.review.digest !== review.digest)) return refuse(reviewed.reason || 'retirement-review-changed', reviewed.archiveLimit, reviewed.nextAction);
const disposition = reviewed?.review.comparison.disposition;
if (disposition === 'review-supersession' && (!locallyMerged || review.acceptSuperseded !== true)) return refuse('retirement-supersession-not-accepted');
if (!locallyMerged && disposition !== 'integrated') return refuse('not-merged-on-recheck');
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 }) => {
try {
await releaseCheckoutWithoutArchive({ repoPath, path: tree.path, branch }, async () => {
if (opts.signal?.aborted) throw new Error('retirement-archive-cancelled');
const status = await execGit(['status', '--porcelain'], tree.path).then(r => r.stdout, () => null);
if (status === null) throw new Error('worktree-status-unavailable');
if (!classifyWorktreeDirt(status).clean) throw new Error('worktree-dirty');
const mergedNow = branch
? await hasBranchMergeEvidence(repoPath, branch, defaultBranch).catch(() => false)
: await isAncestor(repoPath, tree.head, defaultBranch);
// Finish re-reads the review. A forge-integrated detached or lagging
// checkout is not an ancestor of local main yet.
if (!mergedNow && !review) throw new Error('not-merged-on-recheck');
return null;
});
return { archive: { disposable: true } };
} catch (error) {
const reason = ['worktree-dirty', 'not-merged-on-recheck', 'worktree-status-unavailable', 'retirement-archive-cancelled'].includes(error.message)
? error.message : 'checkout-not-disposable';
return { result: { ok: false, reason, ...(reason === 'checkout-not-disposable' && error.message && { detail: error.message }) } };
}
},
finish: async ({ tree, reviewed, checkoutIdentity }) => {
const result = await finishHeldCheckoutRetirement({ repoPath, release, review, reviewed, tree, branch, defaultBranch, checkoutIdentity, mergedObligationSettled }, opts);
return result.ok ? { ...result, checkoutIdentity } : result;
},
});
}
/** The second critical section: re-prove the release, ownership and a clean tree, then remove. */
async function finishHeldCheckoutRetirement({ repoPath, release, review, reviewed, tree, branch, defaultBranch, checkoutIdentity, mergedObligationSettled = false }, opts) {
const { readAgents = readClaimOwnershipAgents } = opts;
if (opts.signal?.aborted) return { ok: false, reason: 'retirement-archive-cancelled' };
const second = await matchRelease(repoPath, release);
if (!second.tree) return { ok: false, reason: second.reason };
if (await readRetirementCheckoutIdentity(tree.path) !== checkoutIdentity) return { ok: false, reason: 'checkout-identity-changed' };
await opts.beforeMutation?.();
if (release.locked) {
const unlocked = await execGit(['worktree', 'unlock', tree.path], repoPath).then(() => true, () => false);
if (!unlocked) return { ok: false, reason: 'worktree-unlock-failed' };
}
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';
if (opts.inventoryCurrent && !await opts.inventoryCurrent()) return 'release-not-in-inventory';
const [reason, fresh, porcelain] = await Promise.all([
ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review), mergedObligationSettled }),
review ? reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl, kind: review.kind, unlocked: release.locked }, opts) : null,
execGit(['status', '--porcelain'], tree.path).then(r => r.stdout, () => null),
]);
if (fresh && !fresh.ok) { capacityRefusal = fresh; return fresh.reason; }
if (fresh && fresh.review.digest !== review.digest) return 'retirement-review-changed';
if (porcelain === null || !classifyWorktreeDirt(porcelain).clean) return 'worktree-dirty';
const locallyMerged = branch
? await hasBranchMergeEvidence(repoPath, branch, defaultBranch).catch(() => false)
: await isAncestor(repoPath, tree.head, defaultBranch);
const disposition = fresh?.review?.comparison?.disposition;
if (disposition === 'review-supersession' && (!locallyMerged || review.acceptSuperseded !== true)) return 'retirement-supersession-not-accepted';
if (!locallyMerged && disposition !== 'integrated') return 'not-merged-on-recheck';
if (reason) return reason;
if (opts.signal?.aborted) return 'retirement-archive-cancelled';
return null;
};
const removal = await forceRemoveWorktreeDir(repoPath, tree.path, {
label: '🧹 held-checkout recovery: remove checkout', log: 'all', verifyRemoval, beforeMutation: opts.beforeMutation,
});
if (!removal.removed) {
// Hand the lock back exactly as released. A lock someone took in the
// meantime makes this fail, which is the outcome we want anyway.
if (release.locked) {
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 capacityRefusal || { ok: false, reason: removal.reason || 'worktree-remove-failed' };
}
console.log(`🧹 held-checkout recovery: retired ${tree.path}`);
if (!branch) return { ok: true, branchDeleted: false };
const hold = await ownerReason({ repoPath, tree: { ...tree, path: null }, branch, readAgents, reviewed: Boolean(review), mergedObligationSettled });
if (hold) return { ok: true, branchDeleted: false, branchRetainedReason: hold };
if (review) {
const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
const forge = await (opts.readForge || readRetirementForgeEvidence)(repoPath, branch, review.prUrl, reviewForgeOptions(release, review.kind, opts)).catch(() => null);
const captured = reviewed.review.policy?.policies?.find(row => row.continuedDelivery)?.continuedDelivery.checkoutIncarnation;
const identity = await integratedPolicyReviewIdentity(repoPath, release, review.prUrl, forge, captured);
const policy = identity ? await retirementPolicy(repoPath, branch, opts, identity) : null;
if (JSON.stringify(policy) !== JSON.stringify(reviewed.review.policy) || JSON.stringify(forge) !== JSON.stringify(reviewed.review.forge)) {
return { ok: true, branchDeleted: false, branchRetainedReason: 'retirement-evidence-changed' };
}
}
// A new checkout/commit cannot be deleted by a stale name-only operation.
const holders = await listWorktrees(repoPath).catch(() => null);
if (!holders || holders.some(holder => shortBranch(holder.branch) === branch)) return { ok: true, branchDeleted: false, branchRetainedReason: 'branch-has-new-holder' };
const deleted = await deleteCompletedLocalBranch(repoPath, branch, release.head, { beforeMutation: opts.beforeMutation });
if (!deleted) return { ok: true, branchDeleted: false, branchRetainedReason: 'branch-ref-changed-or-delete-failed' };
return { ok: true, branchDeleted: true };
}
const sameRelease = (entry, release) => entry.path === release.path && entry.head === release.head
&& (entry.branch ?? null) === (release.branch ?? null) && Boolean(entry.locked) === release.locked
&& (entry.lockReason ?? null) === (release.lockReason ?? null)
&& (!release.checkoutIdentity || entry.checkoutIdentity === release.checkoutIdentity);
/** Tuple-only clients remain compatible; only persisted observation identity
* enters the review digest. Scan times are not incarnation identity.
*/
function bindInventoriedRelease(outcome, release) {
const entry = outcome?.remaining?.find(row => sameRelease(row, release));
if (!entry) return null;
return { path: release.path, head: release.head, branch: release.branch ?? null,
locked: release.locked, lockReason: release.lockReason ?? null,
...(entry.checkoutIdentity && { checkoutIdentity: entry.checkoutIdentity }),
...(entry.checkoutIncarnation && { checkoutIncarnation: entry.checkoutIncarnation }) };
}
// Preview and receipt paths may acquire exact server-verified proof commits
// into the object store, never a branch, index or implicit approval.
export async function fetchRetirementProofObjects(repoPath, release, prUrl, expectedHeadSha, opts) {
const [{ readRetirementForgeEvidence }, { getOriginInfo }, { resolveForgeExecOptions }] = await Promise.all([
import('./heldCheckoutReview.js'), import('../lib/gitRemote.js'), import('./forgeExecOptions.js'),
]);
const forge = await (opts.readForge || readRetirementForgeEvidence)(repoPath, release.branch, prUrl, opts).catch(() => null);
const origin = await getOriginInfo(repoPath).catch(() => null);
if (!origin || !forge || forge.repository !== `${origin.host}/${origin.fullName}` || forge.prUrl !== prUrl) {
return { ok: false, reason: 'retirement-pr-repository-mismatch' };
}
if (expectedHeadSha !== null && forge.prHead !== expectedHeadSha) return { ok: false, reason: 'receipt-pr-head-changed' };
const heads = [...new Set([forge.prHead, forge.mergeCommit, forge.defaultHead, forge.changeBase, forge.firstCommit])];
if (heads.some(head => typeof head !== 'string' || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(head))) {
return { ok: false, reason: 'retirement-forge-unreadable' };
}
const missing = [];
for (const head of heads) {
if (!await execGit(['cat-file', '-e', `${head}^{commit}`], repoPath).then(() => true, () => false)) missing.push(head);
}
if (!missing.length) return { ok: true };
const { env } = await resolveForgeExecOptions(repoPath, { forgeAccount: opts.forgeAccount });
const fetched = await execGit(['-c', 'credential.helper=', '-c', 'credential.helper=!gh auth git-credential',
'-c', 'core.askPass=', 'fetch', '--no-tags', '--no-write-fetch-head', '--no-recurse-submodules',
'--no-auto-maintenance', '--refmap=', '--', `https://${origin.host}/${origin.fullName}.git`, ...missing], repoPath, {
timeout: 30_000, maxBuffer: 4 * 1024 * 1024,
env: { ...env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', SSH_ASKPASS: '', GH_PROMPT_DISABLED: '1' },
}).then(() => true, () => false);
return fetched ? { ok: true } : { ok: false, reason: 'retirement-proof-fetch-failed' };
}
/** Finish only the checkout named by a trusted pending-merge receipt. Unlike an
* operator release, this never unlocks a checkout or accepts supersession. Fresh
* forge evidence must independently prove the exact handed-off head merged and
* remains integrated. Initialized submodules stay held for explicit recovery.
*/
export async function retirePendingMergeCheckout({ repoPath, release, prUrl, expectedHeadSha }, opts = {}) {
if (!release || release.locked !== false || release.lockReason !== null) return { ok: false, reason: 'receipt-checkout-locked' };
if (!release.path || !release.branch || typeof expectedHeadSha !== 'string'
|| !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(expectedHeadSha) || release.head !== expectedHeadSha) {
return { ok: false, reason: 'receipt-checkout-head-unverified' };
}
const receiptOptions = { ...opts, mergedReceipt: { expectedHeadSha } };
let prepared = await reviewCurrentCheckout({ repoPath, release, prUrl }, receiptOptions);
// The read-only preview has already passed identity, ownership, manual policy
// and archival feasibility gates. Missing remote merge objects are recoverable
// here without requiring an unrelated repo-sync to advance local branches.
if (prepared.reason === 'retirement-local-objects-missing') {
const fetched = await fetchRetirementProofObjects(repoPath, release, prUrl, expectedHeadSha, receiptOptions);
if (!fetched.ok) return fetched;
prepared = await reviewCurrentCheckout({ repoPath, release, prUrl }, receiptOptions);
}
if (!prepared.ok) return prepared;
if (prepared.review.forge.prHead !== expectedHeadSha) return { ok: false, reason: 'receipt-pr-head-changed' };
if (prepared.review.comparison.disposition !== 'integrated') return { ok: false, reason: 'retirement-supersession-not-accepted' };
const result = await retireHeldCheckout({ repoPath, release,
review: { prUrl, digest: prepared.review.digest, acceptSuperseded: false },
}, receiptOptions);
if (result.ok) {
const { recordWorkspaceCheckoutRetirement } = await import('./taskSchedule.js');
await recordWorkspaceCheckoutRetirement(repoPath, {
path: release.path, branch: release.branch ?? null, head: release.head,
branchDeleted: result.branchDeleted, ...(result.archiveDir && { archiveDir: result.archiveDir }), checkoutIdentity: result.checkoutIdentity,
});
}
return result;
}
/**
* The Schedule view's entry point: the release must name a row of the app's
* last persisted inventory exactly, so it binds to evidence the operator saw.
*/
export async function retireInventoriedCheckout({ appId, release, review }, opts) {
const [{ getAppById }, taskSchedule] = await Promise.all([import('./apps.js'), import('./taskSchedule.js')]);
const app = await getAppById(appId);
if (!app?.repoPath) return { ok: false, reason: 'app-not-found' };
const outcome = await taskSchedule.getBranchReconcileOutcome(appId);
release = bindInventoriedRelease(outcome, release);
if (!release) return { ok: false, reason: 'release-not-in-inventory' };
const inventoryCurrent = async () => (await taskSchedule.getBranchReconcileOutcome(appId))?.remaining?.some(entry => sameRelease(entry, release)) === true;
const result = await retireHeldCheckout({ repoPath: app.repoPath, release, review }, { ...opts, inventoryCurrent, forgeAccount: app.forgeAccount ?? null });
// A missing original cannot be archived retroactively. Retain its exact
// identity for provenance recovery rather than equating absence with success.
if (!result.ok && result.reason === 'checkout-not-found') {
const gone = await findGoneInventoryRows(app.repoPath, [release]).catch(() => []);
if (gone.length) {
await taskSchedule.recordMissingInventoryRows(appId, gone);
return { ok: false, reason: 'retirement-provenance-unverified' };
}
}
if (result.ok) {
await taskSchedule.recordHeldCheckoutRetirement(appId, {
path: release.path, branch: release.branch ?? null, head: release.head, branchDeleted: result.branchDeleted,
...(result.archiveDir && { archiveDir: result.archiveDir }), checkoutIdentity: result.checkoutIdentity,
});
}
return result;
}