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

64.8 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest';
import EventEmitter from 'events';
import { ChildProcess } from '../lib/childProcess.js';
import { markHostShuttingDown, resetHostShutdownFlagForTests } from '../lib/hostShutdown.js';

// executeCliRun validates that a requested workspace actually exists before
// spawning (#3180 — a bad repoPath used to silently run in the PortOS root), so
// these tests need a real directory rather than a synthetic '/workspace' path.
const TEST_WORKSPACE = process.cwd();

vi.mock('../lib/childProcess.js', async (importOriginal) => {
  const actual = await importOriginal();
  return { ...actual, spawn: vi.fn() };
});

// Keep the real killProcessTree (existing tests below rely on its real
// non-Windows SIGTERM branch) but stub resolveWindowsExecutable AND
// prepareWindowsSafeSpawn so the Windows command-resolution/wrap path can be
// driven deterministically regardless of the host platform actually running
// the suite (prepareWindowsSafeSpawn's own win32 check is bound to the real
// platform by default, which is never win32 in CI).
vi.mock('../lib/bufferedSpawn.js', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    resolveWindowsExecutable: vi.fn(() => null),
    prepareWindowsSafeSpawn: vi.fn((command, args) => ({ command, args })),
  };
});

// Spread the real module and override only the three I/O entry points. A
// hand-listed mock silently drops everything else — the cwd resolution reaches
// for PATHS and expandHome, and an absent expandHome failed every run rather
// than only the bad-workspace one (#3180).
vi.mock('../lib/fileUtils.js', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    tryReadFile: vi.fn().mockResolvedValue(null),
    ensureDir: vi.fn().mockResolvedValue(undefined),
    // atomicWrite replaced the raw writeFile(JSON.stringify) metadata sites (#1837);
    // route it through the mocked fs/promises.writeFile so it resolves cleanly.
    atomicWrite: vi.fn(async (filePath, data) => {
      const payload = (typeof data === 'string' || Buffer.isBuffer(data)) ? data : JSON.stringify(data, null, 2);
      const { writeFile } = await import('fs/promises');
      return writeFile(filePath, payload);
    }),
  };
});

vi.mock('fs/promises', () => ({
  writeFile: vi.fn().mockResolvedValue(undefined),
  readFile: vi.fn().mockResolvedValue('{}'),
}));

const { spawn } = await import('../lib/childProcess.js');
const { writeFile, readFile } = await import('fs/promises');
const { atomicWrite, tryReadFile } = await import('../lib/fileUtils.js');
const runner = await import('./runner.js');
const { analyzeError, ERROR_CATEGORIES } = await import('../lib/aiToolkit/errorDetection.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';
const {
  setAIToolkit, executeCliRun, buildCliArgs, hasModelFlag, extractBakedModel,
  emitRunStarted, finalizeRunRecord, patchRunMetadata,
} = runner;

// Minimal toolkit stub that satisfies executeCliRun's expectations. Mirrors the
// real toolkit runner's declared external-run registry (registerExternalRun /
// unregisterExternalRun) that the override now drives instead of poking a
// private `_portosActiveRuns` map.
function fakeToolkit(errorDetection = null) {
  const externalRuns = new Map();
  const externalStopRequests = new Set();
  return {
    services: {
      runner: {
        registerExternalRun: (runId, killable) => {
          externalStopRequests.delete(runId);
          externalRuns.set(runId, killable);
        },
        unregisterExternalRun: (runId) => {
          externalRuns.delete(runId);
          externalStopRequests.delete(runId);
        },
        hasExternalRun: (runId) => externalRuns.has(runId),
        consumeExternalRunStop: (runId) => {
          const requested = externalStopRequests.has(runId);
          externalStopRequests.delete(runId);
          return requested;
        },
        stopRun: async (runId) => {
          const child = externalRuns.get(runId);
          if (!child) return false;
          externalStopRequests.add(runId);
          child.kill('SIGTERM');
          externalRuns.delete(runId);
          return true;
        },
        _externalRuns: externalRuns,
      },
      errorDetection,
    },
  };
}

// Let executeCliRun run to its spawn(): it awaits ensureDir and the cwd
// resolution first, so a single microtask tick is not enough.
const flushMicrotasks = () => new Promise((resolve) => setImmediate(resolve));

function makeChild() {
  const child = new EventEmitter();
  // killProcessTree tells a spawned child from a node-pty session by
  // `instanceof ChildProcess` (a pty takes a different kill shape), so the fake
  // has to carry the prototype the way a real spawn() result does.
  Object.setPrototypeOf(child, ChildProcess.prototype);
  child.stdout = new EventEmitter();
  child.stderr = new EventEmitter();
  // A real ChildProcess stdin is a stream — the fake is one too, or the
  // production guardChildStdin listener has nothing to attach to (#5655).
  child.stdin = Object.assign(new EventEmitter(), { write: vi.fn(), end: vi.fn(), destroy: vi.fn() });
  child.kill = vi.fn();
  child.killed = false;
  return child;
}

beforeEach(() => {
  vi.clearAllMocks();
  resetHostShutdownFlagForTests();
  setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner' });
});

describe('finalizeRunRecord — authoritative timeout classification', () => {
  it('preserves a structured refusal even when output contains a competing error or partial result', async () => {
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner' });
    const errorAnalysis = { category: 'content-refusal', hasError: true, requiresFallback: false, message: 'Stopped' };
    const executionInterruption = { category: 'content-refusal', source: 'provider' };
    const result = await finalizeRunRecord({ runId: 'run-refusal', output: 'Partial result mentions billing',
      exitCode: 1, success: false, error: 'Stopped', startTime: Date.now(),
      extras: { errorAnalysis, executionInterruption } });
    expect(result).toMatchObject({ success: false, errorCategory: 'content-refusal', errorAnalysis, executionInterruption });
  });

  it('does not let story text misclassify exit 124 as a provider quota failure', async () => {
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner' });

    const metadata = await finalizeRunRecord({
      runId: 'run-story-timeout',
      output: 'A character debates billing, payment, and insufficient credit.',
      exitCode: 124,
      success: false,
      error: 'TUI run timed out after 600000ms',
      startTime: Date.now(),
    });

    expect(metadata).toMatchObject({
      success: false,
      errorCategory: ERROR_CATEGORIES.TIMEOUT,
      errorAnalysis: expect.objectContaining({ category: ERROR_CATEGORIES.TIMEOUT }),
    });
  });

  // Exit 124 is not the only authoritative statement of cause: the local-LLM
  // playground aborts its OWN wall-clock deadline and finalizes with exit 1 +
  // "Timed out after Nms", carrying the partial generation as `output`. Scanning
  // that generation matched nothing, so the run landed in UNKNOWN with the
  // story's first line lifted as its error message — and autoFixer escalated a
  // plain timeout as a Tier-4 provider failure titled with the story headline.
  it('classifies a host-deadline timeout from the stated error, not the generation it interrupted', async () => {
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner' });

    const metadata = await finalizeRunRecord({
      runId: 'run-playground-timeout',
      output: '# THE FIRST PAGE OF EVERYTHING\n\nThe light turned every twelve seconds…',
      exitCode: 1,
      success: false,
      error: 'Timed out after 300000ms',
      startTime: Date.now(),
    });

    expect(metadata).toMatchObject({
      success: false,
      error: 'Timed out after 300000ms',
      errorCategory: ERROR_CATEGORIES.TIMEOUT,
    });
    expect(metadata.errorAnalysis.message).not.toContain('THE FIRST PAGE OF EVERYTHING');
  });

  // The other half of the same rule: a CLI/TUI run whose caller only knows the
  // exit code still has to be classified from the provider banner in its output.
  it('still scans the output when the caller states nothing more than the exit code', async () => {
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner' });

    const metadata = await finalizeRunRecord({
      runId: 'run-cli-banner',
      output: "You've hit your usage limit. Upgrade to Pro to keep going.",
      exitCode: 1,
      success: false,
      error: 'Process exited with code 1',
      startTime: Date.now(),
    });

    expect(metadata).toMatchObject({
      errorCategory: ERROR_CATEGORIES.USAGE_LIMIT,
      errorAnalysis: expect.objectContaining({ category: ERROR_CATEGORIES.USAGE_LIMIT }),
    });
  });

  it('records cancellation without scanning output or firing the provider-failure hook', async () => {
    const errorDetection = { analyzeError: vi.fn() };
    const onRunFailed = vi.fn();
    const onRunCanceled = vi.fn();
    setAIToolkit(fakeToolkit(errorDetection), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunFailed, onRunCanceled },
    });

    const metadata = await finalizeRunRecord({
      runId: 'run-canceled-story',
      output: 'A character debates billing, payment, and insufficient credit.',
      exitCode: 130,
      success: false,
      error: 'TUI canceled (signal SIGTERM)',
      startTime: Date.now(),
      extras: { canceled: true, completionReason: 'canceled' },
    });

    expect(metadata).toMatchObject({
      success: false,
      canceled: true,
      errorCategory: ERROR_CATEGORIES.CANCELED,
    });
    expect(errorDetection.analyzeError).not.toHaveBeenCalled();
    expect(onRunFailed).not.toHaveBeenCalled();
    expect(onRunCanceled).toHaveBeenCalledWith({ runId: 'run-canceled-story' });
  });

  // A caller that synthesizes its own run id instead of going through toolkit
  // `createRun` (the local-model benchmark) leaves no metadata.json to merge
  // into, so the record described a run with no id, provider or model. That
  // anonymous record still reached onRunFailed, and autoFixer filed
  // "Investigate AI provider failure: undefined (undefined)" against it —
  // keying its dedupe and circuit breaker on `undefined-undefined`.
  it('attributes a failure with no stored metadata to the run and provider it was given', async () => {
    const onRunFailed = vi.fn();
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner', hooks: { onRunFailed } });

    const metadata = await finalizeRunRecord({
      runId: 'run-no-record',
      output: '',
      exitCode: 1,
      success: false,
      error: 'TUI exited with code 1',
      startTime: Date.now(),
      identity: { providerId: 'opencode-llama-tui', providerName: 'OpenCode', model: 'dflash' },
    });

    expect(metadata).toMatchObject({
      id: 'run-no-record',
      providerId: 'opencode-llama-tui',
      providerName: 'OpenCode',
      model: 'dflash',
    });
    expect(onRunFailed).toHaveBeenCalledWith(
      expect.objectContaining({ id: 'run-no-record', providerName: 'OpenCode', model: 'dflash' }),
      'TUI exited with code 1',
      '',
    );
  });

  it('never lets identity overwrite what the stored run record already says', async () => {
    readFile.mockResolvedValue(JSON.stringify({
      id: 'run-real', providerId: 'claude-cli', providerName: 'Claude Code', model: 'claude-opus-5',
    }));

    const metadata = await finalizeRunRecord({
      runId: 'run-real',
      output: '',
      exitCode: 1,
      success: false,
      error: 'boom',
      startTime: Date.now(),
      identity: { providerId: 'wrong', providerName: 'Wrong', model: 'wrong-model' },
    });

    readFile.mockResolvedValue('{}');
    expect(metadata).toMatchObject({
      id: 'run-real', providerId: 'claude-cli', providerName: 'Claude Code', model: 'claude-opus-5',
    });
  });

  // A benchmark deliberately probes a model that may not work at all — that is
  // the measurement, not evidence a configured provider broke. Escalating it
  // queued a CoS investigation task per failed benchmark run.
  it('finalizes a probe run without firing the provider-failure hook', async () => {
    const onRunFailed = vi.fn();
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner', hooks: { onRunFailed } });

    const metadata = await finalizeRunRecord({
      runId: 'run-probe',
      output: '',
      exitCode: 1,
      success: false,
      error: 'TUI exited with code 1',
      startTime: Date.now(),
      reportFailure: false,
    });

    expect(metadata).toMatchObject({ success: false, exitCode: 1, error: 'TUI exited with code 1' });
    expect(onRunFailed).not.toHaveBeenCalled();
  });
});

