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

39.5 KB
Raw Blame
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

// Agent → server pending-merge handoff (#12247), end to end through the real
// admission service and the real pr-watcher coordinator over synthetic stores.
const f = vi.hoisted(() => ({
  state: null, tasks: {}, apps: new Map(), checkouts: {}, pr: null, foreign: new Set(), reviewers: [], optionalReviewers: [], queueWriteFailure: false, delivery: null,
}));
vi.mock('../lib/localReviewLifecycle.js', () => ({ localReviewLifecycle: async (_cwd, { prUrl }) => f.delivery?.receipt?.prUrl === prUrl ? f.delivery : { reusable: false } }));
vi.mock('./cosState.js', async () => {
  const { createFileWriteQueue } = await import('../lib/fileWriteQueue.js');
  return {
    withStateLock: createFileWriteQueue(),
    loadState: async () => f.state,
    saveState: async (state) => { f.state = state; },
    readMergeAdmissionStateForSafetyCheck: async () => ({ trusted: true, ...structuredClone(f.state) }),
  };
});
vi.mock('./cosTaskStore.js', () => ({
  addTask: vi.fn(async () => ({ id: 'cleanup-recovery' })),
  getTaskById: async (id) => f.tasks[id] ?? null,
}));
vi.mock('../lib/gitRemote.js', () => ({
  getOriginInfo: async (path) => ({ host: 'github.com', fullName: f.foreign.has(path) ? 'example/other' : 'example/repo' }),
}));
vi.mock('../lib/execGit.js', () => ({
  execGit: async (args, cwd) => {
    const checkout = f.checkouts[cwd];
    if (!checkout) throw new Error('not a git checkout');
    if (args[0] === 'symbolic-ref') return { stdout: `${checkout.branch}\n` };
    if (args.includes('--git-path')) return { stdout: `${join(cwd, 'portos-review-status')}\n` };
    if (args[0] === 'rev-parse') return { stdout: `${checkout.head}\n` };
    throw new Error(`unexpected git ${args.join(' ')}`);
  },
}));
const execGhMock = vi.fn();
vi.mock('./github.js', () => ({
  execGh: (...args) => execGhMock(...args),
  ensureForgeReachable: async () => ({ ok: true, status: 'ok' }),
}));
vi.mock('./forgeExecOptions.js', () => ({ resolveForgeExecOptions: async (cwd) => ({ cwd, env: {} }) }));
vi.mock('./apps.js', () => ({
  getAppById: async (id) => f.apps.get(id) ?? null,
  getActiveApps: async () => [...f.apps.values()],
  updateApp: async (id, patch) => { if (f.queueWriteFailure) throw new Error('disk unavailable'); const next = { ...f.apps.get(id), ...patch }; f.apps.set(id, next); return next; },
}));
vi.mock('./untrustedContent.js', () => ({ screenUntrustedContent: async () => ({ ok: true, screening: { safe: true } }) }));
vi.mock('./codeReview.js', () => ({
  resolveReviewLoopOptions: async () => ({ reviewers: f.reviewers, usernames: [], optionalReviewers: f.optionalReviewers, reviewerMaxRounds: {} }),
}));
// This synthetic managed app has no merged-tree capability. Keep its fake-time
// poll tests independent of real filesystem scheduling; pendingMergeGuard.test
// exercises the actual capability probe and checkout/command boundary.
vi.mock('./pendingMergeGuard.js', async importOriginal => ({
  ...await importOriginal(),
  preparePendingMergeGuard: async () => ({ ok: true, evidence: null }),
}));
const mergePrMock = vi.fn();
vi.mock('./git.js', () => ({ mergePR: (...args) => mergePrMock(...args) }));
const notifyMock = vi.fn(async () => ({ id: 'notification-1' }));
vi.mock('./notifications.js', () => ({
  addNotification: (...args) => notifyMock(...args),
  NOTIFICATION_TYPES: { AGENT_WARNING: 'agent_warning' },
  PRIORITY_LEVELS: { HIGH: 'high' },
}));
const followUpMock = vi.fn(async () => ({ id: 'follow-up-1' }));
vi.mock('./agentWorktreeCleanup.js', () => ({ spawnReviewLoopFollowUp: (...args) => followUpMock(...args) }));
const cleanupMock = vi.fn();
vi.mock('./heldCheckoutRecovery.js', () => ({ retirePendingMergeCheckout: (...args) => cleanupMock(...args) }));

import { handoffPendingMerge, hasQueuedMergeHandoff } from './cosMergeHandoff.js';
import { processPendingMergePrs, readPendingMergePrs, nudgeLocalPendingMergePrs } from './prWatcher.js';
import { claimMergeAdmission } from './cosMergeAdmission.js';
import { addTask } from './cosTaskStore.js';

const HEAD = 'a'.repeat(40);
const PR_URL = 'https://github.com/example/repo/pull/7';
let workspace;

