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
vi.mock('./instanceIdentity.js', () => ({ getInstanceId: vi.fn(async () => 'fixture-local'), UNKNOWN_INSTANCE_ID: 'unknown' }));
vi.mock('../lib/gitRepositoryIdentity.js', () => ({ readGitCommonDirectory: vi.fn(async () => '/repo/.git') }));
import { EventEmitter } from 'node:events';
import { readGitCommonDirectory } from '../lib/gitRepositoryIdentity.js';
vi.mock('./branchCompletionPolicy.js', async () => ({
...await vi.importActual('./branchCompletionPolicy.js'),
readBranchCompletionPolicies: vi.fn(async () => []),
readBranchCompletionHold: vi.fn(async () => null),
}));
/**
* Tests for the post-completion repo-state audit.
*
* The failure this guards is the one the pure layer cannot see: cleanup returned
* ZERO warnings, the completion path called the run a success, and the worktree
* plus its branch are still on disk. Every case drives the real
* `verifyAgentRepoState` against mocked git/forge answers and asserts what it
* files — a recovery task, or deliberately nothing.
*
* The task-queue mocks return `getAllTasks`'s REAL `{user, cos}` shape via the
* real `readAllTasksFlat`. An earlier revision mocked it as a bare array, which
* hid a `tasks.some is not a function` throw that made the pending-owner escape
* permanently false — the audit then filed a recovery task against every branch a
* review-loop follow-up was queued to land.
*/
import { describe, it, expect, beforeEach, vi } from 'vitest';
vi.mock('./agentWorktreeCleanup.js', () => ({ releaseRetryHold: vi.fn(async () => ({})) }));
vi.mock('./repoCleanupRecovery.js', () => ({ inspectOrQueueCompletedReview: vi.fn(async () => ({ disposition: 'held', reason: 'delivery-ci-or-review-pending' })) }));
vi.mock('./repoCleanupObservation.js', async original => ({ ...await original(), readCheckoutPathPresence: vi.fn(async () => false), readLocalBranchPresence: vi.fn(async () => false) }));
vi.mock('../lib/gitRemote.js', () => ({ getOriginInfo: vi.fn(async () => ({ host: 'github.com', fullName: 'example/repo', isGithub: true })) }));
vi.mock('./forgeExecOptions.js', () => ({ resolveForgeExecOptions: vi.fn(async () => ({})) }));
vi.mock('./heldCheckoutReview.js', () => ({ readRetirementForgeEvidence: vi.fn(async () => ({ prHead: '1'.repeat(40), mergeCommit: '3'.repeat(40), defaultHead: '2'.repeat(40) })) }));
vi.mock('./completedCheckoutEvidence.js', async original => ({ ...await original(), readCompletedCheckoutIdentity: vi.fn() }));
vi.mock('./cos.js', () => ({}));
vi.mock('./agentCompletionCleanup.js', () => ({ replayAgentCompletionCleanup: vi.fn(async () => {}) }));
vi.mock('./cosAgentLifecycle.js', () => ({ retryCompletionCheckoutCapture: vi.fn(async () => false), reserveRepoCleanupRecovery: vi.fn(async () => ({ admitted: true, attempt: 1 })), recordRepoCleanupRecovery: vi.fn(async () => true), recordCleanupOutcome: vi.fn(async () => true), updateAgent: vi.fn().mockResolvedValue({}), recordRepoStateRecovery: vi.fn().mockResolvedValue(true), recordRepoStateVerification: vi.fn().mockResolvedValue(true), getAgentRecord: vi.fn(async () => null), recordCompletionCleanup: vi.fn(async () => true) }));
vi.mock('./cosClaimOwnership.js', () => ({ readClaimOwnershipAgents: vi.fn().mockResolvedValue([]), withClaimOwnershipLock: fn => fn() }));
vi.mock('./taskSchedule.js', () => ({ recordBranchReconcileOutcome: vi.fn().mockResolvedValue({}) }));
vi.mock('./heldCheckoutRecovery.js', () => ({
findMissingCheckoutPreservation: vi.fn(async () => null),
retireInventoriedCheckout: vi.fn(async () => ({ ok: true, archiveDir: '/private/archive', branchDeleted: true })),
prepareInventoriedCheckoutRetirement: vi.fn().mockResolvedValue({ ok: true, review: { digest: 'a'.repeat(64) } }),
}));
vi.mock('./cosEvents.js', async original => ({ ...await original(), emitLog: vi.fn() }));
vi.mock('./cosTaskStore.js', () => ({
addTask: vi.fn().mockResolvedValue({ id: 'task-recovery-1' }),
getAllTasks: vi.fn().mockResolvedValue({ user: { tasks: [] }, cos: { tasks: [] } }),
getTaskById: vi.fn().mockResolvedValue(null),
updateTask: vi.fn().mockResolvedValue({ status: 'completed' }),
}));
vi.mock('./prWatcher.js', () => ({ readPendingMergePrs: vi.fn().mockReturnValue([]) }));
vi.mock('./worktreeManager.js', () => ({ listWorktrees: vi.fn().mockResolvedValue([]) }));
vi.mock('./branchReconcile.js', () => ({
listRemoteHeads: vi.fn().mockResolvedValue(new Map()),
cleanupMerged: vi.fn().mockResolvedValue({ cleaned: [] }),
driveToMerge: (pr) => `merge ${pr} from the repo root once CI is green`,
}));
vi.mock('./git.js', () => ({
getDefaultBranch: vi.fn().mockResolvedValue('main'),
hasBranchMergeEvidence: vi.fn().mockResolvedValue(true),
resolveForgeForRepo: vi.fn().mockResolvedValue({ cli: 'gh', env: null }),
}));
vi.mock('./github.js', () => ({
execGh: vi.fn(), getPullRequestState: vi.fn(async () => ({ status: 'known', state: 'MERGED' })),
findPullRequestForBranch: vi.fn().mockResolvedValue({ status: 'none', url: null, detail: null }),
}));
vi.mock('./gitlab.js', () => ({
findMergeRequestForBranch: vi.fn().mockResolvedValue({ status: 'none', url: null, detail: null }),
}));
vi.mock('./apps.js', () => ({ getAppById: vi.fn().mockResolvedValue({ id: 'demo-app', name: 'Demo App' }) }));
vi.mock('./notifications.js', () => ({
addNotification: vi.fn().mockResolvedValue({}),
exists: vi.fn().mockResolvedValue(false),
NOTIFICATION_TYPES: { AGENT_WARNING: 'agent_warning' },
PRIORITY_LEVELS: { HIGH: 'high' },
}));
vi.mock('./brainTaskThreads.js', () => ({ ensureTaskThread: vi.fn().mockResolvedValue({}), reconcileCleanupThreads: vi.fn(async () => ({ candidates: 0, archived: 0 })) }));
vi.mock('../lib/execGit.js', () => ({ execGit: vi.fn() }));
vi.mock('fs', () => ({ existsSync: vi.fn().mockReturnValue(false) }));
import { inspectOrQueueCompletedReview } from './repoCleanupRecovery.js';
import { readLocalBranchPresence, readCheckoutPathPresence } from './repoCleanupObservation.js';
import { readCompletedCheckoutIdentity } from './completedCheckoutEvidence.js';
import { readClaimOwnershipAgents } from './cosClaimOwnership.js';
import { retryCompletionCheckoutCapture, getAgentRecord, recordCleanupOutcome, reserveRepoCleanupRecovery, recordRepoStateRecovery, recordRepoStateVerification } from './cosAgentLifecycle.js';
import { verifyAgentRepoState, sweepRepoStateVerifications, bindCompletionRetirementEvents, REPO_STATE_REMEDIATIONS } from './agentRepoStateVerification.js';
import { readBranchCompletionPolicies } from './branchCompletionPolicy.js';
import { releaseRetryHold } from './agentWorktreeCleanup.js';
import { getTaskById, updateTask } from './cosTaskStore.js';
import { recordBranchReconcileOutcome } from './taskSchedule.js';
import { findMissingCheckoutPreservation, prepareInventoriedCheckoutRetirement, retireInventoriedCheckout } from './heldCheckoutRecovery.js';
import { addTask, getAllTasks } from './cosTaskStore.js';
import { ensureTaskThread } from './brainTaskThreads.js';
import { listWorktrees } from './worktreeManager.js';
import { listRemoteHeads, cleanupMerged } from './branchReconcile.js';
import { hasBranchMergeEvidence, resolveForgeForRepo } from './git.js';
import { findPullRequestForBranch, execGh, getPullRequestState } from './github.js';
import { findMergeRequestForBranch } from './gitlab.js';
import { getAppById } from './apps.js';
import { addNotification, exists as notificationExists } from './notifications.js';
import { emitLog } from './cosEvents.js';
import { readPendingMergePrs } from './prWatcher.js';
import { execGit } from '../lib/execGit.js';
import { existsSync } from 'fs';
import { REPO_STATE_ISSUES, REPO_STATE_SKIPS } from '../lib/repoStateExpectations.js';
const BRANCH = 'cos/task-x/agent-1';
const WORKTREE = '/repo/data/cos/worktrees/agent-1';
const HEAD = '1'.repeat(40);
const RELEASE = { branch: BRANCH, path: WORKTREE, head: HEAD, locked: false, lockReason: null };
const CREATED_AT = '2026-01-01T00:00:00.000Z';
const agentState = (overrides = {}) => ({
startedAt: CREATED_AT,
metadata: {
isWorktree: true,
sourceWorkspace: '/repo',
worktreeBranch: BRANCH,
workspacePath: WORKTREE,
...overrides,
},
});
const task = (metadata = {}) => ({
id: 'task-1',
description: 'Do the thing',
metadata: { app: 'demo-app', appName: 'Demo App', openPR: true, prCompletion: 'merge-on-green', ...metadata },
});
/** `git show-ref --verify refs/heads/<branch>` — exit 0 means the branch is present. */
const localBranch = present => {
readLocalBranchPresence.mockResolvedValue(present);
execGit.mockImplementation(async args => ({ exitCode: args[0] === 'merge-base' || present ? 0 : 1, stdout: args[0] === 'rev-parse' ? `${HEAD}\n` : '', stderr: '' }));
};
const review = () => ({ digest: 'a'.repeat(64), policy: { policies: [{ id: 'agent-1', startedAt: CREATED_AT }] },
comparison: { disposition: 'review-supersession', localPatch: '+old behavior', difference: '+new behavior' }, forge: { prHead: HEAD } });
const openView = (patch = {}) => JSON.stringify({ number: 9, state: 'OPEN', isDraft: false, isCrossRepository: false, headRefName: BRANCH, headRefOid: HEAD, mergeable: 'MERGEABLE', reviewDecision: '', statusCheckRollup: [{ name: 'CI', status: 'QUEUED' }], ...patch });
/** The `{user, cos}` shape `getAllTasks` really returns. Follow-ups land in `cos`. */
const queuedTasks = (tasks) => getAllTasks.mockResolvedValue({ user: { tasks: [] }, cos: { tasks } });
const observeCompletedTask = async task => {
const events = new EventEmitter();
const unbind = bindCompletionRetirementEvents(events);
try { return await events.listeners('tasks:changed')[0]({ task }); }
finally { unbind(); }
};
const run = (overrides = {}) => verifyAgentRepoState({
agentId: 'agent-1',
task: task(),
agentState: agentState(),
success: true,
prExpected: true,
...overrides,
});
beforeEach(() => {
vi.clearAllMocks();
readGitCommonDirectory.mockReset().mockResolvedValue('/repo/.git');
retryCompletionCheckoutCapture.mockReset().mockResolvedValue(false);
getAgentRecord.mockReset().mockResolvedValue(null);
findMissingCheckoutPreservation.mockResolvedValue(null);
inspectOrQueueCompletedReview.mockResolvedValue({ disposition: 'held', reason: 'delivery-ci-or-review-pending' });
readBranchCompletionPolicies.mockResolvedValue([]);
updateTask.mockReset().mockResolvedValue({ status: 'completed' });
getTaskById.mockResolvedValue({ ...task(), status: 'in_progress', metadata: { ...task().metadata,
deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-1' } });
recordBranchReconcileOutcome.mockResolvedValue({ retirementObligations: [{ ...RELEASE, createdAt: CREATED_AT }] });
prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: true, review: review() });
retireInventoriedCheckout.mockResolvedValue({ ok: true, archiveDir: '/private/archive', branchDeleted: true });
execGh.mockResolvedValue(openView());
readClaimOwnershipAgents.mockResolvedValue([]);
reserveRepoCleanupRecovery.mockResolvedValue({ admitted: true, attempt: 1 });
listWorktrees.mockResolvedValue([]);
listRemoteHeads.mockResolvedValue(new Map());
cleanupMerged.mockResolvedValue({ cleaned: [] });
existsSync.mockReturnValue(false);
readCheckoutPathPresence.mockImplementation(async () => existsSync());
hasBranchMergeEvidence.mockResolvedValue(true);
queuedTasks([]);
getAppById.mockResolvedValue({ id: 'demo-app', name: 'Demo App', repoPath: '/repo' });
readPendingMergePrs.mockReturnValue([]);
resolveForgeForRepo.mockResolvedValue({ cli: 'gh', env: null });
findPullRequestForBranch.mockResolvedValue({ status: 'none', url: null, detail: null });
findMergeRequestForBranch.mockResolvedValue({ status: 'none', url: null, detail: null });
notificationExists.mockResolvedValue(false);
addTask.mockResolvedValue({ id: 'task-recovery-1' });
localBranch(false);
});
describe('verifyAgentRepoState — clean runs', () => {
it.each(['pending', 'captured', 'lost-record'])('retries failed-run identity capture without promoting delivery or cleanup: %s', async scenario => {
const state = { ...agentState({ checkoutCapture: { status: 'pending' }, repoStateVerification: { status: 'pending' } }),
id: 'agent-1', status: 'completed', startedAt: CREATED_AT, result: { success: false, executionSuccess: false, orphaned: true } };
retryCompletionCheckoutCapture.mockResolvedValue(scenario !== 'pending');
if (scenario === 'captured') getAgentRecord.mockResolvedValue({ ...state,
metadata: { ...state.metadata, checkoutCapture: { status: 'captured' }, completedCheckouts: [RELEASE] } });
expect(await run({ success: false, agentState: state })).toMatchObject({
skipReason: scenario === 'captured' ? REPO_STATE_SKIPS.FAILED_RUN : 'checkout-capture-pending',
});
expect(state.result).toEqual({ success: false, executionSuccess: false, orphaned: true });
expect(addTask).not.toHaveBeenCalled();
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
});
it('retains unresolved verification after an explicit retry without adopting its task or touching Git', async () => {
getTaskById.mockResolvedValue({ ...task(), status: 'pending' });
const state = { ...agentState({ repoStateVerification: { status: 'pending' } }), result: { cleanupPending: true } };
expect(await run({ success: false, agentState: state })).toMatchObject({ skipReason: 'cleanup-owner-changed' });
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
expect(updateTask).not.toHaveBeenCalled();
expect(recordRepoStateVerification).not.toHaveBeenCalled();
});
it('transfers a cleanup handoff that cannot retire a human leave-open branch', async () => {
updateTask.mockResolvedValueOnce({ status: 'in_progress' });
const pending = { ...task({ prCompletion: 'leave-open' }), status: 'in_progress', metadata: {
...task({ prCompletion: 'leave-open' }).metadata, deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-1',
} };
getTaskById.mockResolvedValue(pending);
existsSync.mockReturnValue(true);
localBranch(true);
const state = { ...agentState(), result: { cleanupPending: true } };
expect(await run({ success: false, agentState: state, task: pending })).toMatchObject({ skipReason: 'cleanup-transferred-to-recovery' });
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
expect(releaseRetryHold).toHaveBeenCalledOnce();
});
it('transfers unsupported cleanup verification back to bounded recovery', async () => {
updateTask.mockResolvedValueOnce({ status: 'in_progress' });
const state = { ...agentState({ isPersistentWorktree: true, repoStateVerification: { status: 'pending' } }),
result: { success: false, cleanupPending: true } };
expect(await run({ success: false, agentState: state })).toMatchObject({ skipReason: 'cleanup-transferred-to-recovery' });
expect(updateTask).toHaveBeenCalledWith('task-1', expect.objectContaining({ status: 'in_progress',
metadata: expect.objectContaining({ failureCount: 1, retryPendingCleanup: 'agent-1' }) }), 'user', expect.any(Object));
expect(releaseRetryHold).toHaveBeenCalledOnce();
expect(recordRepoStateVerification).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({ status: 'completed', reasons: ['cleanup-transferred-to-recovery'] }));
});
it.each(['OPEN', 'CLOSED'])('transfers a definitive %s undelivered PR out of the cleanup hold', async prState => {
updateTask.mockResolvedValueOnce({ status: 'in_progress' });
localBranch(true);
existsSync.mockReturnValue(true);
findPullRequestForBranch.mockResolvedValue({ status: 'found', detail: prState, url: 'https://github.com/example/repo/pull/7' });
const state = { ...agentState(), result: { success: false, cleanupPending: true } };
expect(await run({ success: false, agentState: state })).toMatchObject({ skipReason: 'cleanup-transferred-to-recovery' });
expect(releaseRetryHold).toHaveBeenCalledOnce();
expect(addTask).not.toHaveBeenCalled();
});
it('immediately finalizes a receipt-retired squash delivery when its follow-up completes, including duplicate observations', async () => {
const completed = { version: 1, agentId: 'agent-1', repoPath: '/repo', branch: BRANCH, path: WORKTREE, head: HEAD,
startedAt: CREATED_AT, capturedAt: CREATED_AT, incarnation: { pointer: { dev: '1', ino: '2', birthtimeNs: '3' } } };
const state = { ...agentState({ instanceId: 'fixture-local', completedCheckouts: [completed],
reviewLoopMergeTarget: { url: 'https://github.com/example/repo/pull/7' }, repoStateVerification: { status: 'pending' },
completionCleanup: { version: 1 } }), id: 'agent-1', taskId: 'task-1', status: 'completed',
result: { success: false, executionSuccess: true, cleanupPending: true } };
getAgentRecord.mockResolvedValue(state);
findMissingCheckoutPreservation.mockResolvedValue({ archiveDir: null, evidenceDigest: 'a'.repeat(64), recheck: async () => true });
// The old source SHA is not an ancestor after squash; only the actual merge is.
execGit.mockImplementation(async args => ({ exitCode: args[0] === 'merge-base' ? (args[2] === '3'.repeat(40) ? 0 : 1) : 1, stdout: '' }));
const followUp = { id: 'delivery-follow-up', status: 'completed', metadata: { reviewLoopFollowUp: 'true',
sourceAgentId: 'agent-1', sourceTaskId: 'task-1', reviewLoopPRBranch: BRANCH } };
queuedTasks([followUp]);
const events = new EventEmitter();
const unbind = bindCompletionRetirementEvents(events);
events.emit('tasks:changed', { type: 'internal', task: followUp, previousStatus: 'in_progress' });
events.emit('tasks:changed', { type: 'internal', task: followUp, previousStatus: 'completed' });
await vi.waitFor(() => expect(recordRepoStateVerification).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({ status: 'completed' })));
unbind();
expect(updateTask).toHaveBeenCalledOnce();
expect(updateTask).toHaveBeenLastCalledWith('task-1', expect.objectContaining({ status: 'completed' }), 'user', expect.any(Object));
expect(recordRepoStateVerification).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({ status: 'completed' }));
expect(addTask).not.toHaveBeenCalled();
expect(inspectOrQueueCompletedReview).not.toHaveBeenCalled();
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
expect(findMissingCheckoutPreservation).toHaveBeenCalledWith(expect.objectContaining({ release: expect.objectContaining({ checkoutIdentity: expect.stringMatching(/^[a-f0-9]{64}$/) }) }));
expect(state.result).toEqual({ success: false, executionSuccess: true, cleanupPending: true });
});
it('waits out a pre-release owner-active audit and immediately verifies again after release', async () => {
const completed = { version: 1, agentId: 'agent-1', repoPath: '/repo', branch: BRANCH, path: WORKTREE, head: HEAD,
startedAt: CREATED_AT, capturedAt: CREATED_AT };
const state = { ...agentState({ instanceId: 'fixture-local', completedCheckouts: [completed],
reviewLoopMergeTarget: { url: 'https://github.com/example/repo/pull/7' }, repoStateVerification: { status: 'pending' } }),
id: 'agent-1', taskId: 'task-1', status: 'completed', result: { success: false, cleanupPending: true } };
getAgentRecord.mockResolvedValue(state);
findMissingCheckoutPreservation.mockResolvedValue({ archiveDir: null, evidenceDigest: 'a'.repeat(64), recheck: async () => true });
const followUp = { id: 'follow-up', status: 'completed', metadata: { reviewLoopFollowUp: true,
sourceAgentId: 'agent-1', sourceTaskId: 'task-1', reviewLoopPRBranch: BRANCH } };
queuedTasks([followUp]);
let releaseFirst, entered;
const reached = new Promise(resolve => { entered = resolve; });
getAllTasks.mockImplementationOnce(() => { entered(); return new Promise(resolve => { releaseFirst = resolve; }); });
const preRelease = run({ agentState: state, success: false });
await reached;
const afterRelease = observeCompletedTask(followUp);
releaseFirst({ user: { tasks: [] }, cos: { tasks: [{ ...followUp, status: 'pending', metadata: { ...followUp.metadata, app: 'demo-app' } }] } });
expect(await preRelease).toMatchObject({ skipReason: 'follow-up-pending' });
expect(await afterRelease).toMatchObject({ verified: true });
expect(updateTask).toHaveBeenCalledOnce();
expect(addTask).not.toHaveBeenCalled();
});
it('does not wake a different task or another instance from follow-up metadata', async () => {
const followUp = { status: 'completed', metadata: { reviewLoopFollowUp: true, sourceAgentId: 'agent-1', sourceTaskId: 'task-1' } };
for (const state of [{ taskId: 'another-task', metadata: { instanceId: 'fixture-local' } },
{ taskId: 'task-1', metadata: { instanceId: 'another-instance' } }]) {
getAgentRecord.mockResolvedValue(state);
await observeCompletedTask(followUp);
}
expect(updateTask).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
});
it('ignores the exact cleanup task itself while preserving a different pending owner', async () => {
const own = { ...task(), status: 'in_progress', metadata: { ...task().metadata,
existingBranch: BRANCH, deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-1' } };
const state = { ...agentState(), result: { success: false, cleanupPending: true } };
queuedTasks([own]);
expect((await run({ success: false, agentState: state, task: own })).skipReason).not.toBe('follow-up-pending');
queuedTasks([own, { ...own, id: 'other-task' }]);
expect(await run({ success: false, agentState: state, task: own })).toMatchObject({ skipReason: 'follow-up-pending' });
});
it('ignores independent repositories with the same branch and deduplicates app reads per audit', async () => {
getAppById.mockImplementation(async id => ({ id, repoPath: id === 'demo-app' ? '/repo' : '/other' }));
readGitCommonDirectory.mockImplementation(async path => `${path}/.git`);
queuedTasks(['first', 'second'].map(id => ({ id, status: 'pending', metadata: { app: 'other-app', existingBranch: BRANCH } })));
expect((await run()).skipReason).not.toBe(REPO_STATE_SKIPS.FOLLOW_UP_PENDING);
expect(getAppById.mock.calls.filter(([id]) => id === 'other-app')).toHaveLength(1);
expect(readGitCommonDirectory).toHaveBeenCalledWith('/other');
});
it.each(['/alias', '/linked-worktree'])('preserves another app sharing the common directory through %s', async repoPath => {
getAppById.mockImplementation(async id => ({ id, repoPath: id === 'demo-app' ? '/repo' : repoPath }));
queuedTasks([{ status: 'pending', metadata: { app: 'alias-app', existingBranch: BRANCH } }]);
expect(await run()).toMatchObject({ skipReason: REPO_STATE_SKIPS.FOLLOW_UP_PENDING });
expect(readGitCommonDirectory).toHaveBeenCalledWith(repoPath);
});
it.each(['missing-scope', 'missing-app', 'app-read-failed', 'missing-path', 'unreadable-target', 'unreadable-candidate'])('holds when ownership identity is unknown: %s', async failure => {
getAppById.mockImplementation(async id => {
if (id === 'demo-app') return { id, repoPath: '/repo' };
if (failure === 'app-read-failed') throw new Error('unreadable');
if (failure === 'missing-app') return null;
return { id, repoPath: failure === 'missing-path' ? undefined : '/other' };
});
readGitCommonDirectory.mockImplementation(async path => !path
|| path === (failure === 'unreadable-target' ? '/repo' : failure === 'unreadable-candidate' ? '/other' : '') ? null : `${path}/.git`);
queuedTasks([{ status: 'pending', metadata: { app: failure === 'missing-scope' ? undefined : 'other-app', existingBranch: BRANCH } }]);
expect(await run()).toMatchObject({ skipReason: REPO_STATE_SKIPS.GATE_UNREADABLE });
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
});
it.each([[], ['Branch preserved by ordinary cleanup']])('settles its cleanup handoff after archive and integration proof despite warnings %j', async cleanupWarnings => {
const completed = { version: 1, agentId: 'agent-1', repoPath: '/repo', branch: BRANCH, path: WORKTREE, head: HEAD,
startedAt: CREATED_AT, capturedAt: CREATED_AT };
const state = { ...agentState({ completedCheckouts: [completed],
reviewLoopMergeTarget: { url: 'https://github.com/example/repo/pull/7' }, repoStateVerification: { status: 'pending' } }),
result: { success: false, cleanupPending: true } };
await run({ success: false, agentState: state, cleanupWarnings });
expect(updateTask).not.toHaveBeenCalled();
findMissingCheckoutPreservation.mockResolvedValue({ archiveDir: '/example/archive', evidenceDigest: 'a'.repeat(64), recheck: async () => true });
expect(await run({ success: false, agentState: state, cleanupWarnings })).toMatchObject({ verified: true });
expect(updateTask).toHaveBeenLastCalledWith('task-1', expect.objectContaining({ status: 'completed' }), 'user', {
expectedStatus: 'in_progress', expectedMetadata: { deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-1' },
});
expect(addTask).not.toHaveBeenCalled();
});
it('settles an absent completed checkout from verified original-generation archive evidence without deleting or queueing work', async () => {
const completed = { version: 1, agentId: 'agent-1', repoPath: '/repo', branch: BRANCH, path: WORKTREE, head: HEAD,
startedAt: CREATED_AT, capturedAt: CREATED_AT };
const state = agentState({ completedCheckouts: [completed], reviewLoopMergeTarget: { url: 'https://github.com/example/repo/pull/7' }, repoStateVerification: { status: 'pending' } });
const recheck = vi.fn(async () => true);
findMissingCheckoutPreservation.mockResolvedValue({ archiveDir: '/example/archive', evidenceDigest: 'a'.repeat(64), recheck });
expect(await run({ agentState: state })).toMatchObject({ verified: true, skipReason: null });
expect(findMissingCheckoutPreservation).toHaveBeenCalledWith({ repoPath: '/repo', release: { ...RELEASE, createdAt: CREATED_AT } });
expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({
status: 'verified', reason: 'already-absent-preservation-verified', head: HEAD,
preservation: expect.objectContaining({ capturedAt: CREATED_AT, evidenceDigest: 'a'.repeat(64) }),
}));
expect(recordRepoStateVerification).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({ status: 'completed' }));
expect(addTask).not.toHaveBeenCalled();
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
recordCleanupOutcome.mockResolvedValueOnce(false);
expect(await run({ agentState: state })).toMatchObject({ verified: false, skipReason: 'already-absent-preservation-unverified' });
recheck.mockResolvedValue(false);
expect(await run({ agentState: state })).toMatchObject({ verified: false, skipReason: 'already-absent-preservation-unverified' });
findMissingCheckoutPreservation.mockResolvedValue(null);
expect(await run({ agentState: state })).toMatchObject({ verified: false, skipReason: 'already-absent-preservation-unverified' });
});
it('withholds absent-checkout settlement for a receipt from an earlier execution generation', async () => {
const completed = { version: 1, agentId: 'agent-1', repoPath: '/repo', branch: BRANCH, path: WORKTREE, head: HEAD,
startedAt: '2025-01-01T00:00:00.000Z', capturedAt: CREATED_AT };
const state = agentState({ completedCheckouts: [completed], reviewLoopMergeTarget: { url: 'https://github.com/example/repo/pull/7' } });
findMissingCheckoutPreservation.mockResolvedValue({ archiveDir: '/example/archive', evidenceDigest: 'a'.repeat(64), recheck: async () => true });
expect(await run({ agentState: state })).toMatchObject({ verified: false });
expect(findMissingCheckoutPreservation).not.toHaveBeenCalled();
expect(recordCleanupOutcome).not.toHaveBeenCalledWith('agent-1', expect.objectContaining({ status: 'verified' }));
});
it.each([['broken leaf symlink', true], ['unreadable EACCES leaf', null]])('never treats %s as absent or verified cleanup', async (_name, presence) => {
readCheckoutPathPresence.mockResolvedValue(presence);
const result = await run();
expect(result.verified).toBe(false);
expect(result.observed?.worktreePresent).toBe(presence);
expect(result.skipReason).not.toBe('already-absent-preservation-unverified');
expect(addTask).not.toHaveBeenCalled();
});
it('keeps a reused branch with a different checkout out of recovery across owner completion', async () => {
listWorktrees.mockResolvedValue([{ ...RELEASE, path: '/repo/new-owner' }]);
readClaimOwnershipAgents.mockResolvedValue([{ id: 'new-owner', status: 'running' }]);
for (let i = 0; i < 70; i++) expect(await run()).toMatchObject({ skipReason: 'checkout-incarnation-changed', recoveryTaskId: null });
readClaimOwnershipAgents.mockResolvedValue([{ id: 'new-owner', status: 'completed', result: { success: true } }]);
expect(await run()).toMatchObject({ skipReason: 'checkout-incarnation-changed', recoveryTaskId: null });
expect(addTask).not.toHaveBeenCalled();
expect(prepareInventoriedCheckoutRetirement).not.toHaveBeenCalled();
});
it('retains a recreated same-path checkout despite identical branch and head', async () => {
listWorktrees.mockResolvedValue([RELEASE]);
readCompletedCheckoutIdentity.mockResolvedValue({ head: HEAD, incarnation: { pointer: { ino: 'new' } } });
expect(await run({ agentState: agentState({ completedCheckouts: [{ ...RELEASE, incarnation: { pointer: { ino: 'old' } } }] }) })).toMatchObject({ skipReason: 'checkout-incarnation-changed' });
expect(addTask).not.toHaveBeenCalled();
});
it('keeps missing checkout/ref integration separate from unavailable private content preservation', async () => {
const state = agentState({ reviewLoopMergeTarget: { url: 'https://github.com/example/repo/pull/7' } });
for (let i = 0; i < 70; i++) expect(await run({ agentState: state })).toMatchObject({ verified: false, skipReason: 'already-absent-preservation-unverified' });
expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({ status: 'already-absent', committedIntegrationVerified: true }));
expect(addTask).not.toHaveBeenCalled();
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
});
it('does not associate a stored foreign-repository PR number with this repository', async () => {
localBranch(true);
existsSync.mockReturnValue(true);
await run({ agentState: agentState({ reviewLoopMergeTarget: { url: 'https://github.com/foreign/repo/pull/7' } }) });
expect(getPullRequestState).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
});
it('files nothing when the worktree, branch and PR all landed', async () => {
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });
const result = await run();
expect(result.verified).toBe(false);
expect(result.skipReason).toBe('already-absent-preservation-unverified');
expect(result.issues).toEqual([]);
expect(addTask).not.toHaveBeenCalled();
expect(addNotification).not.toHaveBeenCalled();
});
it('reads the PR state from the list call rather than a second forge round trip', async () => {
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'merged' });
localBranch(true);
const result = await run();
expect(result.observed.prState).toBe('MERGED');
expect(findPullRequestForBranch).toHaveBeenCalledTimes(1);
});
});
describe('verifyAgentRepoState — divergent runs', () => {
it('retires a clean merged branch deterministically instead of queuing an agent', async () => {
existsSync.mockReturnValue(true);
localBranch(true);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });
listWorktrees.mockResolvedValue([RELEASE]);
prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: true, review: { ...review(), comparison: { disposition: 'integrated', localPatch: '', difference: '' } } });
const result = await run();
expect(result).toMatchObject({ verified: true, recoveryTaskId: null });
expect(retireInventoriedCheckout).toHaveBeenCalledWith(expect.objectContaining({ review: expect.objectContaining({ acceptSuperseded: false }) }), expect.objectContaining({ beforeMutation: expect.any(Function) }));
expect(addTask).not.toHaveBeenCalled();
expect(recordCleanupOutcome).toHaveBeenCalledWith('agent-1', expect.objectContaining({ status: 'verified', reason: 'retirement-receipt-verified' }));
});
it('files ONE recovery task for a leftover worktree and branch after a merged PR', async () => {
// The reported failure shape: the agent merged its own PR (branch gone on the
// forge) but its local branch and worktree survived cleanup silently.
existsSync.mockReturnValue(true);
localBranch(true);
listWorktrees.mockResolvedValue([{ ...RELEASE, branch: `refs/heads/${BRANCH}` }]);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });
const result = await run();
expect(result.verified).toBe(false);
expect(result.issues.map(i => i.code)).toEqual([
REPO_STATE_ISSUES.WORKTREE_PRESENT,
REPO_STATE_ISSUES.LOCAL_BRANCH_PRESENT,
]);
expect(addTask).toHaveBeenCalledTimes(1);
const [payload, kind] = addTask.mock.calls[0];
expect(kind).toBe('internal');
expect(payload.description).toContain(BRANCH);
expect(payload.isRecovery).toBe(true);
expect(payload.metadata.recoveryOrigin).toMatchObject({ subsystem: 'repository-cleanup', attempt: 1, noProgress: false });
expect(payload.metadata.recoveryOrigin.observation).toMatch(/^[a-f0-9]{64}$/);
expect(payload.app).toBe('demo-app');
// The recovery agent must not run in a worktree of its own — it is cleaning
// worktrees up.
expect(payload.useWorktree).toBe(false);
// Remediation must be actionable without re-diagnosing, and must forbid
// deleting unmerged work or touching a sibling agent's branch.
expect(payload.context).toContain(`Keep the retained worktree ${WORKTREE}`);
expect(payload.context).toContain('/api/cos/schedule/branch-reconcile/checkouts/review');
expect(payload.context).toContain('/api/cos/schedule/branch-reconcile/checkouts/retire');
expect(payload.context).toContain('FULL returned review.comparison.localPatch and difference');
expect(payload.context).toContain('"digest":"<review.digest>"');
expect(payload.context).toContain('ok:true and branchDeleted:true');
expect(payload.context).not.toMatch(/git (?:worktree (?:remove|unlock|prune)|branch -[dD]|push[^\n]*--delete)|--remove-source-branch/);
expect(payload.metadata.retirementReview).toEqual({ appId: 'demo-app', release: RELEASE, createdAt: CREATED_AT });
expect(recordBranchReconcileOutcome).toHaveBeenCalledWith('demo-app', expect.objectContaining({
retirementObligations: [{ ...RELEASE, reason: 'retirement-review-pending' }],
}));
expect(recordBranchReconcileOutcome.mock.invocationCallOrder[0]).toBeLessThan(prepareInventoriedCheckoutRetirement.mock.invocationCallOrder[0]);
expect(prepareInventoriedCheckoutRetirement.mock.invocationCallOrder[0]).toBeLessThan(addTask.mock.invocationCallOrder[0]);
expect(payload.context).toContain(`touch ONLY ${BRANCH}`);
expect(ensureTaskThread).not.toHaveBeenCalled();
});
it('retains a recovery successor divergence without starting another lineage', async () => {
existsSync.mockReturnValue(true);
localBranch(true);
listWorktrees.mockResolvedValue([{ ...RELEASE, branch: `refs/heads/${BRANCH}` }]);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });
const result = await run({ task: task({ recoveryOrigin: { subsystem: 'repository-cleanup', parentAgentId: 'original' } }) });
expect(result).toMatchObject({ verified: false, skipReason: 'cleanup-successor-review-unresolved' });
expect(addTask).not.toHaveBeenCalled();
expect(recordCleanupOutcome).toHaveBeenCalledWith('agent-1', expect.objectContaining({ status: 'blocked', reason: 'cleanup-successor-review-unresolved' }));
});
it('retains a refused preview obligation and retries fresh evidence without dispatching unsafe cleanup', async () => {
existsSync.mockReturnValue(true);
localBranch(true);
listWorktrees.mockResolvedValue([{ ...RELEASE, branch: `refs/heads/${BRANCH}` }]);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });
prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: false, reason: 'active-agent-owner' });
expect(await run()).toMatchObject({ verified: false, skipReason: 'active-agent-owner', recoveryTaskId: null });
expect(addTask).not.toHaveBeenCalled();
expect(recordBranchReconcileOutcome).toHaveBeenCalledWith('demo-app', expect.objectContaining({ reason: 'active-agent-owner' }));
// The gate declining to retire is its designed outcome: reported at info, never warn.
expect(emitLog).toHaveBeenCalledWith('info', expect.stringContaining('Repo-state retirement retained'), expect.any(Object));
expect(emitLog).not.toHaveBeenCalledWith('warn', expect.stringContaining('Repo-state retirement retained'), expect.anything());
prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: true, review: { ...review(), digest: 'b'.repeat(64) } });
expect(await run()).toMatchObject({ verified: false, recoveryTaskId: 'task-recovery-1' });
// The recovery task is the investigation, so the divergence itself is logged at info.
expect(emitLog).toHaveBeenCalledWith('info', expect.stringContaining('Repo state diverged'), expect.any(Object));
expect(emitLog).not.toHaveBeenCalledWith('warn', expect.stringContaining('Repo state diverged'), expect.anything());
expect(prepareInventoriedCheckoutRetirement).toHaveBeenCalledTimes(2);
});
it.each(['locked', 'persistence-failed', 'obligation-missing', 'inventory-missing'])('preserves %s cleanup without shell fallback', async cause => {
existsSync.mockReturnValue(true);
localBranch(true);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/1', detail: 'MERGED' });
listWorktrees.mockResolvedValue(cause === 'inventory-missing' ? [] : [{ ...RELEASE, locked: cause === 'locked', branch: `refs/heads/${BRANCH}` }]);
if (cause === 'persistence-failed') recordBranchReconcileOutcome.mockRejectedValue(new Error('write refused'));
if (cause === 'obligation-missing') recordBranchReconcileOutcome.mockResolvedValue({});
const result = await run();
expect(result.verified).toBe(false);
expect(result.skipReason).toMatch(/^retirement-/);
expect(prepareInventoriedCheckoutRetirement).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
});
it('finds a worktree git still tracks even when the directory is gone', async () => {
listWorktrees.mockResolvedValue([{ path: WORKTREE, branch: `refs/heads/${BRANCH}` }]);
const result = await run({ prExpected: false });
expect(result.issues.map(i => i.code)).toEqual([REPO_STATE_ISSUES.WORKTREE_PRESENT]);
});
it('holds an orphan OPEN PR waiting for CI through 70 scans without cognitive work', async () => {
localBranch(true);
hasBranchMergeEvidence.mockResolvedValue(false);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/9', detail: 'OPEN', autoMergeEnabled: true, headRefOid: HEAD });
for (let i = 0; i < 70; i++) expect(await run()).toMatchObject({ verified: false, skipReason: 'delivery-ci-or-review-pending', recoveryTaskId: null });
expect(addTask).not.toHaveBeenCalled();
expect(reserveRepoCleanupRecovery).not.toHaveBeenCalled();
});
it.each(['CONFLICTING', 'FAILURE'])('admits genuine exact-head code repair after %s evidence', async failure => {
localBranch(true);
hasBranchMergeEvidence.mockResolvedValue(false);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/9', detail: 'OPEN', headRefOid: HEAD });
execGh.mockResolvedValue(openView(failure === 'CONFLICTING' ? { mergeable: failure } : { statusCheckRollup: [{ name: 'CI', conclusion: failure }] }));
inspectOrQueueCompletedReview.mockResolvedValue({ disposition: 'queued-review', reason: 'code-repair-queued', taskId: 'review-1' });
expect(await run()).toMatchObject({ recoveryTaskId: 'review-1' });
expect(inspectOrQueueCompletedReview).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'agent-1', branch: BRANCH, headSha: HEAD, worktreePath: WORKTREE, repairEvidence: expect.objectContaining({ head: HEAD }) }));
expect(addTask).not.toHaveBeenCalled();
});
it('does not send changed/unpublished head or malformed forge data to code recovery', async () => {
localBranch(true);
hasBranchMergeEvidence.mockResolvedValue(false);
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/9', detail: 'OPEN' });
execGh.mockResolvedValue(openView({ headRefOid: '3'.repeat(40), mergeable: 'CONFLICTING' }));
expect(await run()).toMatchObject({ skipReason: 'delivery-head-unverified', recoveryTaskId: null });
expect(addTask).not.toHaveBeenCalled();
});
it('reports an unmerged PR the agent left open', async () => {
localBranch(true);
hasBranchMergeEvidence.mockResolvedValue(false);
listRemoteHeads.mockResolvedValue(new Map([[BRANCH, 'abc123']]));
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/9', detail: 'OPEN' });
const result = await run();
expect(result.issues.map(i => i.code)).toEqual([
REPO_STATE_ISSUES.LOCAL_BRANCH_PRESENT,
REPO_STATE_ISSUES.REMOTE_BRANCH_PRESENT,
REPO_STATE_ISSUES.BRANCH_UNMERGED,
REPO_STATE_ISSUES.PR_UNMERGED,
]);
expect(result.skipReason).toBe('delivery-ci-or-review-pending');
expect(addTask).not.toHaveBeenCalled();
});
it('does not re-file when a recovery task for the branch already exists', async () => {
existsSync.mockReturnValue(true);
addTask.mockResolvedValue({ id: 'task-recovery-1', duplicate: true });
const result = await run({ prExpected: false });
expect(result.issues.length).toBeGreaterThan(0);
expect(result.recoveryTaskId).toBeNull();
});
it('does not create a Brain recovery thread for routine retained content', async () => {
existsSync.mockReturnValue(true);
await run({ prExpected: false });
expect(ensureTaskThread).not.toHaveBeenCalled();
});
});
describe('verifyAgentRepoState — never fires', () => {
it('is off for an app with verifyRepoStateOnCompletion: false', async () => {
getAppById.mockResolvedValue({ id: 'demo-app', verifyRepoStateOnCompletion: false });
existsSync.mockReturnValue(true);
const result = await run();
expect(result.skipReason).toBe(REPO_STATE_SKIPS.DISABLED);
expect(addTask).not.toHaveBeenCalled();
// The switch must short-circuit the probes too, not just the reporting.
expect(listWorktrees).not.toHaveBeenCalled();
expect(findPullRequestForBranch).not.toHaveBeenCalled();
});
it('leaves a FAILED run alone so its retry can resume from the preserved branch', async () => {
existsSync.mockReturnValue(true);
const result = await run({ success: false });
expect(result.skipReason).toBe(REPO_STATE_SKIPS.FAILED_RUN);
expect(addTask).not.toHaveBeenCalled();
});
it('defers while a review-loop follow-up still owns the branch', async () => {
queuedTasks([{ status: 'pending', metadata: { app: 'demo-app', reviewLoopFollowUp: true, reviewLoopPRBranch: BRANCH } }]);
existsSync.mockReturnValue(true);
const result = await run({ task: task({ prCompletion: 'review-then-merge' }) });
expect(result.skipReason).toBe(REPO_STATE_SKIPS.FOLLOW_UP_PENDING);
expect(addTask).not.toHaveBeenCalled();
});
it('defers while a retry holds the branch as its resume pointer', async () => {
queuedTasks([{ status: 'pending', metadata: { app: 'demo-app', existingBranch: BRANCH } }]);
existsSync.mockReturnValue(true);
const result = await run();
expect(result.skipReason).toBe(REPO_STATE_SKIPS.FOLLOW_UP_PENDING);
});
it('defers while pr-watcher still holds the PR for a deterministic merge', async () => {
// The merge-on-green GitHub path never spawns a follow-up TASK — it queues the
// PR on the app record for the next watcher tick. Reading only the task queue
// would call every one of those branches leaked.
readPendingMergePrs.mockReturnValue([{ prBranch: BRANCH, prUrl: 'https://github.com/example/repo/pull/2' }]);
existsSync.mockReturnValue(true);
const result = await run();
expect(result.skipReason).toBe(REPO_STATE_SKIPS.FOLLOW_UP_PENDING);
expect(addTask).not.toHaveBeenCalled();
});
it('stands down when cleanup already raised a warning (it files its own recovery)', async () => {
const result = await run({
cleanupWarnings: ['Auto-merge failed for branch cos/task-x/agent-1 — branch preserved for manual recovery'],
});
expect(result.skipReason).toBe(REPO_STATE_SKIPS.CLEANUP_WARNED);
expect(addTask).not.toHaveBeenCalled();
});
it('ignores a non-worktree run without reading the app record', async () => {
const result = await run({ agentState: agentState({ isWorktree: false }) });
expect(result.skipReason).toBe(REPO_STATE_SKIPS.NOT_WORKTREE);
expect(getAppById).not.toHaveBeenCalled();
expect(getAllTasks).not.toHaveBeenCalled();
});
it('reports probe-incomplete, not "clean", when git could not be asked at all', async () => {
// A firewalled host must not manufacture a recovery agent per run — and must
// not be logged as a verified-clean repo either.
listWorktrees.mockRejectedValue(new Error('not a git repository'));
execGit.mockRejectedValue(new Error('git unavailable'));
listRemoteHeads.mockResolvedValue(null);
findPullRequestForBranch.mockResolvedValue({ status: 'unavailable', url: null, detail: null });
const result = await run();
expect(result.skipReason).toBe('checkout-inventory-unavailable');
expect(result.verified).toBe(false);
expect(addTask).not.toHaveBeenCalled();
});
it('reports probe-incomplete when only SOME probes were unreadable', async () => {
// The partial case is the dangerous one: worktree and branch both read clean,
// so nothing diverged — but the forge never answered, so the PR could be
// sitting open. Calling that "verified" is the absent-vs-empty conflation.
findPullRequestForBranch.mockResolvedValue({ status: 'unavailable', url: null, detail: null });
const result = await run();
expect(result.skipReason).toBe('absent-checkout-integration-unverified');
expect(addTask).not.toHaveBeenCalled();
});
it('still reports a divergence it COULD read alongside one it could not', async () => {
// Partial knowledge does not suppress a finding — what was readable is fact.
existsSync.mockReturnValue(true);
findPullRequestForBranch.mockResolvedValue({ status: 'unavailable', url: null, detail: null });
const result = await run();
expect(result.issues.map(i => i.code)).toContain(REPO_STATE_ISSUES.WORKTREE_PRESENT);
expect(addTask).not.toHaveBeenCalled();
});
it('fails closed when the app record cannot be read', async () => {
// A transient apps.json failure must not override an explicit per-app opt-out.
getAppById.mockRejectedValue(new Error('apps.json unreadable'));
existsSync.mockReturnValue(true);
const result = await run();
expect(result.skipReason).toBe(REPO_STATE_SKIPS.GATE_UNREADABLE);
expect(addTask).not.toHaveBeenCalled();
});
it('fails closed when the task queue cannot be read', async () => {
// "Could not read the queue" must never become "nobody owns this branch" — a
// follow-up queued to land it would get a recovery task filed against it.
getAllTasks.mockRejectedValue(new Error('tasks file unreadable'));
existsSync.mockReturnValue(true);
const result = await run();
expect(result.skipReason).toBe(REPO_STATE_SKIPS.GATE_UNREADABLE);
expect(addTask).not.toHaveBeenCalled();
});
it('defers while a CHALLENGED task still holds the branch', async () => {
// `challenged` is a parked-for-dispute status, not a terminal one: the task
// keeps its branch and resumes on it.
queuedTasks([{ status: 'challenged', metadata: { app: 'demo-app', existingBranch: BRANCH } }]);
existsSync.mockReturnValue(true);
const result = await run();
expect(result.skipReason).toBe(REPO_STATE_SKIPS.FOLLOW_UP_PENDING);
expect(addTask).not.toHaveBeenCalled();
});
it('reports an unmerged GitLab merge request', async () => {
// GitLab is probed too — leaving it unasked would silently pass an open MR as
// a clean repo. States come back lowercase from glab.
localBranch(true);
resolveForgeForRepo.mockResolvedValue({ cli: 'glab', env: null });
findMergeRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://gitlab.example.com/mr/4', number: 4, detail: 'opened' });
const result = await run();
expect(findPullRequestForBranch).not.toHaveBeenCalled();
expect(result.issues.map(i => i.code)).toContain(REPO_STATE_ISSUES.PR_UNMERGED);
expect(addTask).not.toHaveBeenCalled();
expect(result.verified).toBe(false);
});
it('does not claim unmerged work when the merge check could not be answered', async () => {
// `hasBranchMergeEvidence` fails CLOSED (`false`, not a throw) when it cannot read
// a ref — right for its original caller, inverted into a false finding here.
// An unresolvable ref must read as unknown, not as "carries unmerged commits".
readLocalBranchPresence.mockResolvedValue(true);
execGit.mockImplementation((args) => {
if (args[0] === 'show-ref') return Promise.resolve({ exitCode: 0, stdout: '', stderr: '' });
// rev-parse --verify fails => the ref could not be resolved
return Promise.resolve({ exitCode: 128, stdout: '', stderr: 'bad revision' });
});
hasBranchMergeEvidence.mockResolvedValue(false);
const result = await run({ prExpected: false });
expect(hasBranchMergeEvidence).not.toHaveBeenCalled();
expect(result.observed.branchMerged).toBeNull();
expect(result.issues.map(i => i.code)).not.toContain(REPO_STATE_ISSUES.BRANCH_UNMERGED);
expect(result.observed.unreadable).toContain('branch-merged');
});
it('does not report a MERGED GitLab merge request', async () => {
resolveForgeForRepo.mockResolvedValue({ cli: 'glab', env: null });
findMergeRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://gitlab.example.com/mr/4', detail: 'merged' });
const result = await run();
expect(result.verified).toBe(false);
expect(result.skipReason).toBe('already-absent-preservation-unverified');
});
});
// 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.each([false, true])('records each held claim branch under the reason it returns (pinned=%s)', async pinned => {
readClaimOwnershipAgents.mockRejectedValue(new Error('agents unreadable'));
const state = agentState({ isWorktree: false, worktreeBranch: null, workspacePath: '/repo', claimPicksOwnBranch: !pinned,
...(pinned ? { claimBranch: 'claim/issue-11' } : {}), 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([]);
localBranch(true);
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' });
});
it('settles a receipt-less swarm branch from delivery evidence once its checkout and ref are gone', async () => {
const state = agentState({ isWorktree: false, worktreeBranch: null, workspacePath: '/repo', claimPicksOwnBranch: true, claimBranches: ['claim/issue-11'] });
findPullRequestForBranch.mockResolvedValue({ status: 'found', url: 'https://github.com/example/repo/pull/11', detail: 'MERGED' });
expect((await run({ agentState: state })).branches).toEqual([expect.objectContaining({ branch: 'claim/issue-11', skipReason: 'already-absent-preservation-unverified' })]);
expect(recordCleanupOutcome).toHaveBeenLastCalledWith('agent-1', expect.objectContaining({ branch: 'claim/issue-11', path: null, status: 'already-absent' }));
// A holder or an unreadable ref keeps the identity hold.
listWorktrees.mockResolvedValue([{ ...RELEASE, branch: 'refs/heads/claim/issue-11' }]);
expect((await run({ agentState: state })).branches[0].skipReason).toBe('claim-checkout-identity-unverified');
listWorktrees.mockResolvedValue([]);
readLocalBranchPresence.mockResolvedValue(null);
expect((await run({ agentState: state })).branches[0].skipReason).toBe('claim-checkout-identity-unverified');
expect(retireInventoriedCheckout).not.toHaveBeenCalled();
});
});
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
// switch-with-default it replaced silently accepted a new code.
expect(Object.keys(REPO_STATE_REMEDIATIONS).sort()).toEqual(Object.values(REPO_STATE_ISSUES).sort());
});
it('renders each remediation from the branch, worktree and PR in hand', () => {
const ctx = { branchName: BRANCH, base: 'main', prUrl: 'https://github.com/example/repo/pull/1', worktreePath: WORKTREE };
for (const [code, render] of Object.entries(REPO_STATE_REMEDIATIONS)) {
const text = render(ctx);
expect(text, code).toBeTypeOf('string');
expect(text.length, code).toBeGreaterThan(20);
}
});
});
it.each(['draft', 'leave-open'])('reports divergence without cleanup or recovery for %s delivery', async prCompletion => {
existsSync.mockReturnValue(true);
listWorktrees.mockResolvedValue([{ path: WORKTREE, branch: BRANCH }]);
const result = await run({ task: task({ prCompletion }) });
expect(result.verified).toBe(false);
expect(result.issues.length).toBeGreaterThan(0);
expect(result.recoveryTaskId).toBeNull();
expect(addTask).not.toHaveBeenCalled();
expect(cleanupMerged).not.toHaveBeenCalled();
});
describe('claim-swarm completion', () => {
it('retains each missing claim checkout without spawning bookkeeping agents', async () => {
const branches = ['claim/issue-11', 'claim/issue-12'];
findPullRequestForBranch.mockImplementation(async branch => ({ status: 'found', detail: 'OPEN', number: branches.indexOf(branch) + 11,
url: `https://github.com/example/repo/pull/${branches.indexOf(branch) + 11}` }));
const state = agentState({ isWorktree: false, worktreeBranch: null, workspacePath: '/repo', claimPicksOwnBranch: true,
claimBranches: [branches[0]], claimReleasedBranches: branches });
const result = await run({ agentState: state });
expect(result.branches.map(item => item.branch)).toEqual(branches);
expect(addTask).not.toHaveBeenCalled();
for (const branch of branches) expect(recordCleanupOutcome).toHaveBeenCalledWith('agent-1', expect.objectContaining({ branch, status: 'blocked' }));
expect(cleanupMerged).not.toHaveBeenCalled();
});
// #12769: "Cleanup blocked: claim-owner-ambiguous" named no run, so nobody
// could tell which live run to look at.
it('names the live runs that keep a swarm checkout ambiguous', async () => {
const pending = (id) => ({ id, status: 'running', workspacePath: '/repo',
metadata: { sourceWorkspace: '/repo', claimBranch: `claim/issue-${id.length}`, claimPicksOwnBranch: false, claimSelectionPending: true } });
readClaimOwnershipAgents.mockResolvedValue([pending('agent-a'), pending('agent-bb'),
{ id: 'agent-done', status: 'completed', metadata: { sourceWorkspace: '/repo', claimSelectionPending: true } }]);
const state = agentState({ isWorktree: false, worktreeBranch: null, workspacePath: '/repo', claimPicksOwnBranch: true,
claimBranches: ['claim/issue-11'] });
await run({ agentState: state });
expect(recordCleanupOutcome).toHaveBeenCalledWith('agent-1', expect.objectContaining({
branch: 'claim/issue-11', status: 'blocked', reason: 'claim-owner-ambiguous', owners: ['agent-a', 'agent-bb'] }));
});
it('does not infer branches from output or override manual handoffs and failed retries', async () => {
const state = agentState({ isWorktree: false, worktreeBranch: null, claimPicksOwnBranch: true, claimBranches: ['claim/issue-11'] });
findPullRequestForBranch.mockResolvedValue({ status: 'found', detail: 'OPEN', url: 'https://github.com/example/repo/pull/11' });
await run({ agentState: state, task: task({ prCompletion: 'leave-open' }) });
await run({ agentState: state, success: false });
await run({ agentState: { ...state, metadata: { ...state.metadata, claimBranches: [] }, output: 'claim/issue-22' } });
expect(addTask).not.toHaveBeenCalled();
expect(cleanupMerged).not.toHaveBeenCalled();
});
});
describe('durable completion replay', () => {
const archived = () => ({ ...agentState(), id: 'agent-1', taskId: 'task-1', status: 'completed', result: { success: true },
metadata: { ...agentState().metadata, repoStateVerification: { status: 'pending' } } });
it('resumes a persisted pending audit after restart and settles clean completion', async () => {
readBranchCompletionPolicies.mockResolvedValue([archived()]);
getTaskById.mockResolvedValue(task());
findPullRequestForBranch.mockResolvedValue({ status: 'found', detail: 'MERGED', url: 'https://github.com/example/repo/pull/7' });
expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 1 });
expect(recordRepoStateVerification).toHaveBeenCalledWith('agent-1', expect.objectContaining({ status: 'pending' }));
expect(addTask).not.toHaveBeenCalled();
});
it('backs off repeated machine recovery across restarts without creating tasks', async () => {
const prior = archived();
prior.metadata.completionCleanup = { replayAttempts: 5, retryAt: new Date(Date.now() + 60_000).toISOString() };
readBranchCompletionPolicies.mockResolvedValue([prior]);
expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 0 });
prior.metadata.completionCleanup.retryAt = new Date(Date.now() - 1).toISOString();
getTaskById.mockResolvedValue(task());
expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 1 });
const { recordCompletionCleanup } = await import('./cosAgentLifecycle.js');
expect(recordCompletionCleanup).toHaveBeenCalledWith('agent-1', prior.startedAt, expect.objectContaining({ replayAttempts: 6, retryAt: expect.any(String) }));
expect(addTask).not.toHaveBeenCalled();
});
it('keeps missing policy pending with an updated retry time rather than granting authority or starving other audits', async () => {
getTaskById.mockResolvedValue(null);
readBranchCompletionPolicies.mockResolvedValue([archived()]);
await sweepRepoStateVerifications();
expect(recordRepoStateVerification).toHaveBeenCalledWith('agent-1', expect.objectContaining({ status: 'pending', reasons: ['task-unavailable'], checkedAt: expect.any(String) }));
expect(addTask).not.toHaveBeenCalled();
});
it('uses the exact successor result without creating an unrelated generic recovery task', async () => {
localBranch(true);
execGh.mockResolvedValue(openView({ number: 7, mergeable: 'CONFLICTING' }));
findPullRequestForBranch.mockResolvedValue({ status: 'found', detail: 'OPEN', url: 'https://github.com/example/repo/pull/7' });
inspectOrQueueCompletedReview.mockResolvedValue({ disposition: 'join-existing', reason: 'review-successor-exists', taskId: 'existing' });
expect(await run()).toMatchObject({ skipReason: 'review-successor-exists' });
expect(addTask).not.toHaveBeenCalled();
expect(recordRepoStateRecovery).not.toHaveBeenCalled();
});
});