describe('failRunRecord — pre-spawn failures reach the caller', () => {
  it('streams the reason, persists the record, and settles onComplete', async () => {
    const onData = vi.fn();
    const onComplete = vi.fn();

    const failure = await runner.failRunRecord({
      runId: 'run-no-binary',
      error: 'TUI command not found: opencode',
      exitCode: 127,
      startTime: Date.now(),
      onData,
      onComplete,
      identity: { providerName: 'OpenCode' },
    });

    expect(onData).toHaveBeenCalledWith('\u274c TUI command not found: opencode');
    expect(failure).toMatchObject({
      id: 'run-no-binary',
      success: false,
      exitCode: 127,
      error: 'TUI command not found: opencode',
      providerName: 'OpenCode',
    });
    expect(onComplete).toHaveBeenCalledWith(failure);
  });

  it('does not let a throwing onComplete escape and strand the run', async () => {
    await expect(runner.failRunRecord({
      runId: 'run-throwing-callback',
      error: 'nope',
      onComplete: () => { throw new Error('callback blew up'); },
    })).resolves.toMatchObject({ success: false });
  });
});

describe('patchRunMetadata — serialized merges', () => {
  it('preserves fields from concurrent attribution patches to the same run', async () => {
    let stored = JSON.stringify({ id: 'run-attribution' });
    tryReadFile.mockImplementation(async () => stored);
    atomicWrite.mockImplementation(async (_path, data) => {
      await Promise.resolve();
      stored = JSON.stringify(data);
    });

    await Promise.all([
      patchRunMetadata('run-attribution', { pipelineStage: 'verifyArc' }),
      patchRunMetadata('run-attribution', { effort: 'high' }),
    ]);

    expect(JSON.parse(stored)).toMatchObject({
      id: 'run-attribution', pipelineStage: 'verifyArc', effort: 'high',
    });
    tryReadFile.mockResolvedValue(null);
    atomicWrite.mockImplementation(async (filePath, data) => {
      const payload = (typeof data === 'string' || Buffer.isBuffer(data)) ? data : JSON.stringify(data, null, 2);
      return writeFile(filePath, payload);
    });
  });
});

