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
Require complete preservation before superseded checkout retirement (#13365)
[._.]/2b05ef7a8142
diff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.jsindex 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, staleClaimIdif (!/^[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 todiff --git a/server/services/branchReconcile.test.js b/server/services/branchReconcile.test.jsindex 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.jsindex 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.jsindex 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.jsindex 5e618d3154..686637d266 100644--- a/server/services/cosTaskPreStepBlocks.js+++ b/server/services/cosTaskPreStepBlocks.js@@ -466,6 +466,7 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskSfinishAbandoned: 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.jsindex 7768a8722f..ece4601f3f 100644--- a/server/services/heldCheckoutRecovery.js+++ b/server/services/heldCheckoutRecovery.js@@ -216,7 +216,11 @@ export async function recoverMissingCheckoutPreservations({ appId, repoPath, outif (!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, missingRootreturn 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.jsindex 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 importOrafterAll(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.jsindex 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;/**