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

65.3 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from 'vitest';

import { mkdir, rm, writeFile, readFile, mkdtemp, rename } from 'fs/promises';
import { tmpdir } from 'node:os';
import { existsSync } from 'fs';
import { join } from 'path';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy, ownTestBodies } from '../lib/mockPathsDataRoot.js';

const mockCosState = vi.hoisted(() => ({
  // Use $TMPDIR (falls back to /tmp) rather than a hardcoded /private/tmp — the
  // latter exists on macOS (where /tmp symlinks to it) but not on Linux CI,
  // where `mkdir(recursive)` then tries to create `/private` at the root and
  // hits EACCES. process.env is safe to read inside a vi.hoisted factory
  // (imported bindings like `os.tmpdir` are not yet initialized at hoist time).
  agentsDir: `${process.env.TMPDIR || process.env.TEMP || process.env.TMP || '/tmp'}/portos-cos-agents-test-${process.pid}`,
  state: null
}));

vi.mock('./cosState.js', () => ({
  AGENTS_DIR: mockCosState.agentsDir,
  loadState: vi.fn(async () => mockCosState.state),
  saveState: vi.fn(),
  withStateLock: async (fn) => fn(),
  // The uncached, non-defaulting read the update gate uses. Defaults to
  // "trusted, and these are the records"; one test drives the untrusted answer.
  readAgentsStateForSafetyCheck: vi.fn(async () => ({ trusted: true, agents: mockCosState.state?.agents ?? {} })),
}));

vi.mock('./branchCompletionPolicy.js', () => ({ readBranchCompletionPolicies: vi.fn(async () => Object.values(mockCosState.state?.agents || {})) }));
const recoveryTasks = vi.hoisted(() => new Map());
vi.mock('./cosTaskStore.js', () => ({
  getTaskById: vi.fn(async id => recoveryTasks.get(id) || null),
  getTaskView: vi.fn(async () => ({ user: { tasks: [...recoveryTasks.values()] }, cos: { tasks: [] } })),
}));

vi.mock('./domainUsage.js', () => ({
  recordDomainUsage: vi.fn(async () => {})
}));

vi.mock('./completedCheckoutEvidence.js', async original => ({ ...await original(), captureCompletedCheckouts: vi.fn(async () => []), captureCheckoutSeeds: vi.fn(async () => [{ synthetic: true }]) }));

// Pass-through fs shim with opt-in failure injection, so one test can force the
// archive's cross-filesystem fallback AND a failure partway through its copy.
// Scoped to paths inside a `YYYY-MM-DD` bucket so the flat-dir writes that
// precede the move still succeed. Off for every other test in this file.
const fsFailures = vi.hoisted(() => ({ dateBucketWritesFail: false, rmFailsFor: null }));

vi.mock('fs/promises', async (importOriginal) => {
  const actual = await importOriginal();
  const { relative } = await import('node:path');
  // Accept either separator: the archive path is composed with path.join, so on
  // Windows the date bucket reads '\2026-08-14\' and a '/'-only pattern never
  // matched — the injected failure never fired and completeAgent RESOLVED,
  // making this rollback test assert nothing.
  const failsFor = (p) => {
    const target = relative(mockCosState.agentsDir, String(p));
    return fsFailures.dateBucketWritesFail && /^\d{4}-\d{2}-\d{2}[\\/]/.test(target);
  };
  return {
    ...actual,
    rename: async (from, to, ...rest) => {
      if (failsFor(to)) throw Object.assign(new Error('EXDEV: cross-device link'), { code: 'EXDEV' });
      return actual.rename(from, to, ...rest);
    },
    // Opt-in: rm of any path containing `fsFailures.rmFailsFor` rejects (EBUSY),
    // so deleteAgent's directory cleanup failure can be observed.
    rm: async (target, ...rest) => {
      if (fsFailures.rmFailsFor && String(target).includes(fsFailures.rmFailsFor)) {
        throw Object.assign(new Error('EBUSY: resource busy or locked'), { code: 'EBUSY' });
      }
      return actual.rm(target, ...rest);
    },
    // The archive fallback copies with `cp`; the destination dir is created
    // before the failure so the rollback has a half-copied target to remove.
    cp: async (from, to, ...rest) => {
      if (failsFor(to)) {
        await actual.mkdir(to, { recursive: true });
        throw new Error('simulated copy failure');
      }
      return actual.cp(from, to, ...rest);
    }
  };
});

vi.mock('./cosRunnerClient.js', () => ({
  getActiveAgentsFromRunner: vi.fn().mockResolvedValue([]),
  requestSecurityScanViaRunner: vi.fn(),
}));

// `deleteAgent` / `completeAgent` route through `withBackupAssetPublication`,
// whose admission lease lives under `PATHS.data` (lib/backupSharedAdmission.js).
// Redirect PATHS so that lease is minted in an OS temp dir. Without it, a
// checkout nested under the install's `data/` (a CoS claim worktree) resolves
// `PATHS.data` to its own `data/`, and the real-data write guard refuses the
// admission write. The temp root is lazy because this file imports its SUT
// statically and `vi.mock` is hoisted above any `const` here.
vi.mock('../lib/paths.js', async (importOriginal) => makePathsProxy(await importOriginal(), {
  dataRoot: () => lazyTempDataRoot('portos-cos-lifecycle-'),
}));

import { getAgent, getAgentPrompt, createAgentOutputBatcher, completeAgent, recordCompletionCleanup, retryCompletionCheckoutCapture, recordRepoStateVerification, reserveRepoCleanupRecovery, recordRepoCleanupRecovery, recordCleanupOutcome, updateAgent, registerAgent, cleanupZombieAgents, filterLiveAgentIds, readAgentRecordOrUnreadable, deleteAgent, AGENT_RECORD_UNREADABLE, AGENT_OUTPUT_TAIL_LINES } from './cosAgentLifecycle.js';
import { saveState, loadState, readAgentsStateForSafetyCheck } from './cosState.js';
import { recordDomainUsage } from './domainUsage.js';
import { cosEvents } from './cosEvents.js';
import { loadAgentIndex } from './cosAgentIndex.js';
import { maintenance } from '../lib/maintenanceAdmission.js';
import { getActiveAgentsFromRunner, requestSecurityScanViaRunner } from './cosRunnerClient.js';
import { persistAgentSecurityScan } from './agentSecurityScan.js';
import { captureCompletedCheckouts, captureCheckoutSeeds, completedCheckoutReceiptValid } from './completedCheckoutEvidence.js';
import { materializeGitRepo } from '../lib/gitTestRepo.js';
import { execGit } from '../lib/execGit.js';
import { activeAgents, runnerAgents, completingAgents, spawningTasks } from './agentState.js';

afterAll(cleanupTempDataRoots);