describe('executeCliRun — Codex response channel', () => {
  it.each([
    ['Selected model is at capacity. Please try a different model.', ERROR_CATEGORIES.RATE_LIMIT, false],
    ['Authentication failed: invalid API key', ERROR_CATEGORIES.AUTH_ERROR, true],
  ])('reports the provider rejection after the echoed prompt: %s', async (message, category, actionable) => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const onRunFailed = vi.fn();
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner', hooks: { onRunFailed } });
    const onComplete = vi.fn();
    const prompt = 'Example tool schema: {"description":"authentication and billing", "message":"not an error"}';
    await executeCliRun({
      runId: 'run-rejected-model',
      provider: { id: 'codex', command: 'codex', args: [], timeout: 5000 },
      prompt, workspacePath: TEST_WORKSPACE, onComplete,
    });
    const transcript = `OpenAI Codex v1\nuser\n${prompt}\nERROR: ${message}\n`;
    // The input echo can span arbitrary pipe chunks.
    child.stderr.emit('data', Buffer.from(transcript.slice(0, 70)));
    child.stderr.emit('data', Buffer.from(transcript.slice(70)));
    child.emit('close', 1);
    await flushMicrotasks();
    expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
      success: false, error: message, errorCategory: category,
      errorAnalysis: expect.objectContaining({ requiresFallback: true, actionable }),
    }));
    expect(onRunFailed).toHaveBeenCalledWith(expect.objectContaining({ errorCategory: category }), message, transcript);
    expect(writeFile).toHaveBeenCalledWith(expect.stringContaining('output.txt'), transcript);
  });

  it('returns only stdout while retaining diagnostic chunks for observers', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner' });
    const onComplete = vi.fn();
    const onData = vi.fn();
    await executeCliRun({
      runId: 'run-response-channel',
      provider: { id: 'codex', command: 'codex', args: [], timeout: 5000 },
      prompt: 'Return JSON', workspacePath: TEST_WORKSPACE, onData, onComplete,
    });
    child.stderr.emit('data', Buffer.from('OpenAI Codex v1\nuser\n{"message":"example"}\n'));
    child.stdout.emit('data', Buffer.from('{"message":'));
    child.stderr.emit('data', Buffer.from('tokens used\n20\n'));
    child.stdout.emit('data', Buffer.from('"answer"}'));
    child.emit('close', 0);
    await flushMicrotasks();
    expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({ success: true, text: '{"message":"answer"}' }));
    expect(onData).toHaveBeenCalledTimes(4);
  });
});

describe('executeCliRun — wall-clock timeout classification', () => {
  // The CLI runner kills its own child on timeout, so the close event carries
  // `exitCode: null` rather than the 124 finalizeRunRecord keys on. Without the
  // runner's own timeout verdict, the close handler scanned the output — and
  // Codex echoes the entire prompt to stdout, so one word of story prose
  // ("credit") filed a 5-minute timeout as `quota-exceeded`, benching a healthy
  // provider and spawning an investigation task.
  it('classifies its own timeout kill as a timeout instead of scanning story text', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const onRunFailed = vi.fn();
    setAIToolkit(fakeToolkit({ analyzeError }), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunFailed },
    });
    const onComplete = vi.fn();
    const provider = {
      id: 'codex',
      name: 'Codex CLI',
      command: 'codex',
      args: [],
      defaultModel: 'gpt-test',
      timeout: 1,
    };

    await executeCliRun({
      runId: 'run-cli-timeout',
      provider,
      prompt: 'A story about a designer who sends the work on without demanding credit.',
      workspacePath: TEST_WORKSPACE,
      onComplete,
    });
    // Codex echoes the prompt back on stdout, which is how the quota-shaped
    // word reaches the classifier at all.
    child.stdout.emit('data', Buffer.from('...sends the work on without demanding credit.'));
    // Let the 1ms timer fire, then settle the kill the way the OS would.
    await new Promise((resolve) => setTimeout(resolve, 10));
    child.emit('close', null, 'SIGKILL');
    await flushMicrotasks();

    expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
      success: false,
      completionReason: 'timeout',
      errorCategory: ERROR_CATEGORIES.TIMEOUT,
      errorAnalysis: expect.objectContaining({
        category: ERROR_CATEGORIES.TIMEOUT,
        // A timeout is not evidence the provider is unhealthy: it must not
        // route to the actionable/fallback handling quota-exceeded triggers.
        requiresFallback: false,
        actionable: false,
      }),
    }));
    expect(onComplete.mock.calls.at(-1)[0].error).toMatch(/timed out/i);
  });
});

describe('executeCliRun — intentional cancellation', () => {
  it('refuses a stopped caller after CLI preparation before spawning and files a canceled run', async () => {
    const onRunFailed = vi.fn(); const onRunCanceled = vi.fn();
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner', hooks: { onRunFailed, onRunCanceled } });
    await expect(executeCliRun({ runId: 'run-admission', provider: { id: 'codex', type: 'cli', command: 'codex', args: [] },
      prompt: 'hello', workspacePath: TEST_WORKSPACE, beforeExecute: () => { throw new Error('Production stopped'); } }))
      .rejects.toThrow('Production stopped');
    expect(spawn).not.toHaveBeenCalled();
    expect(onRunCanceled).toHaveBeenCalledOnce(); expect(onRunFailed).not.toHaveBeenCalled();
    expect(atomicWrite).toHaveBeenCalledWith(expect.stringContaining('metadata.json'), expect.objectContaining({ canceled: true, errorCategory: ERROR_CATEGORIES.CANCELED }));
  });

  it.each([1, 0])('handles shutdown exit %i without a Node signal or provider penalty', async (exitCode) => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorDetection = { analyzeError: vi.fn() };
    const onRunFailed = vi.fn();
    setAIToolkit(fakeToolkit(errorDetection), {
      dataDir: '/tmp/test-runner', hooks: { onRunFailed },
    });
    const onComplete = vi.fn();
    await executeCliRun({
      runId: 'run-shutdown-code',
      provider: { id: 'codex', command: 'codex', args: [], defaultModel: 'gpt-test', timeout: 5000 },
      prompt: 'A character readily credits competence.',
      workspacePath: TEST_WORKSPACE,
      onComplete,
    });
    child.stdout.emit('data', Buffer.from('A character readily credits competence.\nturn interrupted\n'));
    markHostShuttingDown();
    child.emit('close', exitCode, null);
    await flushMicrotasks();

    expect(onComplete).toHaveBeenCalledWith(expect.objectContaining(exitCode === 0
      ? { success: true }
      : { success: false, canceled: true, completionReason: 'host-shutdown', errorCategory: ERROR_CATEGORIES.CANCELED }));
    expect(errorDetection.analyzeError).not.toHaveBeenCalled();
    expect(onRunFailed).not.toHaveBeenCalled();
  });

  it('skips output classification and provider-failure hooks after stopRun', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorDetection = { analyzeError: vi.fn() };
    const onRunFailed = vi.fn();
    const onRunCanceled = vi.fn();
    const toolkit = fakeToolkit(errorDetection);
    setAIToolkit(toolkit, {
      dataDir: '/tmp/test-runner',
      hooks: { onRunFailed, onRunCanceled },
    });
    const onComplete = vi.fn();
    const provider = {
      id: 'codex',
      name: 'Codex',
      command: 'codex',
      args: [],
      defaultModel: 'gpt-test',
      timeout: 5000,
    };

    await executeCliRun({
      runId: 'run-cli-canceled',
      provider,
      prompt: 'A story about billing and credit.',
      workspacePath: TEST_WORKSPACE,
      onComplete,
    });
    await toolkit.services.runner.stopRun('run-cli-canceled');
    child.emit('close', null, 'SIGTERM');
    await flushMicrotasks();

    expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
      success: false,
      canceled: true,
      completionReason: 'canceled',
      errorCategory: ERROR_CATEGORIES.CANCELED,
    }));
    expect(errorDetection.analyzeError).not.toHaveBeenCalled();
    expect(onRunFailed).not.toHaveBeenCalled();
    expect(onRunCanceled).toHaveBeenCalledWith({ runId: 'run-cli-canceled' });
  });
});

