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

82.1 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { EventEmitter } from 'events';
import { join } from 'path';

// This suite doubles fs.existsSync for spawn branches; it must not invent a database fence.
vi.mock('../lib/databaseMaintenanceJournal.js', () => ({ assertDatabaseAdmission() {} }));

// Heavy modules needed only by spawnDirectly — mock them all before importing.
vi.mock('./cosEvents.js', () => ({ cosEvents: { emit: vi.fn() }, emitLog: vi.fn() }));
vi.mock('./cosAgentLifecycle.js', () => {
  const appendAgentOutput = vi.fn().mockResolvedValue(undefined);
  const appendAgentOutputLines = vi.fn().mockResolvedValue(undefined);
  // Faithful stand-in for the real debounced batcher: accumulates pushed lines
  // and, on flush(), routes them through the mocked appendAgentOutputLines while
  // swallowing+logging failures (mirrors the real createAgentOutputBatcher in
  // cosAgentLifecycle.js — whose error handling is unit-tested in cosAgentLifecycle.test.js).
  const createAgentOutputBatcher = vi.fn((agentId, { flushBatch } = {}) => {
    let pending = [];
    return {
      push(lineOrLines) {
        if (Array.isArray(lineOrLines)) pending.push(...lineOrLines);
        else pending.push(lineOrLines);
      },
      async flush() {
        if (pending.length === 0) return;
        const batch = pending;
        pending = [];
        await (flushBatch ? flushBatch(batch) : appendAgentOutputLines(agentId, batch)).catch((err) =>
          console.error(`❌ agent ${agentId} output batch flush failed: ${err.message}`));
      },
    };
  });
  return {
    updateAgent: vi.fn().mockResolvedValue(undefined),
    completeAgent: vi.fn().mockResolvedValue(undefined),
    appendAgentOutput,
    appendAgentOutputLines,
    createAgentOutputBatcher,
  };
});
vi.mock('./executionLanes.js', () => ({ release: vi.fn() }));
vi.mock('./toolStateMachine.js', () => ({
  completeExecution: vi.fn(),
  errorExecution: vi.fn(),
}));
vi.mock('./agentErrorAnalysis.js', () => ({ analyzeAgentFailure: vi.fn().mockResolvedValue(null) }));
// The lifecycle ledger is a real file writer (data/cos/run-events.jsonl) — mocked
// so first-output telemetry lands in a spy rather than the developing install's
// ledger, and because this suite's fileUtils mock carries no PATHS.cos (#4540).
const { appendRunEvent } = vi.hoisted(() => ({ appendRunEvent: vi.fn(async () => ({ appended: true })) }));
vi.mock('./agentRunEventLog.js', () => ({ appendRunEvent }));