describe('cosAgentLifecycle', () => {
  beforeEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    await mkdir(mockCosState.agentsDir, { recursive: true });
    mockCosState.state = { agents: {} };
    vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([]);
    activeAgents.clear();
    runnerAgents.clear();
  });

  afterEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
  });

  it('bounds original-parent recoveries across 70 scans, evidence cycles, active ownership and restart', async () => {
    const id = 'agent-recovery-history';
    mockCosState.state.agents[id] = { id, status: 'completed', completedAt: '2026-01-01T00:00:00Z', metadata: {} };
    expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'A')).toMatchObject({ admitted: true, attempt: 1 });
    for (let i = 0; i < 70; i++) expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'B')).toMatchObject({ admitted: false, reason: 'cleanup-publication-unverified' });
    await recordRepoCleanupRecovery(id, 'claim/one', 'A', { phase: 'dispatched', taskId: 'successor-1' });
    recoveryTasks.set('successor-1', { status: 'in_progress' });
    expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'B')).toMatchObject({ admitted: false, reason: 'cleanup-successor-owned' });
    recoveryTasks.set('successor-1', { status: 'completed' });
    expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'B')).toMatchObject({ admitted: true, attempt: 2 });
    await recordRepoCleanupRecovery(id, 'claim/one', 'B', { phase: 'dispatched', taskId: 'successor-2' });
    recoveryTasks.set('successor-2', { status: 'completed' });
    // Reconstruct persisted state; neither the old parent's empty recoveryOrigin
    // nor a process restart resets this history or the total attempt budget.
    mockCosState.state = JSON.parse(JSON.stringify(mockCosState.state));
    for (let i = 0; i < 70; i++) expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'A')).toMatchObject({ admitted: false, reason: 'cleanup-observation-already-attempted' });
    expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'C')).toMatchObject({ admitted: true, attempt: 3 });
    await recordRepoCleanupRecovery(id, 'claim/one', 'C', { phase: 'dispatched', taskId: 'successor-3' });
    recoveryTasks.set('successor-3', { status: 'completed' });
    expect(await reserveRepoCleanupRecovery(id, 'claim/one', 'D')).toMatchObject({ admitted: false, reason: 'cleanup-cognitive-budget-exhausted' });
    expect(mockCosState.state.agents[id].metadata.repoCleanupRecoveries['claim/one'].observations).toEqual(['A', 'B', 'C']);
  });

  it.each(['automatic-retirement-paused', 'review-obligation-changed'])('resumes known-unexecuted %s deferrals without resetting real attempts', async reason => {
    const id = 'agent-deferred-review';
    mockCosState.state.agents[id] = { id, status: 'completed', metadata: {} };
    expect(await reserveRepoCleanupRecovery(id, 'fix/work', 'prior')).toMatchObject({ admitted: true, attempt: 1 });
    await recordRepoCleanupRecovery(id, 'fix/work', 'prior', { phase: 'dispatched', taskId: 'completed-review' });
    recoveryTasks.set('completed-review', { status: 'completed' });
    for (let i = 0; i < 70; i++) {
      expect(await reserveRepoCleanupRecovery(id, 'fix/work', 'current')).toMatchObject({ admitted: true, attempt: 2 });
      await recordRepoCleanupRecovery(id, 'fix/work', 'current', { phase: 'blocked-before-dispatch', taskId: null, reason });
      mockCosState.state = JSON.parse(JSON.stringify(mockCosState.state));
    }
    expect(mockCosState.state.agents[id].metadata.repoCleanupRecoveries['fix/work']).toMatchObject({ attempt: 1, observations: ['prior'] });
    expect(await reserveRepoCleanupRecovery(id, 'fix/work', 'prior')).toMatchObject({ admitted: false, reason: 'cleanup-observation-already-attempted' });
    expect(await reserveRepoCleanupRecovery(id, 'fix/work', 'current')).toMatchObject({ admitted: true, attempt: 2 });
    await recordRepoCleanupRecovery(id, 'fix/work', 'current', { phase: 'dispatched', taskId: 'active-review' });
    recoveryTasks.set('active-review', { status: 'in_progress' });
    expect(await reserveRepoCleanupRecovery(id, 'fix/work', 'changed')).toMatchObject({ admitted: false, reason: 'cleanup-successor-owned' });
  });

  it('replaces provisional owner holds when the original checkout completes without hiding other paths', async () => {
    const id = 'agent-owner-completion';
    mockCosState.state.agents[id] = { id, status: 'completed', metadata: {} };
    await recordCleanupOutcome(id, { branch: 'claim/one', status: 'blocked', reason: 'owner-active' });
    await recordCleanupOutcome(id, { branch: 'claim/other', path: '/example/other', status: 'blocked', reason: 'archive-unavailable' });
    await recordCleanupOutcome(id, { branch: 'claim/one', path: '/example/original', status: 'verified', reason: 'retirement-receipt-verified' });
    expect(mockCosState.state.agents[id].metadata.cleanupOutcome).toMatchObject({ status: 'blocked', total: 2, unresolved: 1, branch: 'claim/other' });
    await recordCleanupOutcome(id, { branch: 'claim/other', path: '/example/new-incarnation', status: 'verified', reason: 'retirement-receipt-verified' });
    expect(mockCosState.state.agents[id].metadata.cleanupOutcome).toMatchObject({ status: 'blocked', total: 3, unresolved: 1 });
    await recordCleanupOutcome(id, { branch: 'claim/other', path: '/example/other', status: 'verified', reason: 'retirement-receipt-verified' });
    expect(mockCosState.state.agents[id].metadata.cleanupOutcome).toMatchObject({ status: 'verified', unresolved: 0 });
  });

  it.each([true, false])('aggregates every branch outcome independently of update order (%s)', async reversed => {
    const id = 'agent-swarm-outcome';
    mockCosState.state.agents[id] = { id, status: 'completed', metadata: {} };
    const rows = [{ branch: 'claim/blocked', path: '/example/blocked', status: 'blocked', reason: 'checkout-incarnation-changed' },
      { branch: 'claim/verified', path: '/example/verified', status: 'verified', reason: 'retirement-receipt-verified' }];
    for (const row of reversed ? rows.reverse() : rows) await recordCleanupOutcome(id, row);
    expect(mockCosState.state.agents[id].metadata.cleanupOutcome).toMatchObject({ status: 'blocked', unresolved: 1, total: 2 });
    expect(Object.values(mockCosState.state.agents[id].metadata.cleanupOutcomes)).toHaveLength(2);
  });

  it('archives interrupted audit findings before removing their workspace and reloads them after live retention', async () => {
    const { settleAuditFindings } = await import('./auditFindings.js');
    const workspace = join(mockCosState.agentsDir, 'audit-workspace');
    await mkdir(workspace);
    mockCosState.state.stats = { agentsSpawned: 0, agentsCompleted: 0, agentsFailed: 0 };
    await registerAgent('agent-disposition', 'task-example', { taskAnalysisType: 'security', auditDispositionVersion: 1 });
    const report = { version: 1, findings: [{ key: 'example-authority', title: 'Example boundary', path: 'server/routes/example.js',
      severity: 8, confidence: 'high', classification: 'actionable', evidence: 'Synthetic mounted route bypass.',
      disposition: { kind: 'unresolved', reason: 'Tracker unavailable.' } }] };
    await writeFile(join(workspace, '.agent-audit-findings-agent-disposition.json'), JSON.stringify(report));
    const disposition = await settleAuditFindings({ agentId: 'agent-disposition', workspacePath: workspace,
      task: { metadata: { auditDispositionVersion: '1', analysisType: 'security' } } });
    await completeAgent('agent-disposition', { success: false, auditDisposition: disposition });
    await rm(workspace, { recursive: true });
    delete mockCosState.state.agents['agent-disposition'];
    const archived = await getAgent('agent-disposition');
    expect(archived.metadata.auditFindings.report).toEqual(report);
    expect(archived.result.auditDisposition.status).toBe('incomplete');
  });

  it('keeps trusted terminal scanner receipts across stale reconnects, agent claims and missing completion', async () => {
    mockCosState.state.stats = { agentsSpawned: 0, agentsCompleted: 0, agentsFailed: 0 };
    await registerAgent('agent-scanner', 'task-example', { taskAnalysisType: 'security', useRunner: true });
    const evidence = { version: 1, source: 'runner', sequence: 3, status: 'refused', model: 'example-model', effort: 'medium', auth: 'chatgpt',
      maxCostUsd: 2, estimatedCostUsd: null, timeLimitSeconds: 180, exitCode: 143,
      artifacts: { findings: false, coverage: false }, cleanup: 'confirmed',
      preflight: { rejectedRequests: 1, lastError: { field: 'paths', index: 0, code: 'path-not-found' } } };
    await persistAgentSecurityScan('agent-scanner', { ...evidence, sequence: 1, status: 'invalid-input', exitCode: null, cleanup: 'not-needed' });
    expect((await getAgent('agent-scanner')).metadata.securityScan).toMatchObject({ status: 'invalid-input', preflight: evidence.preflight });
    await persistAgentSecurityScan('agent-scanner', evidence);
    await persistAgentSecurityScan('agent-scanner', { ...evidence, sequence: 2, status: 'running', exitCode: null });
    await updateAgent('agent-scanner', { metadata: { securityScan: { ...evidence, source: 'agent-report', status: 'completed', exitCode: 0 } } });
    vi.mocked(requestSecurityScanViaRunner).mockResolvedValue({ evidence });
    await completeAgent('agent-scanner', { success: true });
    const agent = await getAgent('agent-scanner');
    expect(agent.metadata.securityScan).toEqual(evidence);
    expect(agent.metadata.executionInterruption.category).toBe('content-refusal');
    expect(agent.result.success).toBe(false);
    expect(agent.result.error).toContain('safety refusal');
  });

  it('records uncertain cleanup if the runner disappears before outer completion', async () => {
    mockCosState.state.stats = { agentsSpawned: 0, agentsCompleted: 0, agentsFailed: 0 };
    await registerAgent('agent-scanner', 'task-example', { taskAnalysisType: 'security', useRunner: true });
    await persistAgentSecurityScan('agent-scanner', { version: 1, source: 'runner', sequence: 3, status: 'running', model: 'example-model', effort: 'medium', auth: 'chatgpt',
      maxCostUsd: 2, estimatedCostUsd: null, timeLimitSeconds: 180, exitCode: null,
      artifacts: { findings: null, coverage: null }, cleanup: 'unconfirmed' });
    vi.mocked(requestSecurityScanViaRunner).mockRejectedValue(new Error('synthetic runner loss'));
    await completeAgent('agent-scanner', { success: false, error: 'Terminated' });
    expect((await getAgent('agent-scanner')).metadata).toMatchObject({ securityScan: { sequence: 3, status: 'running', exitCode: null }, securityScanControl: { status: 'interrupted', cleanup: 'unconfirmed' } });
    const observed = (await getAgent('agent-scanner')).metadata.securityScan;
    await persistAgentSecurityScan('agent-scanner', { ...observed, sequence: 2, status: 'invalid-input', cleanup: 'not-needed',
      preflight: { rejectedRequests: 1, lastError: { field: 'paths', index: 0, code: 'path-not-found' } } });
    expect((await getAgent('agent-scanner')).metadata).toMatchObject({ securityScan: { sequence: 3, status: 'running' }, securityScanControl: { status: 'interrupted', cleanup: 'unconfirmed' } });
    await persistAgentSecurityScan('agent-scanner', { ...observed, sequence: 4, status: 'refused', exitCode: 143, cleanup: 'confirmed' });
    expect((await getAgent('agent-scanner')).metadata).toMatchObject({ securityScan: { status: 'refused', cleanup: 'confirmed' }, securityScanControl: null });
  });

  it('keeps archived prompts readable after state eviction, with UTF-8 byte counts', async () => {
    const id = 'agent-archived-prompt';
    const date = '2026-01-01';
    const dir = join(mockCosState.agentsDir, date, id);
    await mkdir(dir, { recursive: true });
    await writeFile(join(dir, 'metadata.json'), JSON.stringify({ id, status: 'completed', completedAt: `${date}T12:00:00Z` }));
    await writeFile(join(dir, 'prompt.txt'), 'Example café');
    (await loadAgentIndex()).set(id, date);
    await expect(getAgentPrompt(id)).resolves.toEqual({ prompt: 'Example café', bytes: Buffer.byteLength('Example café') });
  });

  it('hydrates paused agents with full preserved output from output.txt', async () => {
    const agentId = 'agent-paused';
    const pausedAt = '2026-05-25T12:00:00.000Z';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'paused',
      pausedAt,
      output: [{ line: 'state tail only', timestamp: pausedAt }]
    };

    await mkdir(join(mockCosState.agentsDir, agentId), { recursive: true });
    await writeFile(join(mockCosState.agentsDir, agentId, 'output.txt'), 'full line one\nfull line two\n');

    const agent = await getAgent(agentId);

    expect(agent.status).toBe('paused');
    expect(agent.output).toEqual([
      { line: 'full line one', timestamp: pausedAt },
      { line: 'full line two', timestamp: pausedAt }
    ]);
    expect(agent.outputTruncated).toBe(false);
  });

  // The predicate behind the "CoS agents running" update gate. Its whole job is
  // to keep the two failure directions apart: a tracked id whose run PortOS has
  // already finalized must not block a restart forever, and a genuinely live one
  // must still block it.
  it('narrows tracked ids to live records, dropping finalized and unknown ones', async () => {
    mockCosState.state.agents = {
      'agent-running': { id: 'agent-running', status: 'running' },
      // A paused agent is still owed a resume, so its record stays live.
      'agent-paused': { id: 'agent-paused', status: 'paused' },
      'agent-done': { id: 'agent-done', status: 'completed', completedAt: '2026-05-25T12:00:00.000Z' }
    };

    await expect(filterLiveAgentIds([
      'agent-running', 'agent-running', 'agent-paused', 'agent-done', 'agent-archived-away'
    ])).resolves.toEqual(['agent-running', 'agent-paused']);
    await expect(filterLiveAgentIds([])).resolves.toEqual([]);
  });

  // The gate this feeds authorizes a pm2 restart that severs live agents, so an
  // unreadable state file must not read as "nothing is running". `loadState`
  // substitutes an EMPTY default state for a corrupt file — trusting that would
  // hand the gate a confident zero and restart PortOS out from under whatever
  // was live.
  it('treats every tracked id as live when the records cannot be established', async () => {
    vi.mocked(readAgentsStateForSafetyCheck).mockResolvedValueOnce({ trusted: false, agents: null });

    await expect(filterLiveAgentIds(['agent-a', 'agent-b']))
      .resolves.toEqual(['agent-a', 'agent-b']);
  });

  // "The read failed" and "there is no such record" lead to opposite decisions —
  // one leaves live tracking alone, the other retires it — so the reader must
  // never let an I/O failure arrive as a plain null.
  it('reports an unreadable record as its own sentinel, not as an absent one', async () => {
    mockCosState.state.agents = { 'agent-running': { id: 'agent-running', status: 'running' } };

    await expect(readAgentRecordOrUnreadable('agent-running'))
      .resolves.toMatchObject({ id: 'agent-running' });
    await expect(readAgentRecordOrUnreadable('agent-never-existed')).resolves.toBeNull();

    loadState.mockRejectedValueOnce(new Error('state.json unreadable'));
    await expect(readAgentRecordOrUnreadable('agent-running'))
      .resolves.toBe(AGENT_RECORD_UNREADABLE);
  });

  // #3498: output.txt is unbounded — a long TUI run writes tens of MB. Reading it
  // whole and mapping EVERY line to an object spiked heap on a single request.
  describe('transcript tail caps (#3498)', () => {
    const writeCompleted = async (agentId, completedAt, contents) => {
      mockCosState.state.agents[agentId] = { id: agentId, status: 'completed', completedAt, metadata: {}, output: [] };
      const dir = join(mockCosState.agentsDir, completedAt.slice(0, 10), agentId);
      await mkdir(dir, { recursive: true });
      await writeFile(join(dir, 'output.txt'), contents);
      return dir;
    };

    it('returns only the tail lines and flags the transcript as truncated', async () => {
      const completedAt = '2026-05-25T12:00:00.000Z';
      const contents = Array.from({ length: 5000 }, (_, i) => `line ${i}`).join('\n');
      await writeCompleted('agent-long', completedAt, contents);

      const agent = await getAgent('agent-long', { limit: 10 });

      expect(agent.output).toHaveLength(10);
      expect(agent.output[0]).toEqual({ line: 'line 4990', timestamp: completedAt });
      expect(agent.output[9]).toEqual({ line: 'line 4999', timestamp: completedAt });
      expect(agent.outputTruncated).toBe(true);
      expect(agent.outputTotalBytes).toBe(Buffer.byteLength(contents));
    });

    it('caps by BYTES too, so a newline-free TUI transcript cannot blow memory', async () => {
      // A repainted TUI screen spools as effectively one enormous line, on which
      // a line-based tail is a no-op — the byte cap is what bounds it.
      const completedAt = '2026-05-26T12:00:00.000Z';
      const contents = 'x'.repeat(200_000);
      await writeCompleted('agent-oneline', completedAt, contents);

      const agent = await getAgent('agent-oneline', { maxBytes: 1024 });

      // The leading partial line is normally dropped, but here it is the ONLY
      // content in the window — a partial last screen beats an empty transcript
      // for a file that is plainly not empty.
      expect(agent.output).toHaveLength(1);
      expect(agent.output[0].line).toBe('x'.repeat(1024));
      expect(agent.outputTruncated).toBe(true);
      expect(agent.outputTotalBytes).toBe(200_000);
    });

    it('drops the partial leading line the byte window starts mid-way through', async () => {
      const completedAt = '2026-05-27T12:00:00.000Z';
      const contents = `${'a'.repeat(50)}\nbbbb\ncccc\n`;
      await writeCompleted('agent-partial', completedAt, contents);

      const agent = await getAgent('agent-partial', { maxBytes: 20 });

      expect(agent.output.map(o => o.line)).toEqual(['bbbb', 'cccc']);
      expect(agent.outputTruncated).toBe(true);
    });

    it('applies the default caps when no options are passed', async () => {
      const completedAt = '2026-05-28T12:00:00.000Z';
      const contents = Array.from({ length: AGENT_OUTPUT_TAIL_LINES + 500 }, (_, i) => `line ${i}`).join('\n');
      await writeCompleted('agent-default', completedAt, contents);

      const agent = await getAgent('agent-default');

      expect(agent.output).toHaveLength(AGENT_OUTPUT_TAIL_LINES);
      expect(agent.outputTruncated).toBe(true);
    });

    it('leaves the record untouched when output.txt is missing', async () => {
      const completedAt = '2026-05-29T12:00:00.000Z';
      mockCosState.state.agents['agent-nofile'] = { id: 'agent-nofile', status: 'completed', completedAt, metadata: {}, output: [] };
      await mkdir(join(mockCosState.agentsDir, '2026-05-29', 'agent-nofile'), { recursive: true });

      const agent = await getAgent('agent-nofile');

      expect(agent.output).toEqual([]);
      expect(agent).not.toHaveProperty('outputTruncated');
    });
  });

  it('persists post-completion metadata updates in the archived agent record', async () => {
    const agentId = 'agent-completed';
    const completedAt = '2026-05-25T12:00:00.000Z';
    mockCosState.state.agents[agentId] = { id: agentId, status: 'completed', completedAt, metadata: {}, output: [] };
    const archiveDir = join(mockCosState.agentsDir, '2026-05-25', agentId);
    await mkdir(archiveDir, { recursive: true });

    await updateAgent(agentId, { metadata: { malwareScan: { verdict: 'DANGEROUS' } } });

    const persisted = JSON.parse(await readFile(join(archiveDir, 'metadata.json'), 'utf8'));
    expect(persisted.metadata.malwareScan.verdict).toBe('DANGEROUS');
  });

  it('publishes saved cleanup diagnostics for an archived owner without reviving execution', async () => {
    const id = 'agent-archived-cleanup';
    const date = '2026-01-01';
    const record = { id, status: 'completed', completedAt: `${date}T12:00:00Z`, metadata: {} };
    const directory = join(mockCosState.agentsDir, date, id);
    await mkdir(directory, { recursive: true });
    await writeFile(join(directory, 'metadata.json'), JSON.stringify(record));
    (await loadAgentIndex()).set(id, date);
    const observed = [];
    const listener = agent => {
      if (agent.id === id) observed.push(agent);
    };
    cosEvents.on('agent:updated', listener);
    try {
      await recordCleanupOutcome(id, { status: 'blocked', reason: 'preservation-unverified' });
      const persisted = JSON.parse(await readFile(join(directory, 'metadata.json'), 'utf8'));
      expect(observed).toEqual([persisted]);
      expect(observed[0]).toMatchObject({ status: 'completed', metadata: { cleanupOutcome: { reason: 'preservation-unverified' } } });
      expect(mockCosState.state.agents[id]).toBeUndefined();
    } finally {
      cosEvents.off('agent:updated', listener);
    }
  });
});