describe('executeCliRun — Codex sentinel suppression', () => {
  it('omits --model when defaultModel is codex-configured-default', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);

    const provider = {
      id: 'codex',
      command: 'codex',
      args: [],
      defaultModel: 'codex-configured-default',
      timeout: 5000,
    };

    setImmediate(() => {
      child.stdout.emit('data', Buffer.from('output'));
      child.emit('close', 0);
    });

    await executeCliRun({ runId: 'run-1', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE });

    const [, capturedArgs] = spawn.mock.calls.at(-1);
    expect(capturedArgs).not.toContain('--model');
    expect(capturedArgs).not.toContain('codex-configured-default');
    // Should still have the exec subcommand and stdin marker
    expect(capturedArgs).toContain('exec');
    expect(capturedArgs).toContain('-');
  });

  it('passes --model when a real model name is provided', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);

    const provider = {
      id: 'codex',
      command: 'codex',
      args: [],
      defaultModel: 'o4-mini',
      timeout: 5000,
    };

    setImmediate(() => {
      child.stdout.emit('data', Buffer.from('output'));
      child.emit('close', 0);
    });

    await executeCliRun({ runId: 'run-2', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE });

    const [, capturedArgs] = spawn.mock.calls.at(-1);
    const modelIdx = capturedArgs.indexOf('--model');
    expect(modelIdx).toBeGreaterThanOrEqual(0);
    expect(capturedArgs[modelIdx + 1]).toBe('o4-mini');
  });

  it('stops the CLI immediately when Claude switches to extra usage', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner' });

    const provider = {
      id: 'claude-code',
      name: 'Claude Code',
      command: 'claude',
      args: [],
      defaultModel: 'claude-opus-4-7',
      timeout: 60000,
    };

    const completed = new Promise((resolve) => {
      executeCliRun({ runId: 'run-extra-usage', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: resolve, timeout: 60000 });
    });

    await flushMicrotasks();
    child.stderr.emit('data', Buffer.from('Now using extra '));
    expect(child.kill).not.toHaveBeenCalled();
    child.stderr.emit('data', Buffer.from('usage\n'));
    expect(child.kill).toHaveBeenCalledWith('SIGTERM');

    child.emit('close', null);
    const metadata = await completed;
    expect(metadata).toMatchObject({
      success: false,
      errorCategory: ERROR_CATEGORIES.USAGE_LIMIT,
      errorAnalysis: expect.objectContaining({
        category: ERROR_CATEGORIES.USAGE_LIMIT,
        requiresFallback: true,
      }),
    });
  });

  it('records failure (not success) when the fallback-killed child exits 0 in the race', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    setAIToolkit(fakeToolkit({ analyzeError }), { dataDir: '/tmp/test-runner' });

    const provider = {
      id: 'claude-code', name: 'Claude Code', command: 'claude', args: [],
      defaultModel: 'claude-opus-4-7', timeout: 60000,
    };

    const completed = new Promise((resolve) => {
      executeCliRun({ runId: 'run-fallback-exit0', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: resolve, timeout: 60000 });
    });

    await flushMicrotasks();
    child.stderr.emit('data', Buffer.from('Now using extra usage\n'));
    expect(child.kill).toHaveBeenCalledWith('SIGTERM');

    // SIGTERM races and the child happens to exit 0 — must NOT be recorded as
    // success, or the usage-limit fallback (onRunFailed) silently never fires.
    child.emit('close', 0);
    const metadata = await completed;
    expect(metadata.success).toBe(false);
    expect(metadata.errorAnalysis).toMatchObject({ requiresFallback: true });
  });
});

describe('executeCliRun — Windows .cmd/.bat shim spawning (#1865)', () => {
  it('wraps a resolved .cmd shim via cmd.exe /c — the actual #1865 fix (never shell:true)', async () => {
    const { resolveWindowsExecutable, prepareWindowsSafeSpawn } = await import('../lib/bufferedSpawn.js');
    const resolvedPath = 'C:\\Users\\Joe\\AppData\\Roaming\\npm\\opencode.cmd';
    vi.mocked(resolveWindowsExecutable).mockReturnValueOnce(resolvedPath);
    // Exercise the REAL wrap logic (not the describe-level identity stub) so
    // this test pins the actual cmd.exe /c contract, with isWin32 forced true
    // since the host running this suite is never win32.
    const { prepareWindowsSafeSpawn: realPrepare } = await vi.importActual('../lib/bufferedSpawn.js');
    vi.mocked(prepareWindowsSafeSpawn).mockImplementationOnce((cmd, args) => realPrepare(cmd, args, true));

    const child = makeChild();
    spawn.mockReturnValue(child);

    const provider = { id: 'codex', command: 'codex', args: ['exec', '-'], timeout: 5000 };

    setImmediate(() => {
      child.stdout.emit('data', Buffer.from('output'));
      child.emit('close', 0);
    });

    await executeCliRun({ runId: 'run-resolved', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE });

    const [command, args, options] = spawn.mock.calls.at(-1);
    expect(command).toBe('cmd.exe');
    // buildCliArgs injects/transforms provider.args per-provider convention —
    // assert the WRAPPING contract (/c + resolved path prepended), not the
    // exact downstream arg list.
    expect(args[0]).toBe('/c');
    expect(args[1]).toBe(resolvedPath);
    // Never set shell:true — DEP0190's unescaped-join hazard. The cmd.exe
    // wrapper relies on Node's own correct non-shell argv escaping instead.
    expect(options.shell).toBeFalsy();
  });

  it('falls back to the bare command when resolution finds nothing (e.g. off win32, or not on PATH)', async () => {
    const { resolveWindowsExecutable } = await import('../lib/bufferedSpawn.js');
    vi.mocked(resolveWindowsExecutable).mockReturnValueOnce(null);

    const child = makeChild();
    spawn.mockReturnValue(child);

    const provider = { id: 'codex', command: 'codex', args: [], timeout: 5000 };

    setImmediate(() => {
      child.stdout.emit('data', Buffer.from('output'));
      child.emit('close', 0);
    });

    await executeCliRun({ runId: 'run-unresolved', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE });

    const [command, , options] = spawn.mock.calls.at(-1);
    expect(command).toBe('codex');
    expect(options.shell).toBeFalsy();
  });
});