vi.mock('./agentRunTracking.js', () => ({ completeAgentRun: vi.fn().mockResolvedValue(undefined) }));
// Mock forgeAuth.js directly so spawnDirectly's GH_TOKEN pinning is exercised without
// pulling in the real worktreeManager → instances module graph. Default: no
// owner-matched account → empty overlay (ambient gh auth untouched).
vi.mock('./forgeAuth.js', () => ({ resolveForgeTokenEnv: vi.fn().mockResolvedValue({}) }));
// The loopback PortOS API token the agent's own `curl`s spend — mocked for the
// same reason: the real one reads settings.json to learn whether this install
// has an instance password.
vi.mock('./agentApiAuth.js', () => ({ resolveAgentApiEnv: vi.fn().mockResolvedValue({}) }));
vi.mock('./agentFinalization.js', () => ({
  finalizeAgent: vi.fn().mockResolvedValue(undefined),
  releaseAgentLane: vi.fn(),
}));
// The close handler hands the run to the shared completion dispatch (pipeline
// progression → worktree cleanup with the PR disposition → retry-hold release).
// Doubled at that boundary: what this suite owns is that the direct-CLI path
// dispatches with the right verdict and PR ownership, and only when it should —
// the dispatch's own sequence is pinned in agentCompletionCleanup.test.js.
// Mocking it also keeps the real cleanup graph (cos.js, git.js, worktreeManager)
// out of this suite.
vi.mock('./agentCompletionCleanup.js', () => ({
  runSpawnerCompletionCleanup: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./agentState.js', () => ({
  activeAgents: new Map(),
  userTerminatedAgents: new Set(),
  pausedAgents: new Map(),
  consumePausedAgentExit: vi.fn(),
  registerSpawnedAgent: vi.fn(),
  unregisterSpawnedAgent: vi.fn(),
  metaStringOr: (value, fallback) => (typeof value === 'string' && value) ? value : fallback,
}));
vi.mock('../lib/fileUtils.js', () => ({
  tryReadFile: vi.fn().mockResolvedValue(null),
  safeJSONParse: (str, fallback) => { try { return JSON.parse(str); } catch { return fallback; } },
  // agentSentinel builds the per-agent sentinel filename with this — a mock
  // missing it makes doneSentinelPath throw inside the close handler.
  sanitizeFilename: (name) => String(name).replace(/[^a-zA-Z0-9._-]/g, '_'),
  writeFileGuarded: vi.fn().mockResolvedValue(undefined),
  PATHS: { root: '/tmp', cosAgents: '/tmp/agents', data: '/tmp/data' },
}));
vi.mock('../lib/codexCliOutput.js', () => ({ createCodexStderrFormatter: vi.fn() }));
vi.mock('fs/promises', () => ({
  readFile: vi.fn().mockResolvedValue('{}'),
  writeFile: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('fs', () => ({ existsSync: vi.fn().mockReturnValue(false) }));

// Default passthrough for the Windows resolve+wrap helper (#2243) — POSIX
// behavior. A specific test overrides it with mockReturnValueOnce to assert the
// spawn wiring uses whatever prepareCliSpawn returns.
// Only the two spawn-shaping helpers are stubbed. `guardChildStdin` stays REAL
// so the stdin-EPIPE containment test below pins the production listener rather
// than a test double of it.
vi.mock('../lib/bufferedSpawn.js', async (importActual) => ({
  ...(await importActual()),
  prepareCliSpawn: vi.fn((command, args) => ({ command, args })),
  killProcessTree: vi.fn(),
}));

// Mock child_process.spawn to return a controllable fake process
let fakeProcess;
vi.mock('../lib/childProcess.js', () => ({
  spawn: vi.fn(() => fakeProcess),
  // `execFile` is pulled in transitively by codeReview.js → lmStudioManager
  // (via `resolveReviewLoopOptions`'s dependency graph), even though this
  // test never spawns one directly.
  execFile: vi.fn(),
}));

vi.mock('./ollamaAgentContext.js', () => ({
  ensureOllamaAgentContext: vi.fn(async () => ({ skipped: true })),
}));
vi.mock('./providers.js', () => ({
  isOllamaBackedProvider: vi.fn(() => false),
}));
vi.mock('../lib/privateSecuritySandbox.js', () => ({
  preparePrivateSecuritySpawn: vi.fn(),
}));
// Real publication admission fsyncs a directory on every flush. A byte-volume
// test with hundreds of flushes opts out so disk latency under load cannot eat
// its timeout; the admission contract keeps its own real-boundary test.
const publicationAdmission = vi.hoisted(() => ({ bypass: false }));
vi.mock('../lib/backupSnapshotBoundary.js', async (importActual) => {
  const actual = await importActual();
  return {
    ...actual,
    withBackupAssetPublication: (work, options) =>
      publicationAdmission.bypass ? work() : actual.withBackupAssetPublication(work, options),
  };
});

import { buildCliSpawnConfig, spawnDirectly } from './agentCliSpawning.js';
import { promptOpensOwnPr } from './promptSections/completion.js';
import { runSpawnerCompletionCleanup } from './agentCompletionCleanup.js';
import { ensureOllamaAgentContext } from './ollamaAgentContext.js';
import { isOllamaBackedProvider } from './providers.js';
// Real module — the flag is a plain process-local boolean, so driving it
// directly exercises the same code path production does.
import { markHostShuttingDown, resetHostShutdownFlagForTests } from '../lib/hostShutdown.js';
import { emitLog } from './cosEvents.js';
import { existsSync } from 'fs';
import { spawn } from '../lib/childProcess.js';
import { prepareCliSpawn, killProcessTree } from '../lib/bufferedSpawn.js';

// Windows takes killProcessTree's tree-wide `taskkill /T` branch instead, so
// `needsProcessGroup` is false there and these sites spawn attached. The policy
// itself is pinned with an injected platform in credentialBootstrap.test.js;
// these assert only that each site plumbs the decision through.
const EXPECT_GROUP = process.platform !== 'win32';

describe('buildCliSpawnConfig', () => {
  it('omits --model for Codex configured-default sentinel but bypasses sandbox/approvals', () => {
    const config = buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'codex-configured-default');

    // The bypass flag is the Codex equivalent of Claude/Antigravity's
    // --dangerously-skip-permissions. Without it, codex exec runs sandboxed (no network → `gh`
    // can't reach api.github.com) and non-interactive approval prompts get cancelled.
    expect(config.args).toEqual(['exec', '--dangerously-bypass-approvals-and-sandbox', '-c', 'check_for_update_on_startup=false']);
  });

  it('passes explicit Codex model selections through alongside the sandbox bypass', () => {
    const config = buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'gpt-5.4');

    expect(config.args).toEqual(['exec', '--dangerously-bypass-approvals-and-sandbox', '-c', 'check_for_update_on_startup=false', '--model', 'gpt-5.4']);
  });

  it('gives a cloud Codex swarm enough threads for its root plus every worker', () => {
    const config = buildCliSpawnConfig(
      { id: 'codex', command: 'codex' },
      'gpt-5.4',
      {},
      { maxConcurrentThreads: 7 },
    );

    expect(config.args).toContain('agents.max_concurrent_threads_per_session=7');
  });

  it('disables the codex update check unconditionally on the headless agent path (ignores provider.args)', () => {
    // This builder constructs codex argv from scratch and never forwards
    // provider.args, so a provider.args pin is NOT honored here — a headless CoS
    // agent can never dismiss the update modal, so the check is always forced off.
    const config = buildCliSpawnConfig(
      { id: 'codex', command: 'codex', args: ['-c', 'check_for_update_on_startup=true'] },
      'gpt-5.4',
    );
    expect(config.args).toContain('check_for_update_on_startup=false');
  });

  it('uses agy print mode for Antigravity without model flags on the configured-default sentinel', () => {
    const config = buildCliSpawnConfig({ id: 'antigravity-cli', command: 'agy', args: [] }, 'antigravity-configured-default');

    expect(config.command).toBe('agy');
    expect(config.args).toEqual(['--dangerously-skip-permissions', '--print']);
  });

  // agy takes the prompt as the trailing --print VALUE, so every injected flag
  // must land before it or agy reads the flag name as its task.
  it('threads the per-task model and effort into agy ahead of --print', () => {
    const config = buildCliSpawnConfig(
      { id: 'antigravity-cli', command: 'agy', args: [] },
      'claude-sonnet-4-6',
      {},
      { effort: 'medium' },
    );

    expect(config.command).toBe('agy');
    expect(config.args).toEqual([
      '--model', 'claude-sonnet-4-6',
      '--effort', 'medium',
      '--dangerously-skip-permissions',
      '--print',
    ]);
    expect(config.args[config.args.length - 1]).toBe('--print');
  });

  // The trailing `--agent build` on every OpenCode argv below pins the
  // tool-enabled agent: OpenCode's role is argv state, so an un-pinned
  // invocation opens in whatever agent the install defaults to (#7405). See
  // ensureOpencodeAgent in lib/providerVendors.js.
  it('runs `opencode run -m ollama/<model>` for a headless OpenCode Ollama agent', () => {
    const config = buildCliSpawnConfig(
      { id: 'opencode-ollama', command: 'opencode', args: ['run'], ollamaBacked: true },
      'qwen2.5:7b',
    );

    expect(config.command).toBe('opencode');
    expect(config.args).toEqual(['run', '-m', 'ollama/qwen2.5:7b', '--agent', 'build']);
    expect(config.stdinMode).toBe('prompt');
    // OpenCode emits plain text, so no stream-json format is requested.
    expect(config.streamFormat).toBeUndefined();
  });

  it('runs `opencode run -m mtplx/<model>` for a headless OpenCode MTPLX agent', () => {
    const config = buildCliSpawnConfig(
      { id: 'opencode-mtplx', command: 'opencode', args: ['run'], mtplxBacked: true },
      'mtplx',
    );

    expect(config.command).toBe('opencode');
    expect(config.args).toEqual(['run', '-m', 'mtplx/mtplx', '--agent', 'build']);
    expect(config.stdinMode).toBe('prompt');
  });

  it('prepends the run subcommand for OpenCode even if saved args dropped it', () => {
    const config = buildCliSpawnConfig({ id: 'opencode-ollama', command: 'opencode', args: [], ollamaBacked: true }, 'qwen2.5:7b');

    expect(config.args).toEqual(['run', '-m', 'ollama/qwen2.5:7b', '--agent', 'build']);
  });

  it('respects a user-baked -m pin on an OpenCode provider and does not duplicate it', () => {
    const config = buildCliSpawnConfig(
      { id: 'opencode-ollama', command: 'opencode', args: ['run', '-m', 'ollama/custom'], ollamaBacked: true },
      'qwen2.5:7b',
    );

    expect(config.args).toEqual(['run', '-m', 'ollama/custom', '--agent', 'build']);
  });

  it('runs `grok` headless with plain output, permission bypass, and stdin prompt file (no --model for configured-default)', () => {
    const config = buildCliSpawnConfig({ id: 'grok-cli', command: 'grok', args: [] }, 'grok-configured-default');
    expect(config.command).toBe('grok');
    expect(config.stdinMode).toBe('prompt');
    expect(config.args).toEqual([
      '--output-format', 'plain',
      '--permission-mode', 'bypassPermissions',
      '--prompt-file', '/dev/stdin',
    ]);
    expect(config.args).not.toContain('--model');
    // Grok is non-Claude, so no claude-only flags leak in.
    expect(config.args).not.toContain('--dangerously-skip-permissions');
    expect(config.args).not.toContain('--print');
    expect(config.args).not.toContain('--append-system-prompt-file');
  });

  it('runs `kimi` headless with --print, no --model for the configured-default sentinel', () => {
    const config = buildCliSpawnConfig({ id: 'kimi-cli', command: 'kimi', args: ['--print'] }, 'kimi-configured-default');
    expect(config.command).toBe('kimi');
    expect(config.stdinMode).toBe('prompt');
    expect(config.args).toEqual(['--print']);
    expect(config.args).not.toContain('--model');
    // Kimi is non-Claude, so no claude-only flags leak in.
    expect(config.args).not.toContain('--dangerously-skip-permissions');
    expect(config.args).not.toContain('--append-system-prompt-file');
  });

  it('injects --model for a concrete kimi model id', () => {
    const config = buildCliSpawnConfig({ id: 'kimi-cli', command: 'kimi', args: ['--print'] }, 'kimi-k2');
    expect(config.command).toBe('kimi');
    expect(config.args).toEqual(['--print', '--model', 'kimi-k2']);
  });

  it('runs `cursor-agent` headless with --print --force and the model on stdin', () => {
    const config = buildCliSpawnConfig({ id: 'cursor-cli', command: 'cursor-agent', args: ['--print', '--force'] }, 'auto');
    expect(config.command).toBe('cursor-agent');
    expect(config.stdinMode).toBe('prompt');
    expect(config.args).toEqual(['--print', '--force', '--model', 'auto']);
    // Cursor is non-Claude, so no claude-only flags leak in.
    expect(config.args).not.toContain('--dangerously-skip-permissions');
    expect(config.args).not.toContain('--append-system-prompt-file');
    // Plain text output — no stream-json parser is claimed for cursor (see cursor.js).
    expect(config.streamFormat).toBeUndefined();
  });

  it('adds --force to a cursor provider whose saved args dropped it (trust gate is fatal without it)', () => {
    const config = buildCliSpawnConfig({ id: 'cursor-cli', command: 'cursor-agent', args: [] }, null);
    expect(config.args).toEqual(['--print', '--force']);
  });

  it('does not Bedrock-map a cursor model id that merely contains "claude"', () => {
    const config = buildCliSpawnConfig(
      { id: 'cursor-cli', command: 'cursor-agent', args: ['--print', '--force'] },
      'claude-opus-5-thinking-high',
      { CLAUDE_CODE_USE_BEDROCK: '1' },
    );
    expect(config.args).toEqual(['--print', '--force', '--model', 'claude-opus-5-thinking-high']);
    expect(config.args.join(' ')).not.toContain('anthropic.');
  });

  it('adds lean-mode flags and the system-prompt file for an Ollama-backed claude CLI', () => {
    const config = buildCliSpawnConfig(
      { id: 'claude-ollama', command: 'claude', ollamaBacked: true },
      'qwen3.6:35b',
      {},
      { systemPromptFile: '/data/cos/agents/agent-1/system-prompt.md' },
    );

    expect(config.args).toContain('--bare');
    expect(config.args).toContain('--strict-mcp-config');
    const idx = config.args.indexOf('--append-system-prompt-file');
    expect(config.args[idx + 1]).toBe('/data/cos/agents/agent-1/system-prompt.md');
    // Lean flags must not disturb the model injection.
    expect(config.args[config.args.indexOf('--model') + 1]).toBe('qwen3.6:35b');
  });

  it('does NOT add lean flags to the standard claude CLI provider', () => {
    const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, 'claude-opus-4-8');
    expect(config.args).not.toContain('--bare');
    expect(config.args).not.toContain('--strict-mcp-config');
    expect(config.args).not.toContain('--append-system-prompt-file');
  });

  it('adds the system-prompt file to a STANDARD claude CLI WITHOUT lean flags', () => {
    const config = buildCliSpawnConfig(
      { id: 'claude-code', command: 'claude' },
      'claude-opus-4-8',
      {},
      { systemPromptFile: '/data/cos/agents/agent-2/system-prompt.md' },
    );
    expect(config.args).not.toContain('--bare');
    const idx = config.args.indexOf('--append-system-prompt-file');
    expect(config.args[idx + 1]).toBe('/data/cos/agents/agent-2/system-prompt.md');
  });

  describe('reasoning-effort override', () => {
    it('adds a -c model_reasoning_effort pair for codex', () => {
      const config = buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'gpt-5.4', {}, { effort: 'xhigh' });
      expect(config.args).toContain('model_reasoning_effort=xhigh');
    });

    it('passes Ultra to supported Codex models and clamps it elsewhere', () => {
      const codex = { id: 'codex', command: 'codex' };
      const maxConfig = buildCliSpawnConfig(codex, 'gpt-5.4', {}, { effort: 'max' });
      expect(maxConfig.args).toContain('model_reasoning_effort=max');
      const ultraConfig = buildCliSpawnConfig(codex, 'gpt-5.6-sol', {}, { effort: 'ultra' });
      expect(ultraConfig.args).toContain('model_reasoning_effort=ultra');
      const clampedConfig = buildCliSpawnConfig(codex, 'gpt-5.4', {}, { effort: 'ultra' });
      expect(clampedConfig.args).toContain('model_reasoning_effort=max');
    });

    it('adds --effort for claude', () => {
      const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, 'claude-opus-4-8', {}, { effort: 'high' });
      expect(config.args[config.args.indexOf('--effort') + 1]).toBe('high');
    });

    it('clamps codex-only values on a claude provider', () => {
      const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, null, {}, { effort: 'ultra' });
      expect(config.args[config.args.indexOf('--effort') + 1]).toBe('max');
    });

    it('omits the flag entirely when no effort is set or the provider has no effort control', () => {
      // Codex always carries `-c check_for_update_on_startup=false`, so assert the
      // absence of the EFFORT config pair specifically, not any `-c`.
      expect(buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'gpt-5.4').args.join(' ')).not.toContain('model_reasoning_effort');
      expect(buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, null).args).not.toContain('--effort');
      const grok = buildCliSpawnConfig({ id: 'grok-cli', command: 'grok', args: [] }, null, {}, { effort: 'high' });
      expect(grok.args.join(' ')).not.toContain('effort');
    });

    it('keys effort on the RESOLVED command, so a blank-command claude provider still qualifies', () => {
      // id gives no claude-code* hint and command is blank; the builder resolves
      // the launch command to `claude`, so the effort pin must apply — matching
      // the TUI builder's re-keying (same pin, same behavior per execution mode).
      const config = buildCliSpawnConfig({ id: 'whatever' }, null, {}, { effort: 'high' });
      expect(config.args[config.args.indexOf('--effort') + 1]).toBe('high');
    });

    it('routes a renamed codex provider through the codex recipe, effort shape included', () => {
      // The vendor registry used to match codex by provider ID alone, so any
      // record but the shipped `codex` fell through to claude's
      // unconditionally-true row — claude-shaped argv on the codex binary, with
      // only the effort pair keyed off the command. Now the whole recipe follows
      // the binary (#6305, which needed a SECOND codex record to build codex argv).
      const config = buildCliSpawnConfig(
        { id: 'my-codex', command: '/opt/tools/codex' },
        null,
        {},
        { effort: 'xhigh' },
      );
      expect(config.args[0]).toBe('exec');
      expect(config.args).not.toContain('--effort');
      expect(config.args.join(' ')).toContain('-c model_reasoning_effort=xhigh');
    });

    it('respects a user-baked --effort pin in provider args (mirrors the --model rule)', () => {
      const config = buildCliSpawnConfig(
        { id: 'claude-code', command: 'claude', args: ['--effort', 'low'] },
        null,
        {},
        { effort: 'max' },
      );
      const effortArgs = config.args.filter(a => a === '--effort');
      expect(effortArgs).toHaveLength(1);
      expect(config.args[config.args.indexOf('--effort') + 1]).toBe('low');
    });
  });

  describe('Bedrock model-id mapping', () => {
    // buildCliSpawnConfig reads process.env for the Bedrock signal; isolate the
    // tests from whatever the host/CI environment happens to set.
    let savedBedrock;
    beforeEach(() => {
      savedBedrock = process.env.CLAUDE_CODE_USE_BEDROCK;
      delete process.env.CLAUDE_CODE_USE_BEDROCK;
    });
    afterEach(() => {
      if (savedBedrock === undefined) delete process.env.CLAUDE_CODE_USE_BEDROCK;
      else process.env.CLAUDE_CODE_USE_BEDROCK = savedBedrock;
    });

    const modelOf = (args) => args[args.indexOf('--model') + 1];

    it('passes a bare Claude model through unchanged when Bedrock mode is off', () => {
      const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, 'claude-opus-4-8');
      expect(modelOf(config.args)).toBe('claude-opus-4-8');
    });

    it('maps a bare Claude model when Bedrock comes ONLY from settings.json env (regression: #1521 blocking)', () => {
      const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
      // provider.envVars empty (plain claude-code), Bedrock supplied via the
      // ~/.claude/settings.json env block — the case the original fix missed.
      const config = buildCliSpawnConfig(
        { id: 'claude-code', command: 'claude', envVars: {} },
        'claude-opus-4-8',
        { CLAUDE_CODE_USE_BEDROCK: '1' },
      );
      expect(modelOf(config.args)).toBe('global.anthropic.claude-opus-4-8');
      spy.mockRestore();
    });

    it('maps a bare Claude model when Bedrock comes from provider.envVars', () => {
      const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
      const config = buildCliSpawnConfig(
        { id: 'claude-code', command: 'claude', envVars: { CLAUDE_CODE_USE_BEDROCK: '1' } },
        'claude-opus-4-8',
      );
      expect(modelOf(config.args)).toBe('global.anthropic.claude-opus-4-8');
      spy.mockRestore();
    });
  });
});