describe('completeAgent budget-ledger ordering (#1683)', () => {
  beforeEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    await mkdir(mockCosState.agentsDir, { recursive: true });
    mockCosState.state = { agents: {}, stats: { tasksCompleted: 0, errors: 0 } };
    recordDomainUsage.mockClear();
  });

  afterEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    cosEvents.removeAllListeners('agent:completed');
  });

  it.each([
    ['scheduled', { taskType: 'scheduled' }],
    ['on-demand', { taskType: 'internal', onDemand: true }],
  ])('records %s action usage BEFORE emitting agent:completed', async (_kind, metadata) => {
    // The agent:completed handler schedules dequeueNextTask(), whose daily
    // action-budget gate reads the usage ledger. If the emit beats the ledger
    // write, the gate counts stale usage and can admit one spawn past the cap.
    const order = [];
    recordDomainUsage.mockImplementation(async () => { order.push('usage'); });
    cosEvents.on('agent:completed', () => { order.push('completed'); });

    const agentId = 'agent-autonomous';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata
    };

    await completeAgent(agentId, { success: true, duration: 1200 });

    expect(recordDomainUsage).toHaveBeenCalledWith('cos', { actions: 1, ms: 1200 });
    expect(order).toEqual(['usage', 'completed']);
  });

  it('retains delivery outcome through archive storage and list projection without changing feedback', async () => {
    const { toAgentListItem } = await import('../lib/cosAgentListProjection.js');
    const agentId = 'agent-task-outcome';
    const taskOutcome = { status: 'blocked', reason: 'Invented prerequisite missing.' };
    const feedback = { rating: 'positive', comment: 'Original feedback.' };
    mockCosState.state.agents[agentId] = { id: agentId, status: 'running', metadata: {}, feedback };
    const completed = await completeAgent(agentId, { success: false, executionSuccess: true, taskOutcome });
    const archived = JSON.parse(await readFile(join(mockCosState.agentsDir, completed.completedAt.slice(0, 10), agentId, 'metadata.json'), 'utf8'));
    expect(toAgentListItem(archived)).toMatchObject({ result: { success: false, executionSuccess: true, taskOutcome }, feedback });
  });

  it('still emits agent:completed when the usage-ledger write rejects', async () => {
    // recordDomainUsage is .catch-guarded, so a ledger-write failure must not
    // swallow the completion event — the scheduler still needs to advance.
    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    recordDomainUsage.mockRejectedValueOnce(new Error('ledger disk full'));

    const agentId = 'agent-ledger-fail';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'scheduled' }
    };
    let emitted = false;
    cosEvents.on('agent:completed', () => { emitted = true; });

    await completeAgent(agentId, { success: true, duration: 500 });

    expect(emitted).toBe(true);
    expect(consoleSpy).toHaveBeenCalledWith(
      expect.stringContaining(`Failed to record CoS budget usage for ${agentId}`)
    );
    consoleSpy.mockRestore();
  });

  it('does not charge stats.errors for a record retired by a resume', async () => {
    // `resumeAgent` retires a PAUSED record here so it stops showing as paused. The
    // run wasn't a failure — the user paused it and its task is already requeued, so
    // the continuation lands in one of these counters itself. Counting it reports an
    // error the user caused deliberately and never saw.
    mockCosState.state.agents['agent-resumed'] = {
      id: 'agent-resumed', status: 'paused', metadata: { taskType: 'user' }
    };
    mockCosState.state.agents['agent-failed'] = {
      id: 'agent-failed', status: 'running', metadata: { taskType: 'user' }
    };

    await completeAgent('agent-resumed', { success: false, resumed: true, resumedTaskId: 'task-abc' });
    expect(mockCosState.state.stats.errors).toBe(0);
    expect(mockCosState.state.agents['agent-resumed'].status).toBe('completed');

    // An ordinary failure still counts.
    await completeAgent('agent-failed', { success: false, exitCode: 1 });
    expect(mockCosState.state.stats.errors).toBe(1);
  });

  it('skips usage accounting for user tasks but still emits agent:completed', async () => {
    const agentId = 'agent-user';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'user' }
    };
    let emitted = false;
    cosEvents.on('agent:completed', () => { emitted = true; });

    await completeAgent(agentId, { success: true });

    expect(recordDomainUsage).not.toHaveBeenCalled();
    expect(emitted).toBe(true);
  });
});