describe('executeCliRun — credential-bootstrap wrapping', () => {
  it('spawns the bootstrap CLI in front of the harness when credentialBootstrap is configured', async () => {
    const { resolveWindowsExecutable } = await import('../lib/bufferedSpawn.js');
    vi.mocked(resolveWindowsExecutable).mockReturnValueOnce(null);

    const child = makeChild();
    spawn.mockReturnValue(child);

    const provider = {
      id: 'claude',
      command: 'claude',
      args: [],
      timeout: 5000,
      credentialBootstrap: { command: 'token-cli', args: ['run'], harnessId: 'claude-code', argsSeparator: '--' },
    };

    setImmediate(() => {
      child.stdout.emit('data', Buffer.from('output'));
      child.emit('close', 0);
    });

    await executeCliRun({ runId: 'run-credential-bootstrap', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE });

    const [command, args] = spawn.mock.calls.at(-1);
    expect(command).toBe('token-cli');
    // Exact order: bootstrap args, then the harness by its bootstrap-side id,
    // then the separator, then the harness's own argv — whose prompt-delivery
    // convention (claude's `-p -`) is still resolved against `provider.command`,
    // not the bootstrap CLI. `arrayContaining` would pass with the separator
    // after the harness args, the exact mistake the wrap exists to prevent.
    expect(args).toEqual(['run', 'claude-code', '--', '-p', '-']);
  });

  // #7496. With a bootstrap provider the direct child is the WRAPPER, not the
  // harness, and nothing obliges it to exec-replace itself. A per-pid SIGTERM
  // would then leave the harness running — possibly with
  // `--dangerously-skip-permissions` in a worktree, holding a freshly minted
  // credential — after the run is finalized and the lane released. These assert
  // the group reaches it, and that an unwrapped provider is untouched.
  const bootstrapProvider = (timeout = 5000) => ({
    id: 'claude',
    command: 'claude',
    args: [],
    timeout,
    credentialBootstrap: { command: 'token-cli', args: ['run'], argsSeparator: '--' },
  });

  it('spawns a bootstrap-wrapped child detached, so its process group is signalable', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);

    setImmediate(() => { child.emit('close', 0); });
    await executeCliRun({ runId: 'run-bootstrap-detached', provider: bootstrapProvider(), prompt: 'p', workspacePath: TEST_WORKSPACE });

    const [, , options] = spawn.mock.calls.at(-1);
    expect(options.detached).toBe(EXPECT_GROUP);
  });

  it('leaves an unwrapped provider attached — its direct child IS the harness', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);

    setImmediate(() => { child.emit('close', 0); });
    await executeCliRun({
      runId: 'run-unwrapped-attached',
      provider: { id: 'codex', command: 'codex', args: [], timeout: 5000 },
      prompt: 'p',
      workspacePath: TEST_WORKSPACE,
    });

    const [, , options] = spawn.mock.calls.at(-1);
    expect(options.detached).toBe(false);
  });

  it.skipIf(process.platform === 'win32')('signals the whole process group on timeout for a bootstrap-wrapped run', async () => {
    // Spy so the negative pid never reaches a real process group.
    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
    const child = makeChild();
    child.pid = 424242;
    spawn.mockReturnValue(child);

    const run = executeCliRun({ runId: 'run-bootstrap-timeout', provider: bootstrapProvider(10), prompt: 'p', workspacePath: TEST_WORKSPACE });
    await new Promise(resolve => setTimeout(resolve, 60));

    expect(killSpy).toHaveBeenCalledWith(-424242, 'SIGTERM');
    // The wrapper's own pid is never signalled directly: the group signal
    // succeeded, so killProcessTree returns without the per-pid fallback.
    expect(child.kill).not.toHaveBeenCalled();

    child.emit('close', null);
    await run;
    killSpy.mockRestore();
  });

  it.skipIf(process.platform === 'win32')('signals only the child pid on timeout for an unwrapped run', async () => {
    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
    const child = makeChild();
    child.pid = 515151;
    spawn.mockReturnValue(child);

    const run = executeCliRun({
      runId: 'run-unwrapped-timeout',
      provider: { id: 'codex', command: 'codex', args: [], timeout: 10 },
      prompt: 'p',
      workspacePath: TEST_WORKSPACE,
    });
    await new Promise(resolve => setTimeout(resolve, 60));

    expect(killSpy).not.toHaveBeenCalledWith(-515151, expect.anything());
    expect(child.kill).toHaveBeenCalledWith('SIGTERM');

    child.emit('close', null);
    await run;
    killSpy.mockRestore();
  });

  it.skipIf(process.platform === 'win32')('registers a group-aware killable so /runs Stop reaches the harness, not just the wrapper', async () => {
    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
    const registered = [];
    const toolkit = fakeToolkit();
    toolkit.services.runner.registerExternalRun = vi.fn((runId, killable) => registered.push(killable));
    setAIToolkit(toolkit, { dataDir: '/tmp/test-runner' });

    const child = makeChild();
    child.pid = 616161;
    spawn.mockReturnValue(child);

    setImmediate(() => { child.emit('close', 0); });
    await executeCliRun({ runId: 'run-bootstrap-stop', provider: bootstrapProvider(), prompt: 'p', workspacePath: TEST_WORKSPACE });

    expect(registered).toHaveLength(1);
    // The toolkit's vendored killProcessTree has no processGroup option and
    // reaches a non-ChildProcess killable through its own .kill().
    expect(registered[0]).not.toBe(child);
    expect(registered[0].pid).toBe(616161);
    registered[0].kill('SIGTERM');
    expect(killSpy).toHaveBeenCalledWith(-616161, 'SIGTERM');
    killSpy.mockRestore();
  });

  it('registers the raw child for an unwrapped run, unchanged', async () => {
    const registered = [];
    const toolkit = fakeToolkit();
    toolkit.services.runner.registerExternalRun = vi.fn((runId, killable) => registered.push(killable));
    setAIToolkit(toolkit, { dataDir: '/tmp/test-runner' });

    const child = makeChild();
    child.pid = 717171;
    spawn.mockReturnValue(child);

    setImmediate(() => { child.emit('close', 0); });
    await executeCliRun({
      runId: 'run-unwrapped-stop',
      provider: { id: 'codex', command: 'codex', args: [], timeout: 5000 },
      prompt: 'p',
      workspacePath: TEST_WORKSPACE,
    });

    expect(registered).toEqual([child]);
  });
});

describe('executeCliRun — stdin pipe containment (#5655)', () => {
  const provider = {
    id: 'codex', command: 'codex', args: [],
    defaultModel: 'codex-configured-default', timeout: 5000,
  };

  it('guards the pipe before writing, so a dead child\'s EPIPE cannot crash the server', async () => {
    // executeCliRun runs outside the Express request lifecycle: an unlistened
    // 'error' on the stdin stream is re-thrown by Node and takes the whole
    // server process down with every live run on it.
    const child = makeChild();
    let listenersAtWriteTime = null;
    child.stdin.write = vi.fn(() => { listenersAtWriteTime = child.stdin.listenerCount('error'); });
    spawn.mockReturnValue(child);

    await executeCliRun({ runId: 'run-stdin-guard', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE });

    expect(listenersAtWriteTime).toBe(1);
    expect(() => child.stdin.emit('error', Object.assign(new Error('write EPIPE'), { code: 'EPIPE' }))).not.toThrow();
    child.emit('close', 0);
  });

  it('closes the pipe and logs when the write throws, rather than stranding the run', async () => {
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const child = makeChild();
    child.stdin.write = vi.fn(() => { throw Object.assign(new Error('write EPIPE'), { code: 'EPIPE' }); });
    spawn.mockReturnValue(child);

    const onComplete = vi.fn();
    // The synchronous throw is contained — executeCliRun still returns normally.
    await executeCliRun({ runId: 'run-stdin-throw', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE, onComplete });

    // A child still reading stdin must see EOF instead of waiting on a write that never lands.
    expect(child.stdin.destroy).toHaveBeenCalled();
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('run run-stdin-throw stdin write failed'));

    child.emit('close', 0);
    await new Promise((resolve) => setImmediate(resolve));
    expect(onComplete).toHaveBeenCalledTimes(1);
    errorSpy.mockRestore();
  });
});

describe('executeCliRun — spawn-site error containment (#5792)', () => {
  const provider = {
    id: 'codex', command: 'codex', args: [],
    defaultModel: 'codex-configured-default', timeout: 5000,
  };

  it('contains a throwing onRunStarted instead of orphaning the spawned child', async () => {
    // Pre-fix, onRunStarted was the one hook invocation in runner.js not routed
    // through safeSettle: a throw rejected executeCliRun with the child already
    // spawned and registered, and the terminal 'error'/'close' handlers ~150
    // lines below never got wired.
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    setAIToolkit(fakeToolkit(), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunStarted: () => { throw new Error('started hook boom'); } },
    });

    const onComplete = vi.fn();
    await expect(executeCliRun({
      runId: 'run-started-hook-throws', provider, prompt: 'test prompt',
      workspacePath: TEST_WORKSPACE, onComplete,
    })).resolves.toBe('run-started-hook-throws');

    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('onRunStarted hook threw during recovery'));

    // The run is still fully wired: its terminal handler settles the caller.
    child.emit('close', 0);
    await new Promise((resolve) => setImmediate(resolve));
    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: true });
    errorSpy.mockRestore();
  });

  it('replays an error emitted before setup finishes into the terminal handler exactly once', async () => {
    // An unlistened 'error' on a ChildProcess is re-thrown by Node and kills the
    // server process, so the listener is claimed in the same tick as spawn() and
    // buffered until the real handler exists. onRunStarted fires inside that
    // window, which makes it a faithful stand-in for the racing child.
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    setAIToolkit(fakeToolkit(), {
      dataDir: '/tmp/test-runner',
      hooks: {
        onRunStarted: () => {
          child.emit('error', Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' }));
        },
      },
    });

    const onComplete = vi.fn();
    await executeCliRun({
      runId: 'run-early-spawn-error', provider, prompt: 'test prompt',
      workspacePath: TEST_WORKSPACE, onComplete,
    });
    await new Promise((resolve) => setImmediate(resolve));

    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: false, errorCategory: 'spawn_error' });

    // Node commonly follows a failed spawn's 'error' with 'close'; the run stays settled once.
    child.emit('close', null);
    await new Promise((resolve) => setImmediate(resolve));
    expect(onComplete).toHaveBeenCalledTimes(1);
    errorSpy.mockRestore();
  });
});