const claimAgent = (id, branch) => ({
  id, taskId: `task-${id}`, startedAt: '2026-01-01T00:00:00.000Z', status: 'running',
  metadata: { sourceWorkspace: '/repos/source', claimPicksOwnBranch: true, claimBranches: [branch] },
});
const handoff = (overrides = {}) => handoffPendingMerge({ agentId: 'agent-1', prUrl: PR_URL, headSha: HEAD, worktreePath: workspace, ...overrides });
const pending = () => readPendingMergePrs(f.apps.get('app1'));
// A receipt starts an immediate sweep; joining it keeps each test's forge reads
// ordered. Imported at call time: the restart case resets the module registry.
const handedOff = async (overrides) => {
  const result = await handoff(overrides);
  await (await import('./prWatcher.js'))._sweepPendingMergeApp('app1');
  return result;
};
const greenChecks = () => { f.pr.statusCheckRollup = [{ conclusion: 'SUCCESS' }]; };

beforeAll(async () => { workspace = await mkdtemp(join(tmpdir(), 'merge-handoff-')); });
afterAll(async () => { await rm(workspace, { recursive: true, force: true }); });

beforeEach(async () => {
  (await import('./prWatcher.js')).cancelHandoffFollowUps();
  (await import('./prWatcher.js')).setHandoffFollowUpGate(async () => null);
  cleanupMock.mockReset().mockResolvedValue({ ok: true, branchDeleted: true, archiveDir: '/archives/example' });
  f.state = { agents: { 'agent-1': claimAgent('agent-1', 'claim/issue-1'), 'agent-2': claimAgent('agent-2', 'claim/issue-2') }, mergeAdmissions: {} };
  f.tasks = Object.fromEntries(['agent-1', 'agent-2'].map((id) => [`task-${id}`, {
    id: `task-${id}`, status: 'in_progress', taskType: 'user', priority: 'MEDIUM', description: 'Example change',
    metadata: { app: 'app1', prCompletion: 'review-then-merge' },
  }]));
  f.apps = new Map([['app1', { id: 'app1', repoPath: '/repos/source', forgeAccount: null, mergeHandoffMinQueuedRuns: 3 }]]);
  f.checkouts = { [workspace]: { branch: 'claim/issue-1', head: HEAD } };
  f.foreign = new Set();
  f.reviewers = ['codex'];
  f.optionalReviewers = [];
  f.queueWriteFailure = false;
  f.delivery = null;
  f.pr = {
    number: 7, title: 'Example change', body: 'Closes #101', author: { login: 'example-user' },
    commits: [{ messageHeadline: 'fix: example', messageBody: '' }], state: 'OPEN', isDraft: false,
    isCrossRepository: false, headRefName: 'claim/issue-1', headRefOid: HEAD,
    mergeStateStatus: 'CLEAN', mergeable: 'MERGEABLE', reviewDecision: 'APPROVED', statusCheckRollup: [{ status: 'QUEUED' }],
  };
  await writeFile(join(workspace, 'portos-review-status'), `REVIEW_STATUS=clean\nREVIEW_HEAD=${HEAD}\n`);
  execGhMock.mockReset().mockImplementation(async (args) => {
    if (args[0] === 'pr' && args[1] === 'view') return JSON.stringify(f.pr);
    if (args[0] === 'pr' && args[1] === 'diff') return 'diff --git a/example.js b/example.js\n+const ok = true;';
    if (args[0] === 'api' && args.some(arg => arg.includes('/actions/runs?'))) return JSON.stringify({ total_count: 3, workflow_runs: [{ status: 'queued' }] });
    if (args[0] === 'api') return JSON.stringify({ number: 101, state: 'open', title: 'Example', body: 'Example need', assignees: [] });
    throw new Error('unexpected forge read');
  });
  mergePrMock.mockReset().mockResolvedValue({ success: true });
  notifyMock.mockClear();
  followUpMock.mockClear();
  addTask.mockClear();
});