describe('completeAgent idempotence (#3384)', () => {
  const emittedCompletions = [];
  const seedBodies = ownTestBodies(it);

  beforeEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    await mkdir(mockCosState.agentsDir, { recursive: true });
    mockCosState.state = { agents: {}, stats: { tasksCompleted: 0, errors: 0 } };
    emittedCompletions.length = 0;
    recordDomainUsage.mockClear();
    recordDomainUsage.mockImplementation(async () => {});
    captureCompletedCheckouts.mockReset().mockResolvedValue([]);
    cosEvents.on('agent:completed', (agent) => emittedCompletions.push(agent));
  });

  afterEach(async () => {
    // Bail settles Vitest's wrapper before its body: retain fixtures and spies
    // until the seed's Git work, completion/retry and finally have all finished.
    try {
      await seedBodies.drain();
    } finally {
      fsFailures.dateBucketWritesFail = false;
      await rm(mockCosState.agentsDir, { recursive: true, force: true });
      cosEvents.removeAllListeners('agent:completed');
    }
  });

  it.each([{ success: true, pinned: false }, { success: false, pinned: false }, { success: true, pinned: true }, { success: false, pinned: true }])('archives checkout evidence before releasing a delivered or cleanup-pending claim ($success, pinned=$pinned)', async ({ success, pinned }) => {
    const agentId = 'claim-completion';
    const receipt = { version: 1, agentId, branch: 'claim/issue-1' };
    mockCosState.state.agents[agentId] = { id: agentId, status: 'running', startedAt: '2026-01-01T00:00:00Z',
      metadata: { claimPicksOwnBranch: !pinned, ...(pinned ? { claimBranch: receipt.branch } : {}), claimBranches: [receipt.branch] }, output: [] };
    captureCompletedCheckouts.mockImplementationOnce(async agent => {
      expect(agent.status).toBe('running');
      expect(mockCosState.state.agents[agentId].status).toBe('running');
      return [receipt];
    });
    const result = await completeAgent(agentId, { success, cleanupPending: !success });
    expect(result.result.success).toBe(success);
    expect(result.metadata.repoStateVerification.status).toBe('pending');
    expect(result.metadata.completionCleanup).toMatchObject({ status: 'abandoned', reason: 'completion-context-unavailable' });
    expect(result.metadata.completedCheckouts).toEqual([receipt]);
    const archived = JSON.parse(await readFile(join(mockCosState.agentsDir, result.completedAt.slice(0, 10), agentId, 'metadata.json'), 'utf8'));
    expect(archived.metadata.completedCheckouts).toEqual([receipt]);
    await completeAgent(agentId, { success: true });
    expect(captureCompletedCheckouts).toHaveBeenCalledTimes(1);
  });

  it('drops replay inputs from durable terminal ledgers without erasing independent preservation holds', async () => {
    const id = 'claim-terminal-ledger';
    const startedAt = '2026-01-01T00:00:00Z';
    mockCosState.state.agents[id] = { id, status: 'running', startedAt, output: [], metadata: {
      claimPicksOwnBranch: true, completionCleanup: { version: 1, status: 'pending',
        context: { task: { id: 'original' }, outputBuffer: 'large legacy output' },
        replay: { version: 1, kind: 'replay', bytes: 123, sha256: 'a'.repeat(64) }, stages: {} } } };
    const completed = await completeAgent(id, { success: true });
    expect(await recordCompletionCleanup(id, startedAt, { status: 'failed', stages: {
      pipeline: { status: 'failed', retryable: false, reason: 'external-state-unknown' } } })).toBe(true);
    const archived = JSON.parse(await readFile(join(mockCosState.agentsDir, completed.completedAt.slice(0, 10), id, 'metadata.json'), 'utf8'));
    expect(archived.metadata.completionCleanup.status).toBe('failed');
    expect(archived.metadata.completionCleanup).not.toHaveProperty('context');
    expect(archived.metadata.completionCleanup).not.toHaveProperty('replay');
    expect(archived.metadata.repoStateVerification.status).toBe('pending');
  });

  it('records transient capture failure as a durable unknown obligation without rerunning finalization', async () => {
    const agentId = 'claim-capture-failed';
    mockCosState.state.agents[agentId] = { id: agentId, status: 'running', metadata: { claimPicksOwnBranch: true }, output: [] };
    captureCompletedCheckouts.mockRejectedValueOnce(new Error('checkout unreadable'));
    const result = await completeAgent(agentId, { success: true });
    expect(result).toMatchObject({ status: 'completed', result: { success: false, executionSuccess: true, cleanupPending: true },
      metadata: { claimPicksOwnBranch: true, completedCheckouts: [], checkoutCapture: { status: 'pending', unknown: true } } });
    await completeAgent(agentId, { success: false, exitCode: 143 });
    expect(mockCosState.state.agents[agentId].result.executionSuccess).toBe(true);
    mockCosState.state.agents['claim-failed'] = { id: 'claim-failed', status: 'running',
      metadata: { claimPicksOwnBranch: true, completedCheckouts: [{ stale: true }] }, output: [] };
    const failed = await completeAgent('claim-failed', { success: false });
    expect(failed.metadata.completedCheckouts).toEqual([]);
    expect(captureCompletedCheckouts).toHaveBeenCalledTimes(2);
  });

  it('archives owned checkout identity on execution failure without claiming delivery success', async () => {
    const id = 'failed-owned-checkout';
    const evidence = { version: 1, agentId: id, branch: 'feature/failed-owned' };
    mockCosState.state.agents[id] = { id, status: 'running', startedAt: '2026-01-01T00:00:00Z', output: [],
      metadata: { isWorktree: true, worktreeBranch: evidence.branch } };
    captureCompletedCheckouts.mockImplementationOnce(async agent => {
      expect(agent.status).toBe('running');
      return [evidence];
    });
    const failed = await completeAgent(id, { success: false, executionSuccess: false, orphaned: true });
    expect(failed.result).toMatchObject({ success: false, executionSuccess: false, orphaned: true });
    expect(failed.result.cleanupPending).not.toBe(true);
    expect(failed.metadata).toMatchObject({ completedCheckouts: [evidence], checkoutCapture: { status: 'captured' } });
    const persisted = JSON.parse(await readFile(join(mockCosState.agentsDir, failed.completedAt.slice(0, 10), id, 'metadata.json'), 'utf8'));
    expect(persisted.result).toEqual(failed.result);
    expect(persisted.metadata.completedCheckouts).toEqual([evidence]);
  });

  for (const scenario of ['unchanged', 'physical-generation', 'new-owner', 'later-head', 'orphan-empty', 'orphan-physical-generation', 'orphan-new-owner', 'orphan-later-head']) {
    seedBodies.it(`recovers only the original completion physical seed after restart, scenario=${scenario}`, async () => {
      const orphan = scenario.startsWith('orphan-');
      const changed = !['unchanged', 'orphan-empty'].includes(scenario);
      const scratch = await mkdtemp(join(tmpdir(), 'portos-completion-capture-seed-'));
      let failFirstRead;
      try {
        const repo = join(scratch, 'repo');
        const checkout = join(scratch, 'checkout');
        await materializeGitRepo(repo);
        await execGit(['worktree', 'add', '-b', 'feature/seeded', checkout, 'main'], repo);
        const actual = await vi.importActual('./completedCheckoutEvidence.js');
        captureCheckoutSeeds.mockImplementationOnce(actual.captureCheckoutSeeds);
        captureCompletedCheckouts.mockImplementationOnce(actual.captureCompletedCheckouts);
        const agentId = `seeded-${changed}`;
        await registerAgent(agentId, 'seeded-task', { isWorktree: true, sourceWorkspace: repo,
          workspacePath: checkout, worktreeBranch: 'feature/seeded' });
        const seed = mockCosState.state.agents[agentId].metadata.checkoutSeeds[0];
        expect(seed).toMatchObject({ agentId, branch: 'feature/seeded' });
        await writeFile(join(checkout, 'delivery.txt'), 'wanted original work');
        await execGit(['add', 'delivery.txt'], checkout);
        await execGit(['-c', 'user.name=Test', '-c', '[email protected]', 'commit', '-m', 'final delivered head'], checkout);
        const head = (await execGit(['rev-parse', 'HEAD'], checkout)).stdout.trim();
        if (orphan) captureCompletedCheckouts.mockReset().mockResolvedValueOnce([]); // Historical failed-run empty capture.
        else failFirstRead = vi.spyOn(await import('./worktreeManager.js'), 'listWorktrees').mockRejectedValueOnce(new Error('first completion Git read unavailable'));
        const completed = await completeAgent(agentId, orphan ? { success: false, executionSuccess: false, orphaned: true } : { success: true });
        if (orphan) expect(completed).toMatchObject({ result: { success: false, executionSuccess: false, orphaned: true },
          metadata: { completedCheckouts: [], checkoutCapture: { status: 'captured' } } });
        else expect(completed).toMatchObject({ status: 'completed', result: { cleanupPending: true, executionSuccess: true },
          metadata: { checkoutCapture: { status: 'pending', unknown: false, targets: [expect.objectContaining({ head })] } } });
        expect(cosEvents.listenerCount('agent:completed')).toBeGreaterThan(0);
        delete mockCosState.state.agents[agentId]; // Restart: only the real archived metadata remains.
        let retainedHead = head;
        if (scenario.endsWith('later-head')) {
          await execGit(['-c', 'user.name=Test', '-c', '[email protected]', 'commit', '--allow-empty', '-m', 'later unrelated writer'], checkout);
          retainedHead = (await execGit(['rev-parse', 'HEAD'], checkout)).stdout.trim();
        }
        if (scenario.endsWith('new-owner')) {
          mockCosState.state.agents['new-owner'] = { id: 'new-owner', status: 'completed', startedAt: new Date().toISOString(),
            metadata: { sourceWorkspace: repo, workspacePath: checkout, worktreeBranch: 'feature/seeded' } };
        }
        if (scenario.endsWith('physical-generation')) {
          const pointer = join(checkout, '.git');
          const bytes = await readFile(pointer);
          await rename(pointer, join(scratch, 'original-git-pointer'));
          await writeFile(pointer, bytes);
        }
        const options = orphan ? { retirement: { repoPath: repo, branch: 'feature/seeded', path: checkout, head } } : {};
        expect(await retryCompletionCheckoutCapture(agentId, options)).toBe(!changed);
        const recovered = await getAgent(agentId);
        if (changed) expect(recovered.metadata.checkoutCapture.status).toBe(orphan ? 'captured' : 'pending');
        else {
          const receipt = recovered.metadata.completedCheckouts[0];
          expect(receipt).toMatchObject({ version: 2, head, seededAt: seed.seededAt });
          expect(Date.parse(receipt.capturedAt)).toBeGreaterThanOrEqual(Date.parse(completed.completedAt));
          expect(completedCheckoutReceiptValid(recovered, receipt)).toBe(true);
        }
        if (orphan) expect(recovered.result).toEqual(completed.result);
        expect(await readFile(join(checkout, 'delivery.txt'), 'utf8')).toBe('wanted original work');
        expect((await execGit(['rev-parse', 'HEAD'], checkout)).stdout.trim()).toBe(retainedHead);
        expect(emittedCompletions).toHaveLength(1);
      } finally {
        failFirstRead?.mockRestore();
        await rm(scratch, { recursive: true, force: true, maxRetries: 3 });
      }
    });
  }

  it('keeps the first verdict when a duplicate completion arrives', async () => {
    // Regression: a stray runner `agent:completed` for an agent that had already
    // finalized on its own sentinel replaced a recorded success with
    // `success: false, exitCode: 143`, flipping the card to Failed and requeueing
    // a finished task.
    const agentId = 'agent-duplicate-completion';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'scheduled' },
      output: []
    };

    const first = await completeAgent(agentId, { success: true, exitCode: 0, duration: 1000 });
    expect(first.result.success).toBe(true);

    saveState.mockClear();
    recordDomainUsage.mockClear();
    emittedCompletions.length = 0;

    const second = await completeAgent(agentId, {
      success: false,
      exitCode: 143,
      errorAnalysis: { category: 'startup-failure' }
    });

    expect(second.result).toEqual(first.result);
    expect(second.result.success).toBe(true);
    expect(second.result.errorAnalysis).toBeUndefined();
    expect(second.completedAt).toBe(first.completedAt);
    expect(mockCosState.state.agents[agentId].result.success).toBe(true);

    // A no-op all the way out: no state write, no double budget charge, and no
    // second `agent:completed` (whose handler schedules the next task).
    expect(saveState).not.toHaveBeenCalled();
    expect(recordDomainUsage).not.toHaveBeenCalled();
    expect(emittedCompletions).toEqual([]);
    expect(mockCosState.state.stats).toEqual({ tasksCompleted: 1, errors: 0 });
  });

  it('does not re-run the completed-agent directory move on a duplicate', async () => {
    const agentId = 'agent-duplicate-archive';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'scheduled' },
      output: []
    };

    const first = await completeAgent(agentId, { success: true, exitCode: 0 });
    const archivedMetadata = join(
      mockCosState.agentsDir, first.completedAt.slice(0, 10), agentId, 'metadata.json'
    );
    expect(existsSync(archivedMetadata)).toBe(true);

    // Late output can land back in the flat dir after the archive move. A second
    // completion must leave it alone rather than sweeping it into the bucket.
    const flatDir = join(mockCosState.agentsDir, agentId);
    await mkdir(flatDir, { recursive: true });
    await writeFile(join(flatDir, 'output.txt'), 'post-archive line\n');

    await completeAgent(agentId, { success: false, exitCode: 143 });

    expect(existsSync(join(flatDir, 'output.txt'))).toBe(true);
    const archived = JSON.parse(await readFile(archivedMetadata, 'utf8'));
    expect(archived.result.success).toBe(true);
    expect(archived.result.exitCode).toBe(0);
  });

  it('finishes a half-done archive using the already-recorded verdict', async () => {
    // A prior completion that threw between its state write and the directory
    // move leaves the record `completed` but never archived. The duplicate call
    // repairs the archive — with the FIRST verdict, not the caller's.
    const agentId = 'agent-half-archived';
    const completedAt = '2026-05-25T12:00:00.000Z';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'completed',
      completedAt,
      result: { validationPassed: null, success: true, exitCode: 0 },
      metadata: { taskType: 'scheduled' },
      output: []
    };
    const flatDir = join(mockCosState.agentsDir, agentId);
    await mkdir(flatDir, { recursive: true });
    await writeFile(join(flatDir, 'output.txt'), 'the run that finished\n');

    const returned = await completeAgent(agentId, { success: false, exitCode: 143 });

    const archiveDir = join(mockCosState.agentsDir, '2026-05-25', agentId);
    const archived = JSON.parse(await readFile(join(archiveDir, 'metadata.json'), 'utf8'));
    expect(archived.result.success).toBe(true);
    expect(archived.result.exitCode).toBe(0);
    expect(existsSync(join(archiveDir, 'output.txt'))).toBe(true);
    expect(existsSync(flatDir)).toBe(false);

    // Repairing the archive is NOT a re-completion: verdict, ledger and the
    // scheduler hand-off all stay untouched.
    expect(returned.result.success).toBe(true);
    expect(recordDomainUsage).not.toHaveBeenCalled();
    expect(emittedCompletions).toEqual([]);
    expect(mockCosState.state.stats).toEqual({ tasksCompleted: 0, errors: 0 });
  });

  it('rolls back a half-copied archive so the next completion can repair it', async () => {
    // `existsSync(targetDir)` is what every later archive attempt reads as
    // "already archived" — so a cross-filesystem copy that dies partway must not
    // leave the destination behind, or the rest of the run's files are stranded.
    const agentId = 'agent-partial-copy';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'scheduled' },
      output: []
    };
    const flatDir = join(mockCosState.agentsDir, agentId);
    await mkdir(flatDir, { recursive: true });
    await writeFile(join(flatDir, 'output.txt'), 'the run that finished\n');

    // The move into the bucket fails as if cross-filesystem, then the copy
    // fallback dies partway through writing the files it created the dir for.
    fsFailures.dateBucketWritesFail = true;

    await expect(completeAgent(agentId, { success: true, exitCode: 0 }))
      .rejects.toThrow('simulated copy failure');

    const archiveDir = join(
      mockCosState.agentsDir,
      mockCosState.state.agents[agentId].completedAt.slice(0, 10),
      agentId
    );
    expect(existsSync(archiveDir)).toBe(false);

    // A completion sweep between failure and retry must not create a bucket
    // that makes archiveCompletedAgent skip the original transcript move.
    await recordRepoStateVerification(agentId, { status: 'pending', reasons: ['retry'] });
    expect(existsSync(archiveDir)).toBe(false);
    expect(await readFile(join(flatDir, 'output.txt'), 'utf8')).toBe('the run that finished\n');

    fsFailures.dateBucketWritesFail = false;
    recordDomainUsage.mockClear();
    emittedCompletions.length = 0;

    // The retry is a duplicate completion (the verdict was persisted before the
    // copy blew up), so it repairs the archive with the FIRST verdict.
    await completeAgent(agentId, { success: false, exitCode: 143 });

    const archived = JSON.parse(await readFile(join(archiveDir, 'metadata.json'), 'utf8'));
    expect(archived.result.success).toBe(true);
    expect(existsSync(join(archiveDir, 'output.txt'))).toBe(true);
    expect(existsSync(flatDir)).toBe(false);
    expect(recordDomainUsage).not.toHaveBeenCalled();
    expect(emittedCompletions).toEqual([]);
  });

  it('re-persists a missing index entry for an already-archived agent', async () => {
    // `saveAgentIndex` swallows its own write errors, so a failed write leaves
    // the in-memory map right and index.json wrong — the archive would be
    // unreachable from history after a restart. A duplicate completion repairs
    // the index even though the directory move itself is already done.
    const agentId = 'agent-unindexed';
    const completedAt = '2026-05-25T12:00:00.000Z';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'completed',
      completedAt,
      result: { validationPassed: null, success: true, exitCode: 0 },
      metadata: { taskType: 'scheduled' },
      output: []
    };
    const archiveDir = join(mockCosState.agentsDir, '2026-05-25', agentId);
    await mkdir(archiveDir, { recursive: true });
    await writeFile(join(archiveDir, 'metadata.json'), JSON.stringify({ id: agentId, result: { success: true } }));

    await completeAgent(agentId, { success: false, exitCode: 143 });

    const index = JSON.parse(await readFile(join(mockCosState.agentsDir, 'index.json'), 'utf8'));
    expect(index[agentId]).toBe('2026-05-25');
    // Repairing the index must not rewrite the archived verdict.
    const archived = JSON.parse(await readFile(join(archiveDir, 'metadata.json'), 'utf8'));
    expect(archived.result.success).toBe(true);
    expect(existsSync(join(mockCosState.agentsDir, agentId))).toBe(false);
  });

  it('completes a still-paused agent (the guard is completed-only, not running-only)', async () => {
    const agentId = 'agent-paused-completion';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'paused',
      pausedAt: '2026-05-25T12:00:00.000Z',
      metadata: { taskType: 'scheduled' },
      output: []
    };

    const done = await completeAgent(agentId, { success: true, exitCode: 0 });

    expect(done.status).toBe('completed');
    expect(done.result.success).toBe(true);
  });

  it('completes a paused agent that resumed back to running', async () => {
    const agentId = 'agent-resumed-completion';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'scheduled' },
      output: []
    };

    const paused = await updateAgent(agentId, { status: 'paused', pausedAt: '2026-05-25T12:00:00.000Z' });
    expect(paused.status).toBe('paused');

    const resumed = await updateAgent(agentId, { status: 'running' });
    expect(resumed.status).toBe('running');

    const done = await completeAgent(agentId, { success: true, exitCode: 0 });

    expect(done.status).toBe('completed');
    expect(done.result.success).toBe(true);
    expect(emittedCompletions).toHaveLength(1);
  });

  it('re-registering an id resets it to running so a retry can complete again', async () => {
    // Spawns mint a fresh `agent-<uuid>` id, so this only matters if one ever
    // collides — registerAgent must still hand back a completable record.
    const agentId = 'agent-reregistered';
    mockCosState.state.agents[agentId] = {
      id: agentId,
      status: 'running',
      metadata: { taskType: 'scheduled' },
      output: []
    };
    await completeAgent(agentId, { success: false, exitCode: 1 });

    const reregistered = await registerAgent(agentId, 'task-retry', { taskType: 'scheduled' });
    expect(reregistered.status).toBe('running');

    const done = await completeAgent(agentId, { success: true, exitCode: 0 });
    expect(done.result.success).toBe(true);
  });
});