describe('executeCliRun — close handler crash guard', () => {
  // Drive a codex run whose first write (output) succeeds and second write
  // (metadata) rejects, so the close handler's recovery path runs. Returns the
  // onComplete spy + console.error spy for assertions.
  async function runWithMetadataWriteFailure(runId, { hooks } = {}) {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    writeFile
      .mockResolvedValueOnce(undefined)
      .mockRejectedValueOnce(new Error('ENOSPC: disk full'));
    if (hooks) setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner', hooks });

    const provider = {
      id: 'codex', command: 'codex', args: [],
      defaultModel: 'codex-configured-default', timeout: 5000,
    };
    const onComplete = vi.fn();
    await executeCliRun({ runId, provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE, onComplete });

    child.stdout.emit('data', Buffer.from('output'));
    child.emit('close', 0);
    await new Promise((resolve) => setImmediate(resolve)); // let the detached handler settle
    return { onComplete, errorSpy };
  }

  it('does not crash and still settles the caller when a metadata write fails on close', async () => {
    const { onComplete, errorSpy } = await runWithMetadataWriteFailure('run-write-fail');

    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('run-write-fail close handler error'));
    // The caller must still be settled with failure metadata, not left hanging.
    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: false, errorCategory: 'finalization_error' });
    errorSpy.mockRestore();
  });

  it('still settles onComplete when the recovery onRunFailed hook itself throws', async () => {
    // Metadata write fails AND the recovery onRunFailed hook throws — the
    // caller must STILL be settled (the hook must not block onComplete).
    const { onComplete, errorSpy } = await runWithMetadataWriteFailure('run-hook-throws', {
      hooks: { onRunFailed: () => { throw new Error('hook boom'); } },
    });

    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: false, errorCategory: 'finalization_error' });
    errorSpy.mockRestore();
  });

  it('does not flip a successful run to failed when onRunCompleted throws', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    // Writes succeed (success path runs); the success hook throws — the caller
    // must still receive success:true, not a finalization-failure flip.
    writeFile.mockResolvedValue(undefined);
    setAIToolkit(fakeToolkit(), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunCompleted: () => { throw new Error('hook boom'); } },
    });

    const provider = {
      id: 'codex', command: 'codex', args: [],
      defaultModel: 'codex-configured-default', timeout: 5000,
    };
    const onComplete = vi.fn();
    await executeCliRun({ runId: 'run-success-hook-throws', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE, onComplete });

    child.stdout.emit('data', Buffer.from('output'));
    child.emit('close', 0);
    await new Promise((resolve) => setImmediate(resolve));

    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: true });
    errorSpy.mockRestore();
  });

  it('observes a rejected promise from an async completion hook (no unhandled rejection)', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    writeFile.mockResolvedValue(undefined);
    // An async hook that REJECTS — safeSettle must attach a .catch so it does
    // not escape as an unhandled rejection, and onComplete must still settle.
    setAIToolkit(fakeToolkit(), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunCompleted: () => Promise.reject(new Error('async hook boom')) },
    });

    const provider = {
      id: 'codex', command: 'codex', args: [],
      defaultModel: 'codex-configured-default', timeout: 5000,
    };
    const onComplete = vi.fn();
    await executeCliRun({ runId: 'run-async-hook-rejects', provider, prompt: 'test prompt', workspacePath: TEST_WORKSPACE, onComplete });

    child.stdout.emit('data', Buffer.from('output'));
    child.emit('close', 0);
    await new Promise((resolve) => setImmediate(resolve));

    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: true });
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('onRunCompleted hook threw during recovery'));
    errorSpy.mockRestore();
  });

  it('finalizes a spawn error exactly once when error is followed by close', async () => {
    const child = makeChild();
    spawn.mockReturnValue(child);
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const onRunFailed = vi.fn();
    const onComplete = vi.fn();
    setAIToolkit(fakeToolkit(), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunFailed },
    });
    readFile.mockResolvedValueOnce(JSON.stringify({
      id: 'run-spawn-error',
      providerId: 'configured-provider',
      providerName: 'Configured Provider',
      model: 'configured-model',
      workspacePath: '/configured/workspace',
      workspaceName: 'configured-workspace',
      source: 'test-source',
      startTime: '2026-07-10T00:00:00.000Z',
    }));

    const provider = {
      id: 'codex', name: 'Codex', command: 'codex', args: [],
      defaultModel: 'codex-configured-default', timeout: 5000,
    };
    await executeCliRun({
      runId: 'run-spawn-error',
      provider,
      prompt: 'test prompt',
      workspacePath: TEST_WORKSPACE,
      onComplete,
    });

    child.emit('error', new Error('spawn ENOENT'));
    child.emit('close', -1);

    await vi.waitFor(() => expect(onComplete).toHaveBeenCalledTimes(1));
    expect(onRunFailed).toHaveBeenCalledTimes(1);
    const metadataWrites = atomicWrite.mock.calls.filter(([path]) => path.endsWith('metadata.json'));
    expect(metadataWrites).toHaveLength(1);

    const persisted = metadataWrites[0][1];
    expect(persisted).toMatchObject({
      id: 'run-spawn-error',
      providerId: 'configured-provider',
      providerName: 'Configured Provider',
      model: 'configured-model',
      workspacePath: '/configured/workspace',
      workspaceName: 'configured-workspace',
      source: 'test-source',
      exitCode: -1,
      success: false,
      error: 'Spawn failed: spawn ENOENT',
      errorCategory: 'spawn_error',
    });
    expect(onComplete).toHaveBeenCalledWith(persisted);
    errorSpy.mockRestore();
  });
});

describe('buildCliArgs — claude-code defaultModel honoring', () => {
  it('appends --model <id> after `-p -` for claude-code', () => {
    const provider = { id: 'claude-code', command: 'claude', args: [], defaultModel: 'claude-opus-4-7' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['-p', '-', '--model', 'claude-opus-4-7']);
  });

  it('omits --model when defaultModel is unset', () => {
    const provider = { id: 'claude-code', command: 'claude', args: [], defaultModel: null };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['-p', '-']);
  });

  it('respects a user-baked --model in provider.args and does NOT duplicate', () => {
    const provider = {
      id: 'claude-code',
      command: 'claude',
      args: ['--model', 'claude-sonnet-4-5'],
      defaultModel: 'claude-opus-4-7',
    };
    const args = buildCliArgs(provider);
    // baked model wins, no extra trailing flag
    expect(args).toEqual(['--model', 'claude-sonnet-4-5', '-p', '-']);
    expect(args.filter((a) => a === '--model').length).toBe(1);
  });

  it('respects a user-baked --model=value joined form', () => {
    const provider = {
      id: 'claude-code',
      command: 'claude',
      args: ['--model=claude-sonnet-4-5'],
      defaultModel: 'claude-opus-4-7',
    };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['--model=claude-sonnet-4-5', '-p', '-']);
  });
});

