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
/**
* Explicit initialized-private-module retirement. A merged, clean checkout is
* removed at its original path. An unmerged or dirty checkout stays there.
* Retirement does not quarantine the tree or copy it under
* data/cos/initialized-checkout-retirements. Historical restore helpers remain
* for journals that already exist.
*/
import { readRetirementCheckoutIdentity } from '../lib/retirementCheckoutObservation.js';
import { spawn } from '../lib/childProcess.js';
import { createHash, randomUUID } from 'node:crypto';
import { link, lstat, mkdir, open, opendir, readFile, readdir } from 'node:fs/promises';
import { isAbsolute, join } from 'node:path';
import { type as hostOsType } from 'node:os';
import { fileURLToPath } from 'node:url';
import { PATHS } from '../lib/paths.js';
import { execGit } from '../lib/execGit.js';
import { assertNotRealDataWrite } from '../lib/testDataIsolation.js';
import { withClaimOwnershipLock } from './cosClaimOwnershipState.js';
import { SPOTLIGHT_MARKER } from '../../scripts/lib/spotlightExclude.js';
const helper = fileURLToPath(new URL('../../scripts/lib/initialized_checkout_archive.py', import.meta.url));
const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
const fail = reason => { throw new Error(reason); };
const sameRelease = (a = {}, b = {}) => ['path', 'head', 'branch', 'locked', 'lockReason'].every(key => (a[key] ?? null) === (b[key] ?? null));
const transactionRoot = () => join(PATHS.cos, 'initialized-checkout-retirements');
/** Native helper holds its own flock until the actual child exits. */
export function _runInitializedCheckoutNative(input, { keepOpen = false, beforeMutation } = {}) {
if (process.platform !== 'darwin') return Promise.reject(new Error('retirement-platform-unsupported'));
return new Promise((resolve, reject) => {
const permit = beforeMutation ? randomUUID() : null;
if (permit && (keepOpen || input.command !== 'resume-quarantine')) return reject(new Error('retirement-native-permit-command-invalid'));
let permissionRequested = false;
const child = spawn('/usr/bin/python3', [helper], { stdio: ['pipe', 'pipe', 'pipe'], env: {
PATH: process.env.PATH, HOME: process.env.HOME, TMPDIR: process.env.TMPDIR,
PYTHONDONTWRITEBYTECODE: '1',
} });
let output = '';
let failure = null;
let acquired = false;
let closed = false;
let escalation;
const stop = error => {
failure ||= error;
child.kill('SIGTERM');
escalation ||= setTimeout(() => child.kill('SIGKILL'), 5000);
};
const timer = setTimeout(() => stop(new Error('retirement-native-timeout')), keepOpen ? 30_000 : 20 * 60_000);
const exited = new Promise(done => child.once('close', done));
child.on('error', error => { failure = error; });
child.on('close', code => {
closed = true;
clearTimeout(timer);
clearTimeout(escalation);
if (keepOpen && acquired) return;
if (failure) return reject(failure);
try {
const result = JSON.parse(output);
if (code !== 0 || result.ok !== true) throw new Error(result.reason || 'retirement-native-failed');
resolve(result);
} catch (error) { reject(error); }
});
child.stdout.on('data', data => {
output += data;
if (output.length > 4 * 1024 * 1024) return stop(new Error('retirement-native-output-limit'));
if (permit && !permissionRequested && output.includes('\n')) {
const newline = output.indexOf('\n');
let ready;
try { ready = JSON.parse(output.slice(0, newline)); } catch { return stop(new Error('retirement-native-permit-invalid')); }
// A refused native verification may finish without requesting permission.
if (ready.ok === false) return;
if (ready.mutationReady !== permit || ready.part !== 'administration'
|| Object.keys(ready).length !== 2) return stop(new Error('retirement-native-permit-invalid'));
permissionRequested = true;
output = output.slice(newline + 1);
Promise.resolve().then(beforeMutation).then(() => {
if (closed || failure) return;
child.stdin.end(`${JSON.stringify({ mutationPermit: permit, allow: true })}\n`);
}).catch(stop);
}
if (keepOpen && !acquired && output.includes('\n')) {
try {
const result = JSON.parse(output.slice(0, output.indexOf('\n')));
if (!result.ok) return stop(new Error(result.reason || 'retirement-executor-busy'));
acquired = true;
clearTimeout(timer);
resolve({ assertHeld: () => { if (closed) fail('retirement-executor-lost'); },
release: async () => { child.stdin.end(); await exited; } });
} catch (error) { stop(error); }
}
});
// Metadata and native diagnostics stay out of public logs.
child.stderr.resume();
child.stdin.on('error', error => { failure ||= error; });
child.stdin.write(`${JSON.stringify(permit ? { ...input, mutationPermit: permit } : input)}\n`);
if (!keepOpen && !permit) child.stdin.end();
});
}
// Native execution remains Darwin-only. Mocked workflow tests may run on
// Windows, where POSIX modes and opening directories for fsync are unsupported.
async function syncDirectory(path) {
if (hostOsType() === 'Windows_NT') return;
const directory = await open(path, 'r');
try { await directory.sync(); } finally { await directory.close(); }
}
async function privateDirectory(path, create = false) {
assertNotRealDataWrite(path, 'initialized checkout recovery');
if (create) await mkdir(path, { recursive: true, mode: 0o700 });
const info = await lstat(path);
if (!info.isDirectory() || info.isSymbolicLink() || (hostOsType() !== 'Windows_NT' && (info.mode & 0o777) !== 0o700)) fail('retirement-journal-directory-unsafe');
}
async function appendStep(directory, state, phase, patch = {}) {
await privateDirectory(directory);
const next = { ...state, ...patch, phase, sequence: (state.sequence ?? -1) + 1,
previous: state.sequence == null ? null : hash(state) };
const name = `${String(next.sequence).padStart(6, '0')}.json`;
const staged = join(directory, `.${name}.${randomUUID()}.staging`);
const file = await open(staged, 'wx', 0o600);
try { await file.writeFile(`${JSON.stringify(next)}\n`); await file.sync(); }
finally { await file.close(); }
// A partial write must never occupy the next committed sequence. Hardlink
// publication is atomic and refuses an existing name on every supported
// test platform. Retain staging names, including interrupted rows, as evidence.
await link(staged, join(directory, name));
await syncDirectory(directory);
return next;
}
async function readJournal(directory, { bounded = false, budget } = {}) {
await privateDirectory(directory);
const names = [];
if (bounded) {
const listing = await opendir(directory);
for await (const entry of listing) {
if (names.length >= 1024) fail('retirement-journal-budget-exceeded');
names.push(entry.name);
}
} else names.push(...await readdir(directory));
const files = names.filter(name => /^\d{6}\.json$/.test(name)).sort();
if (bounded && files.length > 128) fail('retirement-journal-budget-exceeded');
let previous = null, bytes = 0;
for (const [sequence, name] of files.entries()) {
const info = await lstat(join(directory, name));
if (!info.isFile() || info.isSymbolicLink() || (hostOsType() !== 'Windows_NT' && (info.mode & 0o777) !== 0o600)) fail('retirement-journal-unsafe');
bytes += info.size;
if (budget) { budget.remaining -= info.size; if (budget.remaining < 0) fail('retirement-discovery-budget-exceeded'); }
if (bounded && (info.size > 16 * 1024 * 1024 || bytes > 64 * 1024 * 1024)) fail('retirement-journal-budget-exceeded');
const row = JSON.parse(await readFile(join(directory, name), 'utf8'));
if (bounded && previous && ['id', 'appId', 'repoPath', 'release', 'review'].some(key => JSON.stringify(row[key]) !== JSON.stringify(previous[key]))) fail('retirement-journal-identity-changed');
if (row.version !== 1 || row.sequence !== sequence || row.previous !== (previous ? hash(previous) : null)) fail('retirement-journal-invalid');
previous = row;
}
if (!previous) fail('retirement-journal-missing');
return previous;
}
async function defaultContext(appId, release) {
const [{ getAppById }, { getBranchReconcileOutcome }] = await Promise.all([import('./apps.js'), import('./taskSchedule.js')]);
const app = await getAppById(appId);
if (!app?.repoPath) fail('app-not-found');
if (release) {
const inventory = await getBranchReconcileOutcome(appId);
if (!inventory?.remaining?.some(entry => sameRelease(entry, release))) fail('release-not-in-inventory');
}
return { repoPath: app.repoPath, forgeAccount: app.forgeAccount ?? null };
}
/** Factory allows workflow tests to replace native IO and forge/network boundaries. */
export function _createInitializedCheckoutRecovery(deps = {}) {
const native = deps.native || _runInitializedCheckoutNative;
const root = deps.root || transactionRoot;
const context = deps.context || defaultContext;
const fenced = deps.fenced || withClaimOwnershipLock;
const ownership = deps.ownership || (async input => (await import('./heldCheckoutRecovery.js')).inspectCheckoutRetirementOwnership(input));
const admission = async () => deps.admission || await import('../lib/checkoutRetirementAdmission.js');
const forge = deps.forge || (async (ctx, release, prUrl) => (await import('./heldCheckoutReview.js')).readRetirementForgeEvidence(
ctx.repoPath, release.branch, prUrl, { forgeAccount: ctx.forgeAccount, exactAliasHead: release.head }));
const comparison = deps.comparison || (async (ctx, release, prUrl, snapshot, policy, forgeFacts) => {
const { buildCheckoutRetirementReview } = await import('./heldCheckoutReview.js');
const run = () => buildCheckoutRetirementReview({ repoPath: ctx.repoPath, release, prUrl,
contentFingerprint: snapshot.fingerprint, administrationFingerprint: snapshot.administrationFingerprint, policy },
{ readForge: async () => forgeFacts });
try {
return await run();
} catch (error) {
if (error?.message === 'retirement-local-objects-missing') {
const { fetchRetirementProofObjects } = await import('./heldCheckoutRecovery.js');
const fetched = await (deps.fetchProofObjects || fetchRetirementProofObjects)(
ctx.repoPath, release, prUrl, null,
{ forgeAccount: ctx.forgeAccount, readForge: async () => forgeFacts, exactAliasHead: release.head }
);
if (fetched?.ok) return run();
}
throw error;
}
});
const ensureOwner = async (ctx, release, registration = true, reviewed = null) => {
const input = { repoPath: ctx.repoPath, release, registration };
const result = await ownership(input);
if (result.ok) return result.policy;
if (result.reason !== 'retirement-policy-not-legacy-completed' || !reviewed?.checkoutIncarnation) fail(result.reason);
const facts = await forge(ctx, release, reviewed.forge.prUrl);
const continued = await ownership({ ...input, forgeAccount: ctx.forgeAccount, reviewIdentity: {
checkoutPath: release.path, tip: release.head, prUrl: facts.prUrl, verifiedPrHead: facts.prHead,
retirementForge: facts, checkoutIncarnation: reviewed.checkoutIncarnation,
} });
if (!continued.ok || !continued.policy?.policies?.some(row => row.continuedDelivery)) fail(continued.reason || result.reason);
return continued.policy;
};
const makeReview = async ({ appId, release, prUrl, wholeCheckout = false }) => {
const ctx = await context(appId, release);
let checkoutIncarnation;
const policy = await ensureOwner(ctx, release).catch(async error => {
if (error.message !== 'retirement-policy-not-legacy-completed') throw error;
const read = deps.readCompletedIdentity || (await import('./completedCheckoutEvidence.js')).readCompletedCheckoutIdentity;
const generation = await read({ repoPath: ctx.repoPath, ...release, allowLocked: release.locked === true }).catch(() => null);
if (!generation) throw error;
checkoutIncarnation = generation.incarnation;
return ensureOwner(ctx, release, true, { forge: { prUrl }, checkoutIncarnation });
});
const snapshot = await native({ command: 'inspect', repoPath: ctx.repoPath, release, requireOwnership: true,
...(wholeCheckout && { wholeCheckout: true }) });
const facts = await forge(ctx, release, prUrl);
const base = await comparison(ctx, release, prUrl, snapshot, policy, facts);
const checkoutIdentity = await readRetirementCheckoutIdentity(release.path);
if (release.checkoutIdentity && release.checkoutIdentity !== checkoutIdentity) fail('checkout-identity-changed');
const evidence = { ...base, mode: wholeCheckout ? 'whole-checkout' : 'initialized-private-modules', snapshot,
...(checkoutIdentity && { checkoutIdentity }), ...(checkoutIncarnation && { checkoutIncarnation }) };
delete evidence.digest;
return { ctx, review: { digest: hash(evidence), ...evidence } };
};
const review = input => fenced(async () => {
const ctx = await context(input.appId, input.release);
return (await admission()).withCheckoutPublication(ctx.repoPath, async () => ({ ok: true, ...(await makeReview(input)) }));
}).then(({ review: result }) => ({ ok: true, review: result }), error => ({ ok: false, reason: error.message }));
const assertReview = (current, accepted) => {
if (current.digest !== accepted.digest) fail('retirement-review-changed');
if (current.comparison.disposition === 'review-supersession' && accepted.acceptSuperseded !== true) fail('retirement-supersession-not-accepted');
};
const location = id => {
if (!/^[a-f0-9-]{36}$/.test(id)) fail('retirement-transaction-invalid');
return join(root(), id);
};
const retire = input => fenced(async () => {
// A locked registration is not disposable. worktree remove --force leaves it
// registered, and the directory fallback would delete the tree anyway.
if (input.release?.locked === true) return { ok: false, reason: 'checkout-locked' };
const prepared = await makeReview({ ...input, prUrl: input.review.prUrl });
assertReview(prepared.review, input.review);
const { ctx } = prepared;
if (prepared.review.comparison?.disposition !== 'integrated') return { ok: false, reason: 'not-merged-on-recheck' };
// Captured by makeReview before removal. A later lstat of a deleted .git is null.
const checkoutIdentity = prepared.review.checkoutIdentity || input.release.checkoutIdentity || null;
const runGit = deps.execGit || execGit;
const status = await runGit(['status', '--porcelain'], input.release.path, { ignoreExitCode: true }).catch(() => null);
if (!status || status.exitCode !== 0) return { ok: false, reason: 'worktree-status-unavailable' };
if (String(status.stdout || '').trim()) return { ok: false, reason: 'worktree-dirty' };
const removed = await runGit(['worktree', 'remove', '--force', input.release.path], ctx.repoPath, { ignoreExitCode: true }).catch(() => null);
if (!removed || removed.exitCode !== 0) {
const top = await runGit(['rev-parse', '--show-toplevel'], input.release.path, { ignoreExitCode: true }).catch(() => null);
const toplevel = String(top?.stdout || '').trim();
if (!top || top.exitCode !== 0 || !toplevel) return { ok: false, reason: 'checkout-not-removed' };
const { resolve } = await import('node:path');
const { rm } = await import('node:fs/promises');
if (resolve(toplevel) !== resolve(input.release.path)) return { ok: false, reason: 'checkout-not-removed' };
await rm(input.release.path, { recursive: true, force: false });
await runGit(['worktree', 'prune'], ctx.repoPath, { ignoreExitCode: true }).catch(() => null);
}
let branchDeleted = false;
if (input.release.branch) {
const deleteRef = deps.deleteRef || (await import('./worktreeManager.js')).deleteCompletedLocalBranch;
branchDeleted = await deleteRef(ctx.repoPath, input.release.branch, input.release.head, {}) === true;
}
const record = deps.recordRetirement || (await import('./taskSchedule.js')).recordHeldCheckoutRetirement;
let outcome = null;
try {
outcome = await record(input.appId, {
path: input.release.path, branch: input.release.branch ?? null, head: input.release.head, branchDeleted,
...(checkoutIdentity && { checkoutIdentity }),
});
} catch {
return { ok: false, reason: 'retirement-receipt-unverified', branchDeleted };
}
const wantedBranch = input.release.branch ?? null;
const recorded = outcome?.retired?.some(row => (row.path || null) === (input.release.path || null)
&& (row.branch ?? null) === wantedBranch && row.head === input.release.head
&& row.branchDeleted === true && row.archiveDir == null
&& (!checkoutIdentity || row.checkoutIdentity === checkoutIdentity)) === true;
if (!recorded) return { ok: false, reason: 'retirement-receipt-unverified', branchDeleted };
return { ok: true, branchDeleted };
}).catch(error => ({ ok: false, reason: error.message }));
const loadBoundTransaction = async input => {
const directory = location(input.transactionId);
const state = await readJournal(directory);
if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');
const ctx = await context(input.appId);
if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
return { directory, state, ctx };
};
const quarantineProofInput = ({ directory, state, ctx }) => {
const accepted = state.quarantineResumptionReview;
const unsigned = { ...accepted };
delete unsigned.digest;
if (!accepted || accepted.digest !== hash(unsigned) || accepted.mode !== 'resume-initialized-quarantine'
|| accepted.transactionId !== state.id || accepted.repoPath !== ctx.repoPath
|| !sameRelease(accepted.release, state.release) || !state.proof?.manifestSha256
|| !accepted.quarantineResumption) fail('quarantine-resumption-evidence-missing');
return { transactionDir: directory, manifestSha256: state.proof.manifestSha256,
quarantineResumption: accepted.quarantineResumption };
};
const branchReview = async ({ directory, state, ctx }) => {
const transitioned = Boolean(state.quarantineResumptionReview);
if (!['quarantined', 'quarantined-with-metadata-transitions', 'branch-retirement-prepared'].includes(state.phase) || state.branchDeleted) fail('retirement-branch-phase-not-ready');
const policy = await ensureOwner(ctx, state.release, false, state.review);
const proof = await native(transitioned
? { command: 'verify-completed-quarantine', ...quarantineProofInput({ directory, state, ctx }) }
: { command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
if ((transitioned && (proof.verified !== true || proof.quarantineResumptionAccepted !== true))
|| ['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;
if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');
const runGit = deps.execGit || execGit;
const head = await runGit(['rev-parse', '--verify', `refs/heads/${state.release.branch}`], ctx.repoPath, { ignoreExitCode: true });
if (head.exitCode !== 0 || head.stdout.trim() !== state.release.head) fail('branch-ref-changed');
const facts = await forge(ctx, state.release, state.review.forge.prUrl);
const base = await comparison(ctx, state.release, facts.prUrl, state.review.snapshot, policy, facts);
if (JSON.stringify(await ensureOwner(ctx, state.release, false, state.review)) !== JSON.stringify(policy)) fail('retirement-evidence-changed');
const evidence = { ...base, mode: 'quarantined-branch', transactionId: state.id,
journalDigest: hash(state), archiveFingerprint: proof.fingerprint,
...(transitioned ? { quarantineResumptionReview: state.quarantineResumptionReview,
quarantineResumptionObservation: state.quarantineResumptionObservation ?? null } : {}) };
delete evidence.digest;
return { digest: hash(evidence), ...evidence };
};
const reviewBranch = input => fenced(async () => {
const executor = await native({ command: 'lock', transactionDir: location(input.transactionId) }, { keepOpen: true });
try {
const bound = await loadBoundTransaction(input);
const gate = await admission();
const work = async () => {
executor.assertHeld();
if (hash(await readJournal(bound.directory)) !== hash(bound.state)) fail('retirement-journal-changed');
return { ok: true, review: await branchReview(bound) };
};
if (bound.state.phase === 'branch-retirement-prepared') {
const reservation = await gate.readCheckoutReservation(bound.ctx.repoPath, bound.state.id);
if (JSON.stringify(reservation) !== JSON.stringify(bound.state.reservation)) fail('retirement-reservation-changed');
return await gate.withCheckoutReservation(reservation, work);
}
return await gate.withCheckoutPublication(bound.ctx.repoPath, work);
} finally { await executor.release(); }
}).catch(error => ({ ok: false, reason: error.message }));
// A receiver success was fsynced before recording the schedule receipt. Replay
// only those completed phases: this never issues a Git mutation or recreates
// a ref, and still refuses a new branch/holder or changed archive.
const finishBranchReceipt = async ({ directory, ctx, state }, beforeMutation) => {
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
const gate = await admission();
try {
if (hash(await readJournal(directory)) !== hash(state)) fail('retirement-journal-changed');
const verify = async () => {
executor.assertHeld();
await ensureOwner(ctx, state.release, false, state.review);
let placement;
if (state.quarantineResumptionReview) {
placement = await native({ command: 'verify-retired-quarantine', ...quarantineProofInput({ directory, state, ctx }),
confirmedDeletion: { journalDigest: hash(state), branch: state.release.branch, head: state.release.head, phase: state.phase } });
} else {
await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'standalone' });
placement = await native({ command: 'status', manifestSha256: state.proof?.manifestSha256, transactionDir: directory });
}
if ((state.quarantineResumptionReview && (placement.verified !== true || placement.quarantineResumptionAccepted !== true))
|| ['working', 'administration'].some(part => placement.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;
if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');
const absence = await native({ command: 'verify-deleted-branch', transactionDir: directory,
manifestSha256: state.proof?.manifestSha256, confirmedDeletion: { journalDigest: hash(state),
branch: state.release.branch, head: state.release.head, phase: state.phase } });
if (absence.verified !== true || absence.branchAbsent !== true) fail('retirement-deleted-branch-not-absent');
await ensureOwner(ctx, state.release, false, state.review);
executor.assertHeld();
};
const reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(error => {
if (error.code === 'ENOENT' && state.phase === 'retired' && state.receiptRecorded === true) return null;
throw error;
});
if (reservation && JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('retirement-reservation-changed');
const finish = async () => {
await verify();
await beforeMutation();
if (state.phase === 'branch-retired') {
const record = deps.recordRetirement || (await import('./taskSchedule.js')).recordHeldCheckoutRetirement;
await record(state.appId, { path: state.release.path, branch: state.release.branch,
head: state.release.head, branchDeleted: true, archiveDir: directory,
...(state.review.checkoutIdentity && { checkoutIdentity: state.review.checkoutIdentity }) });
state = await appendStep(directory, state, 'retired', { receiptRecorded: true });
}
await beforeMutation();
if (reservation) await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, branchDeleted: true, receiptRecorded: true, archiveDir: directory };
};
return reservation ? await gate.withCheckoutReservation(reservation, finish)
: await gate.withCheckoutPublication(ctx.repoPath, finish);
} finally { await executor.release(); }
};
const retireBranch = (input, { beforeMutation = async () => {} } = {}) => fenced(async () => {
const bound = await loadBoundTransaction(input);
const { directory, ctx } = bound;
let { state } = bound;
if (['branch-retired', 'retired'].includes(state.phase) && state.branchDeleted === true) return finishBranchReceipt(bound, beforeMutation);
// An interrupted receiver may have completed without its journal result.
// It is an explicit uncertainty hold, never permission to recreate a ref.
if (state.phase === 'branch-retirement-intent') fail('retirement-branch-deletion-uncertain');
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
const gate = await admission();
try {
if (hash(await readJournal(directory)) !== hash(state)) fail('retirement-journal-changed');
executor.assertHeld();
let reservation, current;
const prepared = state.phase === 'branch-retirement-prepared';
if (prepared) {
reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id);
if (JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('retirement-reservation-changed');
} else {
current = await branchReview(bound);
assertReview(current, input.review);
await beforeMutation();
reservation = await gate.reserveCheckoutRetirement(ctx.repoPath, state.id);
// Durable preparation binds this new cut before lengthy verification or
// branch archival. It grants no deletion and can be reviewed after restart.
state = await appendStep(directory, state, 'branch-retirement-prepared', { reservation });
}
return await gate.withCheckoutReservation(reservation, async () => {
const fresh = await branchReview({ ...bound, state });
if (prepared) assertReview(fresh, input.review);
else {
const evidence = value => { const { digest: _digest, journalDigest: _journal, ...rest } = value; return rest; };
// Only our just-published journal transition changed. Every substantive
// source/archive/forge/owner field must equal the accepted review.
if (JSON.stringify(evidence(fresh)) !== JSON.stringify(evidence(current))) fail('retirement-evidence-changed');
}
current = fresh;
executor.assertHeld();
await beforeMutation();
const remove = deps.deleteRef || (await import('./worktreeManager.js')).deleteCompletedLocalBranch;
let receiverAuthorized = false;
const deleted = await remove(ctx.repoPath, state.release.branch, state.release.head, { beforeMutation: async () => {
executor.assertHeld();
if (JSON.stringify(await ensureOwner(ctx, state.release, false, state.review)) !== JSON.stringify(current.policy)
|| JSON.stringify(await forge(ctx, state.release, state.review.forge.prUrl)) !== JSON.stringify(current.forge)) fail('retirement-evidence-changed');
await beforeMutation();
executor.assertHeld();
state = await appendStep(directory, state, 'branch-retirement-intent', { reservation, branchReview: current });
receiverAuthorized = true;
await beforeMutation();
executor.assertHeld();
} });
if (!deleted) fail('retirement-branch-delete-refused-or-uncertain');
if (!receiverAuthorized) fail('retirement-branch-receiver-intent-missing');
state = await appendStep(directory, state, 'branch-retired', { branchDeleted: true, branchRetainedReason: null });
await beforeMutation();
const record = deps.recordRetirement || (await import('./taskSchedule.js')).recordHeldCheckoutRetirement;
await record(state.appId, { path: state.release.path, branch: state.release.branch,
head: state.release.head, branchDeleted: true, archiveDir: directory,
...(state.review.checkoutIdentity && { checkoutIdentity: state.review.checkoutIdentity }) });
state = await appendStep(directory, state, 'retired', { receiptRecorded: true });
await beforeMutation();
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, branchDeleted: true, receiptRecorded: true, archiveDir: directory };
});
} finally { await executor.release(); }
}).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
const status = async ({ appId, transactionId }) => {
const directory = location(transactionId);
const state = await readJournal(directory);
const ctx = await context(appId);
if (state.appId !== appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
const hasManifest = await lstat(join(directory, 'manifest.json')).then(() => true, error => {
if (error.code === 'ENOENT') return false;
throw error;
});
// A manifest can be durable before its proof reaches the journal. Only a
// proven pre-move phase may expose cancellation metadata without trusting
// that archive; restore still requires a fresh, unchanged-source inspect.
const unboundPreservation = hasManifest && !state.proof?.manifestSha256
&& ['intent', 'reserved', 'preserved'].includes(state.phase);
const cancelledUnboundPreservation = state.phase === 'restored' && state.cancelledUnboundPreservation === true;
const placement = unboundPreservation || (hasManifest && cancelledUnboundPreservation) ? { preserved: false, unverifiedArchive: true }
: hasManifest ? await native({ command: 'status', manifestSha256: state.proof?.manifestSha256, transactionDir: directory }) : { preserved: false };
let branchRef;
if (state.phase === 'branch-retirement-intent') {
const result = await (deps.execGit || execGit)(['show-ref', '--verify', '--quiet', `refs/heads/${state.release.branch}`], ctx.repoPath, { ignoreExitCode: true }).catch(() => null);
branchRef = result?.exitCode === 0 ? 'present' : result?.exitCode === 1 ? 'absent' : 'unreadable';
}
return { ok: true, transactionId, phase: state.phase, release: state.release, placement,
branchDeleted: state.branchDeleted ?? null, journalDigest: hash(state),
...(unboundPreservation ? { recoveryRequired: true, recoveryAction: 'restore', reason: 'preservation-proof-unbound' } : {}),
...(state.phase === 'branch-retirement-intent' ? { branchDeletion: 'uncertain', branchRef, recoveryRequired: true } : {}),
...(state.phase === 'branch-retired' ? { receiptPending: true, recoveryRequired: true } : {}),
...(state.phase === 'branch-retirement-prepared' ? { recoveryRequired: true, recoveryAction: 'review-branch' } : {}),
...(state.quarantineResumptionReview ? { quarantineResumption: state.quarantineResumptionReview.quarantineResumption,
quarantineResumptionComplete: state.phase === 'quarantined-with-metadata-transitions' } : {}),
...(state.metadataRestoreReview ? { metadataRecovery: state.metadataRestoreReview.metadataRecovery,
metadataChangeCounts: state.metadataRestoreReview.changeCounts,
metadataRestored: state.phase === 'restored-with-metadata-transitions' } : {}),
...(state.restoredFinalizationReview ? {
restoredFinalization: state.restoredFinalizationReview.restoredFinalization,
restoredFinalizationComplete: state.phase === 'restored-with-reviewed-finalization',
} : {}),
...(['branch-retired', 'retired'].includes(state.phase) ? { recoveryAction: 'retire-branch' } : {}) };
};
const verifyArchive = async input => {
const directory = location(input.transactionId);
const state = await readJournal(directory);
if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');
const ctx = await context(input.appId);
if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
const proof = await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'standalone' });
return { ok: true, transactionId: state.id, standaloneCheckoutPath: proof.restorePath,
verified: true, branchDeleted: state.branchDeleted ?? false, proof };
};
const verifyMissingPreservation = async ({ appId, repoPath, release, archiveDir }) => {
const directory = location(archiveDir.split(/[\\/]/).at(-1));
if (directory !== archiveDir) fail('archive-location-mismatch');
const state = await readJournal(directory, { bounded: true });
if (state.appId !== appId || state.repoPath !== repoPath || !sameRelease(state.release, release)) fail('archive-identity-mismatch');
if (!['branch-retired', 'retired'].includes(state.phase) || state.branchDeleted !== true) fail('archive-retirement-unconfirmed');
const archivedAt = state.reservation?.owner?.startedAt;
if (!(Date.parse(archivedAt) >= Date.parse(release.createdAt)) || Date.parse(archivedAt) > Date.now()) fail('archive-generation-mismatch');
// Every archive mutation takes this execution fence. Keep it until the
// schedule writer accepts or refuses the evidence, not just through verify.
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
try {
if (hash(await readJournal(directory, { bounded: true })) !== hash(state)) fail('retirement-journal-changed');
// The journal locates the manifest; the existing native verifier checks its
// digest, every preserved source and the standalone object closure.
const manifestPath = join(directory, 'manifest.json');
const info = await lstat(manifestPath);
if (!info.isFile() || info.isSymbolicLink() || info.size > 16 * 1024 * 1024) fail('archive-manifest-invalid');
const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
if (manifest.facts?.repoPath !== repoPath || !sameRelease(manifest.facts?.release, release)) fail('archive-identity-mismatch');
const result = await verifyArchive({ appId, transactionId: state.id, journalDigest: hash(state) });
if (result.proof?.verified !== true || result.proof?.standalone !== true) fail('archive-preservation-unverified');
if (hash(await readJournal(directory, { bounded: true })) !== hash(state)) fail('retirement-journal-changed');
const recheck = async () => {
executor.assertHeld();
const unchanged = hash(await readJournal(directory, { bounded: true })) === hash(state)
&& createHash('sha256').update(await readFile(manifestPath)).digest('hex') === state.proof.manifestSha256;
executor.assertHeld();
return unchanged;
};
return { repoPath, archiveDir: directory, archivedAt, evidenceDigest: state.proof.manifestSha256, kind: 'initialized', recheck,
releaseFence: () => executor.release() };
} catch (error) { await executor.release(); throw error; }
};
// Explicit recovery restores the exact original inodes. It does not erase
// archives or auto-finish an interrupted ref deletion on stale forge evidence.
const restore = (input, { cancelOnly = false } = {}) => fenced(async () => {
const directory = location(input.transactionId);
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
const gate = await admission();
try {
let state = await readJournal(directory);
if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');
if (cancelOnly && (state.proof?.manifestSha256 || !(['intent', 'reserved'].includes(state.phase)
|| (state.phase === 'restored' && state.cancelledUnboundPreservation === true)))) fail('retirement-cancellation-phase-invalid');
const ctx = await context(input.appId);
if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
await ensureOwner(ctx, state.release, false, state.review);
// A completed quarantine released its cut. An interrupted one retains it.
let newReservation = false;
const reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(async error => {
if (error.code !== 'ENOENT') throw error;
if (['intent', 'reserved', 'preserved'].includes(state.phase) && state.reservation) fail('retirement-reservation-missing');
newReservation = true;
return gate.reserveCheckoutRetirement(ctx.repoPath, state.id);
});
return await gate.withCheckoutReservation(reservation, async () => {
// Preservation can fail before a native manifest exists. No move is
// ever attempted before its fsynced intent; only those early phases
// may cancel the cut. Explicit cancellation proves placement without
// reading/hydrating working bytes; it neither restores nor certifies them.
if (['intent', 'reserved', 'preserved'].includes(state.phase)
|| (state.phase === 'restored' && state.cancelledUnboundPreservation === true)) {
if (state.phase !== 'restored' && !newReservation && state.reservation
&& JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('retirement-reservation-changed');
let cancellationProof;
if (cancelOnly) {
cancellationProof = await native({ command: 'verify-original-placement',
repoPath: ctx.repoPath, release: state.release, transactionDir: directory,
expected: state.review.snapshot });
if (cancellationProof.verified !== true || cancellationProof.originalsUnmoved !== true
|| cancellationProof.archiveVerified !== false || cancellationProof.contentAndMetadataUnverified !== true
|| cancellationProof.partialArchivesRetained !== true) fail('retirement-cancellation-proof-invalid');
} else {
const snapshot = await native({ command: 'inspect', repoPath: ctx.repoPath, release: state.release,
...(state.review.snapshot.wholeCheckout && { wholeCheckout: true }) });
if (JSON.stringify(snapshot) !== JSON.stringify(state.review.snapshot)) {
// Ordinary restore retains its original unchanged-content proof.
if (state.proof?.manifestSha256 || state.phase === 'preserved') fail('retirement-source-changed');
cancellationProof = await native({ command: 'verify-unmoved-preservation',
repoPath: ctx.repoPath, release: state.release, transactionDir: directory,
expected: state.review.snapshot });
if (cancellationProof.verified !== true || cancellationProof.originalsUnmoved !== true) fail('retirement-source-changed');
}
}
await ensureOwner(ctx, state.release, true, state.review);
executor.assertHeld();
state = await appendStep(directory, state, 'restored', { reservation,
cancelledUnboundPreservation: !state.proof?.manifestSha256,
...(cancellationProof ? { cancellationProof } : {}) });
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, restored: true, archivesRetained: true,
...(cancelOnly ? { cancelled: true, archiveVerified: false, contentAndMetadataUnverified: true } : {}) };
}
const { listWorktrees } = await import('./worktreeManager.js');
const trees = await (deps.listWorktrees || listWorktrees)(ctx.repoPath);
if (trees.some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch && tree.path !== state.release.path)) fail('branch-has-new-holder');
await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
const ref = `refs/heads/${state.release.branch}`;
const runGit = deps.execGit || execGit;
const existing = await runGit(['rev-parse', '--verify', ref], ctx.repoPath, { ignoreExitCode: true });
if (existing.exitCode !== 0 || existing.stdout.trim() !== state.release.head) fail('branch-ref-changed');
for (const part of ['administration', 'working']) {
executor.assertHeld();
state = await appendStep(directory, state, `restore-${part}-intent`, { reservation });
await native({ command: 'move', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, part, direction: 'restore' });
state = await appendStep(directory, state, `restored-${part}`);
}
await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
state = await appendStep(directory, state, 'restored');
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, restored: true, archivesRetained: true };
});
} finally { await executor.release(); }
}).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
const metadataRestoreSafety = async ({ ctx, state }) => {
const policy = await ensureOwner(ctx, state.release, false, state.review);
const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;
if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch
&& tree.path !== state.release.path)) fail('branch-has-new-holder');
const head = await (deps.execGit || execGit)(['rev-parse', '--verify', `refs/heads/${state.release.branch}`],
ctx.repoPath, { ignoreExitCode: true });
if (head.exitCode !== 0 || head.stdout.trim() !== state.release.head) fail('branch-ref-changed');
return policy;
};
const metadataReview = async bound => {
const { directory, state, ctx } = bound;
const allowed = ['quarantine-working-intent', 'quarantined-working', 'quarantine-administration-intent',
'quarantined-administration', 'quarantined', 'restore-administration-intent', 'restored-administration',
'restore-working-intent', 'restored-working', 'metadata-restore-approved', 'metadata-restore-administration-intent',
'metadata-restored-administration', 'metadata-restore-working-intent', 'metadata-restored-working',
'restored-with-metadata-transitions'];
if (!allowed.includes(state.phase) || state.branchDeleted || !state.proof?.manifestSha256) fail('metadata-recovery-phase-not-ready');
const policy = await metadataRestoreSafety(bound);
const proof = await native({ command: 'review-metadata-recovery', transactionDir: directory,
manifestSha256: state.proof.manifestSha256 });
const evidence = { version: 1, mode: 'restore-metadata-only', transactionId: state.id,
repoPath: ctx.repoPath, release: state.release, journalDigest: hash(state), phase: state.phase, policy,
metadataRecovery: proof.metadataRecovery, initialPlacements: proof.initialPlacements,
changeCounts: proof.changeCounts, changedPaths: proof.changedPaths };
return { digest: hash(evidence), ...evidence };
};
// The CLI uses this same path before an update can be deployed. Its local
// ownership tail is not a cross-process lock: native execution.lock and the
// exact existing publication cut must both remain held for the entire action.
const withMetadataRestore = (input, work) => fenced(async () => {
const directory = location(input.transactionId);
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
try {
const bound = await loadBoundTransaction(input);
const gate = await admission();
const reservation = await gate.readCheckoutReservation(bound.ctx.repoPath, bound.state.id);
return await gate.withCheckoutReservation(reservation, async () => {
executor.assertHeld();
if (hash(await readJournal(directory)) !== hash(bound.state)) fail('retirement-journal-changed');
return work(bound, { executor, gate, reservation });
});
} finally { await executor.release(); }
}).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
const reviewMetadataRestore = input => withMetadataRestore(input,
async bound => ({ ok: true, review: await metadataReview(bound) }));
const restoreMetadata = input => withMetadataRestore(input, async (bound, { executor, gate, reservation }) => {
const current = await metadataReview(bound);
if (current.digest !== input.review?.digest) fail('metadata-recovery-review-changed');
if (current.initialPlacements.working === 'original' && current.initialPlacements.administration === 'original'
&& bound.state.metadataRestoreReview && bound.state.metadataRestoreObservations?.some(row => row.part === 'working' && row.proof)) {
restoredFinalizationInputs(bound);
fail('metadata-recovery-already-restored-use-finalization');
}
const { directory } = bound;
let state = await appendStep(directory, bound.state, 'metadata-restore-approved',
{ metadataRestoreReview: current, metadataRestoreObservations: [], reservation });
const proof = { transactionDir: directory, manifestSha256: state.proof.manifestSha256,
metadataRecovery: current.metadataRecovery };
for (const part of ['administration', 'working']) {
executor.assertHeld();
const policy = await metadataRestoreSafety({ ...bound, state });
if (JSON.stringify(policy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');
state = await appendStep(directory, state, `metadata-restore-${part}-intent`);
const moved = await native({ command: 'move', ...proof, part, direction: 'restore' });
state = await appendStep(directory, state, `metadata-restored-${part}`, {
metadataRestoreObservations: [...(state.metadataRestoreObservations || []), { part, proof: moved.postMoveObservation }],
});
}
await native({ command: 'verify', ...proof, mode: 'restore' });
const finalPolicy = await metadataRestoreSafety({ ...bound, state });
if (JSON.stringify(finalPolicy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');
executor.assertHeld();
state = await appendStep(directory, state, 'restored-with-metadata-transitions');
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, phase: state.phase, restored: true, archivesRetained: true,
metadataTransitionsPreserved: true, metadataRecovery: current.metadataRecovery, archiveDir: directory };
});
const quarantineSafety = async (bound, administrationQuarantined = false) => {
const { ctx, state } = bound;
const policy = await metadataRestoreSafety(bound);
if (administrationQuarantined) {
const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;
if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');
}
const facts = await forge(ctx, state.release, state.review.forge.prUrl);
const evidence = await comparison(ctx, state.release, facts.prUrl, state.review.snapshot, policy, facts);
const result = { ...evidence, policy, forge: facts };
delete result.digest;
return result;
};
const quarantineReview = async (bound, reservation) => {
const { state, directory, ctx } = bound;
const allowed = ['quarantine-working-intent', 'quarantined-working', 'quarantine-administration-intent',
'quarantined-administration', 'quarantined', 'quarantine-resumption-approved', 'quarantine-resumption-administration-intent',
'quarantine-resumption-administration-complete', 'quarantined-with-metadata-transitions'];
if (!allowed.includes(state.phase) || state.branchDeleted || !state.proof?.manifestSha256) fail('quarantine-resumption-phase-not-ready');
if (JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('quarantine-resumption-reservation-changed');
const before = await quarantineSafety(bound);
const proof = await native({ command: 'review-quarantine-resumption', transactionDir: directory,
manifestSha256: state.proof.manifestSha256 });
if (proof.initialPlacements?.working !== 'quarantine'
|| !['original', 'quarantine'].includes(proof.initialPlacements?.administration)) fail('quarantine-resumption-placement-not-ready');
const current = await quarantineSafety(bound, proof.initialPlacements.administration === 'quarantine');
if (JSON.stringify(current) !== JSON.stringify(before)) fail('retirement-evidence-changed');
// Retain the complete comparison once. This separate hash also binds the
// exact safety projection re-read between moves without duplicating patches.
const evidence = { ...current, safetyEvidenceDigest: hash(current), version: 1, mode: 'resume-initialized-quarantine', transactionId: state.id,
repoPath: ctx.repoPath, release: state.release, journalDigest: hash(state), phase: state.phase, reservation,
quarantineResumption: proof.quarantineResumption, initialPlacements: proof.initialPlacements,
changeCounts: proof.changeCounts, changedPaths: proof.changedPaths };
return { digest: hash(evidence), ...evidence };
};
const reviewQuarantineResumption = input => withMetadataRestore(input,
async (bound, { reservation }) => ({ ok: true, review: await quarantineReview(bound, reservation) }));
const resumeQuarantine = (input, { beforeMutation: mutationGuard } = {}) => withMetadataRestore(input, async (bound, { executor, gate, reservation }) => {
const beforeMutation = mutationGuard || (async () => {});
const current = await quarantineReview(bound, reservation);
assertReview(current, input.review);
await beforeMutation();
const { directory } = bound;
let state = await appendStep(directory, bound.state, 'quarantine-resumption-approved',
{ quarantineResumptionReview: current, quarantineResumptionObservation: null });
const proof = quarantineProofInput({ ...bound, state });
const assertSafety = async administrationQuarantined => {
const fresh = await quarantineSafety({ ...bound, state }, administrationQuarantined);
if (hash(fresh) !== current.safetyEvidenceDigest) fail('retirement-evidence-changed');
executor.assertHeld();
await beforeMutation();
};
await assertSafety(current.initialPlacements.administration === 'quarantine');
await native({ command: 'verify-quarantine-resumption', ...proof });
if (current.initialPlacements.administration === 'original') {
await assertSafety(false);
state = await appendStep(directory, state, 'quarantine-resumption-administration-intent');
await beforeMutation();
const moved = await native({ command: 'resume-quarantine', ...proof }, mutationGuard ? { beforeMutation: async () => {
executor.assertHeld();
await assertSafety(false);
executor.assertHeld();
} } : undefined);
if (moved.moved !== true || !moved.postMoveObservation?.file
|| !/^[a-f0-9]{64}$/.test(moved.postMoveObservation.sha256 || '')
|| !/^[a-f0-9]{64}$/.test(moved.postMoveObservation.digest || '')) fail('quarantine-postmove-evidence-missing');
state = await appendStep(directory, state, 'quarantine-resumption-administration-complete',
{ quarantineResumptionObservation: moved.postMoveObservation ?? null });
}
const complete = await native({ command: 'verify-completed-quarantine', ...proof });
if (complete.verified !== true || complete.quarantineResumptionAccepted !== true || ['working', 'administration'].some(part => complete.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
await assertSafety(true);
state = await appendStep(directory, state, 'quarantined-with-metadata-transitions',
{ branchDeleted: false, branchRetainedReason: 'quarantined-checkout-rollback-ref' });
await beforeMutation();
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, phase: state.phase, originalsQuarantined: true,
branchDeleted: false, branchRetainedReason: state.branchRetainedReason, archiveDir: directory };
});
const restoredFinalizationInputs = ({ directory, state, ctx }) => {
const prior = state.metadataRestoreReview;
const observations = state.metadataRestoreObservations;
const unsigned = { ...prior };
delete unsigned.digest;
if (!state.proof?.manifestSha256 || state.branchDeleted || !prior
|| prior.mode !== 'restore-metadata-only' || prior.digest !== hash(unsigned)
|| prior.transactionId !== state.id || prior.repoPath !== ctx.repoPath || !sameRelease(prior.release, state.release)
|| !Array.isArray(observations) || observations.length !== 2
|| observations.some((row, index) => row?.part !== ['administration', 'working'][index]
|| (row.proof == null ? index !== 0 || prior.initialPlacements?.administration !== 'original'
: !/^[a-f0-9]{64}$/.test(row.proof.sha256 || '')
|| !/^[a-f0-9]{64}$/.test(row.proof.digest || '')))) fail('restored-finalization-evidence-missing');
return { transactionDir: directory, manifestSha256: state.proof.manifestSha256,
metadataRecovery: prior.metadataRecovery, postMoveObservations: observations.map(row => row.proof ?? null) };
};
// A separate endpoint can acknowledge a narrowly reviewed post-restoration
// transition. It never passes that permission to a move or ordinary verifier.
const finalizationReview = async (bound, reservation) => {
const { state, ctx } = bound;
if (!['metadata-restored-working', 'restored-finalization-approved'].includes(state.phase)) fail('restored-finalization-phase-not-ready');
const input = restoredFinalizationInputs(bound);
const policy = await metadataRestoreSafety(bound);
const proof = await native({ command: 'review-restored-finalization', ...input });
if (proof.placements?.working !== 'original' || proof.placements?.administration !== 'original') fail('restored-finalization-originals-not-restored');
const evidence = { version: 1, mode: 'finalize-already-restored', transactionId: state.id,
repoPath: ctx.repoPath, release: state.release, journalDigest: hash(state), phase: state.phase, policy,
reservation, priorMetadataRestoreReview: state.metadataRestoreReview,
postMoveObservations: state.metadataRestoreObservations, restoredFinalization: proof.restoredFinalization,
placements: proof.placements, changeCounts: proof.changeCounts, changedPaths: proof.changedPaths };
return { digest: hash(evidence), ...evidence };
};
const withRestoredFinalization = (input, work, allowReleased = false) => fenced(async () => {
const directory = location(input.transactionId);
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
try {
const bound = await loadBoundTransaction(input);
const gate = await admission();
const reservation = await gate.readCheckoutReservation(bound.ctx.repoPath, bound.state.id).catch(error => {
if (error.code === 'ENOENT' && allowReleased && bound.state.phase === 'restored-with-reviewed-finalization') return null;
throw error;
});
if (reservation && JSON.stringify(reservation) !== JSON.stringify(bound.state.reservation)) fail('restored-finalization-reservation-changed');
const run = async () => {
executor.assertHeld();
if (hash(await readJournal(directory)) !== hash(bound.state)) fail('retirement-journal-changed');
return work(bound, { executor, gate, reservation });
};
return reservation ? await gate.withCheckoutReservation(reservation, run)
: await gate.withCheckoutPublication(bound.ctx.repoPath, run);
} finally { await executor.release(); }
}).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
const reviewRestoredFinalization = input => withRestoredFinalization(input,
async (bound, { reservation }) => ({ ok: true, review: await finalizationReview(bound, reservation) }));
const finalizeRestored = input => withRestoredFinalization(input, async (bound, { executor, gate, reservation }) => {
const { directory } = bound;
let state = bound.state;
const replay = state.phase === 'restored-with-reviewed-finalization';
const current = replay ? state.restoredFinalizationReview : await finalizationReview(bound, reservation);
const unsigned = { ...current };
delete unsigned.digest;
if (!current || current.mode !== 'finalize-already-restored' || current.digest !== hash(unsigned)
|| current.digest !== input.review?.digest) fail('restored-finalization-review-changed');
if (!replay) state = await appendStep(directory, state, 'restored-finalization-approved', { restoredFinalizationReview: current });
const policy = await metadataRestoreSafety({ ...bound, state });
if (JSON.stringify(policy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');
executor.assertHeld();
const proof = await native({ command: 'verify-restored-finalization', ...restoredFinalizationInputs({ ...bound, state }),
restoredFinalization: current.restoredFinalization });
if (proof.verified !== true || proof.alreadyRestored !== true || proof.restoredFinalizationAccepted !== true
|| ['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'original')) fail('restored-finalization-proof-refused');
const finalPolicy = await metadataRestoreSafety({ ...bound, state });
if (JSON.stringify(finalPolicy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');
executor.assertHeld();
if (!replay) state = await appendStep(directory, state, 'restored-with-reviewed-finalization');
if (reservation) await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, phase: state.phase, restored: true, alreadyRestored: true,
archivesRetained: true, metadataTransitionsPreserved: true, restoredFinalization: current.restoredFinalization,
archiveDir: directory };
}, true);
const recoveryBinding = async (id, expectedDigest, budget) => {
const directory = location(id);
const state = await readJournal(directory, { bounded: true, budget });
const original = state.review;
const unsigned = { ...original }; delete unsigned.digest;
if (state.id !== id || typeof state.appId !== 'string' || !state.appId
|| !isAbsolute(state.repoPath || '') || !isAbsolute(state.release?.path || '')
|| typeof state.release?.branch !== 'string' || !state.release.branch
|| !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(state.release?.head || '')
|| !['initialized-private-modules', 'whole-checkout'].includes(original?.mode) || original.digest !== hash(unsigned)
|| !sameRelease(original.release, state.release)) fail('retirement-journal-binding-invalid');
const ctx = await context(state.appId);
if (ctx.repoPath !== state.repoPath) fail('retirement-transaction-app-mismatch');
if (expectedDigest && hash(state) !== expectedDigest) fail('retirement-journal-changed');
return { directory, state, ctx };
};
const completedWithoutCut = async ({ state, ctx }) => {
const complete = (state.phase === 'retired' && state.branchDeleted === true && state.receiptRecorded === true)
|| ['restored', 'restored-with-metadata-transitions', 'restored-with-reviewed-finalization'].includes(state.phase);
if (!complete) return false;
const gate = await admission();
const cut = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(async error => {
if (error.code === 'CHECKOUT_RETIREMENT_RESERVED') {
// A durably completed historical transaction must not consume replay
// slots merely because a different transaction now owns this repo.
// Validate and re-read that owner; never enter or release its cut.
const { directory } = await gate._checkoutAdmission(ctx.repoPath);
const ownerPath = join(directory, 'cut', 'owner.json');
const info = await lstat(ownerPath);
if (!info.isFile() || info.isSymbolicLink() || info.size > 4096
|| (hostOsType() !== 'Windows_NT' && (info.mode & 0o777) !== 0o600)) fail('retirement-reservation-owner-invalid');
const owner = JSON.parse(await readFile(ownerPath, 'utf8'));
if (owner.version !== 1 || !/^[a-f0-9-]{36}$/.test(owner.id || '') || owner.id === state.id
|| owner.generation !== owner.id || owner.kind !== 'snapshot' || !Number.isInteger(owner.pid)
|| typeof owner.startedAt !== 'string' || !Number.isFinite(Date.parse(owner.startedAt))) fail('retirement-reservation-owner-invalid');
const fresh = await gate.readCheckoutReservation(ctx.repoPath, owner.id);
if (JSON.stringify(fresh.owner) !== JSON.stringify(owner)) fail('retirement-reservation-changed');
return null;
}
if (error.code !== 'ENOENT') throw error;
// Missing owner.json inside an extant cut is uncertainty, not release.
const { directory } = await gate._checkoutAdmission(ctx.repoPath);
const exists = await lstat(join(directory, 'cut')).catch(readError => {
if (readError.code === 'ENOENT') return null;
throw readError;
});
if (exists) fail('retirement-reservation-owner-missing');
return null;
});
return cut === null;
};
// Discovery reads only journals; expensive native/forge checks happen on a
// bounded cadence in the daemon drain. A journal is a locator, never a grant.
const discover = async () => {
const rows = [];
const exists = await lstat(root()).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
if (!exists) return { ok: true, transactions: [] };
await privateDirectory(root());
const entries = await opendir(root());
const budget = { remaining: 256 * 1024 * 1024 };
let count = 0;
for await (const entry of entries) {
if (++count > 1000) return { ok: false, reason: 'retirement-discovery-budget-exceeded', transactions: [] };
if (entry.name === SPOTLIGHT_MARKER && entry.isFile()) continue;
if (!/^[a-f0-9-]{36}$/.test(entry.name)) {
rows.push({ transactionId: null, reason: 'retirement-journal-name-invalid' });
continue;
}
const row = await recoveryBinding(entry.name, undefined, budget).then(async bound => {
const { state } = bound;
const settled = await completedWithoutCut(bound).catch(() => false);
return { transactionId: state.id, appId: state.appId, repoPath: state.repoPath,
phase: state.phase, journalDigest: hash(state), release: state.release, settled };
}).catch(error => ({ transactionId: entry.name, reason: error.message }));
if (row.reason === 'retirement-discovery-budget-exceeded') return { ok: false, reason: row.reason, transactions: [] };
rows.push(row);
}
return { ok: true, transactions: rows.sort((a, b) => String(a.transactionId).localeCompare(String(b.transactionId))) };
};
const automaticReview = value => {
if (!value || value.release?.head !== value.forge?.prHead) fail('automatic-retirement-exact-pr-head-required');
if (value.comparison?.disposition !== 'integrated' || value.comparison.difference !== '') fail('automatic-retirement-independent-review-required');
};
// Only the deterministic daemon calls this continuation. It never starts a
// transaction, restores originals, adopts another cut, or accepts supersession.
const recoverAutomatically = async (input, { blocked = async () => 'automatic-retirement-gate-required' } = {}) => {
const permitted = async () => { const reason = await blocked(); if (reason) fail(reason); };
const bound = await recoveryBinding(input.transactionId, input.journalDigest);
const { state, ctx } = bound;
if (state.appId !== input.appId) fail('retirement-transaction-app-mismatch');
await permitted();
if (await completedWithoutCut(bound)) return { ok: true, alreadyComplete: true, phase: state.phase, transactionId: state.id };
if (!/^[a-f0-9]{64}$/.test(state.proof?.manifestSha256 || '')) fail('preservation-proof-unbound');
if (state.phase === 'branch-retirement-intent') fail('retirement-branch-deletion-uncertain');
if (['branch-retired', 'retired'].includes(state.phase) && state.branchDeleted === true) {
// Confirmed deletion is already authorized and durable. A changed default
// branch cannot prevent recording its receipt; this path never deletes.
return retireBranch(input, { beforeMutation: permitted });
}
const finishBranch = async current => {
await permitted();
const reviewed = await reviewBranch(current);
if (!reviewed.ok) return reviewed;
automaticReview(reviewed.review);
await permitted();
return retireBranch({ ...current, review: { digest: reviewed.review.digest } }, { beforeMutation: permitted });
};
if (state.phase === 'branch-retirement-prepared') return finishBranch(input);
const resumable = ['quarantine-working-intent', 'quarantined-working', 'quarantine-administration-intent',
'quarantined-administration', 'quarantined', 'quarantine-resumption-approved',
'quarantine-resumption-administration-intent', 'quarantine-resumption-administration-complete',
'quarantined-with-metadata-transitions'];
if (!resumable.includes(state.phase) || state.branchDeleted) fail('automatic-retirement-phase-requires-review');
const gate = await admission();
const reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(error => {
if (error.code === 'ENOENT' && ['quarantined', 'quarantined-with-metadata-transitions'].includes(state.phase)) return null;
throw error;
});
let current = input;
if (reservation) {
if (JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('retirement-reservation-changed');
const reviewed = await reviewQuarantineResumption(current);
if (!reviewed.ok) return reviewed;
automaticReview(reviewed.review);
await permitted();
const resumed = await resumeQuarantine({ ...current, review: { digest: reviewed.review.digest } }, { beforeMutation: permitted });
if (!resumed.ok) return resumed;
const fresh = await recoveryBinding(state.id);
current = { ...current, journalDigest: hash(fresh.state) };
}
return finishBranch(current);
};
const automatic = async (input, options) => recoverAutomatically(input, options)
.catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
return { discover, recoverAutomatically: automatic, review, retire, status, restore,
cancelPreservation: input => restore(input, { cancelOnly: true }), verifyArchive, verifyMissingPreservation, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata,
reviewRestoredFinalization, finalizeRestored, reviewQuarantineResumption, resumeQuarantine };
}
const recovery = _createInitializedCheckoutRecovery();
export const reviewInitializedCheckout = recovery.review;
export const retireInitializedCheckout = recovery.retire;
export const initializedCheckoutStatus = recovery.status;
export const restoreInitializedCheckout = recovery.restore;
export const verifyInitializedCheckoutArchive = recovery.verifyArchive;
export const verifyMissingInitializedCheckoutPreservation = recovery.verifyMissingPreservation;
export const reviewInitializedCheckoutBranch = recovery.reviewBranch;
export const retireInitializedCheckoutBranch = recovery.retireBranch;
export const reviewInitializedCheckoutMetadataRestore = recovery.reviewMetadataRestore;
export const restoreInitializedCheckoutMetadata = recovery.restoreMetadata;
export const reviewInitializedCheckoutRestoredFinalization = recovery.reviewRestoredFinalization;
export const finalizeInitializedCheckoutRestored = recovery.finalizeRestored;
export const reviewInitializedCheckoutQuarantineResumption = recovery.reviewQuarantineResumption;
export const resumeInitializedCheckoutQuarantine = recovery.resumeQuarantine;
export const discoverInitializedCheckoutRecoveries = recovery.discover;
export const recoverInitializedCheckoutAutomatically = recovery.recoverAutomatically;