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
refactor: turn repo-state verification's block-and-skip exits into named gate steps (#12955) (#13057)
[._.]/93e8e6ebfd91
diff --git a/server/services/agentRepoStateVerification.js b/server/services/agentRepoStateVerification.jsindex a2e3dada9e..74f3e2bc73 100644--- a/server/services/agentRepoStateVerification.js+++ b/server/services/agentRepoStateVerification.js@@ -304,18 +304,46 @@ async function resumeCompletionAudits() {return { checked, pendingAtStart: pending.length };}+const skipped = (skipReason, { issues = [], observed = null } = {}) => ({ verified: false, skipReason, issues, observed, recoveryTaskId: null });++/**+ * The cleanup ledger for one branch. `blockWith` records a hold and returns the+ * matching skip in one step, so a gate cannot return a skip while leaving the+ * ledger silent about the branch it held. `skipReason` overrides the returned+ * reason only where the caller-facing skip code differs from the ledger reason.+ *+ * @param {string} agentId+ * @param {{branch: string, path?: string}} location - stamped on every ledger entry+ */+function branchLedger(agentId, location) {+ const record = async (status, reason, extra = {}) => {+ const { recordCleanupOutcome } = await import('./cosAgentLifecycle.js');+ await recordCleanupOutcome(agentId, { status, reason, ...location, ...extra });+ };+ const blockWith = async (reason, { skipReason = reason, record: extra, issues, observed } = {}) => {+ await record('blocked', reason, extra);+ return skipped(skipReason, { issues, observed });+ };+ return { record, blockWith };+}+async function verifyRunBranches(input) {const meta = input.agentState?.metadata || {};if (meta.isWorktree === true || !isTruthyMeta(meta.claimPicksOwnBranch)) return verifyAgentBranchState(input);const bindings = [meta.claimBranches, meta.claimReleasedBranches];if (bindings.some(value => value != null && (!Array.isArray(value) || value.some(branch => typeof branch !== 'string' || !branch)))) {- return { verified: false, skipReason: REPO_STATE_SKIPS.GATE_UNREADABLE, issues: [], observed: null, recoveryTaskId: null };+ return skipped(REPO_STATE_SKIPS.GATE_UNREADABLE);}const branches = [...new Set(bindings.flatMap(value => value || []))];if (!branches.length) return verifyAgentBranchState(input);const sourceWorkspace = meta.sourceWorkspace || meta.workspacePath;const trees = sourceWorkspace ? await listWorktrees(sourceWorkspace).catch(() => null) : null;- if (!trees) return { verified: false, skipReason: REPO_STATE_SKIPS.GATE_UNREADABLE, issues: [], observed: null, recoveryTaskId: null };+ if (!trees) return skipped(REPO_STATE_SKIPS.GATE_UNREADABLE);+ const holdBranch = async (branch, reason, extra) => {+ // Per-branch swarm results carry no observation; a held branch was never probed.+ const { observed: _unprobed, ...held } = await branchLedger(input.agentId, { branch }).blockWith(reason, { record: extra });+ return { branch, ...held };+ };const results = [];for (const branch of branches) {const { readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');@@ -323,18 +351,14 @@ async function verifyRunBranches(input) {const agents = await readClaimOwnershipAgents().catch(() => null);const owner = claimCheckoutOwner({ branchName: branch, sourceWorkspace, agents });if (owner) {- const { recordCleanupOutcome } = await import('./cosAgentLifecycle.js');- await recordCleanupOutcome(input.agentId, { branch, status: 'blocked', reason: owner.reason, owners: owner.owners });- results.push({ branch, verified: false, skipReason: owner.reason, issues: [], recoveryTaskId: null });+ results.push(await holdBranch(branch, owner.reason, { owners: owner.owners }));continue;}// A current branch holder is not evidence of the old claim's checkout.// Only the server's completion capture names its original incarnation.const original = meta.completedCheckouts?.find(row => row.branch === branch);if (!original?.path) {- const { recordCleanupOutcome } = await import('./cosAgentLifecycle.js');- await recordCleanupOutcome(input.agentId, { branch, status: 'blocked', reason: 'claim-checkout-identity-unverified' });- results.push({ branch, verified: false, skipReason: 'claim-checkout-identity-unverified', issues: [], recoveryTaskId: null });+ results.push(await holdBranch(branch, 'claim-checkout-identity-unverified'));continue;}results.push({ branch, ...await verifyAgentBranchState({ ...input, prExpected: true,@@ -351,7 +375,6 @@ async function verifyAgentBranchState({ agentId, task, agentState, success, prExconst branchName = metadata.worktreeBranch || null;const sourceWorkspace = metadata.sourceWorkspace || null;const appId = task?.metadata?.app || null;- const skipped = (skipReason) => ({ verified: false, skipReason, issues: [], observed: null, recoveryTaskId: null });// Resolved twice on purpose. The first pass applies every FREE gate; only a run// that survives all of them pays for the pending-owner answer (two task-file@@ -384,46 +407,19 @@ async function verifyAgentBranchState({ agentId, task, agentState, success, prExif (app === UNREADABLE) return skipped(REPO_STATE_SKIPS.GATE_UNREADABLE);const worktreePath = isTruthyMeta(metadata.claimPicksOwnBranch) ? metadata.workspacePath : metadata.workspacePath || join(PATHS.worktrees, agentId);- const domain = async (status, reason, extra = {}) => {- const { recordCleanupOutcome } = await import('./cosAgentLifecycle.js');- await recordCleanupOutcome(agentId, { status, reason, branch: branchName, path: worktreePath, ...extra });- };+ const { record, blockWith } = branchLedger(agentId, { branch: branchName, path: worktreePath });const enabled = repoStateVerificationEnabled(app);const owned = enabled ? await branchHasPendingOwner(branchName, app).catch(() => null) : false;- if (owned === null) { await domain('blocked', 'ownership-unreadable'); return skipped(REPO_STATE_SKIPS.GATE_UNREADABLE); }- if (owned) await domain('pending', 'existing-completion-owner');+ if (owned === null) return blockWith('ownership-unreadable', { skipReason: REPO_STATE_SKIPS.GATE_UNREADABLE });+ if (owned) await record('pending', 'existing-completion-owner');const originalPrUrl = [metadata.reviewLoopMergeTarget?.url, metadata.recoveryMergeTarget?.url,task?.metadata?.reviewLoopPRUrl, task?.metadata?.recoveryMergeTarget?.url].find(value => parsePullRequestUrl(value));const expectation = resolveRepoStateExpectation({ ...structural, prExpected: prExpected || !!originalPrUrl, enabled, followUpPending: owned });if (!expectation.verify) return skipped(expectation.skipReason);- // A reused branch is not the old checkout. No model is needed to identify a- // different holder, and its live work must never become this parent's target.- const inventory = await listWorktrees(sourceWorkspace).catch(() => null);- if (!inventory) { await domain('blocked', 'checkout-inventory-unavailable'); return skipped('checkout-inventory-unavailable'); }- const holders = inventory.filter(tree => tree.branch?.replace(/^refs\/heads\//, '') === branchName);- const pathHolder = inventory.find(tree => tree.path === worktreePath);- if (holders.some(tree => tree.path !== worktreePath)- || (pathHolder && pathHolder.branch?.replace(/^refs\/heads\//, '') !== branchName)) {- await domain('blocked', 'checkout-incarnation-changed');- return skipped('checkout-incarnation-changed');- }- const completed = metadata.completedCheckouts?.find(row => row.branch === branchName && resolve(row.path) === resolve(worktreePath));- if (completed && pathHolder) {- const { readCompletedCheckoutIdentity } = await import('./completedCheckoutEvidence.js');- const identity = await readCompletedCheckoutIdentity({ repoPath: sourceWorkspace, branch: branchName,- path: worktreePath, head: pathHolder.head }).catch(() => null);- if (!identity || identity.head !== completed.head || JSON.stringify(identity.incarnation) !== JSON.stringify(completed.incarnation)) {- await domain('blocked', 'checkout-incarnation-changed');- return skipped('checkout-incarnation-changed');- }- }- const { readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');- const { claimCheckoutOwner } = await import('../lib/claimContinuation.js');- const owner = claimCheckoutOwner({ branchName, sourceWorkspace,- agents: await readClaimOwnershipAgents().catch(() => null) });- if (owner) { await domain('blocked', owner.reason, { owners: owner.owners }); return skipped(owner.reason); }+ const hold = await resolveCheckoutIncarnation({ metadata, sourceWorkspace, branchName, worktreePath });+ if (hold) return blockWith(hold.reason, { record: hold.record });const observed = await probeRepoState({sourceWorkspace,branchName,@@ -435,20 +431,10 @@ async function verifyAgentBranchState({ agentId, task, agentState, success, prExreturn null;});- if (!observed) { await domain('blocked', 'probe-incomplete'); return skipped(REPO_STATE_SKIPS.PROBE_INCOMPLETE); }+ if (!observed) return blockWith('probe-incomplete', { skipReason: REPO_STATE_SKIPS.PROBE_INCOMPLETE });- // Missing originals are an accounting gap, not a reason to hire an agent- // to rediscover absence. Never invent a preservation receipt.if (observed.worktreePresent === false && observed.localBranchPresent === false) {- const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');- const proofUrl = originalPrUrl || observed.prUrl;- const forge = proofUrl && observed.prState === 'MERGED' ? await readRetirementForgeEvidence(sourceWorkspace, branchName, proofUrl,- { forgeAccount: app?.forgeAccount ?? null }).catch(() => null) : null;- const integrated = forge && (await execGit(['merge-base', '--is-ancestor', forge.prHead, forge.defaultHead], sourceWorkspace,- { ignoreExitCode: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_LAZY_FETCH: '1' } }).catch(() => null))?.exitCode === 0;- const reason = integrated ? 'already-absent-preservation-unverified' : 'absent-checkout-integration-unverified';- await domain(integrated ? 'already-absent' : 'blocked', reason, { prUrl: originalPrUrl, committedIntegrationVerified: !!integrated });- return skipped(reason);+ return settleAbsentCheckout({ app, sourceWorkspace, branchName, originalPrUrl, observed, record });}const issues = classifyRepoStateIssues(expectation, { ...observed, branchName });if (issues.length === 0) {@@ -457,9 +443,8 @@ async function verifyAgentBranchState({ agentId, task, agentState, success, prEx// repo. Findings still stand on their own: what WAS readable is fact, so a// divergence below is reported even alongside an unreadable probe.if (observed.unreadable.length > 0) {- await domain('blocked', 'probe-incomplete');emitLog('info', `🔎 Repo state only partly readable for ${agentId} (${branchName}) — could not check: ${observed.unreadable.join(', ')}`, { agentId, branchName });- return { verified: false, skipReason: REPO_STATE_SKIPS.PROBE_INCOMPLETE, issues: [], observed, recoveryTaskId: null };+ return blockWith('probe-incomplete', { skipReason: REPO_STATE_SKIPS.PROBE_INCOMPLETE, observed });}emitLog('info', `🔎 Agent branch ${branchName} verified clean for ${agentId}`, { agentId, branchName });return { verified: true, skipReason: null, issues: [], observed, recoveryTaskId: null };@@ -467,58 +452,120 @@ async function verifyAgentBranchState({ agentId, task, agentState, success, prExif (resolvePrCompletion(task?.metadata) === PR_COMPLETIONS.LEAVE_OPEN) {emitLog('warn', `Review-only branch ${branchName} needs attention; automatic cleanup and recovery suppressed`, { agentId, branchName });- return { verified: false, skipReason: null, issues, observed, recoveryTaskId: null };+ return skipped(null, { issues, observed });}- let retirement = null;- if (observed.prState === 'MERGED' && (observed.worktreePresent || observed.localBranchPresent)) {- const prepared = await prepareRecoveryRetirement({ app, sourceWorkspace, branchName, worktreePath, observed })- .catch(() => ({ reason: 'retirement-review-unavailable' }));- if (!prepared.retirement) {- await domain('blocked', prepared.reason);- // The retirement gate declining is its designed outcome; the reason is recorded on the domain above.- emitLog('info', `⏸️ Repo-state retirement retained ${branchName}: ${prepared.reason}`, { agentId, branchName });- return { verified: false, skipReason: prepared.reason, issues, observed, recoveryTaskId: null };- }- retirement = prepared.retirement;- if (prepared.integrated) {- const { retireInventoriedCheckout } = await import('./heldCheckoutRecovery.js');- const { assertAutomaticRetirementAllowed } = await import('./branchReconcileRetirement.js');- const result = await retireInventoriedCheckout({ appId, release: retirement.release,- review: { prUrl: retirement.prUrl, digest: retirement.digest, acceptSuperseded: false } }, { beforeMutation: assertAutomaticRetirementAllowed }).catch(error => ({ reason: ['daemon-stopped', 'automatic-retirement-disabled'].includes(error.message) ? error.message : 'retirement-outcome-uncertain' }));- const verified = result.ok && result.archiveDir && result.branchDeleted === true;- await domain(verified ? 'verified' : 'blocked', verified ? 'retirement-receipt-verified' : result.reason || 'retirement-receipt-unverified');- return { verified: !!verified, skipReason: verified ? null : result.reason || 'retirement-receipt-unverified', issues: verified ? [] : issues, observed, recoveryTaskId: null };+ return settleDivergedBranch({ agentId, task, app, appId, metadata, sourceWorkspace, branchName, worktreePath,+ observed, issues, record, blockWith });+}++/**+ * A reused branch is not the old checkout. No model is needed to identify a+ * different holder, and its live work must never become this parent's target.+ *+ * @returns {Promise<{reason: string, record?: object}|null>} the hold, or null when this run still owns the checkout+ */+async function resolveCheckoutIncarnation({ metadata, sourceWorkspace, branchName, worktreePath }) {+ const inventory = await listWorktrees(sourceWorkspace).catch(() => null);+ if (!inventory) return { reason: 'checkout-inventory-unavailable' };+ const holders = inventory.filter(tree => tree.branch?.replace(/^refs\/heads\//, '') === branchName);+ const pathHolder = inventory.find(tree => tree.path === worktreePath);+ if (holders.some(tree => tree.path !== worktreePath)+ || (pathHolder && pathHolder.branch?.replace(/^refs\/heads\//, '') !== branchName)) {+ return { reason: 'checkout-incarnation-changed' };+ }+ const completed = metadata.completedCheckouts?.find(row => row.branch === branchName && resolve(row.path) === resolve(worktreePath));+ if (completed && pathHolder) {+ const { readCompletedCheckoutIdentity } = await import('./completedCheckoutEvidence.js');+ const identity = await readCompletedCheckoutIdentity({ repoPath: sourceWorkspace, branch: branchName,+ path: worktreePath, head: pathHolder.head }).catch(() => null);+ if (!identity || identity.head !== completed.head || JSON.stringify(identity.incarnation) !== JSON.stringify(completed.incarnation)) {+ return { reason: 'checkout-incarnation-changed' };}}+ const { readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');+ const { claimCheckoutOwner } = await import('../lib/claimContinuation.js');+ const owner = claimCheckoutOwner({ branchName, sourceWorkspace,+ agents: await readClaimOwnershipAgents().catch(() => null) });+ return owner ? { reason: owner.reason, record: { owners: owner.owners } } : null;+}++/**+ * Missing originals are an accounting gap, not a reason to hire an agent+ * to rediscover absence. Never invent a preservation receipt.+ */+async function settleAbsentCheckout({ app, sourceWorkspace, branchName, originalPrUrl, observed, record }) {+ const { readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');+ const proofUrl = originalPrUrl || observed.prUrl;+ const forge = proofUrl && observed.prState === 'MERGED' ? await readRetirementForgeEvidence(sourceWorkspace, branchName, proofUrl,+ { forgeAccount: app?.forgeAccount ?? null }).catch(() => null) : null;+ const integrated = forge && (await execGit(['merge-base', '--is-ancestor', forge.prHead, forge.defaultHead], sourceWorkspace,+ { ignoreExitCode: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_LAZY_FETCH: '1' } }).catch(() => null))?.exitCode === 0;+ const reason = integrated ? 'already-absent-preservation-unverified' : 'absent-checkout-integration-unverified';+ await record(integrated ? 'already-absent' : 'blocked', reason, { prUrl: originalPrUrl, committedIntegrationVerified: !!integrated });+ return skipped(reason);+}++/**+ * The branch diverged from its expected end state. A merged checkout goes+ * through the retirement gate; anything else is an undelivered branch.+ */+async function settleDivergedBranch(ctx) {+ const { agentId, app, sourceWorkspace, branchName, worktreePath, observed, issues, blockWith } = ctx;+ if (observed.prState !== 'MERGED' || !(observed.worktreePresent || observed.localBranchPresent)) {+ return settleUndeliveredBranch(ctx);+ }+ const prepared = await prepareRecoveryRetirement({ app, sourceWorkspace, branchName, worktreePath, observed })+ .catch(() => ({ reason: 'retirement-review-unavailable' }));+ if (!prepared.retirement) {+ const held = await blockWith(prepared.reason, { issues, observed });+ // The retirement gate declining is its designed outcome; the reason is recorded on the ledger above.+ emitLog('info', `⏸️ Repo-state retirement retained ${branchName}: ${prepared.reason}`, { agentId, branchName });+ return held;+ }+ if (prepared.integrated) return retireIntegratedCheckout(ctx, prepared.retirement);+ return fileDivergenceRecovery(ctx, prepared.retirement);+}++async function retireIntegratedCheckout({ appId, observed, issues, record, blockWith }, retirement) {+ const { retireInventoriedCheckout } = await import('./heldCheckoutRecovery.js');+ const { assertAutomaticRetirementAllowed } = await import('./branchReconcileRetirement.js');+ const result = await retireInventoriedCheckout({ appId, release: retirement.release,+ review: { prUrl: retirement.prUrl, digest: retirement.digest, acceptSuperseded: false } }, { beforeMutation: assertAutomaticRetirementAllowed }).catch(error => ({ reason: ['daemon-stopped', 'automatic-retirement-disabled'].includes(error.message) ? error.message : 'retirement-outcome-uncertain' }));+ if (!result.ok || !result.archiveDir || result.branchDeleted !== true) {+ return blockWith(result.reason || 'retirement-receipt-unverified', { issues, observed });+ }+ await record('verified', 'retirement-receipt-verified');+ return { verified: true, skipReason: null, issues: [], observed, recoveryTaskId: null };+}- // Cleanup bookkeeping/unknown forge/CI waits remain deterministic. Only- // source/history judgment or an actual undelivered branch needs cognition.- if (!retirement && !issues.some(issue => issue.code === REPO_STATE_ISSUES.BRANCH_UNMERGED- || issue.code === REPO_STATE_ISSUES.PR_UNMERGED)) {- await domain('blocked', 'deterministic-cleanup-pending');- return { verified: false, skipReason: 'deterministic-cleanup-pending', issues, observed, recoveryTaskId: null };+/**+ * Cleanup bookkeeping/unknown forge/CI waits remain deterministic. Only+ * source/history judgment or an actual undelivered branch needs cognition.+ */+async function settleUndeliveredBranch({ agentId, app, sourceWorkspace, branchName, worktreePath, observed, issues, record, blockWith }) {+ if (!issues.some(issue => issue.code === REPO_STATE_ISSUES.BRANCH_UNMERGED || issue.code === REPO_STATE_ISSUES.PR_UNMERGED)) {+ return blockWith('deterministic-cleanup-pending', { issues, observed });}- if (!retirement && (!observed.prState || observed.unreadable.length)) {- await domain('blocked', 'delivery-evidence-unavailable');- return { verified: false, skipReason: 'delivery-evidence-unavailable', issues, observed, recoveryTaskId: null };+ if (!observed.prState || observed.unreadable.length) return blockWith('delivery-evidence-unavailable', { issues, observed });+ const forgeAccount = app?.forgeAccount ?? null;+ const delivery = observed.prState === 'OPEN'+ ? await inspectOpenDeliveryRepair(sourceWorkspace, branchName, observed.prUrl, { forgeAccount }).catch(() => ({ reason: 'delivery-evidence-unavailable' }))+ : { reason: 'delivery-not-open' };+ let review = null;+ if (delivery.headSha) {+ const { inspectOrQueueCompletedReview } = await import('./repoCleanupRecovery.js');+ review = await inspectOrQueueCompletedReview({ agentId, repoPath: sourceWorkspace, branch: branchName,+ prUrl: observed.prUrl, headSha: delivery.headSha, worktreePath, forgeAccount, repairEvidence: delivery.evidence }).catch(() => ({ disposition: 'held', reason: 'completed-review-inspection-unavailable' }));}- if (!retirement) {- const delivery = observed.prState === 'OPEN' ? await inspectOpenDeliveryRepair(sourceWorkspace, branchName, observed.prUrl, { forgeAccount: app?.forgeAccount ?? null }).catch(() => ({ reason: 'delivery-evidence-unavailable' })) : { reason: 'delivery-not-open' };- let review = null;- if (delivery.headSha) {- const { inspectOrQueueCompletedReview } = await import('./repoCleanupRecovery.js');- review = await inspectOrQueueCompletedReview({ agentId, repoPath: sourceWorkspace, branch: branchName,- prUrl: observed.prUrl, headSha: delivery.headSha, worktreePath, forgeAccount: app?.forgeAccount ?? null, repairEvidence: delivery.evidence }).catch(() => ({ disposition: 'held', reason: 'completed-review-inspection-unavailable' }));- }- if (review?.disposition === 'queued-review') {- await domain('pending', review.reason, { taskId: review.taskId });- return { verified: false, skipReason: review.reason, issues, observed, recoveryTaskId: review.taskId };- }- const reason = review?.reason || delivery.reason || 'completed-review-target-unverified';- await domain('blocked', reason);- return { verified: false, skipReason: reason, issues, observed, recoveryTaskId: null };+ if (review?.disposition === 'queued-review') {+ await record('pending', review.reason, { taskId: review.taskId });+ return { verified: false, skipReason: review.reason, issues, observed, recoveryTaskId: review.taskId };}+ return blockWith(review?.reason || delivery.reason || 'completed-review-target-unverified', { issues, observed });+}++async function fileDivergenceRecovery({ agentId, task, appId, metadata, sourceWorkspace, branchName, worktreePath, observed, issues }, retirement) {// The recovery task filed below is the investigation, so this line only records the divergence; filing failures still warn.emitLog('info', `🔎 Repo state diverged after ${agentId}: ${issues.map(i => i.code).join(', ')}`, { agentId, branchName, taskId: task?.id });diff --git a/server/services/agentRepoStateVerification.test.js b/server/services/agentRepoStateVerification.test.jsindex 32b4f2db65..72a3e3fe0e 100644--- a/server/services/agentRepoStateVerification.test.js+++ b/server/services/agentRepoStateVerification.test.js@@ -581,6 +581,65 @@ describe('verifyAgentRepoState — never fires', () => {});});+// A gate that returns a skip without recording it leaves the cleanup ledger+// silent about a held branch; one that records a different reason than it+// returns makes the Agent card and the completion audit disagree.+describe('verifyAgentRepoState — every hold records the reason it returns', () => {+ const merged = () => findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });+ it.each([+ ['ownership-unreadable', REPO_STATE_SKIPS.GATE_UNREADABLE, {}, () => getAllTasks.mockRejectedValue(new Error('tasks file unreadable'))],+ ['checkout-inventory-unavailable', 'checkout-inventory-unavailable', {}, () => listWorktrees.mockRejectedValue(new Error('not a git repository'))],+ ['checkout-incarnation-changed', 'checkout-incarnation-changed', {}, () => listWorktrees.mockResolvedValue([{ ...RELEASE, path: '/repo/new-owner' }])],+ ['claim-ownership-unreadable', 'claim-ownership-unreadable', { owners: [] }, () => readClaimOwnershipAgents.mockRejectedValue(new Error('agents unreadable'))],+ ['probe-incomplete', REPO_STATE_SKIPS.PROBE_INCOMPLETE, {}, () => readLocalBranchPresence.mockRejectedValue(new Error('git crashed'))],+ ['probe-incomplete', REPO_STATE_SKIPS.PROBE_INCOMPLETE, {}, () => readCheckoutPathPresence.mockResolvedValue(null)],+ ['deterministic-cleanup-pending', 'deterministic-cleanup-pending', {}, () => existsSync.mockReturnValue(true), { prExpected: false }],+ ['delivery-evidence-unavailable', 'delivery-evidence-unavailable', {}, () => { localBranch(true); hasBranchMergeEvidence.mockResolvedValue(false); }, { prExpected: false }],+ ['delivery-ci-or-review-pending', 'delivery-ci-or-review-pending', {}, () => {+ localBranch(true); hasBranchMergeEvidence.mockResolvedValue(false);+ findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/9', detail: 'OPEN', headRefOid: HEAD });+ }],+ ['active-agent-owner', 'active-agent-owner', {}, () => {+ existsSync.mockReturnValue(true); localBranch(true); merged();+ listWorktrees.mockResolvedValue([RELEASE]);+ prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: false, reason: 'active-agent-owner' });+ }],+ ['retirement-outcome-uncertain', 'retirement-outcome-uncertain', {}, () => {+ existsSync.mockReturnValue(true); localBranch(true); merged();+ listWorktrees.mockResolvedValue([RELEASE]);+ prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: true, review: { ...review(), comparison: { disposition: 'integrated', localPatch: '', difference: '' } } });+ retireInventoriedCheckout.mockRejectedValue(new Error('archive write failed'));+ }],+ ])('records %s and returns %s', async (reason, skipReason, extra, arrange, overrides = {}) => {+ arrange();+ const result = await run(overrides);+ expect(result).toMatchObject({ verified: false, skipReason, recoveryTaskId: null });+ expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', { status: 'blocked', reason, branch: BRANCH, path: WORKTREE, ...extra });+ expect(addTask).not.toHaveBeenCalled();+ });++ it('records the queued completed-review as pending under the task it returns', async () => {+ localBranch(true);+ hasBranchMergeEvidence.mockResolvedValue(false);+ findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/9', detail: 'OPEN', headRefOid: HEAD });+ execGh.mockResolvedValue(openView({ mergeable: 'CONFLICTING' }));+ inspectOrQueueCompletedReview.mockResolvedValue({ disposition: 'queued-review', reason: 'code-repair-queued', taskId: 'review-1' });+ expect(await run()).toMatchObject({ verified: false, skipReason: 'code-repair-queued', recoveryTaskId: 'review-1' });+ expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', { status: 'pending', reason: 'code-repair-queued', branch: BRANCH, path: WORKTREE, taskId: 'review-1' });+ });++ it('records each held swarm branch under the reason it returns', async () => {+ readClaimOwnershipAgents.mockRejectedValue(new Error('agents unreadable'));+ const state = agentState({ isWorktree: false, worktreeBranch: null, workspacePath: '/repo', claimPicksOwnBranch: true, claimBranches: ['claim/issue-11'] });+ expect((await run({ agentState: state })).branches).toEqual([{ branch: 'claim/issue-11', verified: false, skipReason: 'claim-ownership-unreadable', issues: [], recoveryTaskId: null }]);+ expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', { branch: 'claim/issue-11', status: 'blocked', reason: 'claim-ownership-unreadable', owners: [] });++ readClaimOwnershipAgents.mockResolvedValue([]);+ expect((await run({ agentState: state })).branches).toEqual([{ branch: 'claim/issue-11', verified: false, skipReason: 'claim-checkout-identity-unverified', issues: [], recoveryTaskId: null }]);+ expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', { branch: 'claim/issue-11', status: 'blocked', reason: 'claim-checkout-identity-unverified' });+ });+});+describe('remediation coverage', () => {it('has a remediation for every issue code', () => {// The map is what makes "a new check must say what to do about it" real — the