Skip to content

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

Require complete preservation before superseded checkout retirement (#13365)

[._.]/2b05ef7a8142
diff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.js
index 5be9c16e29..89b8fbfa4e 100644
--- a/server/services/branchReconcile.js
+++ b/server/services/branchReconcile.js
@@ -1225,7 +1225,7 @@ export async function cleanupMerged(repoPath, defaultBranch, merged, { activeAge
* @returns {Promise<{reaped:string[], held:object[], skipped:{branch:string,reason:string,retryAt?:string}[]}>}
* `held` is the live entries the reap could not take, for the caller to report.
*/
-export async function reapSupersededBranches(repoPath, defaultBranch, superseded, { activeAgentIds, claimOwners, cosDir } = {}) {
+export async function reapSupersededBranches(repoPath, defaultBranch, superseded, { activeAgentIds, claimOwners, cosDir, appId = null } = {}) {
const reaped = [];
const held = [];
const skipped = [];
@@ -1256,13 +1256,23 @@ export async function reapSupersededBranches(repoPath, defaultBranch, superseded
// `prepare` copies them into the backup before anything is removed.
requireCleanWorktree: false,
// A worktree outside the managed roots is reachable here and nowhere else —
- // the verdict and the backup are the proof the location gate asks for, and
+ // the verdict, complete archive and receipt supply the preservation proof, and
// the idle floor covers a process still in the tree. See the constant.
unmanagedIdleMs: SUPERSEDED_UNMANAGED_IDLE_MS,
prepare: async () => {
const backup = await backupSupersededBranch(repoPath, b, { defaultBranch, ...(cosDir ? { cosDir } : {}) })
.catch((err) => ({ error: err.message }));
- if (!backup?.error) return backup;
+ if (!backup?.error) {
+ // No checkout is being removed. The scoped ref receiver still archives
+ // branch configuration, reflogs and complete objects before deletion.
+ if (!b.worktreePath) return backup;
+ const tree = (await listWorktrees(repoPath)).find(holder => holder.path === b.worktreePath);
+ if (!tree || tree.head !== b.tip || tree.branch !== `refs/heads/${b.branch}`) return { error: 'worktree-holder-changed' };
+ const { preserveSupersededCheckout } = await import('./heldCheckoutRecovery.js');
+ const preservation = await preserveSupersededCheckout({ appId, repoPath, tree, defaultBranch, cosDir })
+ .catch(error => ({ error: error.message }));
+ return preservation.error ? { error: preservation.error } : { ...backup, preservation };
+ }
console.error(`❌ branch-reconcile: backup failed for ${b.branch}, not reaping: ${backup.error}`);
return { error: `backup-failed: ${backup.error}` };
},
@@ -1366,7 +1376,7 @@ async function retireBranch(repoPath, b, opts) {
archive: async ({ gated }) => {
const prepared = gated.prepare ? await gated.prepare() : null;
if (prepared?.error) return { result: { ok: false, reason: prepared.error } };
- if (!gated.archiveTree) return { archive: { prepared } };
+ if (!gated.archiveTree) return { archive: { prepared, preservation: prepared?.preservation || null } };
const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
return preserveMergedCheckout(repoPath, gated.archiveTree, gated.mergeTarget).then(preservation => ({ archive: { prepared, preservation } }),
error => ({ result: { ok: false, reason: 'archive-failed', detail: error.message } }));
@@ -1386,6 +1396,7 @@ async function admitBranchRetirement(repoPath, b, { activeAgentIds, staleClaimId
if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(expectedHead || '')) return stop({ ok: false, reason: mergedRetirement ? 'not-merged-on-recheck' : 'branch-head-unavailable' });
const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
const readPolicyHold = (tip = expectedHead) => readBranchCompletionHold({ repoPath, branch: b.branch, tip, retirement: mergedRetirement });
+ if (prepare && expectedHead !== b.tip) return stop({ ok: false, reason: 'branch-head-changed' });
const policyHold = await readPolicyHold();
if (policyHold) return stop({ ok: false, reason: policyHold });
let archiveTree = null;
@@ -1559,8 +1570,12 @@ async function finishBranchRetirement(repoPath, { b, expectedHead, readPolicyHol
}
const { deleteCompletedLocalBranch } = await import('./worktreeManager.js');
const deleted = await deleteCompletedLocalBranch(repoPath, b.branch, expectedHead);
- return deleted ? { ok: true, prepared, ...(preservation && { archiveDir: preservation.archiveDir }) }
- : { ok: false, reason: 'branch-ref-changed-or-delete-failed' };
+ if (!deleted) return { ok: false, reason: 'branch-ref-changed-or-delete-failed' };
+ if (prepared?.preservation) {
+ const recorded = await prepared.preservation.recordRetirement().then(() => true, () => false);
+ if (!recorded) return { ok: false, reason: 'retirement-receipt-unverified', archiveDir: preservation.archiveDir };
+ }
+ return { ok: true, prepared, ...(preservation && { archiveDir: preservation.archiveDir }) };
}
/**
@@ -1758,7 +1773,7 @@ async function reapDetachedWorktrees(repoPath, defaultBranch, detached, { active
* failed mid-cycle. Either way an empty `inFlight` says nothing about the repo
* and the caller must retry rather than park on it (#3358).
*/
-export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSuperseded = false, reapRemotes = false, activeAgentIds = new Set(), claimOwners = undefined, forgeAccount = null, pendingMergeBranches = undefined } = {}) {
+export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSuperseded = false, reapRemotes = false, activeAgentIds = new Set(), claimOwners = undefined, forgeAccount = null, pendingMergeBranches = undefined, appId = null } = {}) {
if (claimOwners === undefined) claimOwners = { agents: await readClaimOwnershipAgents(), readAgents: readClaimOwnershipAgents };
// Worktree cleanup is the first reconcile step, before any forge probe. It
// only removes a tree after proving both that it is completely clean and
@@ -1850,7 +1865,7 @@ export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSup
// the branch merged. Retain it by default; an explicit caller opt-in uses the
// backup-first retirement path and the same owner/holder gates as merged work.
const supersededReap = reapSuperseded
- ? await reapSupersededBranches(repoPath, defaultBranch, superseded, { activeAgentIds, claimOwners })
+ ? await reapSupersededBranches(repoPath, defaultBranch, superseded, { activeAgentIds, claimOwners, appId })
: { reaped: [], held: superseded, skipped: superseded.map((b) => ({ branch: b.branch, reason: 'reap-superseded-disabled' })) };
// Every WIP entry carries its `liveOwnerReason`, so a caller that needs the
// "held by a live owner" subset (to report "the only branches left belong to
diff --git a/server/services/branchReconcile.test.js b/server/services/branchReconcile.test.js
index 66c3091239..196bcca0a7 100644
--- a/server/services/branchReconcile.test.js
+++ b/server/services/branchReconcile.test.js
@@ -17,7 +17,7 @@ vi.mock('./branchCompletionPolicy.js', async () => ({
* inFlight / wip correctly).
*/
-vi.mock('./heldCheckoutRecovery.js', () => ({ preserveMergedCheckout: vi.fn(async () => ({ archiveDir: '/archive', verify: async () => null })) }));
+vi.mock('./heldCheckoutRecovery.js', () => ({ preserveSupersededCheckout: vi.fn(async () => ({ archiveDir: '/archive', verify: async () => null, recordRetirement: async () => {} })), preserveMergedCheckout: vi.fn(async () => ({ archiveDir: '/archive', verify: async () => null })) }));
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { join } from 'node:path';
@@ -1646,7 +1646,7 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
// The abandoned-worktree shape: branch fully behind main, uncommitted work in a
// dead agent's worktree, one collision path with the default branch.
- const setupAbandoned = ({ tip = 'aaaaaaa', replacedByReachable = true } = {}) => {
+ const setupAbandoned = ({ tip = RETIRE_HEAD, replacedByReachable = true } = {}) => {
git.getBranches.mockResolvedValue([
{ name: BRANCH, isDefault: false, current: false, tracking: 'origin/main', merged: false }
]);
@@ -1674,7 +1674,7 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
branch: BRANCH,
repoPath: '/repo',
verdict: 'SUPERSEDED',
- tip: 'aaaaaaa',
+ tip: RETIRE_HEAD,
dirtyPaths: ['server/services/thing.js'],
collisionPaths: ['server/services/thing.js'],
replacedBy: ['ffffff1'],
@@ -1827,7 +1827,7 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
execGit.mockImplementation(async (args) => {
if (pinnedRef(args)) return { stdout: RETIRE_HEAD, exitCode: 0 };
const [cmd] = args;
- if (cmd === 'rev-parse') return { stdout: 'aaaaaaa\n', exitCode: 0 };
+ if (cmd === 'rev-parse') return { stdout: `${RETIRE_HEAD}\n`, exitCode: 0 };
if (cmd === 'merge-base' && args[1] === '--is-ancestor') return { stdout: '', exitCode: 0 };
if (cmd === 'merge-base') return { stdout: 'base000\n', exitCode: 0 };
if (cmd === 'diff') return { stdout: 'server/services/thing.js\n', exitCode: 0 };
@@ -1838,7 +1838,7 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
tryReadFileMock.mockResolvedValue(JSON.stringify({
version: 1,
entries: [{
- branch: CLAIM, repoPath: '/repo', verdict: 'SUPERSEDED', tip: 'aaaaaaa',
+ branch: CLAIM, repoPath: '/repo', verdict: 'SUPERSEDED', tip: RETIRE_HEAD,
dirtyPaths: [], collisionPaths: ['server/services/thing.js'], replacedBy: ['ffffff1']
}]
}));
@@ -1856,12 +1856,12 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
const CLAIM_TREE = '/repo/data/cos/worktrees/claim-issue-5769';
const superseded = [{
branch: CLAIM,
- tip: 'aaaaaaa',
+ tip: RETIRE_HEAD,
worktreePath: CLAIM_TREE,
worktreeLocked: true,
dirtyPaths: [],
verdict: {
- branch: CLAIM, repoPath: '/repo', verdict: 'SUPERSEDED', tip: 'aaaaaaa',
+ branch: CLAIM, repoPath: '/repo', verdict: 'SUPERSEDED', tip: RETIRE_HEAD,
dirtyPaths: [], collisionPaths: ['server/services/thing.js'], replacedBy: ['ffffff1']
}
}];
@@ -1882,11 +1882,12 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
// location gate lacks; a short idle floor covers a process still in the tree.
it('reaps a superseded branch from an unmanaged location once its worktree has sat idle', async () => {
const TMP_TREE = '/private/tmp/portos-deep-oversized-order';
+ wt.listWorktrees.mockResolvedValue([{ head: RETIRE_HEAD, path: TMP_TREE, branch: `refs/heads/${BRANCH}` }]);
const verdict = {
- branch: BRANCH, repoPath: '/repo', verdict: 'SUPERSEDED', tip: 'aaaaaaa',
+ branch: BRANCH, repoPath: '/repo', verdict: 'SUPERSEDED', tip: RETIRE_HEAD,
dirtyPaths: [], collisionPaths: ['server/services/thing.js'], replacedBy: ['ffffff1']
};
- const entry = (worktreeAgeMs) => ({ branch: BRANCH, tip: 'aaaaaaa', worktreePath: TMP_TREE, worktreeLocked: false, worktreeAgeMs, dirtyPaths: [], verdict });
+ const entry = (worktreeAgeMs) => ({ branch: BRANCH, tip: RETIRE_HEAD, worktreePath: TMP_TREE, worktreeLocked: false, worktreeAgeMs, dirtyPaths: [], verdict });
const young = await reapSupersededBranches('/repo', 'main', [entry(5 * 60 * 1000)], { activeAgentIds: new Set() });
expect(wt.forceRemoveWorktreeDir).not.toHaveBeenCalled();
@@ -1922,12 +1923,12 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
it('holds the reap of a superseded branch when an active CoS agent is running in it', async () => {
const superseded = [{
branch: BRANCH,
- tip: 'aaaaaaa',
+ tip: RETIRE_HEAD,
worktreePath: WORKTREE,
worktreeLocked: false,
dirtyPaths: ['server/services/thing.js'],
verdict: {
- branch: BRANCH, repoPath: '/repo', verdict: 'SUPERSEDED', tip: 'aaaaaaa',
+ branch: BRANCH, repoPath: '/repo', verdict: 'SUPERSEDED', tip: RETIRE_HEAD,
dirtyPaths: ['server/services/thing.js'], collisionPaths: ['server/services/thing.js'], replacedBy: ['ffffff1']
}
}];
@@ -1989,8 +1990,8 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
// disagrees with its own verdict — the contract check a direct caller needs.
const { reapSupersededBranches } = await import('./branchReconcile.js');
const out = await reapSupersededBranches('/repo', 'main', [{
- branch: BRANCH, tip: 'aaaaaaa', worktreePath: WORKTREE, dirtyPaths: ['other.js'],
- verdict: { tip: 'aaaaaaa', dirtyPaths: ['server/services/thing.js'] }
+ branch: BRANCH, tip: RETIRE_HEAD, worktreePath: WORKTREE, dirtyPaths: ['other.js'],
+ verdict: { tip: RETIRE_HEAD, dirtyPaths: ['server/services/thing.js'] }
}], { activeAgentIds: new Set() });
expect(out.reaped).toEqual([]);
expect(out.skipped).toEqual([{ branch: BRANCH, reason: 'verdict-does-not-match-branch' }]);
diff --git a/server/services/branchReconcileCompletion.js b/server/services/branchReconcileCompletion.js
index 5ad0832882..7ed20f3db0 100644
--- a/server/services/branchReconcileCompletion.js
+++ b/server/services/branchReconcileCompletion.js
@@ -30,6 +30,7 @@ export async function settleBranchReconcileRun(agent) {
const { readPendingMergePrs } = await import('./prWatcher.js');
const pendingMergeBranches = new Set(readPendingMergePrs(app).map((entry) => entry?.prBranch).filter(Boolean));
const result = await reconcile(app.repoPath, {
+ appId: app.id,
cleanup: true,
reapSuperseded: task.metadata.reapSuperseded !== false,
pendingMergeBranches,
diff --git a/server/services/branchReconcileCompletion.test.js b/server/services/branchReconcileCompletion.test.js
index b327f2c14d..43868847ed 100644
--- a/server/services/branchReconcileCompletion.test.js
+++ b/server/services/branchReconcileCompletion.test.js
@@ -33,7 +33,7 @@ describe('branch reconciliation completion', () => {
it('settles a non-perpetual run immediately using fresh ownership and its target account', async () => {
expect(await settleBranchReconcileRun(agent)).toMatchObject({ cleaned: ['merged'], reapedSuperseded: ['superseded'] });
expect(reconcile).toHaveBeenCalledWith('/example/repo', {
- cleanup: true, reapSuperseded: true, pendingMergeBranches: new Set(['claim/queued']), activeAgentIds: new Set(['active']),
+ appId: 'example', cleanup: true, reapSuperseded: true, pendingMergeBranches: new Set(['claim/queued']), activeAgentIds: new Set(['active']),
claimOwners: { agents: [], readAgents: readClaimOwnershipAgents }, forgeAccount: 'example-account'
});
});
diff --git a/server/services/cosTaskPreStepBlocks.js b/server/services/cosTaskPreStepBlocks.js
index 5e618d3154..686637d266 100644
--- a/server/services/cosTaskPreStepBlocks.js
+++ b/server/services/cosTaskPreStepBlocks.js
@@ -466,6 +466,7 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskS
finishAbandoned: metadata.finishAbandoned
};
const result = await reconcile(app.repoPath, {
+ appId: app.id,
cleanup: actions.cleanupMerged !== false,
// A fresh SUPERSEDED verdict is terminal: nothing else retires the branch,
// so holding it only re-reports it. Backup-first, behind the same owner gates.
diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.js
index 7768a8722f..ece4601f3f 100644
--- a/server/services/heldCheckoutRecovery.js
+++ b/server/services/heldCheckoutRecovery.js
@@ -216,7 +216,11 @@ export async function recoverMissingCheckoutPreservations({ appId, repoPath, out
if (!await historicalCheckoutAbsent(release, trees).catch(() => false)) continue;
const evidence = [];
let proof = null;
- for (const candidate of candidates) {
+ const scopedCandidates = Object.hasOwn(release, 'preservationReceipt')
+ ? candidates.filter(candidate => release.preservationReceipt?.status === 'preserved'
+ && JSON.stringify(release.preservationReceipt.incarnation) === JSON.stringify(release.checkoutIncarnation)
+ && candidate.dir === release.preservationReceipt.archiveDir) : candidates;
+ for (const candidate of scopedCandidates) {
try {
proof = candidate.kind === 'held' ? await verifyHeldArchive(repoPath, candidate.dir, release)
: await (await import('./initializedCheckoutRecovery.js')).verifyMissingInitializedCheckoutPreservation({ appId, repoPath, release, archiveDir: candidate.dir });
@@ -610,6 +614,63 @@ async function recoveryObjectHeads(administration, { repoPath, tree, missingRoot
return heads;
}
+/** Supersession is a content verdict, never a substitute for full preservation.
+ * 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 identityCurrent = async () => JSON.stringify(await readCompletedCheckoutIdentity(target)) === JSON.stringify(identity);
+ const pending = await schedule.recordBranchReconcileOutcome(appId, {
+ status: 'incomplete', reason: 'retirement-receipt-unverified',
+ retirementObligations: [{ ...release, checkoutIncarnation: identity.incarnation, reason: 'retirement-review-pending' }],
+ nextAction: 'Require complete preservation and an exact retirement receipt for the superseded 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, 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 }) {
const [snapshot, administration] = await archiveSnapshots(tree, repoPath, missingRoot);
const recoveryHeads = await recoveryObjectHeads(administration, { repoPath, tree, missingRoot });
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
index b12b59bdb8..d074c15406 100644
--- a/server/services/heldCheckoutRecovery.test.js
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -20,6 +20,7 @@ vi.mock('../lib/paths.js', async importOriginal => makePathsProxy(await importOr
afterAll(cleanupTempDataRoots);
const SYMLINKS = process.platform !== 'win32';
+const retirementFaults = vi.hoisted(() => ({ onRemove: null, onBranchDelete: null, scheduleWrites: 0, failScheduleWrite: null }));
const injected = vi.hoisted(() => ({ policies: [], schedule: null, app: null, fetchRemote: null, fetches: [], onBundle: null, onEvidence: null }));
vi.mock('../lib/execGit.js', async importOriginal => {
@@ -28,6 +29,8 @@ vi.mock('../lib/execGit.js', async importOriginal => {
// Pauses an archive mid-write, after its first snapshot and before its re-read.
if (injected.onBundle && args.includes('bundle') && args.includes('create')) await injected.onBundle();
if (injected.onEvidence && args[0] === 'bundle' && args[1] === 'verify') await injected.onEvidence();
+ if (retirementFaults.onRemove && args[0] === 'worktree' && args[1] === 'remove') await retirementFaults.onRemove();
+ if (retirementFaults.onBranchDelete && args[0] === 'push' && args.some(arg => arg.startsWith(':refs/heads/'))) await retirementFaults.onBranchDelete();
if (args.includes('credential.helper=!gh auth git-credential') && args.includes('fetch')) {
injected.fetches.push({ args, options });
if (injected.fetchRemote) args = args.map(arg => arg === 'https://github.com/example/repo.git' ? injected.fetchRemote : arg);
@@ -46,7 +49,10 @@ vi.mock('./branchCompletionPolicy.js', async (importOriginal) => {
vi.mock('./taskScheduleStore.js', async (importOriginal) => ({
...await importOriginal(),
loadSchedule: async () => injected.schedule,
- updateSchedule: async (mutate) => (await mutate(injected.schedule)).result,
+ updateSchedule: async mutate => {
+ if (++retirementFaults.scheduleWrites === retirementFaults.failScheduleWrite) throw new Error('synthetic receipt persistence failure');
+ return (await mutate(injected.schedule)).result;
+ },
}));
vi.mock('./apps.js', () => ({ getAppById: async (id) => (injected.app?.id === id ? injected.app : null) }));
@@ -62,6 +68,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
const noOwners = async () => [];
beforeEach(async () => {
+ Object.assign(retirementFaults, { onRemove: null, onBranchDelete: null, scheduleWrites: 0, failScheduleWrite: null });
Object.assign(injected, { policies: [], schedule: { tasks: {}, executions: {} }, app: { id: 'app-1', repoPath: null }, fetchRemote: null, fetches: [], onBundle: null, onEvidence: null });
scratch = realpathSync(await mkdtemp(join(tmpdir(), 'portos-held-checkout-')));
const safeRepo = join(scratch, 'repo');
@@ -119,6 +126,167 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
return { release, saved };
}
+ async function supersededCheckout() {
+ const { release } = await heldCheckout('superseded', { branch: 'feature/superseded' });
+ await execGit(['worktree', 'unlock', release.path], repo);
+ await execGit(['add', 'initial.txt'], release.path);
+ await writeFile(join(release.path, 'initial.txt'), 'unstaged original work\n');
+ const gitdir = (await execGit(['rev-parse', '--absolute-git-dir'], release.path)).stdout.trim();
+ await writeFile(join(gitdir, 'private-note'), 'private administration');
+ const dirtyPaths = (await execGit(['status', '--porcelain'], release.path)).stdout.trimEnd().split('\n').filter(Boolean).map(line => line.slice(3));
+ const entry = { branch: release.branch, tip: release.head, worktreePath: release.path, worktreeLocked: false,
+ worktreeAgeMs: 365 * 86400000, dirtyPaths,
+ verdict: { branch: release.branch, tip: release.head, verdict: 'SUPERSEDED', dirtyPaths } };
+ return { entry, release: { ...release, locked: false, lockReason: null } };
+ }
+ const reapSuperseded = async (entry, readAgents = noOwners) => (await import('./branchReconcile.js')).reapSupersededBranches(repo, 'main', [entry], {
+ appId: 'app-1', cosDir, claimOwners: { agents: [], readAgents },
+ });
+
+ it('retires a superseded branch without a worktree through its full branch archive without claiming checkout preservation', async () => {
+ const branch = 'feature/no-worktree';
+ const head = (await execGit(['commit-tree', 'HEAD^{tree}', '-p', 'HEAD', '-m', 'superseded branch-only commit'], repo)).stdout.trim();
+ await execGit(['branch', branch, head], repo);
+ const missingCheckout = { branch, path: join(external, 'lost-original'), head, locked: false, lockReason: null };
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', retirementObligations: [{ ...missingCheckout, reason: 'retirement-provenance-unverified' }] });
+ let archiveDir;
+ retirementFaults.onBranchDelete = async () => {
+ for (const name of await readdir(join(PATHS.cos, 'branch-retirement-archives'))) {
+ const dir = join(PATHS.cos, 'branch-retirement-archives', name);
+ const manifest = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
+ if (manifest.repoPath === repo && manifest.branch === branch && manifest.expectedHead === head) {
+ archiveDir = dir;
+ expect(manifest.recoveryHeads).toContain(head);
+ expect(manifest.bundleSha256).toMatch(/^[a-f0-9]{64}$/);
+ }
+ }
+ expect(archiveDir).toBeTruthy();
+ expect((await execGit(['rev-parse', '--verify', `refs/heads/${branch}`], repo)).stdout.trim()).toBe(head);
+ };
+ const entry = { branch, tip: head, worktreePath: null, dirtyPaths: [], verdict: { branch, tip: head, verdict: 'SUPERSEDED', dirtyPaths: [] } };
+ expect(await reapSuperseded(entry)).toMatchObject({ reaped: [branch], skipped: [] });
+ expect((await execGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], repo, { ignoreExitCode: true })).exitCode).toBe(1);
+ const restored = join(scratch, 'branch-restore.git');
+ await execGit(['init', '--bare', restored], scratch);
+ await execGit(['bundle', 'unbundle', join(archiveDir, 'commits.bundle')], restored);
+ expect((await execGit(['cat-file', '-e', `${head}^{commit}`], restored)).exitCode).toBe(0);
+ const outcome = await getBranchReconcileOutcome('app-1');
+ expect(outcome.retired || []).toEqual([]);
+ expect(outcome.retirementObligations).toContainEqual(expect.objectContaining(missingCheckout));
+ expect(await archives()).toEqual([]);
+ });
+
+ it('archives every superseded checkout byte and persists its exact generation before removal, then records retirement', async () => {
+ const { entry, release } = await supersededCheckout();
+ let prepared;
+ retirementFaults.onRemove = async () => {
+ const outcome = await getBranchReconcileOutcome('app-1');
+ const row = outcome.retirementObligations.find(row => row.branch === release.branch);
+ prepared = row.preservationReceipt;
+ expect(row).toMatchObject(release);
+ expect(outcome.retired || []).toEqual([]);
+ expect(await readFile(join(prepared.archiveDir, 'files', 'ignored.txt'), 'utf8')).toBe('ignored work\n');
+ expect(await readFile(join(prepared.archiveDir, 'administration', 'gitdir', 'private-note'), 'utf8')).toBe('private administration');
+ expect(await readFile(join(prepared.archiveDir, 'index.diff'), 'utf8')).toContain('tracked edit');
+ expect(await readFile(join(prepared.archiveDir, 'worktree.diff'), 'utf8')).toContain('unstaged original work');
+ expect((await execGit(['bundle', 'verify', join(prepared.archiveDir, 'commits.bundle')], repo)).exitCode).toBe(0);
+ };
+ expect(await reapSuperseded(entry)).toMatchObject({ reaped: [release.branch], skipped: [] });
+ expect(prepared.archiveDir).toBeTruthy();
+ const outcome = await getBranchReconcileOutcome('app-1');
+ expect(outcome.retired).toContainEqual(expect.objectContaining({ path: release.path, branch: release.branch, head: release.head,
+ archiveDir: prepared.archiveDir, branchDeleted: true, retiredAt: expect.any(String) }));
+ expect(outcome.retirementObligations).toEqual([]);
+ expect(existsSync(release.path)).toBe(false);
+ expect((await execGit(['rev-parse', '--verify', '--quiet', `refs/heads/${release.branch}`], repo, { ignoreExitCode: true })).exitCode).toBe(1);
+ });
+
+ it.each(['archive failure', 'preservation receipt failure', 'new owner', 'ignored bytes change', 'private administration change', 'checkout identity change', 'app scope change'])('keeps superseded originals on %s', async failure => {
+ const { entry, release } = await supersededCheckout();
+ let owners = [];
+ if (failure === 'preservation receipt failure') retirementFaults.failScheduleWrite = 3;
+ else injected.onBundle = async () => {
+ injected.onBundle = null;
+ if (failure === 'archive failure') throw new Error('synthetic archive failure');
+ if (failure === 'new owner') owners = [{ id: 'new-owner', status: 'running', metadata: { sourceWorkspace: repo, claimBranches: [release.branch] } }];
+ if (failure === 'ignored bytes change') await writeFile(join(release.path, 'ignored.txt'), 'new ignored bytes');
+ if (failure === 'private administration change') {
+ const gitdir = (await execGit(['rev-parse', '--absolute-git-dir'], release.path)).stdout.trim();
+ await writeFile(join(gitdir, 'private-note'), 'new private administration');
+ }
+ if (failure === 'app scope change') injected.app = { ...injected.app, repoPath: join(scratch, 'different-app-repository') };
+ if (failure === 'checkout identity change') {
+ const pointer = join(release.path, '.git');
+ const bytes = await readFile(pointer);
+ await rename(pointer, join(scratch, 'original-indirection'));
+ await writeFile(pointer, bytes);
+ }
+ };
+ const result = await reapSuperseded(entry, async () => owners);
+ expect(result.reaped).toEqual([]);
+ expect(result.skipped).toHaveLength(1);
+ expect(existsSync(release.path)).toBe(true);
+ expect(await registered(release.path)).toBe(true);
+ expect((await execGit(['rev-parse', release.branch], repo)).stdout.trim()).toBe(release.head);
+ expect((await getBranchReconcileOutcome('app-1'))?.retired || []).toEqual([]);
+ });
+
+ it('preserves a superseded branch whose exact head no longer matches its verdict', async () => {
+ const { entry, release } = await supersededCheckout();
+ entry.tip = 'f'.repeat(40);
+ entry.verdict.tip = entry.tip;
+ expect(await reapSuperseded(entry)).toMatchObject({ reaped: [], skipped: [{ branch: release.branch, reason: 'branch-head-changed' }] });
+ expect(existsSync(release.path)).toBe(true);
+ expect(await registered(release.path)).toBe(true);
+ expect(await archives()).toEqual([]);
+ });
+
+ it('never substitutes an older compatible archive when the prepared superseded archive is corrupt', async () => {
+ const { entry, release } = await supersededCheckout();
+ let owners = [];
+ injected.onBundle = async () => {
+ injected.onBundle = null;
+ owners = [{ id: 'temporary-owner', status: 'running', metadata: { sourceWorkspace: repo, claimBranches: [release.branch] } }];
+ };
+ expect((await reapSuperseded(entry, async () => owners)).reaped).toEqual([]);
+ const first = await getBranchReconcileOutcome('app-1');
+ const older = { archiveDir: first.retirementObligations[0].preservationReceipt.archiveDir };
+ owners = [];
+ await writeFile(join(release.path, 'ignored.txt'), 'new private ignored work');
+ retirementFaults.failScheduleWrite = retirementFaults.scheduleWrites + 4;
+ expect((await reapSuperseded(entry)).reaped).toEqual([]);
+ const outcome = await getBranchReconcileOutcome('app-1');
+ const archiveDir = outcome.retirementObligations[0].preservationReceipt.archiveDir;
+ expect(archiveDir).not.toBe(older.archiveDir);
+ expect(await readFile(join(older.archiveDir, 'files', 'ignored.txt'), 'utf8')).toBe('ignored work\n');
+ await writeFile(join(archiveDir, 'files', 'ignored.txt'), 'corrupt the exact prepared archive');
+ const recovered = await recoverMissingCheckoutPreservations({ appId: 'app-1', repoPath: repo, outcome }, { cosDir });
+ expect(recovered.retirementObligations).toHaveLength(1);
+ expect(recovered.recoveredPreservations || []).toEqual([]);
+ expect(recovered.retirementObligations[0].preservationReceipt.archiveDir).toBe(archiveDir);
+ });
+
+ it('preserves an existing checkout when its historical obligation has no original incarnation proof', async () => {
+ const { entry, release } = await supersededCheckout();
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', retirementObligations: [{ ...release, reason: 'retirement-review-pending' }] });
+ expect(await reapSuperseded(entry)).toMatchObject({ reaped: [], skipped: [{ branch: release.branch, reason: 'retirement-checkout-generation-unverified' }] });
+ expect(existsSync(release.path)).toBe(true);
+ expect(await registered(release.path)).toBe(true);
+ expect((await getBranchReconcileOutcome('app-1')).retirementObligations).toHaveLength(1);
+ expect(await archives()).toEqual([]);
+ });
+
+ it('keeps a durable preservation obligation when final retirement receipt persistence fails', async () => {
+ const { entry, release } = await supersededCheckout();
+ retirementFaults.failScheduleWrite = 4;
+ expect(await reapSuperseded(entry)).toMatchObject({ reaped: [], skipped: [{ branch: release.branch, reason: 'retirement-receipt-unverified' }] });
+ const outcome = await getBranchReconcileOutcome('app-1');
+ expect(outcome.retired || []).toEqual([]);
+ expect(outcome.retirementObligations).toContainEqual(expect.objectContaining({ path: release.path, head: release.head,
+ preservationReceipt: expect.objectContaining({ archiveDir: expect.any(String), preparedAt: expect.any(String) }) }));
+ expect(existsSync(release.path)).toBe(false);
+ });
+
it('recovers complete preservation through the schedule boundary with only the primary checkout, without claiming branch deletion', async () => {
const { release, saved } = await historicalArchive();
const before = (await execGit(['show-ref'], repo)).stdout;
diff --git a/server/services/taskSchedule.js b/server/services/taskSchedule.js
index 5c922965d2..4c24df4a7c 100644
--- a/server/services/taskSchedule.js
+++ b/server/services/taskSchedule.js
@@ -915,6 +915,22 @@ async function reconcileMissingInventory(appId, outcome) {
})) };
}
+/** A prepared archive does not claim deletion. This exact-generation receipt
+ * must exist before superseded cleanup is allowed to remove its originals.
+ */
+export async function recordHeldCheckoutPreservation(appId, { path, branch, head, createdAt, archiveDir, incarnation }) {
+ return updateSchedule(async schedule => {
+ const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
+ const outcome = record.branchReconcileOutcome;
+ const row = outcome?.retirementObligations?.find(entry => sameRetirementCheckout(entry, { path, branch, head }) && entry.createdAt === createdAt);
+ if (!row || !incarnation?.pointer || !incarnation?.gitdir
+ || JSON.stringify(row.checkoutIncarnation) !== JSON.stringify(incarnation)
+ || (archiveDir !== null && (typeof archiveDir !== 'string' || !archiveDir))) throw new Error('retirement-obligation-changed');
+ row.preservationReceipt = { archiveDir, incarnation: structuredClone(incarnation), status: archiveDir === null ? 'preparing' : 'preserved', preparedAt: new Date().toISOString() };
+ return { result: row.preservationReceipt, changed: true };
+ });
+}
+
const RETIRED_CHECKOUTS_KEPT = 20;
/**