describe('buildCliArgs — gemini-cli defaultModel honoring', () => {
  it('appends -m <id> for legacy gemini-cli', () => {
    const provider = { id: 'gemini-cli', command: 'gemini', args: [], defaultModel: 'gemini-2.5-pro' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['-m', 'gemini-2.5-pro']);
  });

  it('omits -m when defaultModel is unset', () => {
    const provider = { id: 'gemini-cli', command: 'gemini', args: [], defaultModel: null };
    const args = buildCliArgs(provider);
    expect(args).toEqual([]);
  });

  it('respects a user-baked -m in provider.args', () => {
    const provider = {
      id: 'gemini-cli',
      command: 'gemini',
      args: ['-m', 'gemini-2.0-flash'],
      defaultModel: 'gemini-2.5-pro',
    };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['-m', 'gemini-2.0-flash']);
    expect(args.filter((a) => a === '-m').length).toBe(1);
  });

  it('respects a user-baked --model in provider.args (long-form)', () => {
    const provider = {
      id: 'gemini-cli',
      command: 'gemini',
      args: ['--model', 'gemini-2.0-flash'],
      defaultModel: 'gemini-2.5-pro',
    };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['--model', 'gemini-2.0-flash']);
  });
});

describe('buildCliArgs — antigravity-cli headless mode', () => {
  it('uses agy print mode and does not pass model flags', () => {
    const provider = { id: 'antigravity-cli', command: 'agy', args: [], defaultModel: 'antigravity-configured-default' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['--dangerously-skip-permissions', '--print']);
  });

  it('strips legacy Gemini flags during invocation', () => {
    const provider = { id: 'antigravity-cli', command: 'agy', args: ['--yolo', '-m', 'gemini-2.5-pro', '--output-format', 'text'], defaultModel: 'antigravity-configured-default' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['--dangerously-skip-permissions', '--print']);
  });
});

describe('buildCliArgs — codex (regression coverage for the existing logic)', () => {
  it('omits --model when defaultModel is the sentinel', () => {
    const provider = { id: 'codex', command: 'codex', args: [], defaultModel: 'codex-configured-default' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['exec', '-c', 'check_for_update_on_startup=false', '-']);
  });

  it('appends --model when a real model is given', () => {
    const provider = { id: 'codex', command: 'codex', args: [], defaultModel: 'o4-mini' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['exec', '-c', 'check_for_update_on_startup=false', '--model', 'o4-mini', '-']);
  });
});

describe('buildCliArgs — strips dangling --model from baseArgs before injecting', () => {
  it('drops a bare --model at end of args (claude-code) and appends the valid one', () => {
    const provider = { id: 'claude-code', command: 'claude', args: ['--model'], defaultModel: 'sonnet-3.7' };
    const args = buildCliArgs(provider);
    // Bare --model would survive into argv and conflict with our injected
    // --model sonnet-3.7. The sanitizer drops it so only the valid pair remains.
    expect(args).toEqual(['-p', '-', '--model', 'sonnet-3.7']);
  });

  it('drops a --model followed by another flag (gemini-cli) and appends the valid one', () => {
    const provider = { id: 'gemini-cli', command: 'gemini', args: ['-m', '--other'], defaultModel: 'gemini-flash' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['--other', '-m', 'gemini-flash']);
  });

  it('drops an empty joined model flag (--model=) and appends the valid one', () => {
    const provider = { id: 'claude-code', command: 'claude', args: ['--model='], defaultModel: 'sonnet-3.7' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['-p', '-', '--model', 'sonnet-3.7']);
  });

  it('drops dangling --model on codex too (regression)', () => {
    const provider = { id: 'codex', command: 'codex', args: ['--model'], defaultModel: 'o4-mini' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['exec', '-c', 'check_for_update_on_startup=false', '--model', 'o4-mini', '-']);
  });

  it('preserves a properly-pinned --model and does NOT inject our own', () => {
    const provider = { id: 'claude-code', command: 'claude', args: ['--model', 'baked-in'], defaultModel: 'would-be-ignored' };
    const args = buildCliArgs(provider);
    expect(args).toEqual(['--model', 'baked-in', '-p', '-']);
  });
});

describe('hasModelFlag', () => {
  it('detects separated long form (--model X)', () => {
    expect(hasModelFlag(['--model', 'foo'])).toBe(true);
  });
  it('detects separated short form (-m X)', () => {
    expect(hasModelFlag(['-m', 'foo'])).toBe(true);
  });
  it('detects joined long form (--model=X)', () => {
    expect(hasModelFlag(['--model=foo'])).toBe(true);
  });
  it('detects joined short form (-m=X)', () => {
    expect(hasModelFlag(['-m=foo'])).toBe(true);
  });
  it('returns false when no model flag is present', () => {
    expect(hasModelFlag(['--other', 'foo'])).toBe(false);
    expect(hasModelFlag([])).toBe(false);
  });
  it('returns false for non-array input', () => {
    expect(hasModelFlag(null)).toBe(false);
    expect(hasModelFlag(undefined)).toBe(false);
    expect(hasModelFlag('--model foo')).toBe(false);
  });
  it('returns false for a separated flag at end of argv (no value follows)', () => {
    expect(hasModelFlag(['--model'])).toBe(false);
    expect(hasModelFlag(['-m'])).toBe(false);
    expect(hasModelFlag(['--other', '--model'])).toBe(false);
  });
  it('returns false when the value following looks like another flag', () => {
    expect(hasModelFlag(['--model', '--other'])).toBe(false);
    expect(hasModelFlag(['-m', '-x'])).toBe(false);
  });
  it('returns false for an empty joined value (--model= / -m=)', () => {
    expect(hasModelFlag(['--model='])).toBe(false);
    expect(hasModelFlag(['-m='])).toBe(false);
  });
});

describe('extractBakedModel', () => {
  it('extracts from separated long form', () => {
    expect(extractBakedModel(['--model', 'sonnet-3.7'])).toBe('sonnet-3.7');
  });
  it('extracts from separated short form', () => {
    expect(extractBakedModel(['-m', 'gemini-2.5-pro'])).toBe('gemini-2.5-pro');
  });
  it('extracts from joined long form', () => {
    expect(extractBakedModel(['--model=opus-4.7'])).toBe('opus-4.7');
  });
  it('extracts from joined short form', () => {
    expect(extractBakedModel(['-m=gemini-flash'])).toBe('gemini-flash');
  });
  it('returns null when separated form has no value following the flag', () => {
    expect(extractBakedModel(['--model'])).toBe(null);
  });
  it('returns null when the value following looks like another flag (matches hasModelFlag)', () => {
    // Without this guard, extractBakedModel would extract '--other' as the
    // model id while hasModelFlag returned false, leaving the two functions
    // out of sync. Both must agree on what counts as a real pin.
    expect(extractBakedModel(['--model', '--other'])).toBe(null);
    expect(extractBakedModel(['-m', '-x'])).toBe(null);
  });
  it('returns null when no model flag is present', () => {
    expect(extractBakedModel(['--other', 'foo'])).toBe(null);
    expect(extractBakedModel([])).toBe(null);
  });
  it('returns null for non-array input', () => {
    expect(extractBakedModel(null)).toBe(null);
    expect(extractBakedModel(undefined)).toBe(null);
  });
  it('returns the FIRST baked flag when more than one is present', () => {
    expect(extractBakedModel(['--model', 'first', '-m', 'second'])).toBe('first');
  });
});