describe('stream error containment', () => {
  // Build a minimal fake process with stdin/stdout/stderr EventEmitters.
  function makeFakeProcess({ failWith = null, noStdin = false } = {}) {
    const proc = new EventEmitter();
    if (!noStdin) {
      proc.pid = 12345;
      // A real ChildProcess stdin is a stream, so the fake is one too — otherwise
      // the production `guardChildStdin` listener has nothing to attach to and the
      // stdin-EPIPE path below would be tested against a shape that can't occur.
      proc.stdin = Object.assign(new EventEmitter(), { write: vi.fn(), end: vi.fn() });
    }
    proc.stdout = new EventEmitter();
    proc.stderr = new EventEmitter();
    if (failWith) setImmediate(() => proc.emit('error', failWith));
    return proc;
  }

  // The stamp `agentLifecycle` writes for a run, derived through the REAL
  // predicate instead of hand-written — a literal here is what let the suite
  // pin an ownership value the spawn path never produces for a Claude host
  // (#6869). `minimalArgs.provider` is the slashdo-capable `claude-code` CLI.
  const stampPrOpenedBy = (task, provider = minimalArgs.provider) => promptOpensOwnPr(task, {
    providerType: provider.type,
    providerId: provider.id,
    providerCommand: provider.command,
    leanMode: false,
    worktreeInfo: { branchName: 'agent/t', worktreePath: '/tmp/wt', baseBranch: 'main' },
  });

  const minimalArgs = {
    agentId: 'agent-test',
    task: { id: 'task-1', description: 'do stuff' },
    prompt: 'Hello',
    workspacePath: '/tmp',
    model: 'claude-3',
    provider: { id: 'claude-code', type: 'cli', command: 'claude', args: [], envVars: {} },
    runId: 'run-1',
    cliConfig: {
      command: 'claude',
      args: ['--dangerously-skip-permissions', '--print', '--output-format', 'stream-json', '--verbose', '--include-partial-messages'],
      stdinMode: 'prompt',
      streamFormat: 'stream-json',
    },
    agentDir: '/tmp',
    executionId: null,
    laneName: null,
  };

  // Re-import the mocked cosAgentLifecycle module reference once — mocking is module-scoped.
  let agentStateMocks;
  beforeEach(async () => {
    fakeProcess = makeFakeProcess();
    // Fresh mocked module reference for each test so mockRejectedValueOnce is clean.
    agentStateMocks = await import('./cosAgentLifecycle.js');
    // Reset all implementations to their default "resolve" state before each test.
    agentStateMocks.updateAgent.mockResolvedValue(undefined);
    agentStateMocks.completeAgent.mockResolvedValue(undefined);
    agentStateMocks.appendAgentOutput.mockResolvedValue(undefined);
    agentStateMocks.appendAgentOutputLines.mockResolvedValue(undefined);
    (await import('./agentRunTracking.js')).completeAgentRun.mockResolvedValue(undefined);
    (await import('./agentFinalization.js')).finalizeAgent.mockResolvedValue(undefined);
    // Completion waits must observe this test, not a previous cleanup call.
    runSpawnerCompletionCleanup.mockClear();
    runSpawnerCompletionCleanup.mockResolvedValue(undefined);
    vi.mocked(existsSync).mockReturnValue(false);
    vi.mocked(isOllamaBackedProvider).mockReturnValue(false);
    vi.mocked(ensureOllamaAgentContext).mockResolvedValue({ skipped: true });
    // Reset the resolve+wrap helper to its POSIX passthrough before each test
    // (afterEach's restoreAllMocks can clear the factory implementation).
    vi.mocked(prepareCliSpawn).mockImplementation((command, args) => ({ command, args }));
  });

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

  describe('spawn failure containment', () => {
    it('settles private sandbox preparation failure without spawning an uncontained child', async () => {
      const { preparePrivateSecuritySpawn } = await import('../lib/privateSecuritySandbox.js');
      const { finalizeAgent, releaseAgentLane } = await import('./agentFinalization.js');
      const { spawn } = await import('../lib/childProcess.js');
      spawn.mockClear();
      finalizeAgent.mockClear();
      releaseAgentLane.mockClear();
      preparePrivateSecuritySpawn.mockRejectedValueOnce(new Error('synthetic sandbox unavailable'));
      const task = { id: 'private-task', taskType: 'internal', metadata: { analysisType: 'private-security-assessment' } };
      await expect(spawnDirectly({ ...minimalArgs, task })).resolves.toBeNull();
      expect(spawn).not.toHaveBeenCalled();
      expect(releaseAgentLane).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'agent-test', success: false }));
      expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({
        task, success: false, exitCode: 1, completionReason: 'spawn-error', outputBuffer: '',
      }));
    });

    const failedSpawn = () => makeFakeProcess({
      noStdin: true,
      failWith: Object.assign(new Error('spawn claude ENOENT'), { code: 'ENOENT' }),
    });

    const waitForSpawnFailure = async () => {
      await new Promise((resolve) => setImmediate(resolve));
      await new Promise((resolve) => setImmediate(resolve));
    };

    it('the failing fake really has no stdin (bypass probe)', () => {
      expect(makeFakeProcess({ noStdin: true }).stdin).toBeUndefined();
    });

    it('settles with a startup failure when the provider CLI is missing', async () => {
      fakeProcess = failedSpawn();

      await expect(spawnDirectly(minimalArgs)).resolves.toBe('agent-test');
      await waitForSpawnFailure();

      expect(agentStateMocks.completeAgent).toHaveBeenCalledWith(
        'agent-test',
        expect.objectContaining({ success: false, error: expect.stringContaining('ENOENT') }),
      );
    });

    it('does not leave the agent registered in activeAgents after a failed spawn', async () => {
      const { activeAgents, registerSpawnedAgent } = await import('./agentState.js');
      activeAgents.clear();
      registerSpawnedAgent.mockClear();
      agentStateMocks.updateAgent.mockClear();
      fakeProcess = failedSpawn();

      await spawnDirectly(minimalArgs);
      await waitForSpawnFailure();

      expect(activeAgents.has('agent-test')).toBe(false);
      expect(registerSpawnedAgent).not.toHaveBeenCalled();
      expect(agentStateMocks.updateAgent).not.toHaveBeenCalled();
    });

    it('surfaces the spawn error message to the run log', async () => {
      agentStateMocks.appendAgentOutputLines.mockClear();
      fakeProcess = failedSpawn();

      await spawnDirectly(minimalArgs);
      await waitForSpawnFailure();

      const lines = agentStateMocks.appendAgentOutputLines.mock.calls.flatMap(([, batch]) => batch);
      expect(lines.some((line) => line.includes('ENOENT'))).toBe(true);
    });

    it('contains an EPIPE on stdin from a child that died before reading the prompt', async () => {
      // Two hazards in one shape, both fatal to the WHOLE server process because
      // this runs outside the Express request lifecycle (no next(err) to bubble to):
      //   1. a synchronous throw from stdin.write on an already-destroyed pipe, and
      //   2. an 'error' emitted on the stdin stream with no listener, which Node re-throws.
      // Regression guard for the listener drifting back below the write.
      const epipe = () => Object.assign(new Error('write EPIPE'), { code: 'EPIPE' });
      fakeProcess = makeFakeProcess();
      // Captured INSIDE write so the assertion is about ordering, not just
      // eventual presence — a guard moved below the write would read 0 here.
      let listenersAtWriteTime = null;
      fakeProcess.stdin = Object.assign(new EventEmitter(), {
        write: vi.fn(function () {
          listenersAtWriteTime = fakeProcess.stdin.listenerCount('error');
          throw epipe();
        }),
        end: vi.fn(),
        destroy: vi.fn(),
      });

      const spawnPromise = spawnDirectly(minimalArgs);
      await new Promise((r) => setTimeout(r, 10));

      // The guard was already in place when the write ran…
      expect(listenersAtWriteTime).toBe(1);
      // …so a late pipe error is swallowed instead of thrown.
      expect(() => fakeProcess.stdin.emit('error', epipe())).not.toThrow();
      // …and the pipe was closed anyway, so a child still reading stdin sees EOF.
      expect(fakeProcess.stdin.destroy).toHaveBeenCalled();

      fakeProcess.emit('close', 0);
      // The synchronous write throw did not escape as a rejected spawn either.
      await expect(spawnPromise).resolves.toBe('agent-test');
    });
  });

  // ─── Fast-exiting child: events emitted during the post-spawn await (#5791) ─

  it('does not drop stdout or close emitted while the post-spawn await is still yielding', async () => {
    // The child's whole life cycle can land between spawn() and the point where
    // the real stdout/stderr/close handler bodies are installed: the
    // `updateAgent(agentId, { pid })` in between is real state-file I/O, so it
    // yields for a macrotask, not just a microtask. A CLI that dies instantly
    // (bad flag, instant auth refusal) exits inside that window — before the fix
    // its output was lost and its `close` landed on nothing, leaving the run
    // record, the execution lane and the activeAgents entry non-terminal until
    // the orphan reaper eventually noticed.
    const { activeAgents } = await import('./agentState.js');
    const { finalizeAgent } = await import('./agentFinalization.js');
    activeAgents.clear();
    finalizeAgent.mockClear();
    agentStateMocks.updateAgent.mockImplementationOnce(async () => {
      // Emit from inside the same macrotask yield the real updateAgent creates.
      await new Promise((r) => setImmediate(r));
      fakeProcess.stdout.emit('data', Buffer.from(
        '{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"unknown flag --nope\\n"}}}\n'
      ));
      fakeProcess.emit('close', 2);
    });

    await expect(spawnDirectly(minimalArgs)).resolves.toBe('agent-test');
    await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });

    expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({
      agentId: 'agent-test',
      exitCode: 2,
      success: false,
      // The output the child managed to write before exiting is exactly what
      // explains the failure, so it has to survive the buffering too.
      outputBuffer: expect.stringContaining('unknown flag --nope'),
    }));
    expect(activeAgents.has('agent-test')).toBe(false);
  });

  // ─── Lifecycle ledger — the first-output boundary (#4540) ─────────────────

  it('records ONE run.output on the first real byte, and never again', async () => {
    // Bounded on purpose: a per-chunk event would make the ledger a copy of the
    // output it deliberately redacts. What one event buys is time-to-first-output
    // — the only thing that separates a run that stalled after speaking from one
    // that never spoke at all.
    appendRunEvent.mockClear();
    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10));

    fakeProcess.stdout.emit('data', Buffer.from('{\"type\":\"result\",\"result\":\"one\"}\n'));
    fakeProcess.stdout.emit('data', Buffer.from('{\"type\":\"result\",\"result\":\"two\"}\n'));
    await new Promise((r) => setTimeout(r, 20));

    const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
    expect(outputs).toHaveLength(1);
    expect(outputs[0]).toMatchObject({ runId: 'run-1', agentId: 'agent-test', taskId: 'task-1', data: { source: 'cli-stdout' } });

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  it('counts stderr-only output too — several providers say everything there', async () => {
    // codex's entire progress feed is stderr and lands in the same transcript.
    // A stdout-only recorder would file those runs as having produced nothing.
    appendRunEvent.mockClear();
    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10));

    fakeProcess.stderr.emit('data', Buffer.from('thinking...\n'));
    await new Promise((r) => setTimeout(r, 20));

    const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
    expect(outputs).toHaveLength(1);
    expect(outputs[0].data).toMatchObject({ source: 'cli-stderr' });

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  it('records no run.output for a run that never produced any', async () => {
    // The 3s initialization timer flips the record to "working" with nothing
    // behind it, which is exactly the run this boundary must NOT vouch for.
    appendRunEvent.mockClear();
    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10));

    fakeProcess.emit('close', 1);
    await spawnPromise.catch(() => {});

    expect(appendRunEvent.mock.calls.map(([e]) => e.kind)).not.toContain('run.output');
  });

  it.each([
    ['final result', { type: 'result', result: 'Saved a partial checkpoint.' }, 'Saved a partial checkpoint.'],
    ['missing result', null, ''],
    ['malformed result', { type: 'result', result: { text: 'invalid' } }, null],
  ])('passes only an explicit completion through finalization: %s', async (_label, result, expected) => {
    const { finalizeAgent } = await import('./agentFinalization.js');
    finalizeAgent.mockClear();
    await spawnDirectly(minimalArgs);
    const events = [
      { type: 'assistant', message: { content: [{ type: 'text', text: 'Thinking about files.' }] } },
      { type: 'assistant', message: { content: [{ type: 'text', text: 'Running another command.' }] } },
      ...(result ? [result] : []),
    ];
    fakeProcess.stdout.emit('data', Buffer.from(events.map(event => JSON.stringify(event)).join('\n') + '\n'));
    fakeProcess.stderr.emit('data', Buffer.from('trailing runner diagnostics\n'));
    fakeProcess.emit('close', 0);
    await vi.waitFor(() => expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({ finalSummary: expected })));
  });

  it('drains stdout output on close and a failed batch flush is logged, not leaked as an unhandled rejection', async () => {
    // stdout output is now batched: the data handler pushes lines to the output
    // batcher and the close handler drains it. Make the drain's state write fail
    // and assert the batcher swallows+logs it with a ❌ prefix — no escape.
    agentStateMocks.appendAgentOutputLines.mockRejectedValueOnce(new Error('db write failed'));

    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const unhandledRejections = [];
    const onUnhandled = (reason) => unhandledRejections.push(reason);
    process.on('unhandledRejection', onUnhandled);


    // Act: start spawnDirectly. Note: spawnDirectly awaits getClaudeSettingsEnv()
    // before registering stdout/stderr listeners, so we must yield before emitting.
    const spawnPromise = spawnDirectly(minimalArgs);

    // Yield to let the await inside spawnDirectly resolve so listeners are registered.
    await new Promise((r) => setTimeout(r, 10));

    // Emit a stream-json text delta on stdout so the parser yields a line the
    // handler enqueues into the batcher.
    fakeProcess.stdout.emit('data', Buffer.from(
      '{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"hello\\n"}}}\n'
    ));

    // Give the microtask queue a chance to drain so the async handler runs.
    await new Promise((r) => setTimeout(r, 50));

    // Trigger close so the batcher drains and spawnDirectly resolves.
    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});

    process.off('unhandledRejection', onUnhandled);

    // Assert: error was swallowed into console.error, not an unhandled rejection
    expect(unhandledRejections).toHaveLength(0);
    const logged = consoleSpy.mock.calls.some(
      (args) => typeof args[0] === 'string' && args[0].startsWith('❌ agent agent-test state write failed')
    );
    expect(logged).toBe(true);
  });

  it('prepares the configured Ollama context before a direct CLI agent spawns', async () => {
    vi.mocked(spawn).mockClear();
    vi.mocked(ensureOllamaAgentContext).mockClear();
    vi.mocked(isOllamaBackedProvider).mockReturnValue(true);
    vi.mocked(ensureOllamaAgentContext).mockResolvedValue({
      skipped: false,
      applied: true,
      contextLength: 131072,
      warning: '⚠️ Example context warning',
    });

    const spawnPromise = spawnDirectly({
      ...minimalArgs,
      provider: { ...minimalArgs.provider, id: 'claude-ollama', ollamaBacked: true },
    });
    await new Promise((r) => setTimeout(r, 10));

    expect(ensureOllamaAgentContext).toHaveBeenCalledWith(
      expect.objectContaining({ id: 'claude-ollama' }),
      { model: 'claude-3' },
    );
    expect(ensureOllamaAgentContext.mock.invocationCallOrder[0]).toBeLessThan(spawn.mock.invocationCallOrder[0]);

    fakeProcess.emit('close', 0);
    await spawnPromise;
    await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });

    expect(agentStateMocks.appendAgentOutputLines).toHaveBeenCalledWith('agent-test', [
      '⚠️ Example context warning',
      '🪟 Reloaded Ollama at a 131072-token context window',
    ]);
  });

  it('drains stderr output on close and a failed batch flush is logged, not leaked as an unhandled rejection', async () => {
    agentStateMocks.appendAgentOutputLines.mockRejectedValueOnce(new Error('stderr db write failed'));

    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const unhandledRejections = [];
    const onUnhandled = (reason) => unhandledRejections.push(reason);
    process.on('unhandledRejection', onUnhandled);

    const spawnPromise = spawnDirectly(minimalArgs);

    // Yield to let the await inside spawnDirectly resolve so listeners are registered.
    await new Promise((r) => setTimeout(r, 10));

    // Emit data on stderr to enqueue a batched `[stderr] …` line.
    fakeProcess.stderr.emit('data', Buffer.from('some stderr output\n'));

    await new Promise((r) => setTimeout(r, 50));

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});

    process.off('unhandledRejection', onUnhandled);

    expect(unhandledRejections).toHaveLength(0);
    const logged = consoleSpy.mock.calls.some(
      (args) => typeof args[0] === 'string' && args[0].startsWith('❌ agent agent-test state write failed')
    );
    expect(logged).toBe(true);
  });

  it('publishes a CLI transcript flush with its state batch before admitting a snapshot', async () => {
    const fs = await vi.importActual('node:fs/promises');
    const { tmpdir } = await import('node:os');
    const { writeFileGuarded } = await import('../lib/fileUtils.js');
    const { activeAgents } = await import('./agentState.js');
    const { acquireBackupSnapshotCut } = await import('../lib/backupSnapshotBoundary.js');
    const dir = await fs.mkdtemp(join(tmpdir(), 'cli-publication-'));
    let reached; let finish;
    const reachedPromise = new Promise(resolve => { reached = resolve; });
    const finishPromise = new Promise(resolve => { finish = resolve; });
    writeFileGuarded.mockImplementation((path, bytes, options) => fs.writeFile(path, bytes, options));
    const persistedLines = [];
    agentStateMocks.appendAgentOutputLines.mockImplementation(async (_id, batch) => {
      reached(); await finishPromise;
      persistedLines.push(...batch);
      await fs.writeFile(join(dir, 'state.json'), JSON.stringify({ lines: persistedLines }));
    });
    try {
      await spawnDirectly({ ...minimalArgs, agentDir: dir,
        cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
      fakeProcess.stdout.emit('data', Buffer.from('complete batch\n'));
      const flushing = activeAgents.get('agent-test').flushOutput();
      await reachedPromise;
      // A later chunk must not change either member of the in-flight batch.
      fakeProcess.stdout.emit('data', Buffer.from('later batch\n'));
      await new Promise(resolve => setImmediate(resolve));
      let acquired = false;
      const cut = acquireBackupSnapshotCut().then(release => { acquired = true; return release; });
      try { await new Promise(resolve => setImmediate(resolve)); expect(acquired).toBe(false); }
      finally { finish(); }
      await flushing;
      const release = await cut;
      try {
        expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('complete batch\n');
        expect(JSON.parse(await fs.readFile(join(dir, 'state.json'), 'utf8')).lines).toEqual(['complete batch\n']);
      } finally { release(); }
      await activeAgents.get('agent-test').flushOutput();
      expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('complete batch\nlater batch\n');
      expect(JSON.parse(await fs.readFile(join(dir, 'state.json'), 'utf8')).lines)
        .toEqual(['complete batch\n', 'later batch\n']);
      fakeProcess.emit('close', 0);
      // Completion runs after the in-flight transcript write lands, and since
      // #12025 every atomicWrite fsyncs: the Windows runner needs more than
      // vi.waitFor's 1s default (observed 1045ms) while a never-called cleanup
      // still fails within the budget.
      await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { timeout: 10_000 });
    } finally {
      finish();
      writeFileGuarded.mockResolvedValue(undefined);
      agentStateMocks.appendAgentOutputLines.mockResolvedValue(undefined);
      await fs.rm(dir, { recursive: true, force: true });
    }
  });

  describe('incremental transcript persistence', () => {
    let fs;
    let dir;
    let writeFileGuarded;
    let activeAgents;
    beforeEach(async () => {
      fs = await vi.importActual('node:fs/promises');
      const { tmpdir } = await import('node:os');
      ({ writeFileGuarded } = await import('../lib/fileUtils.js'));
      ({ activeAgents } = await import('./agentState.js'));
      dir = await fs.mkdtemp(join(tmpdir(), 'cli-transcript-'));
      writeFileGuarded.mockReset();
      writeFileGuarded.mockImplementation((path, bytes, options) => fs.writeFile(path, bytes, options));
    });
    afterEach(async () => {
      publicationAdmission.bypass = false;
      writeFileGuarded.mockResolvedValue(undefined);
      await fs.rm(dir, { recursive: true, force: true });
    });
    const finish = async () => {
      fakeProcess.emit('close', 0);
      // Completion runs after the in-flight transcript write lands, and since
      // #12025 every atomicWrite fsyncs: the Windows runner needs more than
      // vi.waitFor's 1s default (observed 1045ms) while a never-called cleanup
      // still fails within the budget.
      await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { timeout: 10_000 });
    };
    const emitTextAndFlush = async text => {
      fakeProcess.stdout.emit('data', Buffer.from(text));
      await activeAgents.get('agent-test').flushOutput();
    };

    it('writes a growing transcript once per byte plus the terminal rewrite, preserving mixed UTF-8 output', async () => {
      // Each flush is a real file write, so wall time scales with the flush count and
      // timed out at 240 under loaded pregate workers. The once-per-byte contract does
      // not depend on cadence: full-prefix writes would submit O(n^2) bytes here
      // (~9.6M for 393,216 bytes of output) versus the 786,432 that deltas plus the
      // final rewrite need.
      publicationAdmission.bypass = true;
      await fs.writeFile(join(dir, 'output.txt'), 'stale previous transcript');
      await spawnDirectly({ ...minimalArgs, agentDir: dir,
        cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
      const FLUSHES = 48;
      const chunk = `é${'x'.repeat(8189)}\n`;
      for (let i = 0; i < FLUSHES; i++) await emitTextAndFlush(chunk);
      fakeProcess.stderr.emit('data', Buffer.from('尾\n'));
      await activeAgents.get('agent-test').flushOutput();
      const expected = `${chunk.repeat(FLUSHES)}[stderr] 尾\n`;
      expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe(expected);
      await finish();
      expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe(expected);
      const submittedBytes = writeFileGuarded.mock.calls.reduce((sum, [, bytes]) => sum + Buffer.byteLength(bytes), 0);
      expect(submittedBytes).toBe(Buffer.byteLength(expected) * 2);
    });

    it('rewrites after an uncertain partial append instead of duplicating or dropping its bytes', async () => {
      vi.spyOn(console, 'error').mockImplementation(() => {});
      await spawnDirectly({ ...minimalArgs, agentDir: dir,
        cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
      await emitTextAndFlush('first\n');
      writeFileGuarded.mockImplementationOnce(async (path, bytes, options) => {
        await fs.writeFile(path, bytes.slice(0, 3), options);
        throw Object.assign(new Error('synthetic partial write'), { code: 'EIO' });
      });
      await emitTextAndFlush('second\n');
      await emitTextAndFlush('third\n');
      expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('first\nsecond\nthird\n');
      expect(agentStateMocks.updateAgent).toHaveBeenCalledWith('agent-test', {
        metadata: { transcriptWriteFailed: { file: 'output.txt', code: 'EIO' } },
      });
      await finish();
    });

    it('waits for an already draining transcript before a second manual drain can finish', async () => {
      await spawnDirectly({ ...minimalArgs, agentDir: dir,
        cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
      let reached;
      let release;
      const reachedPromise = new Promise(resolve => { reached = resolve; });
      const blocked = new Promise(resolve => { release = resolve; });
      writeFileGuarded.mockImplementationOnce(async (path, bytes, options) => {
        reached();
        await blocked;
        await fs.writeFile(path, bytes, options);
      });
      const first = emitTextAndFlush('complete before termination\n');
      await reachedPromise;
      let drained = false;
      const second = activeAgents.get('agent-test').flushOutput().then(() => { drained = true; });
      try {
        await new Promise(resolve => setImmediate(resolve));
        expect(drained).toBe(false);
      } finally { release(); }
      await Promise.all([first, second]);
      expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('complete before termination\n');
      await finish();
    });

    it('replaces streamed progress with the authoritative result when close overlaps a write', async () => {
      await spawnDirectly({ ...minimalArgs, agentDir: dir });
      const delta = text => JSON.stringify({ type: 'stream_event', event: {
        type: 'content_block_delta', delta: { type: 'text_delta', text },
      } }) + '\n';
      await emitTextAndFlush(delta('initial progress\n'));
      let reached;
      let release;
      const reachedPromise = new Promise(resolve => { reached = resolve; });
      const blocked = new Promise(resolve => { release = resolve; });
      writeFileGuarded.mockImplementationOnce(async (path, bytes, options) => {
        reached();
        await blocked;
        await fs.writeFile(path, bytes, options);
      });
      const flushing = emitTextAndFlush(delta('later progress\n'));
      await reachedPromise;
      fakeProcess.stdout.emit('data', Buffer.from(delta('last fragment') + JSON.stringify({
        type: 'result', result: 'Final result that differs from the streamed progress.',
      }) + '\n'));
      const finishing = finish();
      release();
      await Promise.all([flushing, finishing]);
      expect(await fs.readFile(join(dir, 'output.txt'), 'utf8'))
        .toBe('Final result that differs from the streamed progress.');
    });
  });

  it('detects a fallback signal and terminates immediately even while an earlier transcript write is blocked, keeping output ordered (#2384)', async () => {
    killProcessTree.mockClear();

    // Block the FIRST chunk's serialized transcript body at its phase-working
    // updateAgent await (the pid updateAgent at spawn time carries no
    // metadata.phase, so it resolves normally and lets spawn finish).
    let releaseFirstWrite;
    const firstWriteGate = new Promise((r) => { releaseFirstWrite = r; });
    agentStateMocks.updateAgent.mockImplementation((id, patch) => {
      if (patch?.metadata?.phase === 'working') return firstWriteGate;
      return Promise.resolve(undefined);
    });

    // Non-stream provider so outputBuffer is raw text and ordering is trivial to assert.
    const args = {
      ...minimalArgs,
      cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' },
    };

    const spawnPromise = spawnDirectly(args);
    // Yield so spawnDirectly's awaits resolve and the stdout listener registers.
    await new Promise((r) => setTimeout(r, 10));

    // Chunk 1: ordinary output → its serialized write body blocks on the gate.
    fakeProcess.stdout.emit('data', Buffer.from('first output line\n'));
    await new Promise((r) => setTimeout(r, 10));

    // Chunk 2: a usage-limit fallback signal arrives WHILE chunk 1 is blocked.
    // The synchronous detector must fire the kill without waiting for the gate.
    fakeProcess.stdout.emit('data', Buffer.from('Now using extra usage\n'));

    // Assert: termination was immediate — killProcessTree fired synchronously in
    // the data listener, before the blocked first write could settle.
    expect(killProcessTree).toHaveBeenCalledTimes(1);
    expect(killProcessTree.mock.calls[0][1]).toBe('SIGTERM');
    fakeProcess.killed = true;

    // Release the gate, let the serialized chain drain, then close.
    releaseFirstWrite();
    await new Promise((r) => setTimeout(r, 20));
    fakeProcess.emit('close', 143);
    await spawnPromise.catch(() => {});

    // Assert: the two chunks landed in emission order (serialized, not reordered
    // by the blocked first write racing the second).
    const allLines = agentStateMocks.appendAgentOutputLines.mock.calls.flatMap((c) => c[1]);
    const firstIdx = allLines.findIndex((l) => l.includes('first output line'));
    const usageIdx = allLines.findIndex((l) => l.includes('Now using extra usage'));
    expect(firstIdx).toBeGreaterThanOrEqual(0);
    expect(usageIdx).toBeGreaterThan(firstIdx);
  });

  // A headless CLI still colors its progress feed. `opencode run` wraps its
  // status line in bare SGR resets, and those bytes used to reach the transcript
  // verbatim — the browser drops only the ESC, so the agent card rendered
  // `[stderr] [0m` and a working agent read as a wedged one.
  describe('ANSI decoloring of headless CLI output', () => {
    const textArgs = () => ({
      ...minimalArgs,
      cliConfig: { command: 'opencode', args: ['run'], stdinMode: 'prompt', streamFormat: 'text' },
    });

    const emittedLines = () =>
      agentStateMocks.appendAgentOutputLines.mock.calls.flatMap(([, batch]) => batch);

    // The shared mock accumulates across the whole file; these assertions are
    // about the exact transcript ONE run produced.
    beforeEach(() => agentStateMocks.appendAgentOutputLines.mockClear());

    it('strips color codes from stdout and stderr instead of leaking them into the transcript', async () => {
      const spawnPromise = spawnDirectly(textArgs());
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stdout.emit('data', Buffer.from('\x1B[32mbuilding\x1B[0m\n'));
      fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m> build · some-model\n'));
      await new Promise((r) => setTimeout(r, 30));

      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});

      const lines = emittedLines();
      expect(lines).toContain('building\n');
      expect(lines).toContain('[stderr] > build · some-model\n');
      expect(lines.join('')).not.toMatch(/\x1B|\[0m|\[32m/);
    });

    it('reassembles an escape sequence split across two chunks rather than leaking its tail', async () => {
      const spawnPromise = spawnDirectly(textArgs());
      await new Promise((r) => setTimeout(r, 10));

      // The reset straddles the chunk boundary: a per-chunk strip would emit `2m…`.
      fakeProcess.stdout.emit('data', Buffer.from('ready\x1B['));
      await new Promise((r) => setTimeout(r, 20));
      fakeProcess.stdout.emit('data', Buffer.from('32mgreen\n'));
      await new Promise((r) => setTimeout(r, 20));

      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});

      expect(emittedLines().join('')).toBe('readygreen\n');
    });

    it('drops a chunk that was ONLY terminal control rather than tagging a blank [stderr] line', async () => {
      const spawnPromise = spawnDirectly(textArgs());
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m'));
      fakeProcess.stdout.emit('data', Buffer.from('\x1B[0m'));
      await new Promise((r) => setTimeout(r, 30));

      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});

      expect(emittedLines()).not.toContain('[stderr] ');
      expect(emittedLines().some((line) => line.trim() === '')).toBe(false);
    });

    it('drops the claude CLI SDK unrecognized-model telemetry line from the surfaced tail', async () => {
      const spawnPromise = spawnDirectly(textArgs());
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stderr.emit('data', Buffer.from(
        '[claude-code:unrecognized_model] {"model":"gemma3:27b","query_source":"sdk"}\n'
      ));
      await new Promise((r) => setTimeout(r, 30));

      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});

      expect(emittedLines().join('')).not.toMatch(/unrecognized_model/);
    });

    it('still records a colors-only chunk as run output — it is proof the child is alive', async () => {
      // Counting the DECOLORED length would report zero bytes and file a run that
      // was steadily redrawing its progress line as having produced nothing.
      appendRunEvent.mockClear();
      const spawnPromise = spawnDirectly(textArgs());
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m'));
      await new Promise((r) => setTimeout(r, 30));

      const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
      expect(outputs).toHaveLength(1);
      expect(outputs[0].data).toMatchObject({ source: 'cli-stderr' });

      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});
    });

    it('detects a fallback signal that the CLI printed with color codes inside it', async () => {
      // The detector matches provider prose; an SGR pair mid-sentence used to
      // split the phrase and let a usage-limit signal through unnoticed.
      killProcessTree.mockClear();
      const spawnPromise = spawnDirectly(textArgs());
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stdout.emit('data', Buffer.from('\x1B[33mNow using \x1B[1mextra usage\x1B[0m\n'));

      expect(killProcessTree).toHaveBeenCalledTimes(1);
      fakeProcess.killed = true;

      await new Promise((r) => setTimeout(r, 20));
      fakeProcess.emit('close', 143);
      await spawnPromise.catch(() => {});
    });
  });

  it('routes the CLI command through prepareCliSpawn and spawns its resolved+wrapped result (#2243)', async () => {
    // The reported bug: on Windows a bare `opencode`/`claude` .cmd shim can't be
    // spawned directly under shell:false → ENOENT (-4058) → startup-failure.
    // spawnDirectly must hand the command through prepareCliSpawn (resolve +
    // cmd.exe wrap) and spawn WHATEVER it returns — asserted here with a sentinel.
    vi.mocked(prepareCliSpawn).mockReturnValueOnce({
      command: 'cmd.exe',
      args: ['/c', 'C:\\npm\\claude.cmd', '--print'],
    });

    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10)); // let the getClaudeSettingsEnv await settle

    // Called with the logical command + args and the child env (PATH-bearing) so
    // a provider PATH override is honored.
    expect(prepareCliSpawn).toHaveBeenCalledWith(
      minimalArgs.cliConfig.command,
      minimalArgs.cliConfig.args,
      expect.objectContaining({ PATH: expect.anything() }),
    );
    // spawn() received the resolved+wrapped pair, NOT the bare command.
    expect(spawn).toHaveBeenCalledWith(
      'cmd.exe',
      ['/c', 'C:\\npm\\claude.cmd', '--print'],
      expect.objectContaining({ shell: false }),
    );

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  it('injects the repo-owner-pinned GH_TOKEN into the spawn env so the agent\'s own `gh` uses the right account', async () => {
    const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
    vi.mocked(resolveForgeTokenEnv).mockResolvedValueOnce({ GH_TOKEN: 'ghp_pinned_owner_token' });

    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10)); // let the resolveForgeTokenEnv await settle

    // Resolved against the workspace dir (the worktree the agent will PR from).
    expect(resolveForgeTokenEnv).toHaveBeenCalledWith('/tmp');
    expect(spawn).toHaveBeenCalledWith(
      expect.anything(),
      expect.anything(),
      expect.objectContaining({ env: expect.objectContaining({ GH_TOKEN: 'ghp_pinned_owner_token' }) }),
    );

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  // The agent's own prompt hands it `curl`s against this install's API, which is
  // gated whenever an instance password is set. The token is the only way an
  // agent — which holds no browser cookie — can answer that gate.
  it('injects the loopback PortOS API token into the spawn env', async () => {
    const { resolveAgentApiEnv } = await import('./agentApiAuth.js');
    vi.mocked(resolveAgentApiEnv).mockResolvedValueOnce({ PORTOS_API_TOKEN: 'portos-session-token' });

    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10)); // let the resolveAgentApiEnv await settle

    expect(spawn).toHaveBeenCalledWith(
      expect.anything(),
      expect.anything(),
      expect.objectContaining({ env: expect.objectContaining({ PORTOS_API_TOKEN: 'portos-session-token' }) }),
    );

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  it('spawns a Creative Director task in an isolated scratch cwd, not the PortOS root (#4650)', async () => {
    const { creativeDirectorScratchCwd } = await import('../lib/spawnCwd.js');
    const args = {
      ...minimalArgs,
      task: {
        id: 'task-cd',
        description: 'Evaluate scene',
        metadata: { creativeDirector: { projectId: 'p', kind: 'evaluate' }, useWorktree: false },
      },
      workspacePath: '/tmp', // the previous default — must not win over the scratch path
    };
    const spawnPromise = spawnDirectly(args);
    await new Promise((r) => setTimeout(r, 10));
    const expectedCwd = creativeDirectorScratchCwd('agent-test');
    expect(spawn).toHaveBeenCalledWith(
      expect.anything(),
      expect.anything(),
      expect.objectContaining({ cwd: expectedCwd }),
    );
    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  it('leaves the spawn env\'s ambient GH_TOKEN untouched when there is no owner match', async () => {
    const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
    vi.mocked(resolveForgeTokenEnv).mockResolvedValueOnce({});
    const prev = process.env.GH_TOKEN;
    process.env.GH_TOKEN = 'ghp_ambient';

    const spawnPromise = spawnDirectly(minimalArgs);
    await new Promise((r) => setTimeout(r, 10));

    expect(spawn).toHaveBeenCalledWith(
      expect.anything(),
      expect.anything(),
      expect.objectContaining({ env: expect.objectContaining({ GH_TOKEN: 'ghp_ambient' }) }),
    );

    if (prev === undefined) delete process.env.GH_TOKEN; else process.env.GH_TOKEN = prev;
    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  it('skips the owner-token probe when the provider supplies its own GITHUB_TOKEN', async () => {
    const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
    vi.mocked(resolveForgeTokenEnv).mockClear();
    vi.mocked(spawn).mockClear();

    const args = { ...minimalArgs, provider: { ...minimalArgs.provider, envVars: { GITHUB_TOKEN: 'ghp_provider_bot' } } };
    const spawnPromise = spawnDirectly(args);
    await new Promise((r) => setTimeout(r, 10));

    // gh prefers GH_TOKEN over GITHUB_TOKEN — injecting the owner GH_TOKEN would
    // shadow the provider's explicit bot credential, so the probe is skipped.
    expect(resolveForgeTokenEnv).not.toHaveBeenCalled();
    const env = vi.mocked(spawn).mock.calls.at(-1)[2].env;
    expect(env.GITHUB_TOKEN).toBe('ghp_provider_bot');

    fakeProcess.emit('close', 0);
    await spawnPromise.catch(() => {});
  });

  describe('initialization timeout — 3-second phase transition', () => {
    it('calls updateAgent with working phase after 3s when agent has not started working', async () => {
      vi.useFakeTimers();
      const { activeAgents } = await import('./agentState.js');
      const agents = agentStateMocks;

      const spawnPromise = spawnDirectly(minimalArgs);
      // Yield two microtask rounds so the getClaudeSettingsEnv await resolves and
      // the setTimeout is registered before we seed activeAgents.
      await vi.advanceTimersByTimeAsync(10);

      // Manually seed the activeAgents map so the guard inside the timeout passes.
      activeAgents.set(minimalArgs.agentId, { process: fakeProcess });

      await vi.advanceTimersByTimeAsync(3000);

      expect(agents.updateAgent).toHaveBeenCalledWith(
        minimalArgs.agentId,
        { metadata: { phase: 'working' } }
      );

      // Clean up: close the fake process so spawnDirectly can settle.
      activeAgents.delete(minimalArgs.agentId);
      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});
    });

    it('does NOT crash when updateAgent rejects inside the timeout callback', async () => {
      vi.useFakeTimers();
      const { activeAgents } = await import('./agentState.js');
      // spawnDirectly calls updateAgent once synchronously (PID update at line ~406)
      // before the 3-second setTimeout fires. Allow that first call to resolve
      // normally so spawnDirectly doesn't throw before the timeout test begins;
      // then reject the SECOND call (the phase-transition inside the timeout).
      agentStateMocks.updateAgent
        .mockResolvedValueOnce(undefined)     // PID update — let it pass
        .mockRejectedValueOnce(new Error('db write failed')); // timeout update — reject

      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
      const unhandledRejections = [];
      const onUnhandled = (reason) => unhandledRejections.push(reason);
      process.on('unhandledRejection', onUnhandled);

      const spawnPromise = spawnDirectly(minimalArgs);
      await vi.advanceTimersByTimeAsync(10);

      activeAgents.set(minimalArgs.agentId, { process: fakeProcess });

      // Advance the initialization threshold and let the callback's rejected
      // update settle without burning three seconds of wall clock.
      await vi.advanceTimersByTimeAsync(3000);

      process.off('unhandledRejection', onUnhandled);

      expect(unhandledRejections).toHaveLength(0);
      const logged = consoleSpy.mock.calls.some(
        (args) => typeof args[0] === 'string' && args[0].startsWith('❌ agentCliSpawning init timeout failed')
      );
      expect(logged).toBe(true);

      activeAgents.delete(minimalArgs.agentId);
      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});
      consoleSpy.mockRestore();
    });
  });

  it('hands a slashdo-capable harness to the dispatch as owning its PR, with the claim expected', async () => {
    const { finalizeAgent } = await import('./agentFinalization.js');
    finalizeAgent.mockClear();
    const task = {
      id: 'task-rv',
      description: 'do stuff',
      metadata: { openPR: true, reviewers: ['codex', 'antigravity'], reviewStopMode: 'on-clean' },
    };

    spawnDirectly({ ...minimalArgs, task, prOpenedBy: stampPrOpenedBy(task) });
    await new Promise((r) => setTimeout(r, 10));
    fakeProcess.stdout.emit('data', Buffer.from('{"type":"result","result":"ok"}\n'));
    await new Promise((r) => setTimeout(r, 50));
    fakeProcess.emit('close', 0);
    // spawnDirectly returns before the close handler's async cleanup finishes.
    await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledTimes(1), { interval: 5 });

    // A claude-code CLI both owns its PR workflow and can type `/do:pr`, so
    // finalize was expected to verify the claim (its mock here verified none).
    // The reviewer metadata travels on the task; the dispatch resolves it against
    // the Code Review Defaults (agentCompletionCleanup.test.js).
    expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(expect.objectContaining({
      agentId: minimalArgs.agentId,
      task,
      success: true,
      prOwnership: { taskOpenPR: true, prOpenedBy: 'agent-slashdo', agentOpensOwnPr: true, prClaimExpected: true },
      prClaimVerified: false,
    }));
    // The claim predicate, not the ownership one, is what finalize verifies (#3358).
    expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({ prExpected: true }));
  });

  it('hands a read-only CLI run to PortOS using the prompt ownership stamp', async () => {
    const task = { id: 'task-read-only', description: 'analyze the code', metadata: { openPR: true, readOnly: true } };
    const spawnPromise = spawnDirectly({ ...minimalArgs, task, prOpenedBy: stampPrOpenedBy(task) });
    await vi.waitFor(() => expect(fakeProcess.listenerCount('close')).toBeGreaterThan(0));
    fakeProcess.emit('close', 0);
    await spawnPromise;
    await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledTimes(1));
    expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(expect.objectContaining({
      prOwnership: { taskOpenPR: true, prOpenedBy: 'portos', agentOpensOwnPr: false, prClaimExpected: true },
    }));
  });

  // The dispatch releases the retry hold with this verdict (#3368 — its ordering
  // after worktree cleanup is pinned in agentCompletionCleanup.test.js). What
  // this pins is that the close handler hands it the REAL verdict: a hardcoded
  // value would stamp resume pointers on every completed run, or on none.
  it('hands the dispatch the run verdict — failure on a non-zero exit, success on a clean one', async () => {
    const task = { id: 'task-rp', description: 'do stuff', metadata: {} };
    spawnDirectly({ ...minimalArgs, task });
    await new Promise((r) => setTimeout(r, 10));
    fakeProcess.emit('close', 1);
    await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(
      expect.objectContaining({ agentId: minimalArgs.agentId, task, success: false }),
    ), { interval: 5 });

    runSpawnerCompletionCleanup.mockClear();
    fakeProcess = makeFakeProcess();
    spawnDirectly({ ...minimalArgs, task: { id: 'task-rp-ok', description: 'do stuff', metadata: {} } });
    await new Promise((r) => setTimeout(r, 10));
    fakeProcess.stdout.emit('data', Buffer.from('{"type":"result","result":"ok"}\n'));
    await new Promise((r) => setTimeout(r, 50));
    fakeProcess.emit('close', 0);
    await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(
      expect.objectContaining({ success: true }),
    ), { interval: 5 });
  });

  // pm2's TreeKill takes direct-CLI children down with portos-server exactly as
  // it does TUI PTYs (#3202). Finalizing here would charge the task's failure
  // budget — and possibly file an investigation task — for a fault the agent
  // didn't have, and hand its worktree to cleanup, discarding the state a resume
  // needs. The run is abandoned instead, leaving the record `running` for the
  // next boot's orphan sweep to reconcile from the host-shutdown marker.
  describe('host restart (#3202)', () => {
    // The outer beforeEach re-sets implementations but not call history, and the
    // mocks are module-scoped — clear so "was it called" reads only this test.
    beforeEach(async () => {
      const { finalizeAgent } = await import('./agentFinalization.js');
      finalizeAgent.mockClear();
      agentStateMocks.updateAgent.mockClear();
    });

    afterEach(() => resetHostShutdownFlagForTests());

    const runToClose = async (args, code = 0) => {
      spawnDirectly(args);
      await new Promise((r) => setTimeout(r, 10));
      markHostShuttingDown();
      fakeProcess.emit('close', code);
    };

    it('abandons without finalizing or dispatching cleanup', async () => {
      const { finalizeAgent } = await import('./agentFinalization.js');

      await runToClose({ ...minimalArgs });
      await vi.waitFor(() => expect(agentStateMocks.updateAgent).toHaveBeenCalledWith(
        minimalArgs.agentId,
        { metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
      ), { interval: 5 });

      expect(finalizeAgent).not.toHaveBeenCalled();
      expect(runSpawnerCompletionCleanup).not.toHaveBeenCalled();
      // The breadcrumb the orphan sweep falls back on when no marker names the agent.
      expect(agentStateMocks.updateAgent).toHaveBeenCalledWith(
        minimalArgs.agentId,
        { metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
      );
    });

    it('still finalizes a user-terminated run so it is recorded as terminated, not resurrected', async () => {
      const { userTerminatedAgents } = await import('./agentState.js');
      const { finalizeAgent } = await import('./agentFinalization.js');
      userTerminatedAgents.add(minimalArgs.agentId);

      await runToClose({ ...minimalArgs });
      await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });

      expect(finalizeAgent).toHaveBeenCalledWith(
        expect.objectContaining({ terminatedByUser: true, success: false }),
      );
      userTerminatedAgents.delete(minimalArgs.agentId);
    });

    it('still finalizes when the agent already wrote its completion sentinel', async () => {
      const { finalizeAgent } = await import('./agentFinalization.js');
      // The sentinel is named per agent instance so two worktree-less runs
      // sharing one workspace can't be finalized on each other's signal.
      vi.mocked(existsSync).mockImplementation((path) =>
        path === join(minimalArgs.workspacePath, '.agent-done-agent-test'));

      await runToClose({ ...minimalArgs }, null);
      await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });

      expect(finalizeAgent).toHaveBeenCalledWith(
        expect.objectContaining({
          agentId: minimalArgs.agentId,
          success: true,
          workspacePath: minimalArgs.workspacePath,
        }),
      );
    });
  });

  // ── Shared finalize-sequence contract (#6619) ────────────────────────────────
  //
  // The CLI close handler and the TUI `finish()` used to hold two hand-mirrored
  // copies of this teardown, kept in sync by prose comments and running their two
  // gates in OPPOSITE order. These three tests are the oracle for the invariants
  // that mirroring protected — the same three, asserted the same way, live in
  // agentTuiSpawning.test.js. They pin the lane/registry/marker effects that the
  // other suites' finalizeAgent-argument assertions do not observe.
  describe('shared finalize sequence (#6619)', () => {
    beforeEach(async () => {
      const { releaseAgentLane } = await import('./agentFinalization.js');
      const { consumePausedAgentExit } = await import('./agentState.js');
      releaseAgentLane.mockClear();
      consumePausedAgentExit.mockClear();
      agentStateMocks.updateAgent.mockClear();
    });

    afterEach(async () => {
      const { pausedAgents, userTerminatedAgents } = await import('./agentState.js');
      pausedAgents.clear();
      userTerminatedAgents.clear();
      resetHostShutdownFlagForTests();
    });

    // A paused run was already finalized (and lane-released) by markAgentPaused.
    // Re-releasing the same executionId logs a spurious "Invalid state
    // transition", so the paused gate must win over the host-shutdown gate.
    it('paused run exiting during host shutdown takes the paused path, releasing no lane and writing no interrupted marker', async () => {
      const { releaseAgentLane } = await import('./agentFinalization.js');
      const { pausedAgents, consumePausedAgentExit, activeAgents } = await import('./agentState.js');

      spawnDirectly({ ...minimalArgs });
      await new Promise((r) => setTimeout(r, 10));
      pausedAgents.set(minimalArgs.agentId, true);
      markHostShuttingDown();
      fakeProcess.emit('close', 0);

      await vi.waitFor(() => expect(consumePausedAgentExit).toHaveBeenCalledWith(minimalArgs.agentId), { interval: 5 });
      expect(releaseAgentLane).not.toHaveBeenCalled();
      expect(activeAgents.has(minimalArgs.agentId)).toBe(false);
      expect(agentStateMocks.updateAgent).not.toHaveBeenCalledWith(
        minimalArgs.agentId,
        { metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
      );
    });

    // The process can win the race and exit 0 after the user killed it. Recording
    // that as a success leaves the task blocked with a "successful" run attached.
    it('user-terminated run that exits 0 finalizes as failure with the terminated error', async () => {
      const { finalizeAgent, releaseAgentLane } = await import('./agentFinalization.js');
      const { userTerminatedAgents } = await import('./agentState.js');
      userTerminatedAgents.add(minimalArgs.agentId);

      spawnDirectly({ ...minimalArgs });
      await new Promise((r) => setTimeout(r, 10));
      fakeProcess.emit('close', 0);

      await vi.waitFor(() => expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({
        terminatedByUser: true,
        success: false,
        error: 'Agent terminated by user',
      })), { interval: 5 });
      expect(releaseAgentLane).toHaveBeenCalledWith(expect.objectContaining({
        success: false,
        errorExecutionMessage: 'Agent terminated by user',
      }));
      // Consumed, so a later resume of the same agent id is not misread as a kill.
      expect(userTerminatedAgents.has(minimalArgs.agentId)).toBe(false);
    });

    // pm2's TreeKill took the child down with portos-server. The run has no
    // outcome: leave the record `running` for the next boot's orphan sweep and
    // do NOT release the lane through the finalize path.
    it('run interrupted by host shutdown with no sentinel is abandoned without releasing its lane', async () => {
      const { finalizeAgent, releaseAgentLane } = await import('./agentFinalization.js');

      spawnDirectly({ ...minimalArgs });
      await new Promise((r) => setTimeout(r, 10));
      markHostShuttingDown();
      fakeProcess.emit('close', 0);

      await vi.waitFor(() => expect(agentStateMocks.updateAgent).toHaveBeenCalledWith(
        minimalArgs.agentId,
        { metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
      ), { interval: 5 });
      expect(releaseAgentLane).not.toHaveBeenCalled();
      expect(finalizeAgent).not.toHaveBeenCalled();
      // A restart the operator caused, preserved for resume, is the normal path: info, never warn.
      expect(emitLog).toHaveBeenCalledWith('info', expect.stringContaining('interrupted by a PortOS host restart'), expect.any(Object));
      expect(emitLog).not.toHaveBeenCalledWith('warn', expect.stringContaining('interrupted by a PortOS host restart'), expect.anything());
    });
  });

  // #7496. With a credentialBootstrap provider the direct child is the user's
  // bootstrap CLI, not the harness — and `<bootstrap> run <harness> -- <args>`
  // is the shape of a supervising PARENT, not an exec-replacement. A per-pid
  // SIGTERM would leave the harness running (possibly with
  // `--dangerously-skip-permissions` in a worktree, holding a freshly minted
  // credential) after the agent is finalized and its lane released.
  describe('credential-bootstrap process-group teardown', () => {
    const bootstrapArgs = {
      ...minimalArgs,
      provider: {
        ...minimalArgs.provider,
        credentialBootstrap: { command: 'token-cli', args: ['run'], argsSeparator: '--' },
      },
    };

    it('spawns a bootstrap-wrapped child detached and records the flag for the stop paths', async () => {
      const { spawn } = await import('../lib/childProcess.js');
      const { activeAgents } = await import('./agentState.js');
      activeAgents.clear();
      spawn.mockClear();

      const spawnPromise = spawnDirectly(bootstrapArgs);
      await vi.waitFor(() => expect(activeAgents.has(bootstrapArgs.agentId)).toBe(true), { interval: 5 });

      const [command, , options] = spawn.mock.calls.at(-1);
      expect(command).toBe('token-cli');
      expect(options.detached).toBe(EXPECT_GROUP);
      // agentManagement's pause/terminate/force-kill hold only this entry and
      // cannot re-derive the wrap, so the flag has to travel with it.
      expect(activeAgents.get(bootstrapArgs.agentId).processGroup).toBe(EXPECT_GROUP);

      activeAgents.delete(bootstrapArgs.agentId);
      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});
    });

    it('leaves an unwrapped provider attached with no group flag', async () => {
      const { spawn } = await import('../lib/childProcess.js');
      const { activeAgents } = await import('./agentState.js');
      activeAgents.clear();
      spawn.mockClear();

      const spawnPromise = spawnDirectly(minimalArgs);
      await vi.waitFor(() => expect(activeAgents.has(minimalArgs.agentId)).toBe(true), { interval: 5 });

      const [, , options] = spawn.mock.calls.at(-1);
      expect(options.detached).toBe(false);
      expect(activeAgents.get(minimalArgs.agentId).processGroup).toBe(false);

      activeAgents.delete(minimalArgs.agentId);
      fakeProcess.emit('close', 0);
      await spawnPromise.catch(() => {});
    });

    it('kills by process group when a provider-fallback signal stops a wrapped run', async () => {
      killProcessTree.mockClear();
      const spawnPromise = spawnDirectly(bootstrapArgs);
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stdout.emit('data', Buffer.from('Now using extra usage\n'));

      expect(killProcessTree).toHaveBeenCalledTimes(1);
      expect(killProcessTree.mock.calls[0][1]).toBe('SIGTERM');
      expect(killProcessTree.mock.calls[0][2]).toEqual({ processGroup: EXPECT_GROUP });

      fakeProcess.killed = true;
      fakeProcess.emit('close', 143);
      await spawnPromise.catch(() => {});
    });

    it('kills by pid alone when the same signal stops an UNWRAPPED run', async () => {
      killProcessTree.mockClear();
      const spawnPromise = spawnDirectly(minimalArgs);
      await new Promise((r) => setTimeout(r, 10));

      fakeProcess.stdout.emit('data', Buffer.from('Now using extra usage\n'));

      expect(killProcessTree).toHaveBeenCalledTimes(1);
      expect(killProcessTree.mock.calls[0][2]).toEqual({ processGroup: false });

      fakeProcess.killed = true;
      fakeProcess.emit('close', 143);
      await spawnPromise.catch(() => {});
    });
  });
});