describe('pending-merge handoff', () => {
  it('keeps original ownership by default and when backlog is unknown or below the configured threshold', async () => {
    delete f.apps.get('app1').mergeHandoffMinQueuedRuns;
    expect(await handoff()).toMatchObject({ queued: false, reason: 'ci-backlog-policy-disabled' });
    f.apps.get('app1').mergeHandoffMinQueuedRuns = 3;
    const forge = execGhMock.getMockImplementation();
    for (const [backlog, reason] of [[{}, 'ci-backlog-unreadable'], [{ total_count: 2, workflow_runs: [] }, 'ci-backlog-below-threshold']]) {
      execGhMock.mockImplementation(async args => args.some(arg => arg.includes('/actions/runs?')) ? JSON.stringify(backlog) : forge(args));
      expect(await handoff()).toMatchObject({ queued: false, reason });
    }
    expect(pending()).toEqual([]);
    expect(mergePrMock).not.toHaveBeenCalled();
  });

  it.each([
    { statusCheckRollup: [{ status: 'COMPLETED', conclusion: 'FAILURE' }] },
    { statusCheckRollup: [] }, { mergeable: 'CONFLICTING' }, { reviewDecision: 'REVIEW_REQUIRED' },
  ])('refuses an unhealthy or unverified current PR despite a repository backlog: %j', async change => {
    Object.assign(f.pr, change);
    expect(await handoff()).toMatchObject({ queued: false, reason: 'pr-not-waiting-on-healthy-ci' });
    expect(pending()).toEqual([]);
  });

  it('requires an available successor and a successfully persisted receipt', async () => {
    const watcher = await import('./prWatcher.js');
    watcher.cancelHandoffFollowUps();
    expect(await handoff()).toMatchObject({ queued: false, reason: 'merge-successor-unavailable' });
    watcher.setHandoffFollowUpGate(async () => null);
    f.queueWriteFailure = true;
    expect(await handoff()).toMatchObject({ queued: false, reason: 'queue-write-failed' });
    expect(pending()).toEqual([]);
    expect(mergePrMock).not.toHaveBeenCalled();
  });

  it('does not run the immediate receipt pass while paused', async () => {
    const result = await handedOff();
    greenChecks();
    const watcher = await import('./prWatcher.js');
    watcher.setHandoffFollowUpGate(async () => 'paused');
    await watcher.followUpHandoffReceipt('app1', result.receipt.id);
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(pending()).toHaveLength(1);
  });

  it('an on-demand local nudge recovers the existing conflicted receipt once and preserves remote-only/locked receipts', async () => {
    await handedOff();
    f.tasks['task-agent-1'].status = 'completed';
    const original = pending()[0];
    const untouched = ['remote-only', 'locked'].map((kind, i) => ({ ...structuredClone(original), prNumber: 80 + i,
      prUrl: `https://github.com/example/repo/pull/${80 + i}`, prBranch: `claim/${kind}`,
      handoff: { ...original.handoff, receiptId: kind }, ticks: 9 }));
    f.apps.get('app1').pendingMergePrs.push(...untouched);
    f.pr.mergeStateStatus = 'DIRTY';
    const local = { getBranches: async () => [{ name: 'claim/issue-1' }, { name: 'claim/locked' }],
      listWorktrees: async () => [{ branch: 'refs/heads/claim/locked', locked: true }] };
    const results = await Promise.all([nudgeLocalPendingMergePrs('app1', local), nudgeLocalPendingMergePrs('app1', local)]);
    expect(results[0]).toMatchObject({ escalated: 1, checked: 1 });
    expect(followUpMock).toHaveBeenCalledTimes(1);
    expect(pending()).toEqual(untouched);
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(await nudgeLocalPendingMergePrs('app1', local)).toMatchObject({ checked: 0 });
    expect(followUpMock).toHaveBeenCalledTimes(1);
  });

  it('waits for an active original claim before dispatching CI failure recovery and transfers custody once', async () => {
    await handedOff();
    f.pr.statusCheckRollup = [{ conclusion: 'FAILURE' }];
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ waiting: 1, escalated: 0 });
    expect(followUpMock).not.toHaveBeenCalled();
    f.tasks['task-agent-1'].status = 'completed';
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ escalated: 1 });
    await processPendingMergePrs(f.apps.get('app1'));
    expect(followUpMock).toHaveBeenCalledTimes(1);
    expect(pending()).toEqual([]);
  });

  it('retains a closed unmerged PR instead of dispatching recovery from its stale failed CI', async () => {
    await handedOff();
    f.tasks['task-agent-1'].status = 'completed';
    f.pr.state = 'CLOSED';
    f.pr.statusCheckRollup = [{ conclusion: 'CANCELLED' }];
    await processPendingMergePrs(f.apps.get('app1'));
    expect(pending()[0].recoveryBlocked).toBe('pr-closed-unmerged');
    expect(followUpMock).not.toHaveBeenCalled();
    expect(mergePrMock).not.toHaveBeenCalled();
  });

  it('preserves custody through forge outages past the polling budget and recovers when it returns', async () => {
    await handedOff();
    const forge = execGhMock.getMockImplementation();
    execGhMock.mockImplementation(async args => args[0] === 'pr' && args[1] === 'view' ? null : forge(args));
    pending()[0].ticks = 11;
    await processPendingMergePrs(f.apps.get('app1'));
    expect(pending()[0].attention).toBe('forge-unreadable');
    expect(notifyMock).toHaveBeenCalledWith(expect.objectContaining({
      description: expect.stringContaining('retains its pending-merge receipt and continues checking'),
    }));
    await processPendingMergePrs(f.apps.get('app1'));
    expect(notifyMock).toHaveBeenCalledTimes(1);
    execGhMock.mockImplementation(forge);
    greenChecks();
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 1 });
    expect(pending()).toEqual([]);
  });

  it('names a cleanup recovery owner for a retained merged checkout and confirms cleanup after it finishes', async () => {
    await handedOff();
    f.tasks['task-agent-1'].status = 'completed';
    cleanupMock.mockResolvedValue({ ok: false, reason: 'retirement-submodule-not-uninitialized' });
    greenChecks();
    await processPendingMergePrs(f.apps.get('app1'));
    f.pr.state = 'MERGED';
    pending()[0].cleanup.retryAt = 0;
    await processPendingMergePrs(f.apps.get('app1'));
    expect(pending()[0].cleanup.recoveryTaskId).toBe('cleanup-recovery');
    expect(addTask).toHaveBeenCalledWith(expect.objectContaining({
      description: expect.stringContaining('Prepare retained checkout'),
      context: expect.stringContaining('Do not delete the checkout or refs yourself.'),
    }), 'user');
    f.tasks['cleanup-recovery'] = { id: 'cleanup-recovery', status: 'completed' };
    await processPendingMergePrs(f.apps.get('app1'));
    cleanupMock.mockResolvedValue({ ok: true, branchDeleted: true });
    await processPendingMergePrs(f.apps.get('app1'));
    expect(pending()).toEqual([]);
  });

  it.each(['retirement-submodule-not-uninitialized', 'active-owner'])(
    'holds an unresolved completed recovery after one final retirement attempt: %s', async reason => {
      await handedOff();
      f.tasks['task-agent-1'].status = 'completed';
      f.pr.state = 'MERGED';
      cleanupMock.mockResolvedValue({ ok: false, reason: 'retirement-submodule-not-uninitialized' });
      await processPendingMergePrs(f.apps.get('app1'));
      pending()[0].cleanup.retryAt = 0;
      await processPendingMergePrs(f.apps.get('app1'));
      expect(pending()[0].cleanup.recoveryTaskId).toBe('cleanup-recovery');

      f.tasks['cleanup-recovery'] = { id: 'cleanup-recovery', status: 'completed' };
      await processPendingMergePrs(f.apps.get('app1'));
      cleanupMock.mockResolvedValue({ ok: false, reason });
      await processPendingMergePrs(f.apps.get('app1'));
      expect(pending()[0].cleanup).toMatchObject({
        status: 'held', reason, recoveryTaskId: 'cleanup-recovery', recoveryCompleted: true,
      });

      // Completion is not proof of preservation. Later sweeps keep the same
      // owner and refusal, even when the final attempt found a transient reason.
      for (let sweep = 0; sweep < 2; sweep += 1) {
        pending()[0].cleanup.retryAt = 0;
        await processPendingMergePrs(f.apps.get('app1'));
      }
      expect(pending()).toHaveLength(1);
      expect(pending()[0].cleanup.status).toBe('held');
      expect(cleanupMock).toHaveBeenCalledTimes(2);
      expect(addTask).toHaveBeenCalledTimes(1);
      expect(mergePrMock).not.toHaveBeenCalled();
    },
  );

  it('persists the verified binding and merges only that head once a concurrent lease releases, across a restart', async () => {
    const result = await handedOff();
    expect(result).toMatchObject({ queued: true, receipt: { appId: 'app1', prNumber: 7, headSha: HEAD, repository: 'github.com/example/repo' } });
    // The merge-gate audit (#12549) exempts exactly this head from the run's own record.
    expect(f.state.agents['agent-1'].metadata.mergeHandoffReceipts).toEqual([
      expect.objectContaining({ receiptId: result.receipt.id, prUrl: PR_URL, headSha: HEAD }),
    ]);
    // The receipt's immediate sweep found CI pending and spent no tick budget.
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(pending()).toEqual([expect.objectContaining({
      prBranch: 'claim/issue-1', sourceAgentId: 'agent-1', ticks: 0,
      handoff: expect.objectContaining({ receiptId: result.receipt.id, headSha: HEAD, prCompletion: 'review-then-merge', reviewStatus: 'clean' }),
    })]);

    // Another run holds repository admission: the coordinator waits without
    // spending its budget and never merges around the lease.
    greenChecks();
    const lease = await claimMergeAdmission({ agentId: 'agent-2', action: 'acquire' });
    expect(lease.admitted).toBe(true);
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ waiting: 1, merged: 0 });
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(pending()[0].ticks).toBe(0);
    await claimMergeAdmission({ agentId: 'agent-2', action: 'release', token: lease.token, outcome: 'merged' });

    // A fresh server process drives the persisted queue entry to a pinned merge.
    vi.resetModules();
    const restarted = await import('./prWatcher.js');
    expect(await restarted.processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 1 });
    expect(mergePrMock).toHaveBeenCalledWith('/repos/source', 7, { forgeAccount: null, expectedHeadSha: HEAD });
    expect(pending()).toEqual([]);
    expect(f.state.agents['agent-1'].metadata.mergeHandoffReceipts[0].coordinatorMergedAt).toEqual(expect.any(String));
  });

  it('marks a receipt coordinator-merged only for its own merge, never for a PR that turned up merged', async () => {
    await handedOff();
    f.pr.state = 'MERGED';
    await processPendingMergePrs(f.apps.get('app1'));
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(f.state.agents['agent-1'].metadata.mergeHandoffReceipts[0].coordinatorMergedAt).toBeUndefined();
  });

  it.each([
    ['an unregistered caller', () => ({ agentId: 'ghost' }), 'handoff-owner-unverified'],
    ['another run\'s branch', () => { f.pr.headRefName = 'claim/issue-2'; }, 'pr-branch-not-owned'],
    ['a PR in another repository', () => ({ prUrl: 'https://github.com/example/other/pull/7' }), 'pr-repository-mismatch'],
    ['a head that moved after review', () => { f.pr.headRefOid = 'b'.repeat(40); }, 'pr-head-moved'],
    ['a checkout not at the handed-off head', () => { f.checkouts[workspace].head = 'c'.repeat(40); }, 'checkout-head-unverified'],
    ['a checkout of another repository', () => { f.foreign.add(workspace); }, 'checkout-head-unverified'],
    ['a draft PR', () => { f.pr.isDraft = true; }, 'pr-draft'],
    ['a leave-open policy', () => { f.tasks['task-agent-1'].metadata.prCompletion = 'leave-open'; }, 'completion-policy-leaves-open'],
    ['a JIRA human handoff', () => { f.tasks['task-agent-1'].metadata.jiraTicketId = 'EX-1'; }, 'completion-policy-leaves-open'],
    ['blocked review evidence', () => writeFile(join(workspace, 'portos-review-status'), 'REVIEW_STATUS=review-blocked\n'), 'review-evidence-incomplete'],
    ['a clean verdict for an earlier head', () => writeFile(join(workspace, 'portos-review-status'), `REVIEW_STATUS=clean\nREVIEW_HEAD=${'f'.repeat(40)}\n`), 'review-evidence-incomplete'],
    ['missing required review evidence', () => rm(join(workspace, 'portos-review-status')), 'review-evidence-incomplete'],
  ])('refuses %s and queues nothing', async (_name, arrange, reason) => {
    const overrides = await arrange();
    expect(await handoff(overrides || {})).toMatchObject({ queued: false, reason, retryable: false });
    expect(pending()).toEqual([]);
  });

  it('accepts original completed pre-PR evidence after feedback pushes only for the bound PR', async () => {
    const oldHead = 'f'.repeat(40);
    await writeFile(join(workspace, 'portos-review-status'), `REVIEW_STATUS=clean\nREVIEW_HEAD=${oldHead}\n`);
    f.delivery = { reusable: true, receipt: { status: 'clean', reviewedHead: oldHead, prUrl: PR_URL } };
    expect((await handoffPendingMerge({ agentId: 'agent-1', prUrl: PR_URL, headSha: HEAD, worktreePath: workspace })).queued).toBe(true);
  });

  it('queues an all-optional roster on a clean status without a REVIEW_HEAD, but not blocked or a required reviewer', async () => {
    f.optionalReviewers = ['codex'];
    await writeFile(join(workspace, 'portos-review-status'), 'REVIEW_STATUS=clean\n');
    expect(await handoff()).toMatchObject({ queued: true });

    await writeFile(join(workspace, 'portos-review-status'), 'REVIEW_STATUS=review-blocked\n');
    expect(await handoff()).toMatchObject({ queued: false, reason: 'review-evidence-incomplete' });

    f.optionalReviewers = [];
    await writeFile(join(workspace, 'portos-review-status'), 'REVIEW_STATUS=clean\n');
    expect(await handoff()).toMatchObject({ queued: false, reason: 'review-evidence-incomplete' });
  });

  it.each(['\n', '\r\n'])('queues current-head optional quota/no-verdict evidence without inventing a clean verdict (line ending %j)', async (newline) => {
    f.optionalReviewers = ['codex'];
    await writeFile(join(workspace, 'portos-review-status'), `REVIEW_STATUS=optional-inconclusive${newline}REVIEW_HEAD=${HEAD}${newline}`);
    expect(await handedOff()).toMatchObject({ queued: true });
    expect(pending()[0].handoff).toMatchObject({ reviewStatus: 'optional-inconclusive', headSha: HEAD });
    greenChecks();
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 1 });
    expect(mergePrMock).toHaveBeenCalledWith('/repos/source', 7, { forgeAccount: null, expectedHeadSha: HEAD });
  });

  it.each([[[]], [['codex', 'claude']]])('refuses optional inconclusive evidence without an all-optional nonempty roster: %j', async (reviewers) => {
    f.reviewers = reviewers;
    f.optionalReviewers = ['codex'];
    await writeFile(join(workspace, 'portos-review-status'), `REVIEW_STATUS=optional-inconclusive\nREVIEW_HEAD=${HEAD}\n`);
    expect(await handoff()).toMatchObject({ queued: false, reason: 'review-evidence-incomplete' });
    expect(pending()).toEqual([]);
  });

  it.each([
    ['a required reviewer', `REVIEW_STATUS=optional-inconclusive\nREVIEW_HEAD=${HEAD}\n`, false],
    ['an earlier attempted head', `REVIEW_STATUS=optional-inconclusive\nREVIEW_HEAD=${'f'.repeat(40)}\n`],
    ['no attempted head', 'REVIEW_STATUS=optional-inconclusive\n'],
    ['a malformed head', 'REVIEW_STATUS=optional-inconclusive\nREVIEW_HEAD=invalid\n'],
    ['an empty duplicate status', `REVIEW_STATUS=optional-inconclusive\nREVIEW_STATUS=\nREVIEW_HEAD=${HEAD}\n`],
    ['duplicate heads', `REVIEW_STATUS=optional-inconclusive\nREVIEW_HEAD=${HEAD}\nREVIEW_HEAD=${HEAD}\n`],
    ['duplicate statuses', `REVIEW_STATUS=optional-inconclusive\nREVIEW_STATUS=clean\nREVIEW_HEAD=${HEAD}\n`],
    ['pending review', `REVIEW_STATUS=pending\nREVIEW_HEAD=${HEAD}\n`],
    ['unresolved findings', `REVIEW_STATUS=findings\nREVIEW_HEAD=${HEAD}\n`],
    ['a required availability block', `REVIEW_STATUS=review-blocked\nREVIEW_HEAD=${HEAD}\n`],
    ['an unspecified inconclusive result', `REVIEW_STATUS=inconclusive\nREVIEW_HEAD=${HEAD}\n`],
    ['empty evidence', ''],
    ['missing evidence', null],
  ])('refuses optional handoff with %s', async (_name, evidence, optional = true) => {
    f.optionalReviewers = optional ? ['codex'] : [];
    if (evidence === null) await rm(join(workspace, 'portos-review-status'));
    else await writeFile(join(workspace, 'portos-review-status'), evidence);
    expect(await handoff()).toMatchObject({ queued: false, reason: 'review-evidence-incomplete' });
    expect(pending()).toEqual([]);
    expect(mergePrMock).not.toHaveBeenCalled();
  });

  it('keeps an already-green PR with its original owner for immediate merge', async () => {
    greenChecks();
    expect(await handoff()).toMatchObject({ queued: false, reason: 'pr-not-waiting-on-healthy-ci' });
    expect(pending()).toEqual([]);
    expect(mergePrMock).not.toHaveBeenCalled();
  });

  it.each(['leave-open', 'draft', 'readOnly', 'blocked'])('honors a live coordinator %s hold after CI turns green', async hold => {
    await handedOff();
    greenChecks();
    // Change the owner during the final contribution read, proving that a
    // policy snapshot taken before remote assessment cannot authorize merge.
    const read = execGhMock.getMockImplementation();
    execGhMock.mockImplementation(async (...args) => {
      if (args[0][0] === 'pr' && args[0][1] === 'diff') {
        const task = f.tasks['task-agent-1'];
        if (hold === 'blocked') task.status = 'blocked';
        else if (hold === 'readOnly') task.metadata.readOnly = true;
        else task.metadata.prCompletion = hold;
      }
      return read(...args);
    });
    await processPendingMergePrs(f.apps.get('app1'));
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(pending()[0].recoveryBlocked).toEqual(expect.any(String));
    await processPendingMergePrs(f.apps.get('app1'));
    expect(notifyMock).toHaveBeenCalledTimes(1);
    expect(followUpMock).not.toHaveBeenCalled();
  });

  it('defers an unreadable coordinating task without losing its receipt or retry budget', async () => {
    await handedOff();
    greenChecks();
    const task = f.tasks['task-agent-1'];
    delete f.tasks['task-agent-1'];
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ waiting: 1, merged: 0 });
    expect(pending()[0]).toMatchObject({ ticks: 0 });
    expect(mergePrMock).not.toHaveBeenCalled();
    f.tasks['task-agent-1'] = task;
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 1 });
    expect(pending()).toEqual([]);
  });

  it('does not transfer a human-held original claim to a new recovery task after CI fails', async () => {
    await handedOff();
    f.tasks['task-agent-1'].metadata.prCompletion = 'leave-open';
    f.pr.statusCheckRollup = [{ conclusion: 'FAILURE' }];
    await processPendingMergePrs(f.apps.get('app1'));
    expect(followUpMock).not.toHaveBeenCalled();
    expect(pending()[0].recoveryBlocked).toEqual(expect.any(String));
    greenChecks();
    await processPendingMergePrs(f.apps.get('app1'));
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(notifyMock).toHaveBeenCalledTimes(1);
  });

  it('keeps merged cleanup owned and bounded after an archival refusal, without holding merge admission', async () => {
    cleanupMock.mockImplementation(async () => {
      expect(Object.keys(f.state.mergeAdmissions)).toHaveLength(0);
      return { ok: false, reason: 'retirement-forge-unreadable' };
    });
    await handedOff();
    greenChecks();
    await processPendingMergePrs(f.apps.get('app1'));
    expect(pending()[0]).toMatchObject({ cleanup: { status: 'pending', attempts: 1, reason: 'retirement-forge-unreadable' } });
    f.pr.state = 'MERGED';
    await processPendingMergePrs(f.apps.get('app1'));
    expect(cleanupMock).toHaveBeenCalledTimes(1);
    // A process restart retains the retry time and the exact cleanup target.
    vi.resetModules();
    await (await import('./prWatcher.js')).processPendingMergePrs(f.apps.get('app1'));
    expect(cleanupMock).toHaveBeenCalledTimes(1);
    const app = f.apps.get('app1');
    app.pendingMergePrs[0].cleanup.retryAt = 0;
    cleanupMock.mockResolvedValue({ ok: true, branchDeleted: true, archiveDir: '/archives/example' });
    await (await import('./prWatcher.js')).processPendingMergePrs(app);
    expect(pending()).toEqual([]);
  });

  it.each(['pr-completion-human-handoff', 'retirement-submodule-not-uninitialized'])('holds merged cleanup requiring explicit recovery: %s', async reason => {
    cleanupMock.mockResolvedValue({ ok: false, reason });
    await handedOff();
    greenChecks();
    await processPendingMergePrs(f.apps.get('app1'));
    expect(pending()[0].cleanup).toMatchObject({ status: 'held', reason });
    f.pr.state = 'MERGED';
    pending()[0].cleanup.retryAt = 0;
    await processPendingMergePrs(f.apps.get('app1'));
    expect(cleanupMock).toHaveBeenCalledTimes(1);
    expect(pending()).toHaveLength(1);
  });

  it('rechecks the queue after an overlapping sweep that read it before the receipt', async () => {
    let releaseRead;
    const blocked = new Promise((resolve) => { releaseRead = resolve; });
    const other = { ...f.pr, number: 8, headRefName: 'cos/other', headRefOid: 'b'.repeat(40), statusCheckRollup: [{ status: 'IN_PROGRESS' }] };
    const forge = execGhMock.getMockImplementation();
    execGhMock.mockImplementation(async (args) => (args[0] === 'pr' && args[1] === 'view' && args[2] === '8'
      ? blocked.then(() => JSON.stringify(other)) : forge(args)));
    f.apps.set('app1', { ...f.apps.get('app1'), pendingMergePrs: [{
      prUrl: 'https://github.com/example/repo/pull/8', prNumber: 8, prBranch: 'cos/other', ticks: 0,
      sourceTask: { id: 'task-other', priority: 'MEDIUM', description: 'Other change', metadata: { app: 'app1' } },
    }] });

    // The live module instance, the one the handoff's receipt sweep joins.
    const timer = (await import('./prWatcher.js')).processPendingMergePrs(f.apps.get('app1'));
    expect(await handoff()).toMatchObject({ queued: true });
    greenChecks();
    releaseRead();
    await timer;
    await vi.waitFor(() => expect(mergePrMock).toHaveBeenCalledWith('/repos/source', 7, { forgeAccount: null, expectedHeadSha: HEAD }));
    expect(pending().map((entry) => entry.prNumber)).toEqual([8]);
  });

  it('reports a queued receipt only for the exact handed-off PR, branch and head', async () => {
    await handedOff();
    const target = { prUrl: 'https://GitHub.com/Example/Repo/pull/7', prBranch: 'claim/issue-1', headSha: HEAD.toUpperCase() };
    expect(await hasQueuedMergeHandoff(target)).toBe(true);
    expect(await hasQueuedMergeHandoff({ ...target, headSha: 'b'.repeat(40) })).toBe(false);
    expect(await hasQueuedMergeHandoff({ ...target, prBranch: 'claim/issue-2' })).toBe(false);
    expect(await hasQueuedMergeHandoff({ ...target, prUrl: 'https://github.com/example/other/pull/7' })).toBe(false);
  });

  it('accepts a merge-on-green run with no local reviewers', async () => {
    f.tasks['task-agent-1'].metadata.prCompletion = 'merge-on-green';
    await rm(join(workspace, 'portos-review-status'));
    expect(await handedOff()).toMatchObject({ queued: true });
    expect(pending()[0]).toMatchObject({ handoff: { reviewStatus: 'not-configured', prCompletion: 'merge-on-green' }, followUp: { reviewers: [] } });
  });

  it('invalidates a binding whose head moved and dispatches the recorded review policy instead of merging', async () => {
    await handedOff();
    f.tasks['task-agent-1'].status = 'completed';
    f.pr.headRefOid = 'd'.repeat(40);
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 0, escalated: 1, invalidated: 1 });
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(followUpMock).toHaveBeenCalledWith(expect.objectContaining({
      prUrl: PR_URL, prBranch: 'claim/issue-1', prCompletion: 'review-then-merge', reviewers: ['codex'],
    }));
    expect(pending()).toEqual([]);
  });

  it('withholds the merge when the head moves inside the admission window', async () => {
    await handedOff();
    greenChecks();
    const views = [{ ...f.pr }, { ...f.pr, headRefOid: 'e'.repeat(40) }];
    const forge = execGhMock.getMockImplementation();
    execGhMock.mockImplementation(async (args) => (args[0] === 'pr' && args[1] === 'view'
      ? JSON.stringify(views.length > 1 ? views.shift() : views[0]) : forge(args)));
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 0 });
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(pending()).toEqual([expect.objectContaining({ ticks: 1, handoff: expect.objectContaining({ headSha: HEAD }) })]);
  });

  it('keeps the head binding when an unbound duplicate is queued for the same PR', async () => {
    await handedOff();
    const { queuePendingMerge } = await import('./prWatcher.js');
    const { handoff: _binding, followUp: _roster, ...unbound } = pending()[0];
    expect(await queuePendingMerge('app1', unbound)).toBe(true);
    expect(pending()[0].handoff).toMatchObject({ headSha: HEAD });
  });

  it('never merges an unreadable binding and hands it to the operator', async () => {
    await handedOff();
    f.apps.set('app1', { ...f.apps.get('app1'), pendingMergePrs: [{ ...pending()[0], handoff: { headSha: 'not-a-sha' } }] });
    expect(await processPendingMergePrs(f.apps.get('app1'))).toMatchObject({ merged: 0, invalidated: 1 });
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(notifyMock).toHaveBeenCalledWith(expect.objectContaining({ link: PR_URL, priority: 'high' }));
    expect(pending()[0].recoveryBlocked).toBe('handoff-binding-unreadable');
  });
});

