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([issue-12682]): archive retiring checkouts outside the claim-ownership lock

[._.]/ Adam Eivydf278dd0c11b
diff --git a/server/services/README.md b/server/services/README.md
index 9fb8836ae6..fdeb62b35c 100644
--- a/server/services/README.md
+++ b/server/services/README.md
@@ -14,7 +14,7 @@ image-generation paths below are useful entry points when tracing render jobs.
| `initializedCheckoutRecovery.js` | Explicit macOS private-module checkout archive, standalone recovery proof, durable reservation, reversible whole-directory quarantine and transaction-bound branch finalization/receipt replay; automatic module cleanup remains blocked. |
| `heldCheckoutReview.js` | Computes fresh forge identity, merged PR/default refs and exact code comparisons for a digest-bound operator retirement; no saved consent or policy rewrites. |
| `heldCheckoutRecovery.js` | Prepares scoped retirement reviews and preserves checkout content, empty gitlinks and private Git administration before ownership-checked removal and expected-head local ref deletion. Pending-merge receipts use `retirePendingMergeCheckout`, which independently verifies the merged head and refuses locks, supersession and initialized submodules. |
-| `cosClaimOwnershipState.js` | Shared ownership lock and fail-closed live-agent reader used by claim binding and worktree cleanup. Re-exported by `cosClaimOwnership.js` for existing callers; does not import reconciliation. |
+| `cosClaimOwnershipState.js` | Shared ownership lock, per-checkout retirement fence with `retireWithUnlockedArchive` (archives run between two lock sections), and fail-closed live-agent reader used by claim binding and worktree cleanup. Re-exported by `cosClaimOwnership.js` for existing callers; does not import reconciliation. |
| `systemActivityNotify.js` | Coalesced activity invalidation signal and LLM lifecycle adapters; producers do not import media execution. |
| `systemActivityWatchers.js` | Socket initialization arms media and CoS activity subscriptions here, sharing the notification signal without pulling boot observers into producers. |
| `branchCompletionPolicy.js` | Retains explicit registered PR completion policy through agent archives. `readBranchCompletionHold` gates reconciliation by exact repository/branch/PR identity; human handoffs and configured review stay held, explicit releases require a fresh matching forge head, and verified merged retirement is a separate action. |
diff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.js
index b016781eb1..f897fd6a44 100644
--- a/server/services/branchReconcile.js
+++ b/server/services/branchReconcile.js
@@ -41,7 +41,7 @@ import { PROTECTED_BRANCHES } from '../lib/gitArgs.js';
import { ledgerPath, readVerdictLedger, partitionSuperseded, recordVerdictInstruction, recordVerdict, sameDirtyPaths } from './supersededLedger.js';
import { backupSupersededBranch } from './supersededBackup.js';
import { claimCheckoutOwnerReason, RECONCILE_AGENT_ID_PLACEHOLDER } from '../lib/claimContinuation.js';
-import { withClaimOwnershipLock, readClaimOwnershipAgents } from './cosClaimOwnership.js';
+import { withClaimOwnershipLock, readClaimOwnershipAgents, retireWithUnlockedArchive } from './cosClaimOwnership.js';
import { agentApiCurl } from '../lib/agentApiToken.js';
import { localApiBaseUrl } from '../lib/networkExposure.js';
@@ -1309,44 +1309,60 @@ async function retireBranch(repoPath, b, opts) {
// under the lock binding takes: a bind lands before this check or after the
// removal, never between them.
if (b.claimOwnerReason) return { ok: false, reason: b.claimOwnerReason };
- return withClaimOwnershipLock(async () => {
- const agents = await readAgents().catch(() => null);
- const reason = claimCheckoutOwnerReason({
- branchName: b.branch, holderPath: b.worktreePath, sourceWorkspace: repoPath, agents,
- });
- if (reason) return { ok: false, reason };
- // A fresh registry read under the binding lock supersedes the directory-age
- // proxy. A claim name alone is not a live owner. Keep all other retirement
- // gates, and refresh workspace owners too (not only explicit claim bindings).
- return retireBranchNow(repoPath, b, {
- ...opts,
- activeAgentIds: buildActiveOwnerIds(opts.activeAgentIds, agents),
- allowLiveClaim: true,
- });
+ // A merged checkout's archive runs between two ownership critical sections
+ // (#12682) so it cannot starve the shared queue; removal re-proves everything.
+ return retireWithUnlockedArchive({
+ busy: () => ({ ok: false, reason: 'checkout-retirement-reserved' }),
+ admit: async () => {
+ const agents = await readAgents().catch(() => null);
+ const reason = claimCheckoutOwnerReason({
+ branchName: b.branch, holderPath: b.worktreePath, sourceWorkspace: repoPath, agents,
+ });
+ if (reason) return { result: { ok: false, reason } };
+ // A fresh registry read under the binding lock supersedes the directory-age
+ // proxy. A claim name alone is not a live owner. Keep all other retirement
+ // gates, and refresh workspace owners too (not only explicit claim bindings).
+ const gated = await admitBranchRetirement(repoPath, b, {
+ ...opts,
+ activeAgentIds: buildActiveOwnerIds(opts.activeAgentIds, agents),
+ allowLiveClaim: true,
+ });
+ if (gated.result) return gated;
+ if (!gated.archiveTree) return { result: await finishBranchRetirement(repoPath, gated, null) };
+ return { fence: { repoPath, path: gated.archiveTree.path, branch: gated.b.branch }, gated };
+ },
+ archive: async ({ gated }) => {
+ const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
+ return preserveMergedCheckout(repoPath, gated.archiveTree, gated.mergeTarget).then(archive => ({ archive }),
+ error => ({ result: { ok: false, reason: 'archive-failed', detail: error.message } }));
+ },
+ finish: ({ gated }, preservation) => finishBranchRetirement(repoPath, gated, preservation),
});
}
-async function retireBranchNow(repoPath, b, { activeAgentIds = new Set(), staleClaimIdleMs = STALE_CLAIM_IDLE_MS, allowLiveClaim = false, label, requireCleanWorktree = true, unmanagedIdleMs, prepare, claimOwners, mergedRetirement = false, mergeTarget }) {
- if (PROTECTED_BRANCHES.includes(b.branch)) return { ok: false, reason: 'protected-branch' };
+/** Every gate before the archive. Returns `{ result }` to stop, else the context removal needs. */
+async function admitBranchRetirement(repoPath, b, { activeAgentIds = new Set(), staleClaimIdleMs = STALE_CLAIM_IDLE_MS, allowLiveClaim = false, label, requireCleanWorktree = true, unmanagedIdleMs, prepare, claimOwners, mergedRetirement = false, mergeTarget }) {
+ 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);
- if (!defaultBranch) return { ok: false, reason: 'default-branch-unavailable' };
- if (b.branch === defaultBranch) return { ok: false, reason: 'protected-branch' };
+ if (!defaultBranch) return stop({ ok: false, reason: 'default-branch-unavailable' });
+ if (b.branch === defaultBranch) return stop({ ok: false, reason: 'protected-branch' });
const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
const readPolicyHold = () => readBranchCompletionHold({ repoPath, branch: b.branch, retirement: mergedRetirement });
const policyHold = await readPolicyHold();
- if (policyHold) return { ok: false, reason: policyHold };
- let preservation = null;
+ if (policyHold) return stop({ ok: false, reason: policyHold });
+ let archiveTree = null;
const expectedHead = (await execGit(['rev-parse', '--verify', `refs/heads/${b.branch}`], repoPath).catch(() => null))?.stdout?.trim();
- if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(expectedHead || '')) return { ok: false, reason: mergedRetirement ? 'not-merged-on-recheck' : 'branch-head-unavailable' };
+ if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(expectedHead || '')) return stop({ ok: false, reason: mergedRetirement ? 'not-merged-on-recheck' : 'branch-head-unavailable' });
if (mergedRetirement) {
// Completion audits may know only the branch. Resolve its actual holder,
// and pin merge evidence to its current commit rather than the scan's flag.
const holders = await listWorktrees(repoPath).catch(() => null);
- if (!holders) return { ok: false, reason: 'worktree-ownership-unreadable' };
+ if (!holders) return stop({ ok: false, reason: 'worktree-ownership-unreadable' });
const holder = holders.find(wt => wt.branch === `refs/heads/${b.branch}`);
- if (!await hasBranchMergeEvidence(repoPath, expectedHead, mergeTarget).catch(() => false)) return { ok: false, reason: 'not-merged-on-recheck' };
- if (b.worktreePath && b.worktreePath !== holder?.path) return { ok: false, reason: 'worktree-holder-changed' };
- if (holder?.path === repoPath) return { ok: false, reason: 'currently-checked-out' };
+ if (!await hasBranchMergeEvidence(repoPath, expectedHead, mergeTarget).catch(() => false)) return stop({ ok: false, reason: 'not-merged-on-recheck' });
+ if (b.worktreePath && b.worktreePath !== holder?.path) return stop({ ok: false, reason: 'worktree-holder-changed' });
+ if (holder?.path === repoPath) return stop({ ok: false, reason: 'currently-checked-out' });
b = { ...b, worktreePath: holder?.path || null, worktreeLocked: holder?.locked || false };
}
if (b.worktreePath) {
@@ -1370,11 +1386,11 @@ async function retireBranchNow(repoPath, b, { activeAgentIds = new Set(), staleC
// still inside its grace window). Without it the caller can only park on
// the recheck cadence and the two waits stack — see boundParkedUntil.
const retryAt = worktreeProtectionExpiresAt(gate);
- return { ok: false, reason: protectedReason, ...(retryAt ? { retryAt } : {}) };
+ return stop({ ok: false, reason: protectedReason, ...(retryAt ? { retryAt } : {}) });
}
const dirty = await isWorktreeDirty(b.worktreePath);
- if (dirty === null) return { ok: false, reason: 'worktree-status-unavailable' };
- if (requireCleanWorktree && dirty) return { ok: false, reason: 'worktree-dirty' };
+ if (dirty === null) return stop({ ok: false, reason: 'worktree-status-unavailable' });
+ if (requireCleanWorktree && dirty) return stop({ ok: false, reason: 'worktree-dirty' });
}
if (mergedRetirement && b.worktreePath) {
if (isHumanClaimWorktree(worktreeAgentId(b.worktreePath))) {
@@ -1386,14 +1402,17 @@ async function retireBranchNow(repoPath, b, { activeAgentIds = new Set(), staleC
const completed = records && await hasCompletedCheckoutEvidence(records, {
repoPath, branch: b.branch, path: b.worktreePath, head: expectedHead,
});
- if (!completed) return { ok: false, reason: records ? 'claim-completion-unverified' : 'claim-ownership-unreadable' };
+ if (!completed) return stop({ ok: false, reason: records ? 'claim-completion-unverified' : 'claim-ownership-unreadable' });
}
const tree = (await listWorktrees(repoPath)).find(wt => wt.path === b.worktreePath);
- if (!tree || tree.head !== expectedHead) return { ok: false, reason: 'worktree-holder-changed' };
- const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
- preservation = await preserveMergedCheckout(repoPath, tree, mergeTarget).catch(error => ({ error }));
- if (preservation.error) return { ok: false, reason: 'archive-failed', detail: preservation.error.message };
+ 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 };
+}
+
+/** Removal and branch deletion; `preservation` is the archive taken after admission, if any. */
+async function finishBranchRetirement(repoPath, { b, expectedHead, readPolicyHold, mergeTarget, label, requireCleanWorktree, prepare, claimOwners, mergedRetirement }, preservation) {
const prepared = prepare ? await prepare() : null;
if (prepared?.error) return { ok: false, reason: prepared.error };
if (b.worktreePath) {
@@ -1566,31 +1585,39 @@ async function reapDetachedWorktrees(repoPath, defaultBranch, detached, { active
// Re-verify at action time against what the tree holds NOW: its HEAD may have
// been switched to a branch or an unmerged commit since the gather.
if (!await isStillDetachedOnMerged(repoPath, tree.path, defaultBranch)) continue;
- const removal = await withClaimOwnershipLock(async () => {
- const verifyRemoval = async (holder) => {
- if (!holder || holder.branch) return 'worktree-holder-changed';
- if (claimOwners !== undefined) {
- const agents = claimOwners?.readAgents ? await claimOwners.readAgents().catch(() => null) : claimOwners?.agents;
- // Detached HEAD has no claim branch, but a run may occupy its directory.
- const reason = claimCheckoutOwnerReason({ branchName: 'HEAD', holderPath: tree.path, sourceWorkspace: repoPath, agents });
- if (reason) return reason;
- }
- const dirty = await isWorktreeDirty(tree.path);
- if (dirty === null) return 'worktree-status-unavailable';
- if (dirty) return 'worktree-dirty';
- return await isStillDetachedOnMerged(repoPath, tree.path, defaultBranch) ? null : 'worktree-head-changed';
- };
- const current = (await listWorktrees(repoPath).catch(() => null))?.find(holder => holder.path === tree.path);
- if (!current || current.head !== tree.head || current.branch) return { removed: false, reason: 'worktree-holder-changed' };
- const initialHold = await verifyRemoval(current);
- if (initialHold) return { removed: false, reason: initialHold };
- const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
- const preservation = await preserveMergedCheckout(repoPath, current, defaultBranch).catch(error => ({ error }));
- if (preservation.error) return { removed: false, reason: 'archive-failed' };
- return forceRemoveWorktreeDir(repoPath, tree.path, {
+ const verifyRemoval = async (holder) => {
+ if (!holder || holder.branch) return 'worktree-holder-changed';
+ if (claimOwners !== undefined) {
+ const agents = claimOwners?.readAgents ? await claimOwners.readAgents().catch(() => null) : claimOwners?.agents;
+ // Detached HEAD has no claim branch, but a run may occupy its directory.
+ const reason = claimCheckoutOwnerReason({ branchName: 'HEAD', holderPath: tree.path, sourceWorkspace: repoPath, agents });
+ if (reason) return reason;
+ }
+ const dirty = await isWorktreeDirty(tree.path);
+ if (dirty === null) return 'worktree-status-unavailable';
+ if (dirty) return 'worktree-dirty';
+ return await isStillDetachedOnMerged(repoPath, tree.path, defaultBranch) ? null : 'worktree-head-changed';
+ };
+ // The archive runs between two ownership critical sections (#12682) so it
+ // cannot starve the shared ownership queue; removal re-proves everything.
+ const removal = await retireWithUnlockedArchive({
+ busy: () => ({ removed: false, reason: 'checkout-retirement-reserved' }),
+ admit: async () => {
+ const current = (await listWorktrees(repoPath).catch(() => null))?.find(holder => holder.path === tree.path);
+ if (!current || current.head !== tree.head || current.branch) return { result: { removed: false, reason: 'worktree-holder-changed' } };
+ const initialHold = await verifyRemoval(current);
+ if (initialHold) return { result: { removed: false, reason: initialHold } };
+ return { fence: { repoPath, path: tree.path }, current };
+ },
+ archive: async ({ current }) => {
+ const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
+ return preserveMergedCheckout(repoPath, current, defaultBranch).then(archive => ({ archive }),
+ () => ({ result: { removed: false, reason: 'archive-failed' } }));
+ },
+ finish: (_admitted, preservation) => forceRemoveWorktreeDir(repoPath, tree.path, {
label: '🔀 branch-reconcile: remove detached worktree', log: 'all',
verifyRemoval: async holder => await verifyRemoval(holder) || await preservation.verify(holder),
- });
+ }),
});
if (!removal.removed) {
hold(tree, removal.reason || 'worktree-remove-failed');
diff --git a/server/services/branchReconcile.test.js b/server/services/branchReconcile.test.js
index c5984159e8..6b24e6de46 100644
--- a/server/services/branchReconcile.test.js
+++ b/server/services/branchReconcile.test.js
@@ -134,6 +134,7 @@ import {
import * as git from './git.js';
import * as wt from './worktreeManager.js';
import { preserveMergedCheckout } from './heldCheckoutRecovery.js';
+import { withClaimOwnershipLock, checkoutRetirementFenceReason } from './cosClaimOwnership.js';
import { hasCompletedCheckoutEvidence } from './completedCheckoutEvidence.js';
import { execGit } from '../lib/execGit.js';
import { execGh } from './github.js';
@@ -142,6 +143,28 @@ import { getOriginInfo } from '../lib/gitRemote.js';
import { __resetForgeNoAccessLog } from '../lib/forgeAccessErrors.js';
const RETIRE_HEAD = 'a'.repeat(40);
+/**
+ * #12682: hold preservation open and prove, while it is pending, that the shared
+ * ownership queue is free and only the retiring checkout is fenced.
+ */
+async function expectArchiveOutsideOwnershipLock(retirement, fenced) {
+ let started;
+ let finish;
+ const archiving = new Promise(resolve => { started = resolve; });
+ preserveMergedCheckout.mockImplementationOnce(() => new Promise(resolve => {
+ finish = () => resolve({ archiveDir: '/archive', verify: async () => null });
+ started();
+ }));
+ const pending = retirement();
+ await archiving;
+ expect(await withClaimOwnershipLock(() => 'settled')).toBe('settled');
+ expect(checkoutRetirementFenceReason({ repoPath: '/repo', ...fenced })).toBe('checkout-retirement-reserved');
+ expect(checkoutRetirementFenceReason({ repoPath: '/repo', branch: 'feature/unrelated', path: '/repo/data/cos/worktrees/other' })).toBe(null);
+ finish();
+ const result = await pending;
+ expect(checkoutRetirementFenceReason({ repoPath: '/repo', ...fenced })).toBe(null);
+ return result;
+}
const pinnedRef = args => args[0] === 'rev-parse' && args[1] === '--verify' && /^refs\/heads\/[^{}]+$/.test(args[2]);
const gitFixtureResult = (stdout = '', exitCode = 0) => async args => ({ stdout: pinnedRef(args) ? RETIRE_HEAD : stdout, exitCode });
let retirementTrees = [];
@@ -438,6 +461,15 @@ describe('cleanupMerged', () => {
expect(git.deleteBranch).not.toHaveBeenCalled();
});
+ it('archives a merged checkout outside the ownership lock while fencing its branch', async () => {
+ git.hasBranchMergeEvidence.mockResolvedValue(true);
+ const worktreePath = '/repo/.claude/worktrees/next-2190';
+ const res = await expectArchiveOutsideOwnershipLock(
+ () => cleanupMerged('/repo', 'main', [{ branch: 'next/issue-2190', worktreePath }]), { branch: 'next/issue-2190' });
+ expect(res.cleaned).toEqual(['next/issue-2190']);
+ expect(wt.forceRemoveWorktreeDir).toHaveBeenCalledWith('/repo', worktreePath, expect.any(Object));
+ });
+
it('deletes a merged branch with no worktree', async () => {
git.hasBranchMergeEvidence.mockResolvedValue(true);
const res = await cleanupMerged('/repo', 'main', [{ branch: 'orphan', worktreePath: null }]);
@@ -1910,6 +1942,14 @@ describe('reconcile — detached-HEAD worktrees (#10825)', () => {
expect(preserveMergedCheckout).toHaveBeenCalledWith('/repo', detachedTree(path), 'main');
});
+ it('archives a detached tree outside the ownership lock while fencing its path', async () => {
+ const path = '/repo/data/cos/worktrees/agent-1234abcd';
+ wt.listWorktrees.mockResolvedValue([MAIN, detachedTree(path)]);
+ stubGit();
+ const res = await expectArchiveOutsideOwnershipLock(() => reconcile('/repo'), { path });
+ expect(res.cleaned).toContain(path);
+ });
+
it.each(['archive-failed', 'checkout-content-changed'])('preserves detached recovery evidence on %s', async reason => {
const path = '/repo/data/cos/worktrees/agent-1234abcd';
wt.listWorktrees.mockResolvedValue([MAIN, detachedTree(path)]);
diff --git a/server/services/cosClaimOwnership.js b/server/services/cosClaimOwnership.js
index e49387776b..1a5c2f4d32 100644
--- a/server/services/cosClaimOwnership.js
+++ b/server/services/cosClaimOwnership.js
@@ -19,13 +19,13 @@
import { resolve } from 'path';
import { bindClaimBranch, releaseClaimBranch, reserveReconcileBranch, claimCheckoutOwnerReason } from '../lib/claimContinuation.js';
-import { withClaimOwnershipLock, readClaimOwnershipAgents } from './cosClaimOwnershipState.js';
+import { withClaimOwnershipLock, readClaimOwnershipAgents, checkoutRetirementFenceReason } from './cosClaimOwnershipState.js';
const normalize = (p) => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
const samePath = (a, b) => typeof a === 'string' && typeof b === 'string' && normalize(a) === normalize(b);
const branchOf = (wt) => String(wt?.branch || '').replace(/^refs\/heads\//, '');
-export { withClaimOwnershipLock, readClaimOwnershipAgents } from './cosClaimOwnershipState.js';
+export { withClaimOwnershipLock, readClaimOwnershipAgents, checkoutRetirementFenceReason, reserveCheckoutRetirementFence, retireWithUnlockedArchive } from './cosClaimOwnershipState.js';
// Match merge admission's pre-start budget, across BOTH queues. A deadline is
// cancellation only until the state callback starts; afterwards it diagnoses
@@ -106,6 +106,10 @@ export async function updateClaimOwnership({ agentId, action, branch }) {
if (!agent || agent.id !== agentId) return { [done]: false, reason: 'owner-unknown' };
const repoPath = agent.sourceWorkspace || agent.metadata?.sourceWorkspace || agent.workspacePath || agent.metadata?.workspacePath;
if (!repoPath) return { [done]: false, reason: 'ownership-unreadable' };
+ // Binding a checkout that is mid-archive would hand it to a run that the
+ // retirement then removes; releasing a branch never needs the fence.
+ const fenced = action === 'bind' && checkoutRetirementFenceReason({ repoPath, branch });
+ if (fenced) return { [done]: false, reason: fenced };
const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
return withCheckoutPublication(repoPath, async () => {
const patch = action === 'bind' ? bindClaimBranch(agent, branch, Object.values(state.agents)) : releaseClaimBranch(agent, branch);
@@ -160,6 +164,8 @@ export async function checkReconcileOwnership(input, deps = {}) {
if (completionHold) return { admitted: false, reason: completionHold };
const holder = worktrees.find((wt) => branchOf(wt) === branch) || null;
if (worktreePath && !samePath(holder?.path, worktreePath)) return { admitted: false, reason: 'holder-changed' };
+ const fenced = checkoutRetirementFenceReason({ repoPath, branch, path: holder?.path || null });
+ if (fenced) return { admitted: false, reason: fenced };
const others = agentId ? agents.filter((a) => a?.id !== agentId) : agents;
const reason = resolveLiveOwnerReason({
branch, path: holder?.path || null, locked: Boolean(holder?.locked),
diff --git a/server/services/cosClaimOwnership.test.js b/server/services/cosClaimOwnership.test.js
index 93c5578b89..1abdebac1a 100644
--- a/server/services/cosClaimOwnership.test.js
+++ b/server/services/cosClaimOwnership.test.js
@@ -22,7 +22,7 @@ vi.mock('./cosEvents.js', () => ({ cosEvents: { emit: vi.fn() } }));
const { updateClaimOwnership, checkReconcileOwnership, CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS } = await import('./cosClaimOwnership.js');
// Hold the same leaf fence cleanup uses while exercising binding through its public service.
-const { withClaimOwnershipLock } = await import('./cosClaimOwnershipState.js');
+const { withClaimOwnershipLock, reserveCheckoutRetirementFence } = await import('./cosClaimOwnershipState.js');
const { claimContinuationAdmission, claimBranchAdmission } = await import('../lib/claimContinuation.js');
const { withStateLock, readAgentsStateForSafetyCheck, saveState } = await import('./cosState.js');
@@ -291,6 +291,26 @@ describe('checkReconcileOwnership reservation', () => {
expect(store.state.agents['agent-recon'].metadata.claimBranches).toBeUndefined();
});
+ // #12682: retirement archives with the ownership lock released, fenced per checkout.
+ it('refuses binds and admissions for a checkout being archived, and only that checkout, until the fence lifts', async () => {
+ const before = structuredClone(store.state);
+ const releaseFence = await withClaimOwnershipLock(() => reserveCheckoutRetirementFence({ repoPath: SOURCE, path: CHILD, branch: 'refs/heads/claim/issue-101' }));
+ expect(await withClaimOwnershipLock(() => reserveCheckoutRetirementFence({ repoPath: `${SOURCE}/`, path: CHILD }))).toBeNull();
+
+ expect(await bind()).toEqual({ bound: false, reason: 'checkout-retirement-reserved' });
+ expect(await admit('agent-recon')).toEqual({ admitted: false, reason: 'checkout-retirement-reserved' });
+ expect(await admit(undefined)).toEqual({ admitted: false, reason: 'checkout-retirement-reserved' });
+ expect(store.state).toEqual(before);
+ // Releasing a branch and binding a different one are not fenced.
+ expect(await updateClaimOwnership({ agentId: 'agent-picker', action: 'bind', branch: 'claim/issue-102' }))
+ .toEqual({ bound: true, branch: 'claim/issue-102' });
+ expect(await updateClaimOwnership({ agentId: 'agent-picker', action: 'release', branch: 'claim/issue-102' }))
+ .toEqual({ released: true, branch: 'claim/issue-102' });
+
+ await withClaimOwnershipLock(releaseFence);
+ expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
+ });
+
it('reserves nothing for a branch no claim run can bind', async () => {
const before = structuredClone(store.state);
const feature = { path: '/repos/app-x/other', branch: 'refs/heads/feature/x' };
diff --git a/server/services/cosClaimOwnershipState.js b/server/services/cosClaimOwnershipState.js
index 31681eeaed..8dfe16c3f3 100644
--- a/server/services/cosClaimOwnershipState.js
+++ b/server/services/cosClaimOwnershipState.js
@@ -1,4 +1,6 @@
/** Shared claim-ownership fence and trusted reader, independent of reconciliation. */
+import { resolve } from 'path';
+
// One in-process tail shared by binding and branch-reconcile's retirement, so a
// bind cannot land between cleanup's ownership re-read and its removal.
let ownershipTail = Promise.resolve();
@@ -8,6 +10,71 @@ export function withClaimOwnershipLock(work) {
return run;
}
+// Checkouts being archived for retirement with the ownership lock released
+// (#12682). Every ownership operation queues behind that lock with a 15 s budget,
+// so slow archive I/O runs outside it; this fence keeps binds and reconcile
+// admissions off the one checkout meanwhile. The removal path still re-reads
+// owners and fingerprints under the lock, so the fence adds refusal, never permission.
+const retirementFences = new Set();
+const fencePath = p => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
+const fenceBranch = b => (b ? String(b).replace(/^refs\/heads\//, '') : null);
+
+/** `checkout-retirement-reserved` when `branch` or checkout `path` of `repoPath` is fenced. */
+export function checkoutRetirementFenceReason({ repoPath, path = null, branch = null }) {
+ if (!repoPath) return null;
+ const repo = fencePath(repoPath);
+ const at = path ? fencePath(path) : null;
+ const name = fenceBranch(branch);
+ for (const fence of retirementFences) {
+ if (fence.repo !== repo) continue;
+ if ((at && fence.path === at) || (name && name !== 'HEAD' && fence.branch === name)) return 'checkout-retirement-reserved';
+ }
+ return null;
+}
+
+/**
+ * Fence one checkout while it is archived outside the lock. Call while holding
+ * `withClaimOwnershipLock`, after the ownership checks pass, and call the returned
+ * release under the lock once removal settles (it is idempotent, so a `finally`
+ * may repeat it). Returns null when the checkout is already fenced.
+ */
+export function reserveCheckoutRetirementFence({ repoPath, path, branch = null }) {
+ if (checkoutRetirementFenceReason({ repoPath, path, branch })) return null;
+ const fence = { repo: fencePath(repoPath), path: fencePath(path), branch: fenceBranch(branch) };
+ retirementFences.add(fence);
+ return () => { retirementFences.delete(fence); };
+}
+
+/**
+ * Retire one checkout with its archive between two ownership critical sections.
+ * - `admit()` runs under the lock and returns `{ result }` to settle there, or
+ * `{ fence: { repoPath, path, branch }, ... }` to archive. An already-fenced
+ * checkout settles as `busy()`.
+ * - `archive(admitted)` runs with the lock released and the fence held, and
+ * returns `{ result }` to stop or `{ archive }` to continue.
+ * - `finish(admitted, archive)` runs under the lock again with the fence held;
+ * it must re-prove ownership and the archived bytes before removing anything.
+ */
+export async function retireWithUnlockedArchive({ admit, archive, finish, busy }) {
+ const admitted = await withClaimOwnershipLock(async () => {
+ const step = await admit();
+ if (!step.fence) return step;
+ const release = reserveCheckoutRetirementFence(step.fence);
+ return release ? { ...step, release } : { result: busy() };
+ });
+ if (!admitted.release) return admitted.result;
+ try {
+ const archived = await archive(admitted);
+ if (!('archive' in archived)) return archived.result;
+ return await withClaimOwnershipLock(async () => {
+ try { return await finish(admitted, archived.archive); }
+ finally { admitted.release(); }
+ });
+ } finally {
+ admitted.release();
+ }
+}
+
/** Destructive callers must not consume loadState's empty recovery default. */
export async function readClaimOwnershipAgents() {
const { readAgentsStateForSafetyCheck } = await import('./cosState.js');
diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.js
index 80c1483fe0..b0ff0bab2d 100644
--- a/server/services/heldCheckoutRecovery.js
+++ b/server/services/heldCheckoutRecovery.js
@@ -29,7 +29,7 @@ import { claimCheckoutOwnerReason } from '../lib/claimContinuation.js';
import { backupSlug } from './supersededBackup.js';
import { listWorktrees, forceRemoveWorktreeDir, deleteCompletedLocalBranch } from './worktreeManager.js';
import { getDefaultBranch, hasBranchMergeEvidence } from './git.js';
-import { withClaimOwnershipLock, readClaimOwnershipAgents } from './cosClaimOwnership.js';
+import { withClaimOwnershipLock, readClaimOwnershipAgents, retireWithUnlockedArchive } from './cosClaimOwnership.js';
export const heldCheckoutArchiveRoot = (cosDir = PATHS.cos) => join(cosDir, 'held-checkout-archives');
@@ -474,83 +474,95 @@ async function retireHeldCheckout({ repoPath, release, review }, opts = {}) {
if (!defaultBranch) return { ok: false, reason: 'default-branch-unavailable' };
if (branch === defaultBranch) return { ok: false, reason: 'protected-branch' };
- return withClaimOwnershipLock(async () => {
- if (opts.inventoryCurrent && !await opts.inventoryCurrent()) return { ok: false, reason: 'release-not-in-inventory' };
- await opts.beforeMutation?.();
- const first = await matchRelease(repoPath, release);
- if (!first.tree) return { ok: false, reason: first.reason };
- const { tree } = first;
- const merged = branch
- ? await hasBranchMergeEvidence(repoPath, branch, defaultBranch).catch(() => false)
- : await isAncestor(repoPath, tree.head, defaultBranch);
- if (!merged && !review) return { ok: false, reason: 'not-merged-on-recheck' };
- const reviewed = review ? await reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl }, opts) : null;
- if (reviewed && (!reviewed.ok || reviewed.review.digest !== review.digest)) return { ok: false, reason: reviewed.reason || 'retirement-review-changed' };
- if (reviewed?.review.comparison.disposition === 'review-supersession' && review.acceptSuperseded !== true) return { ok: false, reason: 'retirement-supersession-not-accepted' };
- const owner = await ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review) });
- if (owner) return { ok: false, reason: owner };
-
- const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, release, cosDir, review: reviewed?.review })
- .catch(error => ({ error }));
- if (archive.error) {
+ // Every ownership check queues behind the claim-ownership lock with a short
+ // budget, so the archive runs between two critical sections (#12682).
+ const refuse = reason => ({ result: { ok: false, reason } });
+ return retireWithUnlockedArchive({
+ busy: () => ({ ok: false, reason: 'checkout-retirement-reserved' }),
+ admit: async () => {
+ if (opts.inventoryCurrent && !await opts.inventoryCurrent()) return refuse('release-not-in-inventory');
+ await opts.beforeMutation?.();
+ const first = await matchRelease(repoPath, release);
+ if (!first.tree) return refuse(first.reason);
+ const { tree } = first;
+ const merged = branch
+ ? await hasBranchMergeEvidence(repoPath, branch, defaultBranch).catch(() => false)
+ : await isAncestor(repoPath, tree.head, defaultBranch);
+ if (!merged && !review) return refuse('not-merged-on-recheck');
+ const reviewed = review ? await reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl }, opts) : null;
+ if (reviewed && (!reviewed.ok || reviewed.review.digest !== review.digest)) return refuse(reviewed.reason || 'retirement-review-changed');
+ if (reviewed?.review.comparison.disposition === 'review-supersession' && review.acceptSuperseded !== true) return refuse('retirement-supersession-not-accepted');
+ const owner = await ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review) });
+ if (owner) return refuse(owner);
+ return { fence: { repoPath, path: tree.path, branch }, tree, reviewed };
+ },
+ archive: async ({ tree, reviewed }) => {
+ const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, release, cosDir, review: reviewed?.review })
+ .catch(error => ({ error }));
+ if (!archive.error) return { archive };
console.error(`❌ held-checkout recovery: archive failed for ${tree.path}, checkout kept: ${archive.error.message}`);
- return { ok: false, reason: 'archive-failed', detail: archive.error.message };
- }
+ return { result: { ok: false, reason: 'archive-failed', detail: archive.error.message } };
+ },
+ finish: ({ tree, reviewed }, archive) => finishHeldCheckoutRetirement({ repoPath, release, review, reviewed, tree, branch, archive }, opts),
+ });
+}
- // Archiving takes time; never unlock a lock that changed hands meanwhile.
- const second = await matchRelease(repoPath, release);
- if (!second.tree) return { ok: false, reason: second.reason, archiveDir: archive.dir };
- await opts.beforeMutation?.();
+/** The second critical section: re-prove the release, ownership and archived bytes, then remove. */
+async function finishHeldCheckoutRetirement({ repoPath, release, review, reviewed, tree, branch, archive }, opts) {
+ const { readAgents = readClaimOwnershipAgents } = opts;
+ // Archiving takes time; never unlock a lock that changed hands meanwhile.
+ const second = await matchRelease(repoPath, release);
+ if (!second.tree) return { ok: false, reason: second.reason, archiveDir: archive.dir };
+ await opts.beforeMutation?.();
+ if (release.locked) {
+ const unlocked = await execGit(['worktree', 'unlock', tree.path], repoPath).then(() => true, () => false);
+ if (!unlocked) return { ok: false, reason: 'worktree-unlock-failed', archiveDir: archive.dir };
+ }
+ const verifyRemoval = async (holder) => {
+ if (!holder || holder.head !== tree.head || shortBranch(holder.branch) !== branch) return 'worktree-holder-changed';
+ if (opts.inventoryCurrent && !await opts.inventoryCurrent()) return 'release-not-in-inventory';
+ const [reason, fresh] = await Promise.all([
+ ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review) }),
+ review ? reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl, unlocked: release.locked }, opts) : null,
+ ]);
+ if (fresh && (!fresh.ok || fresh.review.digest !== review.digest)) return fresh.reason || 'retirement-review-changed';
+ // The byte comparisons stay last so nothing else ages between them and removal.
+ const [administration, current] = await Promise.all([snapshotAdministration(tree.path), snapshotContent(tree.path).catch(() => null)]);
+ if (administration.fingerprint !== archive.administrationFingerprint) return 'checkout-administration-changed';
+ if (reason) return reason;
+ return current?.fingerprint === archive.fingerprint ? null : 'checkout-content-changed';
+ };
+ const removal = await forceRemoveWorktreeDir(repoPath, tree.path, {
+ label: '🧹 held-checkout recovery: remove checkout', log: 'all', verifyRemoval, beforeMutation: opts.beforeMutation,
+ });
+ if (!removal.removed) {
+ // Hand the lock back exactly as released. A lock someone took in the
+ // meantime makes this fail, which is the outcome we want anyway.
if (release.locked) {
- const unlocked = await execGit(['worktree', 'unlock', tree.path], repoPath).then(() => true, () => false);
- if (!unlocked) return { ok: false, reason: 'worktree-unlock-failed', archiveDir: archive.dir };
+ const args = ['worktree', 'lock', ...(release.lockReason != null ? ['--reason', release.lockReason] : []), tree.path];
+ await execGit(args, repoPath).catch(err => console.warn(`⚠️ held-checkout recovery: could not restore lock on ${tree.path}: ${err.message}`));
}
- const verifyRemoval = async (holder) => {
- if (!holder || holder.head !== tree.head || shortBranch(holder.branch) !== branch) return 'worktree-holder-changed';
- if (opts.inventoryCurrent && !await opts.inventoryCurrent()) return 'release-not-in-inventory';
- const [reason, fresh] = await Promise.all([
- ownerReason({ repoPath, tree, branch, readAgents, reviewed: Boolean(review) }),
- review ? reviewCurrentCheckout({ repoPath, release, prUrl: review.prUrl, unlocked: release.locked }, opts) : null,
- ]);
- if (fresh && (!fresh.ok || fresh.review.digest !== review.digest)) return fresh.reason || 'retirement-review-changed';
- // The byte comparisons stay last so nothing else ages between them and removal.
- const [administration, current] = await Promise.all([snapshotAdministration(tree.path), snapshotContent(tree.path).catch(() => null)]);
- if (administration.fingerprint !== archive.administrationFingerprint) return 'checkout-administration-changed';
- if (reason) return reason;
- return current?.fingerprint === archive.fingerprint ? null : 'checkout-content-changed';
- };
- const removal = await forceRemoveWorktreeDir(repoPath, tree.path, {
- label: '🧹 held-checkout recovery: remove checkout', log: 'all', verifyRemoval, beforeMutation: opts.beforeMutation,
- });
- if (!removal.removed) {
- // Hand the lock back exactly as released. A lock someone took in the
- // meantime makes this fail, which is the outcome we want anyway.
- if (release.locked) {
- const args = ['worktree', 'lock', ...(release.lockReason != null ? ['--reason', release.lockReason] : []), tree.path];
- await execGit(args, repoPath).catch(err => console.warn(`⚠️ held-checkout recovery: could not restore lock on ${tree.path}: ${err.message}`));
- }
- return { ok: false, reason: removal.reason || 'worktree-remove-failed', archiveDir: archive.dir };
- }
- console.log(`🧹 held-checkout recovery: retired ${tree.path} (archive: ${archive.dir})`);
- if (!branch) return { ok: true, archiveDir: archive.dir, branchDeleted: false };
-
- const hold = await ownerReason({ repoPath, tree: { ...tree, path: null }, branch, readAgents, reviewed: Boolean(review) });
- if (hold) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: hold };
- if (review) {
- const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
- const forge = await (opts.readForge || readRetirementForgeEvidence)(repoPath, branch, review.prUrl, { forgeAccount: opts.forgeAccount }).catch(() => null);
- const policy = await retirementPolicy(repoPath, branch, opts, policyReviewIdentity(release, review.prUrl, forge));
- if (JSON.stringify(policy) !== JSON.stringify(reviewed.review.policy) || JSON.stringify(forge) !== JSON.stringify(reviewed.review.forge)) {
- return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: 'retirement-evidence-changed' };
- }
+ return { ok: false, reason: removal.reason || 'worktree-remove-failed', archiveDir: archive.dir };
+ }
+ console.log(`🧹 held-checkout recovery: retired ${tree.path} (archive: ${archive.dir})`);
+ if (!branch) return { ok: true, archiveDir: archive.dir, branchDeleted: false };
+
+ const hold = await ownerReason({ repoPath, tree: { ...tree, path: null }, branch, readAgents, reviewed: Boolean(review) });
+ if (hold) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: hold };
+ if (review) {
+ const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
+ const forge = await (opts.readForge || readRetirementForgeEvidence)(repoPath, branch, review.prUrl, { forgeAccount: opts.forgeAccount }).catch(() => null);
+ const policy = await retirementPolicy(repoPath, branch, opts, policyReviewIdentity(release, review.prUrl, forge));
+ if (JSON.stringify(policy) !== JSON.stringify(reviewed.review.policy) || JSON.stringify(forge) !== JSON.stringify(reviewed.review.forge)) {
+ return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: 'retirement-evidence-changed' };
}
- // A new checkout/commit cannot be deleted by a stale name-only operation.
- const holders = await listWorktrees(repoPath).catch(() => null);
- if (!holders || holders.some(holder => shortBranch(holder.branch) === branch)) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: 'branch-has-new-holder' };
- const deleted = await deleteCompletedLocalBranch(repoPath, branch, release.head, { beforeMutation: opts.beforeMutation });
- if (!deleted) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: 'branch-ref-changed-or-delete-failed' };
- return { ok: true, archiveDir: archive.dir, branchDeleted: true };
- });
+ }
+ // A new checkout/commit cannot be deleted by a stale name-only operation.
+ const holders = await listWorktrees(repoPath).catch(() => null);
+ if (!holders || holders.some(holder => shortBranch(holder.branch) === branch)) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: 'branch-has-new-holder' };
+ const deleted = await deleteCompletedLocalBranch(repoPath, branch, release.head, { beforeMutation: opts.beforeMutation });
+ if (!deleted) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: 'branch-ref-changed-or-delete-failed' };
+ return { ok: true, archiveDir: archive.dir, branchDeleted: true };
}
const sameRelease = (entry, release) => entry.path === release.path && entry.head === release.head
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
index 596723b3da..def46254b0 100644
--- a/server/services/heldCheckoutRecovery.test.js
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -20,11 +20,13 @@ vi.mock('../lib/paths.js', async importOriginal => makePathsProxy(await importOr
afterAll(cleanupTempDataRoots);
const SYMLINKS = process.platform !== 'win32';
-const injected = vi.hoisted(() => ({ policies: [], schedule: null, app: null, fetchRemote: null, fetches: [] }));
+const injected = vi.hoisted(() => ({ policies: [], schedule: null, app: null, fetchRemote: null, fetches: [], onBundle: null }));
vi.mock('../lib/execGit.js', async importOriginal => {
const actual = await importOriginal();
- return { ...actual, execGit: (args, cwd, options) => {
+ return { ...actual, execGit: async (args, cwd, options) => {
+ // 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 (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);
@@ -49,6 +51,7 @@ vi.mock('./apps.js', () => ({ getAppById: async (id) => (injected.app?.id === id
const { retireInventoriedCheckout, prepareInventoriedCheckoutRetirement, retirePendingMergeCheckout, heldCheckoutArchiveRoot, preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
const { recordBranchReconcileOutcome, getBranchReconcileOutcome } = await import('./taskSchedule.js');
+const { withClaimOwnershipLock, checkReconcileOwnership } = await import('./cosClaimOwnership.js');
describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', () => {
let scratch;
@@ -58,7 +61,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
const noOwners = async () => [];
beforeEach(async () => {
- Object.assign(injected, { policies: [], schedule: { executions: {} }, app: { id: 'app-1', repoPath: null }, fetchRemote: null, fetches: [] });
+ Object.assign(injected, { policies: [], schedule: { executions: {} }, app: { id: 'app-1', repoPath: null }, fetchRemote: null, fetches: [], onBundle: null });
scratch = realpathSync(await mkdtemp(join(tmpdir(), 'portos-held-checkout-')));
const safeRepo = join(scratch, 'repo');
await mkdir(safeRepo);
@@ -385,6 +388,48 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(await archives()).toEqual([]);
});
+ // #12682: archive I/O ran inside the shared ownership lock and starved every
+ // claim-ownership check behind its 15 s queue budget for minutes.
+ it('archives with the ownership queue free while fencing only the checkout being retired', async () => {
+ const { path, release } = await heldCheckout('fenced', { branch: 'feature/fenced' });
+ let paused;
+ let resume;
+ const pausedArchive = new Promise(resolve => { paused = resolve; });
+ injected.onBundle = () => new Promise(resolve => { resume = resolve; paused(); });
+ const admission = branch => checkReconcileOwnership({ appId: 'app-1', branch },
+ { getAgents: async () => [], getActiveAgentIds: () => [], readCompletionHold: async () => null });
+
+ const retiring = retire(release);
+ await pausedArchive;
+ injected.onBundle = null;
+ expect(await withClaimOwnershipLock(() => 'settled')).toBe('settled');
+ expect(await admission('feature/fenced')).toEqual({ admitted: false, reason: 'checkout-retirement-reserved' });
+ expect(await admission('feature/unrelated')).toEqual({ admitted: true });
+ expect(await retireInventoriedCheckout({ appId: 'app-1', release }, { cosDir, readAgents: noOwners }))
+ .toEqual({ ok: false, reason: 'checkout-retirement-reserved' });
+ expect(existsSync(join(path, 'ignored.txt'))).toBe(true);
+
+ resume();
+ expect(await retiring).toMatchObject({ ok: true });
+ expect(existsSync(path)).toBe(false);
+ expect(await admission('feature/fenced')).toEqual({ admitted: true });
+ });
+
+ it.each([
+ // A file the archive did not see when it started, so only the final re-read catches it.
+ ['content', async (path) => writeFile(join(path, 'late.txt'), 'late work\n'), 'checkout content changed while archiving'],
+ ['administration', async (path) => writeFile(join((await execGit(['rev-parse', '--absolute-git-dir'], path)).stdout.trim(), 'MERGE_MSG'), 'synthetic\n'),
+ 'administration changed while archiving'],
+ ])('keeps the checkout when its %s changes while the unlocked archive runs', async (label, change, detail) => {
+ const { path, release } = await heldCheckout(`mid-archive-${label}`);
+ injected.onBundle = () => change(path);
+
+ expect(await retire(release)).toEqual({ ok: false, reason: 'archive-failed', detail });
+ expect(await registered(release.path)).toBe(true);
+ expect(await lockText(release.path)).toBe('synthetic external owner');
+ expect(await archives()).toEqual([]);
+ });
+
it('refuses unmerged work and a manual completion handoff before archiving anything', async () => {
const unmerged = await heldCheckout('unmerged');
await execGit(['worktree', 'unlock', unmerged.path], repo);
diff --git a/server/services/worktreeManager.js b/server/services/worktreeManager.js
index 18206aa113..44379118b9 100644
--- a/server/services/worktreeManager.js
+++ b/server/services/worktreeManager.js
@@ -1964,7 +1964,7 @@ export async function reapMergedWorktrees(sourceWorkspace, {
includeClaudeTrees = true
} = {}) {
const { getDefaultBranch, hasBranchMergeEvidence } = await import('./git.js');
- const { withClaimOwnershipLock, readClaimOwnershipAgents } = await import('./cosClaimOwnershipState.js');
+ const { readClaimOwnershipAgents, retireWithUnlockedArchive } = await import('./cosClaimOwnershipState.js');
const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
// Every entry point (scheduled or reconcile) needs a trusted
// registry. loadState/getAgents may default a corrupt file to empty state.
@@ -2030,41 +2030,52 @@ export async function reapMergedWorktrees(sourceWorkspace, {
if (!hasMergeEvidence) { hold('unmerged'); continue; }
// The early reconcile pass must see the SAME registered owners and branch
- // reservations as later retirement. Keep binding excluded until removal and
- // branch deletion settle, and re-read after a Git refusal too.
- await withClaimOwnershipLock(async () => {
- const verifyRemoval = async (holder) => {
- if (!holder || holder.branch !== wt.branch) return 'worktree-holder-changed';
- const agents = await readOwners();
- const ownerReason = claimCheckoutOwnerReason({ branchName, holderPath: wt.path, sourceWorkspace, agents });
- if (ownerReason) return ownerReason;
- const policyHold = await readBranchCompletionHold({ repoPath: sourceWorkspace, branch: branchName, retirement: true });
- if (policyHold) return policyHold;
- const reason = worktreeOwnershipReason({ path: wt.path, locked: holder.locked, activeAgentIds: readActiveIds(), roots: managedRoots, requireKnownLiveness: true });
- if (reason) return reason;
- const freshStatus = await readWorktreeStatus(wt.path);
- if (freshStatus === null) return 'worktree-status-unavailable';
- if (!classifyWorktreeDirt(freshStatus).clean) return 'worktree-dirty';
- return await hasBranchMergeEvidence(sourceWorkspace, branchName, target).catch(() => false) ? null : 'unmerged';
- };
- const initialHold = await verifyRemoval(wt);
- if (initialHold) { hold(initialHold); return; }
- const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');
- const preservation = await preserveMergedCheckout(sourceWorkspace, wt, target).catch(error => ({ error }));
- if (preservation.error) { skipped.push({ path: wt.path, branch: branchName, reason: 'archive-failed', detail: preservation.error.message }); return; }
- const removal = await forceRemoveWorktreeDir(sourceWorkspace, wt.path, {
- label: `worktree remove failed for ${wt.path}`,
- verifyRemoval: async holder => await verifyRemoval(holder) || await preservation.verify(holder),
- });
- if (!removal.removed) {
- skipped.push({ path: wt.path, branch: branchName, reason: removal.reason || 'remove-failed', warning: removal.warning });
- return;
- }
- const holders = await listWorktrees(sourceWorkspace).catch(() => null);
- const branchDeleted = holders && !holders.some(holder => holder.branch === wt.branch)
- && await deleteCompletedLocalBranch(sourceWorkspace, branchName, wt.head);
- 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');
+ // reservations as later retirement. Binding stays excluded until removal and
+ // branch deletion settle — by the lock, and by the checkout fence while the
+ // archive runs between the two critical sections (#12682).
+ const verifyRemoval = async (holder) => {
+ if (!holder || holder.branch !== wt.branch) return 'worktree-holder-changed';
+ const agents = await readOwners();
+ const ownerReason = claimCheckoutOwnerReason({ branchName, holderPath: wt.path, sourceWorkspace, agents });
+ if (ownerReason) return ownerReason;
+ const policyHold = await readBranchCompletionHold({ repoPath: sourceWorkspace, branch: branchName, retirement: true });
+ if (policyHold) return policyHold;
+ const reason = worktreeOwnershipReason({ path: wt.path, locked: holder.locked, activeAgentIds: readActiveIds(), roots: managedRoots, requireKnownLiveness: true });
+ if (reason) return reason;
+ const freshStatus = await readWorktreeStatus(wt.path);
+ if (freshStatus === null) return 'worktree-status-unavailable';
+ if (!classifyWorktreeDirt(freshStatus).clean) return 'worktree-dirty';
+ return await hasBranchMergeEvidence(sourceWorkspace, branchName, target).catch(() => false) ? null : 'unmerged';
+ };
+ await retireWithUnlockedArchive({
+ busy: () => hold('checkout-retirement-reserved'),
+ admit: async () => {
+ const initialHold = await verifyRemoval(wt);
+ if (initialHold) { hold(initialHold); return {}; }
+ 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) => {
+ skipped.push({ path: wt.path, branch: branchName, reason: 'archive-failed', detail: error.message });
+ return {};
+ });
+ },
+ finish: async (_admitted, preservation) => {
+ const removal = await forceRemoveWorktreeDir(sourceWorkspace, wt.path, {
+ label: `worktree remove failed for ${wt.path}`,
+ verifyRemoval: async holder => await verifyRemoval(holder) || await preservation.verify(holder),
+ });
+ if (!removal.removed) {
+ skipped.push({ path: wt.path, branch: branchName, reason: removal.reason || 'remove-failed', warning: removal.warning });
+ return;
+ }
+ const holders = await listWorktrees(sourceWorkspace).catch(() => null);
+ const branchDeleted = holders && !holders.some(holder => holder.branch === wt.branch)
+ && await deleteCompletedLocalBranch(sourceWorkspace, branchName, wt.head);
+ 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');
+ },
});
}
diff --git a/server/services/worktreeReap.test.js b/server/services/worktreeReap.test.js
index ee42e5c72c..10ec99eb03 100644
--- a/server/services/worktreeReap.test.js
+++ b/server/services/worktreeReap.test.js
@@ -33,6 +33,15 @@ import { hasBranchMergeEvidence, getStatus, getStatusPorcelain } from './git.js'
import { reapMergedWorktrees, cleanupOrphanedWorktrees, deleteCompletedLocalBranch, readWorktreeStatus } from './worktreeManager.js';
vi.mock('./branchCompletionPolicy.js', () => ({ readBranchCompletionHold: async () => null }));
vi.mock('./cosState.js', () => ({ readAgentsStateForSafetyCheck: async () => ({ trusted: true, agents: {} }) }));
+const archiveGate = vi.hoisted(() => ({ beforeArchive: null }));
+vi.mock('./heldCheckoutRecovery.js', async importOriginal => {
+ const actual = await importOriginal();
+ return { ...actual, preserveMergedCheckout: async (...args) => {
+ await archiveGate.beforeArchive?.();
+ return actual.preserveMergedCheckout(...args);
+ } };
+});
+import { withClaimOwnershipLock, checkoutRetirementFenceReason } from './cosClaimOwnershipState.js';
/**
* Why `wantedPath` was skipped, matched separator-insensitively — `skipped[].path`
@@ -474,6 +483,30 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('reapMergedWorktrees', () => {
expect(branches).toContain('pending-br');
});
+ // #12682: the archive ran inside the shared ownership lock and starved every
+ // claim-ownership check queued behind it.
+ it('archives with the ownership queue free while fencing only the reaped checkout', async () => {
+ const mergedPath = await addWorktree(dir, 'fenced', 'fenced-br');
+ await execGit(['merge', '--no-ff', 'fenced-br', '--no-edit'], dir);
+ let started;
+ let resume;
+ const archiving = new Promise(resolve => { started = resolve; });
+ archiveGate.beforeArchive = () => new Promise(resolve => { resume = resolve; started(); });
+ try {
+ const reaping = reapMergedWorktrees(dir, { includeClaudeTrees: true });
+ await archiving;
+ expect(await withClaimOwnershipLock(() => 'settled')).toBe('settled');
+ expect(checkoutRetirementFenceReason({ repoPath: dir, branch: 'fenced-br' })).toBe('checkout-retirement-reserved');
+ expect(checkoutRetirementFenceReason({ repoPath: dir, branch: 'unrelated-br' })).toBe(null);
+ resume();
+ expect((await reaping).reaped.map(r => r.branch)).toContain('fenced-br');
+ } finally {
+ archiveGate.beforeArchive = null;
+ }
+ expect(existsSync(mergedPath)).toBe(false);
+ expect(checkoutRetirementFenceReason({ repoPath: dir, branch: 'fenced-br' })).toBe(null);
+ });
+
it('preserves a merged worktree that has uncommitted changes', async () => {
const path = await addWorktree(dir, 'dirty', 'dirty-br');
await execGit(['merge', '--no-ff', 'dirty-br', '--no-edit'], dir);