describe('createAgentOutputBatcher', () => {
  const agentId = 'agent-batch';

  beforeEach(() => {
    saveState.mockClear();
    mockCosState.state = { agents: { [agentId]: { id: agentId, output: [] } } };
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it('coalesces many pushed lines into a single state write on flush', async () => {
    const batcher = createAgentOutputBatcher(agentId);
    batcher.push('line 1');
    batcher.push('line 2');
    batcher.push(['line 3', 'line 4']); // array push appends each line
    await batcher.flush();

    // Write-amplification guard: 4 lines, one load+save — not one per line.
    expect(saveState).toHaveBeenCalledTimes(1);
    expect(mockCosState.state.agents[agentId].output.map((o) => o.line)).toEqual([
      'line 1', 'line 2', 'line 3', 'line 4'
    ]);
  });

  it('flush() is a no-op (no state write) when nothing was pushed', async () => {
    const batcher = createAgentOutputBatcher(agentId);
    await batcher.flush();
    expect(saveState).not.toHaveBeenCalled();
  });

  it('captures lines pushed during an in-flight drain', async () => {
    const batcher = createAgentOutputBatcher(agentId);
    batcher.push('first');
    const flushing = batcher.flush();
    batcher.push('raced-in'); // arrives while the first drain is awaiting
    await flushing;
    await batcher.flush(); // second flush picks up the raced-in line

    expect(mockCosState.state.agents[agentId].output.map((o) => o.line)).toEqual([
      'first', 'raced-in'
    ]);
  });

  it('swallows + logs a state-write failure so flush() never rejects', async () => {
    saveState.mockRejectedValueOnce(new Error('disk full'));
    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});

    const batcher = createAgentOutputBatcher(agentId);
    batcher.push('doomed line');

    await expect(batcher.flush()).resolves.toBeUndefined();
    const logged = consoleSpy.mock.calls.some(
      (args) => typeof args[0] === 'string' &&
        args[0].startsWith(`❌ agent ${agentId} output batch flush failed:`)
    );
    expect(logged).toBe(true);
  });
});

