Skip to content

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

fix: retain exact receipts for normal branch retirement (#13366)

Adam Eivy56ed2a76c7f5
diff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.js
index 16b90f4861..6f4575f212 100644
--- a/server/services/branchReconcile.js
+++ b/server/services/branchReconcile.js
@@ -1097,7 +1097,7 @@ export function describeIdleReconcilePark(skipped = [], heldLive = [], { wip = [
...(entry.branch && { branch: entry.branch }),
...((entry.path || entry.worktreePath) && { path: entry.path || entry.worktreePath }),
...(entry.issue && { issue: entry.issue }),
- ...(entry.head && { head: entry.head }),
+ ...((entry.head || entry.tip) && { head: entry.head || entry.tip }),
...(entry.observedAt && { observedAt: entry.observedAt }),
...(entry.checkoutIdentity && { checkoutIdentity: entry.checkoutIdentity }),
...(entry.locked !== undefined && { locked: entry.locked, lockReason: entry.lockReason ?? null }),
@@ -1169,7 +1169,7 @@ async function claimIssueUnreserved(target, issue, forgeExec) {
* @returns {Promise<{cleaned:string[], skipped:{branch:string,reason:string,retryAt?:string}[]}>}
* A skip carries `retryAt` when its hold is known to lift at a specific time.
*/
-export async function cleanupMerged(repoPath, defaultBranch, merged, { activeAgentIds, claimOwners, origin, forgeExec, forgeAccount = null } = {}) {
+export async function cleanupMerged(repoPath, defaultBranch, merged, { activeAgentIds, claimOwners, origin, forgeExec, forgeAccount = null, appId = null } = {}) {
const cleaned = [];
const skipped = [];
const claimMarkersHeld = [];
@@ -1178,6 +1178,7 @@ export async function cleanupMerged(repoPath, defaultBranch, merged, { activeAge
activeAgentIds,
claimOwners,
mergedRetirement: true,
+ appId,
mergeTarget: defaultBranch,
forgeAccount,
label: `🔀 branch-reconcile: remove worktree for ${b.branch}`,
@@ -1381,8 +1382,13 @@ async function retireBranch(repoPath, b, opts) {
const prepared = gated.prepare ? await gated.prepare() : null;
if (prepared?.error) return { result: { ok: false, reason: prepared.error } };
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 } }),
+ const { preserveMergedCheckout, preserveSupersededCheckout } = await import('./heldCheckoutRecovery.js');
+ // Both merged and superseded app checkouts need the same pre-archive
+ // obligation and post-deletion receipt, including after an interrupted sweep.
+ const preserve = opts.appId
+ ? preserveSupersededCheckout({ appId: opts.appId, repoPath, tree: gated.archiveTree, defaultBranch: gated.mergeTarget })
+ : preserveMergedCheckout(repoPath, gated.archiveTree, gated.mergeTarget);
+ return preserve.then(preservation => ({ archive: { prepared, preservation } }),
error => ({ result: { ok: false, reason: 'archive-failed', detail: error.message } }));
},
finish: ({ gated }, { prepared, preservation }) => finishBranchRetirement(repoPath, gated, { prepared, preservation }),
@@ -1390,7 +1396,7 @@ async function retireBranch(repoPath, b, opts) {
}
/** Every gate before the archive. Returns `{ result }` to stop, else the context removal needs. */
-async function admitBranchRetirement(repoPath, b, { activeAgentIds, staleClaimIdleMs = STALE_CLAIM_IDLE_MS, allowLiveClaim = false, label, requireCleanWorktree = true, unmanagedIdleMs, prepare, claimOwners, mergedRetirement = false, mergeTarget, forgeAccount = null }) {
+async function admitBranchRetirement(repoPath, b, { activeAgentIds, staleClaimIdleMs = STALE_CLAIM_IDLE_MS, allowLiveClaim = false, label, requireCleanWorktree = true, unmanagedIdleMs, prepare, claimOwners, mergedRetirement = false, mergeTarget, forgeAccount = null, appId = null }) {
const stop = result => ({ result });
if (PROTECTED_BRANCHES.includes(b.branch)) return stop({ ok: false, reason: 'protected-branch' });
const defaultBranch = await getDefaultBranch(repoPath, { strict: true }).catch(() => null);
@@ -1474,7 +1480,7 @@ async function admitBranchRetirement(repoPath, b, { activeAgentIds, staleClaimId
if (!tree || tree.head !== expectedHead) return stop({ ok: false, reason: 'worktree-holder-changed' });
archiveTree = tree;
}
- return { b, expectedHead, readPolicyHold, archiveTree, mergeTarget, label, requireCleanWorktree, prepare, claimOwners, mergedRetirement, claimCompletion };
+ return { b, expectedHead, readPolicyHold, archiveTree, mergeTarget, label, requireCleanWorktree, prepare, claimOwners, mergedRetirement, claimCompletion, appId };
}
/**
@@ -1520,7 +1526,7 @@ export async function checkoutIdleMs(worktreePath) {
* Removal and branch deletion. `preservation` is the archive and `prepared` the
* `prepare` backup, each taken after admission with the ownership lock released.
*/
-async function finishBranchRetirement(repoPath, { b, expectedHead, readPolicyHold, mergeTarget, label, requireCleanWorktree, claimOwners, mergedRetirement, claimCompletion }, { prepared = null, preservation = null } = {}) {
+async function finishBranchRetirement(repoPath, { b, expectedHead, readPolicyHold, mergeTarget, label, requireCleanWorktree, claimOwners, mergedRetirement, claimCompletion, appId }, { prepared = null, preservation = null } = {}) {
let removal = null;
if (b.worktreePath) {
const verifyRemoval = async (holder, worktrees) => {
@@ -1573,10 +1579,29 @@ async function finishBranchRetirement(repoPath, { b, expectedHead, readPolicyHol
if (backup?.exitCode !== 0) return { ok: false, reason: 'recovery-ref-failed' };
}
const { deleteCompletedLocalBranch } = await import('./worktreeManager.js');
- const deleted = await deleteCompletedLocalBranch(repoPath, b.branch, expectedHead);
- if (!deleted) return { ok: false, reason: 'branch-ref-changed-or-delete-failed' };
- if (prepared?.preservation) {
- const recorded = await prepared.preservation.recordRetirement().then(() => true, () => false);
+ let branchReceipt = null;
+ let branchArchive = null;
+ if (appId && mergedRetirement && !b.worktreePath) {
+ const { getAppById } = await import('./apps.js');
+ const app = await getAppById(appId);
+ if (!app?.repoPath || resolve(app.repoPath) !== resolve(repoPath)) return { ok: false, reason: 'retirement-receipt-scope-unavailable' };
+ branchReceipt = async ({ archiveDir }) => {
+ branchArchive = archiveDir;
+ const { recordHeldCheckoutRetirement } = await import('./taskSchedule.js');
+ const absent = await execGit(['show-ref', '--verify', '--quiet', `refs/heads/${b.branch}`], repoPath, { ignoreExitCode: true });
+ if (absent.exitCode !== 1) throw new Error('retirement-branch-recreated');
+ const outcome = await recordHeldCheckoutRetirement(appId, { branch: b.branch, head: expectedHead, branchDeleted: true, archiveDir });
+ if (!outcome?.retired?.some(row => !row.path && row.branch === b.branch && row.head === expectedHead
+ && row.branchDeleted === true && row.archiveDir === archiveDir)) throw new Error('retirement-receipt-unverified');
+ };
+ }
+ const deleted = await deleteCompletedLocalBranch(repoPath, b.branch, expectedHead,
+ ...(branchReceipt ? [{ onRetired: branchReceipt }] : [])).catch(() => false);
+ if (!deleted) return branchArchive ? { ok: false, reason: 'retirement-receipt-unverified', archiveDir: branchArchive }
+ : { ok: false, reason: 'branch-ref-changed-or-delete-failed' };
+ const receipt = prepared?.preservation || preservation;
+ if (receipt?.recordRetirement) {
+ const recorded = await receipt.recordRetirement().then(() => true, () => false);
if (!recorded) return { ok: false, reason: 'retirement-receipt-unverified', archiveDir: preservation.archiveDir };
}
return { ok: true, prepared, ...(preservation && { archiveDir: preservation.archiveDir }) };
@@ -1787,7 +1812,7 @@ export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSup
// squash/rebase-equivalent merges). Keeping this pass ahead of gh means a
// temporary forge outage cannot strand locally-provable completed work.
const worktreeCleanup = cleanup
- ? await reapMergedWorktrees(repoPath, { activeAgentIds, claimOwners, includeClaudeTrees: true }).catch(() => ({ reaped: [] }))
+ ? await reapMergedWorktrees(repoPath, { activeAgentIds, claimOwners, includeClaudeTrees: true, ...(appId && { appId }) }).catch(() => ({ reaped: [] }))
: { reaped: [] };
const cleanedWorktrees = (worktreeCleanup.reaped || []).filter(entry => typeof entry === 'string' || entry?.branchDeleted)
.map((entry) => typeof entry === 'string' ? entry : entry?.branch)
@@ -1879,7 +1904,7 @@ export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSup
const wip = classified.filter((c) => c.state === 'WIP');
const { cleaned: cleanedBranches, skipped, claimMarkersHeld: mergedMarkerHolds = [] } = cleanup
- ? await cleanupMerged(repoPath, defaultBranch, merged, { activeAgentIds, claimOwners, origin, forgeExec, forgeAccount })
+ ? await cleanupMerged(repoPath, defaultBranch, merged, { activeAgentIds, claimOwners, origin, forgeExec, forgeAccount, appId })
: { cleaned: [], skipped: merged.map((m) => ({ branch: m.branch, reason: 'cleanup-disabled' })) };
// Detached worktrees have no branch, so nothing above can see them (#10825).
const postCleanupWorktrees = await listWorktrees(repoPath).catch(() => []);
diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.js
index 013b07204f..c9e309d336 100644
--- a/server/services/heldCheckoutRecovery.js
+++ b/server/services/heldCheckoutRecovery.js
@@ -632,7 +632,7 @@ async function recoveryObjectHeads(administration, { repoPath, tree, missingRoot
return heads;
}
-/** Supersession is a content verdict, never a substitute for full preservation.
+/** Shared app-scoped preservation for merged and superseded checkouts.
* Persist the original generation before archiving, then its exact preservation
* receipt before the caller can remove anything under the retirement fence.
*/
@@ -646,11 +646,18 @@ export async function preserveSupersededCheckout({ appId, repoPath, tree, defaul
const target = { repoPath, branch: release.branch, path: release.path, head: release.head };
const identity = await readCompletedCheckoutIdentity(target);
if (!identity) throw new Error('checkout-incarnation-unavailable');
+ const checkoutIdentity = await readRetirementCheckoutIdentity(tree.path);
+ if (!checkoutIdentity) throw new Error('checkout-incarnation-unavailable');
+ const previous = await schedule.getBranchReconcileOutcome(appId);
+ if (unresolvedRetirements(previous).some(row => sameRelease(row, release)
+ && JSON.stringify(row.checkoutIncarnation) !== JSON.stringify(identity.incarnation))) {
+ throw new Error('retirement-checkout-generation-unverified');
+ }
const identityCurrent = async () => JSON.stringify(await readCompletedCheckoutIdentity(target)) === JSON.stringify(identity);
const pending = await schedule.recordBranchReconcileOutcome(appId, {
status: 'incomplete', reason: 'retirement-receipt-unverified',
- retirementObligations: [{ ...release, checkoutIncarnation: identity.incarnation, reason: 'retirement-review-pending' }],
- nextAction: 'Require complete preservation and an exact retirement receipt for the superseded checkout.',
+ retirementObligations: [{ ...release, checkoutIdentity, checkoutIncarnation: identity.incarnation, reason: 'retirement-review-pending' }],
+ nextAction: 'Require complete preservation and an exact retirement receipt for the checkout.',
});
const obligation = pending?.retirementObligations?.find(row => sameRelease(row, release));
if (!Number.isFinite(Date.parse(obligation?.createdAt))) throw new Error('retirement-obligation-unavailable');
@@ -680,7 +687,7 @@ export async function preserveSupersededCheckout({ appId, repoPath, tree, defaul
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 });
+ const outcome = await schedule.recordHeldCheckoutRetirement(appId, { ...release, checkoutIdentity, branchDeleted: true, archiveDir: archive.archiveDir });
if (!outcome?.retired?.some(row => sameRelease(row, release) && row.branchDeleted === true
&& row.archiveDir === archive.archiveDir && Date.parse(row.retiredAt) >= Date.parse(obligation.createdAt))) {
throw new Error('retirement-receipt-unverified');
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
index a3efd2f0f7..75b8822d95 100644
--- a/server/services/heldCheckoutRecovery.test.js
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -161,6 +161,64 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
appId: 'app-1', cosDir, claimOwners: { agents: [], readAgents },
});
+ // Both automatic retirement entry points used to omit their receipt, so the
+ // next persisted scan manufactured a missing-source obligation after archival.
+ it.each(['cleanupMerged', 'early reaper'])('settles a normally merged checkout before the next scan through %s', async entryPoint => {
+ const branch = 'feature/merged-receipt';
+ const path = join(repo, '.claude', 'worktrees', 'merged-receipt');
+ await mkdir(dirname(path), { recursive: true });
+ await execGit(['worktree', 'add', '-b', branch, path, 'main'], repo);
+ await writeFile(join(path, '.gitignore'), 'ignored.txt\n');
+ await execGit(['add', '.gitignore'], path);
+ await execGit(['commit', '-m', 'fixture ignore rule'], path);
+ await execGit(['merge', '--ff-only', branch], repo);
+ await writeFile(join(path, 'ignored.txt'), 'synthetic ignored checkout bytes');
+ const holder = (await (await import('./worktreeManager.js')).listWorktrees(repo)).find(tree => tree.branch === `refs/heads/${branch}`);
+ const release = { branch, path: holder.path, head: holder.head, locked: false, lockReason: null };
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', remaining: [{ ...release,
+ checkoutIdentity: await readRetirementCheckoutIdentity(path), reason: 'checkout-retained' }] });
+ const options = { appId: 'app-1', activeAgentIds: new Set(), claimOwners: { agents: [], readAgents: noOwners } };
+ if (entryPoint === 'cleanupMerged') {
+ const result = await (await import('./branchReconcile.js')).cleanupMerged(repo, 'main', [{ branch, worktreePath: holder.path }], options);
+ expect(result).toMatchObject({ cleaned: [branch], skipped: [] });
+ } else {
+ const result = await (await import('./worktreeManager.js')).reapMergedWorktrees(repo, options);
+ expect(result.reaped).toEqual([expect.objectContaining({ branch, branchDeleted: true })]);
+ expect(result.skipped).toEqual([]);
+ }
+ expect(existsSync(path)).toBe(false);
+ expect((await execGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], repo, { ignoreExitCode: true })).exitCode).toBe(1);
+ const first = await getBranchReconcileOutcome('app-1');
+ expect(first.retired).toEqual([expect.objectContaining({ branch, path: holder.path, head: holder.head, branchDeleted: true, archiveDir: expect.any(String) })]);
+ const manifest = JSON.parse(await readFile(join(first.retired[0].archiveDir, 'manifest.json'), 'utf8'));
+ expect(manifest.captured.files).toContainEqual(expect.objectContaining({ path: 'ignored.txt', sha256: expect.any(String) }));
+ await recordBranchReconcileOutcome('app-1', { status: 'complete', remaining: [] });
+ const next = await getBranchReconcileOutcome('app-1');
+ expect(next).toMatchObject({ remaining: [], retirementObligations: [] });
+ expect(next.retired).toEqual(first.retired);
+ });
+
+ it('settles a normally retired branch-only row while retaining unrelated unexplained disappearance', async () => {
+ const branch = 'feature/merged-branch-only';
+ await execGit(['branch', branch, 'main'], repo);
+ const head = (await execGit(['rev-parse', branch], repo)).stdout.trim();
+ const vanished = { branch: 'feature/unexplained-disappearance', head, reason: 'branch-held' };
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', remaining: [{ branch, head, reason: 'branch-held' }, vanished] });
+ const result = await (await import('./branchReconcile.js')).cleanupMerged(repo, 'main', [{ branch }], {
+ appId: 'app-1', activeAgentIds: new Set(), claimOwners: { agents: [], readAgents: noOwners },
+ });
+ expect(result).toMatchObject({ cleaned: [branch], skipped: [] });
+ const first = await getBranchReconcileOutcome('app-1');
+ expect(first.retired).toEqual([expect.objectContaining({ branch, head, branchDeleted: true, archiveDir: expect.any(String) })]);
+ expect(first.remaining).toEqual([vanished]);
+ const manifest = JSON.parse(await readFile(join(first.retired[0].archiveDir, 'manifest.json'), 'utf8'));
+ expect(manifest).toMatchObject({ repoPath: repo, branch, expectedHead: head, bundleSha256: expect.any(String) });
+ await recordBranchReconcileOutcome('app-1', { status: 'complete', remaining: [] });
+ const next = await getBranchReconcileOutcome('app-1');
+ expect(next.retirementObligations).toEqual([expect.objectContaining({ branch: vanished.branch, head, reason: 'retirement-provenance-unverified' })]);
+ expect(next.remaining).toEqual(next.retirementObligations);
+ });
+
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();
diff --git a/server/services/taskSchedule.js b/server/services/taskSchedule.js
index a9aed0ea14..c04e00d665 100644
--- a/server/services/taskSchedule.js
+++ b/server/services/taskSchedule.js
@@ -997,7 +997,7 @@ export async function recordHeldCheckoutRetirement(appId, { path, branch, branch
updatedAt: retiredAt,
remaining: Array.isArray(outcome.remaining)
? outcome.remaining.filter(entry => retirementObligations.some(row => sameRetirementObservation(row, entry))
- || (entry.path !== path && !(branchDeleted && branch && entry.branch === branch)))
+ || !(sameRetirementObservation(entry, receipt) || (!entry.checkoutIdentity && sameRetirementCheckout(entry, receipt))))
: outcome.remaining ?? null,
retired,
};
diff --git a/server/services/worktreeManager.js b/server/services/worktreeManager.js
index 3ff3c00c3a..50fb8cfda8 100644
--- a/server/services/worktreeManager.js
+++ b/server/services/worktreeManager.js
@@ -271,9 +271,10 @@ async function queueWorktreeCreate(repo, fn) {
* transaction also compares the old object id. The local absolute destination
* cannot resolve through an origin push URL. Existing hooks and denyDeletes
* policy still apply. Share the creation lane so managed attachments cannot
- * enter between the receiver's holder check and ref transaction.
+ * enter between the receiver's holder check and ref transaction. `onRetired`
+ * receives the verified branch archive only after deletion and config retirement.
*/
-export function deleteCompletedLocalBranch(repoPath, branch, expectedHead, { beforeMutation = async () => {} } = {}) {
+export function deleteCompletedLocalBranch(repoPath, branch, expectedHead, { beforeMutation = async () => {}, onRetired = async () => {} } = {}) {
let callbackError;
return queueWorktreeCreate(repoPath, async (commonDir) => {
if (PROTECTED_BRANCHES.includes(branch)) return false;
@@ -289,12 +290,14 @@ export function deleteCompletedLocalBranch(repoPath, branch, expectedHead, { bef
const preservation = await preserveBranchRetirement(repoPath, common, branch, expectedHead);
if (!await preservation.verify()) return false;
await Promise.resolve().then(beforeMutation).catch(error => { callbackError = error; throw error; });
- return preservation.retire(async () => {
+ const retired = await preservation.retire(async () => {
const result = await execGit(['push',
'--receive-pack=git -c receive.denyCurrentBranch=refuse -c receive.denyDeleteCurrent=refuse -c receive.autogc=false receive-pack',
`--force-with-lease=${ref}:${expectedHead}`, '--', common, `:${ref}`], repoPath, { ignoreExitCode: true });
return result.exitCode === 0;
});
+ if (retired) await Promise.resolve().then(() => onRetired(preservation)).catch(error => { callbackError = error; throw error; });
+ return retired;
}).catch(error => { if (error === callbackError) throw error; return false; });
}
@@ -2157,7 +2160,8 @@ export async function cleanupOrphanedWorktrees(sourceWorkspace, getActiveIds, {
export async function reapMergedWorktrees(sourceWorkspace, {
activeAgentIds = new Set(),
claimOwners,
- includeClaudeTrees = true
+ includeClaudeTrees = true,
+ appId = null
} = {}) {
const { getDefaultBranch, hasBranchMergeEvidence } = await import('./git.js');
const { readClaimOwnershipAgents, retireWithUnlockedArchive } = await import('./cosClaimOwnershipState.js');
@@ -2251,8 +2255,11 @@ export async function reapMergedWorktrees(sourceWorkspace, {
return { fence: { repoPath: sourceWorkspace, path: wt.path, branch: branchName } };
},
archive: async () => {
- const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
- return preserveMergedCheckout(sourceWorkspace, wt, target).then(archive => ({ archive }), (error) => {
+ const { preserveMergedCheckout, preserveSupersededCheckout } = await import('./heldCheckoutRecovery.js');
+ const preserve = appId
+ ? preserveSupersededCheckout({ appId, repoPath: sourceWorkspace, tree: wt, defaultBranch: target })
+ : preserveMergedCheckout(sourceWorkspace, wt, target);
+ return preserve.then(archive => ({ archive }), (error) => {
skipped.push({ path: wt.path, branch: branchName, reason: 'archive-failed', detail: error.message });
return {};
});
@@ -2269,6 +2276,10 @@ export async function reapMergedWorktrees(sourceWorkspace, {
const holders = removal.entries || await listWorktrees(sourceWorkspace).catch(() => null);
const branchDeleted = holders && !holders.some(holder => holder.branch === wt.branch)
&& await deleteCompletedLocalBranch(sourceWorkspace, branchName, wt.head);
+ if (branchDeleted && preservation.recordRetirement) {
+ const recorded = await preservation.recordRetirement().then(() => true, () => false);
+ if (!recorded) { hold('retirement-receipt-unverified'); return; }
+ }
reaped.push({ path: wt.path, branch: branchName, locked: !!wt.locked, branchDeleted: Boolean(branchDeleted), archiveDir: preservation.archiveDir });
if (!branchDeleted) hold('branch-ref-changed-or-new-holder');
},