// A receipt whose CI is still running gets a bounded follow-up poll instead of
// waiting up to a whole 30-minute timer interval after CI turns green.
describe('handoff follow-up poll', () => {
  let gate;
  let prWatcher;
  // setImmediate stays real: it drains the poll's promise chain between ticks.
  const settle = async () => { for (let i = 0; i < 50; i++) await new Promise((r) => setImmediate(r)); };
  const forgeViews = () => execGhMock.mock.calls.filter(([args]) => args[0] === 'pr' && args[1] === 'view').length;
  const minutes = (n) => vi.advanceTimersByTimeAsync(n * 60 * 1000).then(settle);

  // The coordinator's lazy imports load from disk, which a setImmediate drain
  // does not wait for; warm them so a fresh worker settles like a warm one.
  beforeAll(() => Promise.all(['./prReviewerSecurity.js', './pendingMergeGuard.js', '../lib/validation.js'].map((m) => import(m))));

  beforeEach(async () => {
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
    prWatcher = await import('./prWatcher.js');
    gate = vi.fn(async () => null);
    prWatcher.setHandoffFollowUpGate(gate);
    vi.spyOn(console, 'log').mockImplementation(() => {});
    vi.spyOn(console, 'warn').mockImplementation(() => {});
    vi.spyOn(console, 'error').mockImplementation(() => {});
  });

  afterEach(() => {
    prWatcher.cancelHandoffFollowUps();
    // Spies first: one captured under fake timers must not outlive them.
    vi.restoreAllMocks();
    vi.useRealTimers();
  });

  const handOffPending = async () => {
    const result = await handoff();
    await settle();
    return result;
  };

  it('polls a pending head, merges it once CI turns green, then stops', async () => {
    await handOffPending();
    expect(vi.getTimerCount()).toBe(1);
    expect(mergePrMock).not.toHaveBeenCalled();

    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(vi.getTimerCount()).toBe(1);

    greenChecks();
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(mergePrMock).toHaveBeenCalledWith('/repos/source', 7, { forgeAccount: null, expectedHeadSha: HEAD });
    expect(pending()).toEqual([]);
    expect(vi.getTimerCount()).toBe(0);
    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('every handed-off entry settled'));
  });

  it('never arms when the immediate pass already merged', async () => {
    greenChecks();
    await handOffPending();
    expect(mergePrMock).not.toHaveBeenCalled();
    expect(vi.getTimerCount()).toBe(0);
  });

  it('extends the active poller for a second receipt instead of arming another timer', async () => {
    const first = await handOffPending();
    const second = await handOffPending();
    expect(second.receipt.id).not.toBe(first.receipt.id);
    expect(vi.getTimerCount()).toBe(1);

    greenChecks();
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(mergePrMock).toHaveBeenCalledTimes(1);
    expect(vi.getTimerCount()).toBe(0);
  });

  it('backs off, spends no tick budget, and hands back to the timer sweep at the cap', async () => {
    await handOffPending();
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_FAST_POLLS);
    const fastReads = forgeViews();
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_BACKOFF_MS / 60000 / 2);
    expect(forgeViews()).toBe(fastReads);

    await minutes(prWatcher.HANDOFF_FOLLOW_UP_CAP_MS / 60000);
    expect(vi.getTimerCount()).toBe(0);
    expect(pending()).toEqual([expect.objectContaining({ ticks: 0 })]);
    // Handing back to the timer sweep at the cap is the designed bounded wait, not a fault: stdout.
    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('the timer sweep owns 1 entry'));
    expect(console.warn).not.toHaveBeenCalled();
    const finalReads = forgeViews();
    await minutes(60);
    expect(forgeViews()).toBe(finalReads);
  });

  it('skips a poll the daemon gate blocks without reading the forge', async () => {
    await handOffPending();
    const reads = forgeViews();
    gate.mockResolvedValue('daemon paused');
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(forgeViews()).toBe(reads);
    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('skipped: daemon paused'));
    expect(console.warn).not.toHaveBeenCalled();
    expect(vi.getTimerCount()).toBe(1);
  });

  it('stops when the daemon stops', async () => {
    const armed = await handOffPending();
    const reads = forgeViews();
    prWatcher.cancelHandoffFollowUps();
    expect(vi.getTimerCount()).toBe(0);
    await minutes(10);
    expect(forgeViews()).toBe(reads);

    // A receipt while the daemon is stopped leaves the entry to the timer sweep.
    await handOffPending();
    expect(vi.getTimerCount()).toBe(0);
    // Declining to arm is the designed handoff to the timer sweep: stdout, not stderr.
    await prWatcher.followUpHandoffReceipt('app1', armed.receipt.id);
    expect(vi.getTimerCount()).toBe(0);
    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('not armed: CoS daemon is stopped'));
    expect(console.warn).not.toHaveBeenCalled();
  });

  it('owns a throwing poll and keeps polling', async () => {
    await handOffPending();
    const read = f.apps.get.bind(f.apps);
    f.apps.get = () => { throw new Error('apps store unreadable'); };
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(console.error).toHaveBeenCalledWith(expect.stringContaining('apps store unreadable'));
    expect(vi.getTimerCount()).toBe(1);

    f.apps.get = read;
    greenChecks();
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(mergePrMock).toHaveBeenCalledTimes(1);
    expect(vi.getTimerCount()).toBe(0);
  });

  // Both ends of the bounded wait hand the entry to the timer sweep: designed, so stdout.
  it('drops the poll without a fault when the gate reports the daemon stopped', async () => {
    await handOffPending();
    gate.mockResolvedValue('daemon-stopped');
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_INTERVAL_MS / 60000);
    expect(vi.getTimerCount()).toBe(0);
    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('stopped: CoS daemon is stopped'));
    expect(console.warn).not.toHaveBeenCalled();
  });

  it('hands a poll that keeps throwing back to the timer sweep at the cap, logging each throw as an error', async () => {
    await handOffPending();
    f.apps.get = () => { throw new Error('apps store unreadable'); };
    await minutes(prWatcher.HANDOFF_FOLLOW_UP_CAP_MS / 60000 + prWatcher.HANDOFF_FOLLOW_UP_BACKOFF_MS / 60000);
    expect(vi.getTimerCount()).toBe(0);
    expect(console.error).toHaveBeenCalledWith(expect.stringContaining('apps store unreadable'));
    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('reached its cap; the timer sweep owns its entries'));
    expect(console.warn).not.toHaveBeenCalled();
  });
});