describe('cleanupZombieAgents — runner listing is not proof of life', () => {
  beforeEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    await mkdir(mockCosState.agentsDir, { recursive: true });
    mockCosState.state = { agents: {} };
    vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([]);
    activeAgents.clear();
    runnerAgents.clear();
    spawningTasks.clear();
  });

  afterEach(async () => {
    spawningTasks.clear();
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
  });

  it('leaves an exited runner to its in-flight completion, then reaps if completion failed', async () => {
    await writeFile(join(mockCosState.agentsDir, 'index.json'), '{}');
    mockCosState.state.agents['agent-finishing'] = {
      id: 'agent-finishing', status: 'running', pid: 2147483646,
      startedAt: new Date(Date.now() - 60_000).toISOString(),
    };
    completingAgents.add('agent-finishing');
    try {
      expect((await cleanupZombieAgents()).cleaned).toEqual([]);
      expect(mockCosState.state.agents['agent-finishing'].status).toBe('running');
    } finally {
      completingAgents.delete('agent-finishing');
    }
    expect((await cleanupZombieAgents()).cleaned).toEqual(['agent-finishing']);
  });

  it('does not reap a pid-less record while its task is still being dispatched', async () => {
    await writeFile(join(mockCosState.agentsDir, 'index.json'), '{}');
    mockCosState.state.agents['agent-slow'] = {
      id: 'agent-slow',
      taskId: 'task-slow',
      status: 'running',
      startedAt: new Date(Date.now() - 5 * 60_000).toISOString(),
    };
    spawningTasks.add('task-slow');

    expect((await cleanupZombieAgents()).cleaned).toEqual([]);
    expect(mockCosState.state.agents['agent-slow'].status).toBe('running');

    // Once the dispatch gives up the task without ever recording a pid, the
    // record really is a never-started zombie again.
    spawningTasks.delete('task-slow');
    expect((await cleanupZombieAgents()).cleaned).toEqual(['agent-slow']);
    expect(mockCosState.state.agents['agent-slow'].result.error).toMatch(/never started/);
  });

  it('does not reap a runner-owned TUI while the runner probe is unavailable', async () => {
    mockCosState.state.agents['agent-tui'] = {
      id: 'agent-tui',
      status: 'running',
      pid: 0,
      startedAt: new Date(Date.now() - 60_000).toISOString(),
      metadata: { useRunner: true, executionMode: 'runner-tui' },
    };
    vi.mocked(getActiveAgentsFromRunner).mockRejectedValueOnce(new Error('runner is booting'));

    const result = await cleanupZombieAgents();
    expect(result.cleaned).toEqual([]);
    expect(mockCosState.state.agents['agent-tui'].status).toBe('running');
  });

  it('leaves a live runner-owned TUI whose onExit liveness is true', async () => {
    mockCosState.state.agents['agent-tui'] = {
      id: 'agent-tui',
      status: 'running',
      pid: 0,
      startedAt: new Date(Date.now() - 60_000).toISOString(),
    };
    vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([{
      id: 'agent-tui',
      pid: 0,
      kind: 'tui',
      processActive: true,
      liveness: 'pty',
    }]);

    const result = await cleanupZombieAgents();
    expect(result.cleaned).toEqual([]);
    expect(mockCosState.state.agents['agent-tui'].status).toBe('running');
  });

  it('retires a stale listing even if runnerAgents already adopted the id', async () => {
    await writeFile(join(mockCosState.agentsDir, 'index.json'), '{}');
    runnerAgents.set('agent-stale', { taskId: 'task-1' });
    mockCosState.state.agents['agent-stale'] = {
      id: 'agent-stale',
      status: 'running',
      pid: 2147483646,
      startedAt: new Date(Date.now() - 60_000).toISOString(),
    };
    vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([{
      id: 'agent-stale',
      pid: 2147483646,
      kind: 'cli',
      processActive: false,
      liveness: 'pid',
    }]);

    const result = await cleanupZombieAgents();
    expect(result.cleaned).toEqual(['agent-stale']);
    expect(mockCosState.state.agents['agent-stale'].status).toBe('completed');
  });

  it('retires a durable running record whose runner listing is stale', async () => {
    await writeFile(join(mockCosState.agentsDir, 'index.json'), '{}');
    mockCosState.state.agents['agent-stale'] = {
      id: 'agent-stale',
      status: 'running',
      pid: 2147483646,
      startedAt: new Date(Date.now() - 60_000).toISOString(),
    };
    vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([{
      id: 'agent-stale',
      pid: 2147483646,
      kind: 'cli',
      processActive: false,
      liveness: 'pid',
    }]);

    const result = await cleanupZombieAgents();
    expect(result.cleaned).toEqual(['agent-stale']);
    expect(mockCosState.state.agents['agent-stale'].status).toBe('completed');
    expect(mockCosState.state.agents['agent-stale'].result.error).toMatch(/terminated unexpectedly/);
  });

  describe('agent:completed emission (#11766)', () => {
    const completedEvents = [];
    const onCompleted = (agent) => completedEvents.push(agent);

    beforeEach(() => {
      completedEvents.length = 0;
      cosEvents.on('agent:completed', onCompleted);
    });

    afterEach(() => {
      cosEvents.off('agent:completed', onCompleted);
    });

    it('emits exactly one agent:completed for a reaped zombie, and none on a second sweep', async () => {
      await writeFile(join(mockCosState.agentsDir, 'index.json'), '{}');
      mockCosState.state.agents['agent-dead'] = {
        id: 'agent-dead',
        taskId: 'task-dead',
        status: 'running',
        pid: 2147483646,
        startedAt: new Date(Date.now() - 60_000).toISOString(),
        metadata: { taskType: 'scheduled' },
      };
      // Listeners that re-read state must already see the finalized record.
      let statusSeenByListener;
      cosEvents.once('agent:completed', () => {
        statusSeenByListener = mockCosState.state.agents['agent-dead'].status;
      });

      expect((await cleanupZombieAgents()).cleaned).toEqual(['agent-dead']);

      expect(statusSeenByListener).toBe('completed');
      expect(completedEvents).toHaveLength(1);
      expect(completedEvents[0]).toMatchObject({
        id: 'agent-dead',
        taskId: 'task-dead',
        metadata: { taskType: 'scheduled' },
        result: { success: false },
      });

      expect((await cleanupZombieAgents()).cleaned).toEqual([]);
      expect(completedEvents).toHaveLength(1);
    });

    it('emits nothing for live, dispatching or runner-shielded records', async () => {
      mockCosState.state.agents['agent-owned'] = {
        id: 'agent-owned', status: 'running', pid: 2147483646,
        startedAt: new Date(Date.now() - 60_000).toISOString(),
      };
      activeAgents.set('agent-owned', {});
      mockCosState.state.agents['agent-spawning'] = {
        id: 'agent-spawning', taskId: 'task-spawning', status: 'running',
        startedAt: new Date(Date.now() - 5 * 60_000).toISOString(),
      };
      spawningTasks.add('task-spawning');
      mockCosState.state.agents['agent-tui'] = {
        id: 'agent-tui', status: 'running', pid: 0,
        startedAt: new Date(Date.now() - 60_000).toISOString(),
      };
      vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([{
        id: 'agent-tui', pid: 0, kind: 'tui', processActive: true, liveness: 'pty',
      }]);

      expect((await cleanupZombieAgents()).cleaned).toEqual([]);
      expect(completedEvents).toEqual([]);
    });
  });
});