// emitRunStarted's payload-flattening contract is consumed by tuiPromptRunner.js
// (and any future non-toolkit execution path) — the TUI tests mock emitRunStarted
// itself, so this is the only place the `name || id` and `model ?? defaultModel`
// fallbacks are pinned. A regression here would silently break run-tracking
// attribution without any other suite catching it.
describe('emitRunStarted — payload-flattening contract', () => {
  function captureHook() {
    const onRunStarted = vi.fn();
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner', hooks: { onRunStarted } });
    return onRunStarted;
  }

  it('prefers provider.name over provider.id when both are present', () => {
    const onRunStarted = captureHook();
    emitRunStarted({
      runId: 'r1',
      provider: { name: 'codex', id: 'codex-id', defaultModel: 'gpt-5' },
      model: 'gpt-4o',
    });
    expect(onRunStarted).toHaveBeenCalledWith({ runId: 'r1', provider: 'codex', model: 'gpt-4o' });
  });

  it('falls back to provider.id when provider.name is missing', () => {
    const onRunStarted = captureHook();
    emitRunStarted({
      runId: 'r2',
      provider: { id: 'gemini-cli', defaultModel: 'gemini-2.5-pro' },
      model: 'gemini-2.0-flash',
    });
    expect(onRunStarted).toHaveBeenCalledWith({ runId: 'r2', provider: 'gemini-cli', model: 'gemini-2.0-flash' });
  });

  it('uses the explicit model argument when given (overrides provider.defaultModel)', () => {
    const onRunStarted = captureHook();
    emitRunStarted({
      runId: 'r3',
      provider: { name: 'claude-code', defaultModel: 'claude-opus-4-7' },
      model: 'claude-sonnet-4-6',
    });
    expect(onRunStarted).toHaveBeenCalledWith({ runId: 'r3', provider: 'claude-code', model: 'claude-sonnet-4-6' });
  });

  it('falls back to provider.defaultModel when model is undefined', () => {
    const onRunStarted = captureHook();
    emitRunStarted({
      runId: 'r4',
      provider: { name: 'codex', defaultModel: 'codex-configured-default' },
      model: undefined,
    });
    expect(onRunStarted).toHaveBeenCalledWith({
      runId: 'r4',
      provider: 'codex',
      model: 'codex-configured-default',
    });
  });

  it('falls back to provider.defaultModel when model is null (?? semantics)', () => {
    const onRunStarted = captureHook();
    emitRunStarted({
      runId: 'r5',
      provider: { name: 'codex', defaultModel: 'o4-mini' },
      model: null,
    });
    expect(onRunStarted).toHaveBeenCalledWith({ runId: 'r5', provider: 'codex', model: 'o4-mini' });
  });

  it('keeps an empty-string model rather than falling back (?? treats "" as defined)', () => {
    // Guards the ?? semantics — if this ever flips to ||, intentionally-empty
    // models would be silently rewritten to defaultModel.
    const onRunStarted = captureHook();
    emitRunStarted({
      runId: 'r6',
      provider: { name: 'codex', defaultModel: 'o4-mini' },
      model: '',
    });
    expect(onRunStarted).toHaveBeenCalledWith({ runId: 'r6', provider: 'codex', model: '' });
  });

  it('emits undefined provider/model when provider is missing entirely', () => {
    const onRunStarted = captureHook();
    emitRunStarted({ runId: 'r7', provider: undefined, model: undefined });
    expect(onRunStarted).toHaveBeenCalledWith({ runId: 'r7', provider: undefined, model: undefined });
  });

  it('is a no-op when no onRunStarted hook is registered', () => {
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner' });
    expect(() => emitRunStarted({
      runId: 'r8',
      provider: { name: 'codex', defaultModel: 'o4-mini' },
      model: 'gpt-4',
    })).not.toThrow();
  });

  it('contains a throwing onRunStarted hook instead of rejecting the TUI spawn path (#6002)', () => {
    // emitRunStarted fires after the PTY is already registered in the
    // active-run map (tuiPromptRunner.js), so a throw here would reject the
    // spawn with a live PTY and no terminal settlement — the same orphaned
    // shape #5792 closed for the CLI path.
    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    setAIToolkit(fakeToolkit(), {
      dataDir: '/tmp/test-runner',
      hooks: { onRunStarted: () => { throw new Error('tui started hook boom'); } },
    });
    expect(() => emitRunStarted({
      runId: 'r-tui-throw',
      provider: { name: 'codex', defaultModel: 'gpt-5' },
      model: 'gpt-4o',
    })).not.toThrow();
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('onRunStarted hook threw during recovery'));
    errorSpy.mockRestore();
  });
});

describe('executeCliRun — workspace validation (#3180)', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner' });
  });

  const provider = { id: 'codex', name: 'Codex', command: 'codex', args: [], timeout: 5000 };

  // The bug: a workspace that doesn't exist used to fall through to spawn(),
  // which quietly ran the agent in the PortOS checkout. A prompt naming a
  // relative file then wrote into the wrong repo with no error anywhere.
  // Also asserts the call RESOLVES rather than rejecting: the /runs route
  // invokes executeCliRun without awaiting it, so a bare throw would surface
  // only as an unhandled rejection and leave the run looking stuck.
  it('fails the run instead of spawning when the workspace does not exist', async () => {
    const onComplete = vi.fn();
    const onData = vi.fn();

    await expect(executeCliRun({
      runId: 'run-bad-workspace',
      provider,
      prompt: 'test prompt',
      workspacePath: '/definitely/not/a/real/repo/path',
      onData,
      onComplete,
    })).resolves.toBeUndefined();

    expect(spawn).not.toHaveBeenCalled();
    expect(onData).toHaveBeenCalledWith(expect.stringContaining('Workspace path does not exist'));
    expect(onComplete).toHaveBeenCalledTimes(1);
    expect(onComplete.mock.calls[0][0]).toMatchObject({ success: false });
  });
});

describe('resolveRunCwd — callback containment (#3180)', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    setAIToolkit(fakeToolkit(), { dataDir: '/tmp/test-runner' });
  });

  // /runs never awaits its executor, so a throwing onComplete here would reject
  // resolveRunCwd AFTER the failed run was persisted — landing as the unhandled
  // rejection and hung-looking run this helper exists to prevent.
  it('does not reject when the caller onComplete throws on the failure path', async () => {
    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const onComplete = vi.fn(() => { throw new Error('caller exploded'); });

    await expect(runner.resolveRunCwd({
      runId: 'run-cb-throws',
      workspacePath: '/definitely/not/a/real/repo/path',
      label: 'Run cb',
      onComplete,
    })).resolves.toMatchObject({ failure: expect.objectContaining({ success: false }) });

    expect(onComplete).toHaveBeenCalledTimes(1);
    errSpy.mockRestore();
  });

  it('does not reject when the caller onComplete rejects asynchronously', async () => {
    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const onComplete = vi.fn(async () => { throw new Error('async caller exploded'); });

    await expect(runner.resolveRunCwd({
      runId: 'run-cb-rejects',
      workspacePath: '/definitely/not/a/real/repo/path',
      label: 'Run cb2',
      onComplete,
    })).resolves.toBeTruthy();
    errSpy.mockRestore();
  });

  // The whitespace-only repoPath z.string().min(1) still lets through.
  it('fails the run for a whitespace-only workspace rather than using the root', async () => {
    const onComplete = vi.fn();
    const { failure, cwd } = await runner.resolveRunCwd({
      runId: 'run-blank-ws', workspacePath: '   ', label: 'Run blank', onComplete,
    });
    expect(cwd).toBeUndefined();
    expect(failure).toMatchObject({ success: false });
    expect(failure.error).toMatch(/blank/);
  });
});