describe('deleteAgent directory cleanup (#11446)', () => {
  beforeEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    await mkdir(mockCosState.agentsDir, { recursive: true });
    mockCosState.state = { agents: {} };
  });

  afterEach(async () => {
    fsFailures.rmFailsFor = null;
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
  });

  it('logs the agentId and error when removing the agent directory fails, and still drops the record', async () => {
    const agentId = 'agent-rm-busy';
    await mkdir(join(mockCosState.agentsDir, agentId), { recursive: true });
    mockCosState.state.agents[agentId] = { id: agentId };
    fsFailures.rmFailsFor = agentId;
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    try {
      const result = await deleteAgent(agentId);
      expect(result).toEqual({ success: true, agentId });
      expect(mockCosState.state.agents[agentId]).toBeUndefined();
      expect(errorSpy).toHaveBeenCalledWith(expect.stringMatching(/^❌ .*agent-rm-busy.*EBUSY/));
    } finally {
      errorSpy.mockRestore();
    }
  });
});

describe('agent maintenance reservations on terminal transitions (#12737)', () => {
  const reserved = (agentId) => maintenance.status().blockers.some(b => b.kind === 'agent' && b.resource === agentId);
  beforeEach(async () => {
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
    await mkdir(mockCosState.agentsDir, { recursive: true });
    await writeFile(join(mockCosState.agentsDir, 'index.json'), '{}');
    mockCosState.state = { agents: {} };
    vi.mocked(getActiveAgentsFromRunner).mockResolvedValue([]);
    activeAgents.clear();
    runnerAgents.clear();
    spawningTasks.clear();
  });
  afterEach(async () => {
    for (const id of ['agent-zombie', 'agent-purged', 'agent-live']) await maintenance.finishResource('agent', id);
    await rm(mockCosState.agentsDir, { recursive: true, force: true });
  });

  it('releases the reservation of a reaped zombie', async () => {
    maintenance.admit('agent', 'agent-zombie');
    mockCosState.state.agents['agent-zombie'] = {
      id: 'agent-zombie', status: 'running', pid: 2147483646,
      startedAt: new Date(Date.now() - 60_000).toISOString(),
    };
    expect((await cleanupZombieAgents()).cleaned).toEqual(['agent-zombie']);
    expect(reserved('agent-zombie')).toBe(false);
  });

  it('releases the reservation of a purged completed agent but keeps a running one', async () => {
    maintenance.admit('agent', 'agent-purged');
    maintenance.admit('agent', 'agent-live');
    mockCosState.state.agents['agent-purged'] = { id: 'agent-purged', status: 'completed' };
    mockCosState.state.agents['agent-live'] = { id: 'agent-live', status: 'running' };
    await deleteAgent('agent-purged');
    await deleteAgent('agent-live');
    expect(reserved('agent-purged')).toBe(false);
    expect(reserved('agent-live')).toBe(true);
  });
});