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

92.2 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mkdtemp, rm, writeFile } from 'fs/promises';
import { tmpdir } from 'os';
import { join, resolve } from 'path';

// executeTuiRun 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 '/cwd' sentinel.
const TEST_WORKSPACE = process.cwd();

// node-pty + runner hooks are mocked so executeTuiRun can be driven
// synchronously from the test without spawning a real terminal. fileUtils
// stays real except for `ensureDir` (which would otherwise create real run
// directories the SUT never needs in these tests) and `tryReadFile` (which
// serves seeded response files from memory — see below). Mocks live
// inside vi.hoisted so the vi.mock factories (which are themselves hoisted
// to the top of the file) can reference them.
const { ptyInstances, ptySpawnMock, runnerMocks, shellMocks, runsTmpDirRef, responseFiles, processEnvMocks } = vi.hoisted(() => ({
  ptyInstances: [],
  ptySpawnMock: vi.fn(),
  // The pre-spawn binary probe. Defaults to "resolved" so every other test in
  // this file exercises the spawn path regardless of which agent CLIs happen to
  // be installed on the host running the suite.
  processEnvMocks: {
    findCommandOnPath: vi.fn((name) => `/usr/local/bin/${name}`),
  },
  runsTmpDirRef: { current: null },
  // Absolute response-file path → contents, for the runs driven under fake
  // timers (see the fileUtils mock below).
  responseFiles: new Map(),
  runnerMocks: {
    finalizeRunRecord: vi.fn(),
    failRunRecord: vi.fn(async ({ runId, error, exitCode, onData, onComplete }) => {
      const failure = { id: runId, success: false, exitCode, error };
      onData?.(`\u274c ${error}`);
      onComplete?.(failure);
      return failure;
    }),
    emitRunStarted: vi.fn(),
    registerActiveRun: vi.fn(),
    unregisterActiveRun: vi.fn(),
    consumeRunStopRequested: vi.fn(() => false),
    getRunsPath: vi.fn(),
    // Real implementation (and its bad-workspace failure path) is covered by
    // lib/spawnCwd.test.js + services/runner.test.js; here it just needs to
    // hand back the cwd so the PTY spawn assertions below still see it.
    resolveRunCwd: vi.fn(async ({ workspacePath }) => ({ cwd: workspacePath })),
  },
  // shell.js is mocked so the runner's Shell-view registration is observable
  // here without dragging in the real session registry singleton.
  // isExternalSessionAttached defaults to "no viewer" so idle/timeout fire as
  // they would for an unattended pipeline run; tests flip it to assert the pause.
  shellMocks: {
    registerExternalSession: vi.fn(),
    unregisterExternalSession: vi.fn(),
    isExternalSessionAttached: vi.fn(() => false),
    // The run registers its own PTY as an external session, so a paste routed
    // through the session registry lands back on that PTY. Modelled faithfully
    // (bracketed paste, then the submit Enter, then an interval handle for the
    // caller to cancel) so assertions can read pty.write like the direct path.
    pasteToSession: vi.fn((_sessionId, text) => {
      const pty = ptyInstances[ptyInstances.length - 1];
      if (!pty) return false;
      pty.write(`\x1b[200~${text}\x1b[201~`);
      pty.write('\r');
      return setInterval(() => {}, 60000);
    }),
  },
}));
runnerMocks.getRunsPath.mockImplementation(() => runsTmpDirRef.current);

vi.mock('node-pty', () => ({ spawn: (...args) => ptySpawnMock(...args) }));
vi.mock('./runner.js', () => runnerMocks);
vi.mock('./shell.js', () => shellMocks);
vi.mock('../lib/processEnv.js', async () => {
  const actual = await vi.importActual('../lib/processEnv.js');
  return { ...actual, findCommandOnPath: (...args) => processEnvMocks.findCommandOnPath(...args) };
});
vi.mock('../lib/fileUtils.js', async () => {
  const actual = await vi.importActual('../lib/fileUtils.js');
  // Imported here rather than relied on from the module scope: vi.mock
  // factories are hoisted above the import list.
  const { resolve: resolvePath } = await import('path');
  return {
    ...actual,
    ensureDir: vi.fn(async () => {}),
    // Response-file reads resolve from `responseFiles` when the test seeded
    // that path, and fall through to the real read otherwise (the
    // resolveTuiResponseText suite below drives real temp files directly).
    //
    // Why in-memory (#3874): executeTuiRun's size-stability window is polled
    // on a 1s interval that these suites drive with fake timers, but a REAL
    // `readFile` resolves on the libuv threadpool — advancing fake timers
    // does not wait for it. Under load a poll's read could land after the
    // test moved on, so the baseline was never seeded and the run took the
    // timeout/fallback path instead of the response-file path. A seeded read
    // settles as a microtask, which timer advancement always drains.
    // Keys are normalized on both sides so a relative or unnormalized path
    // from the SUT still hits the seeded entry rather than silently falling
    // through to a real (missing-file) read.
    //
    // The UNSEEDED reads under the runs dir have to be served from memory too,
    // for the same reason. Those are the polls that fire before a test seeds
    // its file; letting them hit the real threadpool means one can still be
    // in flight when the seed lands, and its late `null` resets the
    // size-stability baseline that the post-seed poll just established — so
    // the salvage path sees an unsettled file and finishes as a plain
    // fallback. That reproduces about one run in three. Everything outside the
    // runs dir still falls through: the resolveTuiResponseText suite below
    // drives real files in a temp dir of its own.
    tryReadFile: vi.fn(async (filePath, ...rest) => {
      const key = resolvePath(filePath);
      if (responseFiles.has(key)) return responseFiles.get(key);
      const runsDir = runsTmpDirRef.current;
      if (runsDir && key.startsWith(resolvePath(runsDir))) return null;
      return actual.tryReadFile(filePath, ...rest);
    }),
  };
});

import { cleanTuiResponse, resolveTuiResponseText, executeTuiRun } from './tuiPromptRunner.js';
import { markHostShuttingDown, resetHostShutdownFlagForTests } from '../lib/hostShutdown.js';
import { SELF_CLEARING_RESUBMIT_INTERVAL_MS, SELF_CLEARING_RESUBMIT_ECHO_MS, TUI_INPUT_READY_DEADLINE_MS } from '../lib/tuiHandshake.js';

const makeFakePty = () => {
  const fake = {
    _dataHandler: null,
    _exitHandler: null,
    killed: false,
    onData: vi.fn((fn) => { fake._dataHandler = fn; }),
    onExit: vi.fn((fn) => { fake._exitHandler = fn; }),
    write: vi.fn(),
    kill: vi.fn(() => { fake.killed = true; }),
    emitData: (chunk) => fake._dataHandler?.(chunk),
    emitExit: (payload) => fake._exitHandler?.(payload),
  };
  ptyInstances.push(fake);
  return fake;
};

const flushAsync = () => new Promise((res) => setImmediate(res));

// Stands in for "the model wrote its complete response to the file the runner
// directed it to" — same absolute path executeTuiRun derives (getRunsPath() →
// runId → tui-response.txt), served from memory so the read is deterministic
// under fake timers.
const seedResponseFile = (runId, text) => {
  responseFiles.set(resolve(runsTmpDirRef.current, runId, 'tui-response.txt'), text);
};

// Targeted coverage for the cleanTuiResponse helper — it shapes what every
// TUI-provider caller sees as the model response (paste-marker removal,
// prompt-echo strip). Bugs here would silently corrupt prose generation
// and JSON parsing downstream.

describe('cleanTuiResponse', () => {
  describe('empty / non-string inputs', () => {
    it('returns empty string for empty input', () => {
      expect(cleanTuiResponse('', 'anything')).toBe('');
    });
    it('returns empty string for non-string raw', () => {
      expect(cleanTuiResponse(null, 'anything')).toBe('');
      expect(cleanTuiResponse(undefined, 'anything')).toBe('');
      expect(cleanTuiResponse(42, 'anything')).toBe('');
    });
  });

  describe('paste-marker removal', () => {
    it('drops the Claude Code [Pasted text #N +M lines] marker', () => {
      const raw = 'before\n[Pasted text #1 +42 lines]\nresponse body';
      expect(cleanTuiResponse(raw, '')).toBe('before\n\nresponse body');
    });

    it('drops multiple paste markers from the same buffer', () => {
      const raw = '[Pasted text #1 +3 lines] reply A [Pasted text #2 +5 lines] reply B';
      expect(cleanTuiResponse(raw, '')).toBe('reply A  reply B');
    });

    it('leaves text that resembles but does not match the marker pattern alone', () => {
      const raw = 'Look at [Pasted text without number] and continue';
      expect(cleanTuiResponse(raw, '')).toBe('Look at [Pasted text without number] and continue');
    });
  });

  describe('prompt echo elision', () => {
    it('strips a verbatim prompt that the TUI echoes back', () => {
      const prompt = 'Write a sonnet about an ocelot wearing a crown of starlight';
      const raw = `${prompt}\n\nShall I compare thee to a summer's ocelot?`;
      expect(cleanTuiResponse(raw, prompt)).toBe(`Shall I compare thee to a summer's ocelot?`);
    });

    it('strips every echoed occurrence (some TUIs render the prompt twice)', () => {
      const prompt = 'Generate a six-word science fiction story about regret';
      const raw = `${prompt}\nresponse 1\n${prompt}\nresponse 2`;
      const out = cleanTuiResponse(raw, prompt);
      expect(out).not.toContain(prompt);
      expect(out).toContain('response 1');
      expect(out).toContain('response 2');
    });

    it('skips prompt-echo elision when the prompt is shorter than the 16-char guard', () => {
      // Short prompts could appear naturally inside the model's response
      // (e.g. prompt="ok" appearing in "okay, here is..."). The guard
      // keeps the response intact instead of mass-deleting bigrams.
      const prompt = 'Write?';
      const raw = `Write? Sure, here is my best Writeful Writeup`;
      expect(cleanTuiResponse(raw, prompt)).toBe(raw);
    });

    it('does NOT strip prompt-substring matches inside the response — only exact full-prompt matches', () => {
      // split-join uses the full prompt as the splitter, so a substring
      // of the prompt that appears in the model's reply survives. This
      // is the right behavior: a model often refers back to phrases
      // from the prompt without echoing the whole thing.
      const prompt = 'Continue the story: The cat sat on the mat';
      const raw = `${prompt}\nThe cat sat on the mat for many hours.`;
      const out = cleanTuiResponse(raw, prompt);
      // First occurrence (the full prompt echo) elided; the substring
      // reference in the reply is preserved.
      expect(out).toBe('The cat sat on the mat for many hours.');
    });

    it('handles undefined/non-string prompt without throwing', () => {
      expect(cleanTuiResponse('plain response', undefined)).toBe('plain response');
      expect(cleanTuiResponse('plain response', null)).toBe('plain response');
      expect(cleanTuiResponse('plain response', 12345)).toBe('plain response');
    });
  });

  describe('integration — marker + prompt + trim together', () => {
    it('removes paste marker AND prompt echo AND trims surrounding whitespace', () => {
      const prompt = 'Summarize the plot of Aster of Pan in a single sentence';
      const raw = `\n\n[Pasted text #7 +1 lines]\n${prompt}\n\nA child rebuilds wonder in a green ruin.\n\n`;
      expect(cleanTuiResponse(raw, prompt)).toBe('A child rebuilds wonder in a green ruin.');
    });
  });
});

// resolveTuiResponseText is the file-or-fallback chooser called from
// executeTuiRun.finish. The PTY path is irreplicable in a unit test, so the
// helper was extracted to make this decision (which is the actual new
// behavior of the PR) testable in isolation.

describe('resolveTuiResponseText', () => {
  let tmpDir;
  let responseFilePath;

  beforeEach(async () => {
    tmpDir = await mkdtemp(join(tmpdir(), 'tui-response-test-'));
    responseFilePath = join(tmpDir, 'tui-response.txt');
  });
  afterEach(async () => {
    await rm(tmpDir, { recursive: true, force: true }).catch(() => null);
  });

  it('returns the response file contents trimmed and flags usedResponseFile=true on success', async () => {
    await writeFile(responseFilePath, '\n  the prose body  \n');
    const out = await resolveTuiResponseText({
      success: true,
      responseFilePath,
      outputBuffer: 'screen chrome',
      wrappedPrompt: 'wrapped',
    });
    expect(out).toEqual({ text: 'the prose body', usedResponseFile: true });
  });

  it('falls back to cleanTuiResponse(outputBuffer) when the file does not exist', async () => {
    const out = await resolveTuiResponseText({
      success: true,
      responseFilePath: join(tmpDir, 'does-not-exist.txt'),
      outputBuffer: '[Pasted text #1 +0 lines]\nfallback body',
      wrappedPrompt: 'wrapped',
    });
    expect(out).toEqual({ text: 'fallback body', usedResponseFile: false });
  });

  it('falls back to cleanTuiResponse when the file exists but is empty', async () => {
    await writeFile(responseFilePath, '');
    const out = await resolveTuiResponseText({
      success: true,
      responseFilePath,
      outputBuffer: 'fallback body',
      wrappedPrompt: 'wrapped',
    });
    expect(out).toEqual({ text: 'fallback body', usedResponseFile: false });
  });

  it('falls back to cleanTuiResponse when the file is whitespace-only', async () => {
    await writeFile(responseFilePath, '   \n\t  \n');
    const out = await resolveTuiResponseText({
      success: true,
      responseFilePath,
      outputBuffer: 'fallback body',
      wrappedPrompt: 'wrapped',
    });
    expect(out).toEqual({ text: 'fallback body', usedResponseFile: false });
  });

  it('does NOT read the file when success=false — falls back unconditionally', async () => {
    // A failed run shouldn't trust a partial file the model may have started
    // writing. Even if the file exists with usable content, the caller
    // rejects with an error and the response text path doesn't matter much
    // — but the contract is: success=false ⇒ usedResponseFile=false.
    await writeFile(responseFilePath, 'partial response that should not be used');
    const out = await resolveTuiResponseText({
      success: false,
      responseFilePath,
      outputBuffer: 'partial screen scrape',
      wrappedPrompt: 'wrapped',
    });
    expect(out).toEqual({ text: 'partial screen scrape', usedResponseFile: false });
  });

  it('passes wrappedPrompt into cleanTuiResponse on the fallback path so prompt-echo elision strips the directive-wrapped prompt', async () => {
    const wrappedPrompt = 'WRITE TO FILE INSTRUCTIONS AND TASK BODY — a long enough string to clear the 16-char guard';
    const out = await resolveTuiResponseText({
      success: true,
      responseFilePath: join(tmpDir, 'absent.txt'),
      outputBuffer: `${wrappedPrompt}\nthe model reply`,
      wrappedPrompt,
    });
    expect(out).toEqual({ text: 'the model reply', usedResponseFile: false });
  });
});

// executeTuiRun owns the PTY lifecycle — spawn, ready-watch, paste, idle
// detection, hard timeout, command-not-found probe, exit/signal handling.
// The PTY is mocked so each behavior can be triggered deterministically
// from the test without spawning a real terminal.

describe('executeTuiRun', () => {
  beforeEach(async () => {
    runsTmpDirRef.current = await mkdtemp(join(tmpdir(), 'tui-runner-test-'));
    responseFiles.clear();
    ptyInstances.length = 0;
    ptySpawnMock.mockReset();
    ptySpawnMock.mockImplementation(() => makeFakePty());
    runnerMocks.finalizeRunRecord.mockReset();
    runnerMocks.finalizeRunRecord.mockImplementation(
      async ({ runId, output, exitCode, success, error, startTime, extras }) => ({
        runId,
        output,
        exitCode,
        success,
        error,
        duration: Date.now() - startTime,
        ...extras,
      }),
    );
    runnerMocks.emitRunStarted.mockClear();
    runnerMocks.registerActiveRun.mockClear();
    runnerMocks.unregisterActiveRun.mockClear();
    runnerMocks.consumeRunStopRequested.mockReset();
    runnerMocks.consumeRunStopRequested.mockReturnValue(false);
    runnerMocks.getRunsPath.mockClear();
    runnerMocks.failRunRecord.mockClear();
    processEnvMocks.findCommandOnPath.mockReset();
    processEnvMocks.findCommandOnPath.mockImplementation((name) => `/usr/local/bin/${name}`);
    resetHostShutdownFlagForTests();
    shellMocks.registerExternalSession.mockClear();
    shellMocks.unregisterExternalSession.mockClear();
    shellMocks.isExternalSessionAttached.mockReset();
    shellMocks.isExternalSessionAttached.mockReturnValue(false);
    vi.spyOn(console, 'log').mockImplementation(() => {});
    vi.spyOn(console, 'error').mockImplementation(() => {});
  });

  afterEach(async () => {
    vi.useRealTimers();
    resetHostShutdownFlagForTests();
    vi.restoreAllMocks();
    await rm(runsTmpDirRef.current, { recursive: true, force: true }).catch(() => null);
  });

  describe('input validation', () => {
    it('settles a caller admission refusal before spawning the prepared TUI', async () => {
      await expect(executeTuiRun({ runId: 'run-admission', provider: { id: 'example-tui', type: 'tui', command: 'codex', args: [] },
        prompt: 'hello', workspacePath: TEST_WORKSPACE, beforeExecute: () => { throw new Error('Production stopped'); } }))
        .rejects.toThrow('Production stopped');
      expect(ptySpawnMock).not.toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({ extras: { canceled: true, completionReason: 'canceled' } }));
    });

    it('throws when provider is missing', async () => {
      await expect(executeTuiRun({ runId: 'run-x', provider: null, prompt: 'prompt', workspacePath: '/tmp' }))
        .rejects.toThrow(/provider is required/);
      expect(ptySpawnMock).not.toHaveBeenCalled();
    });

    it('throws when prompt is empty', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      await expect(executeTuiRun({ runId: 'run-x', provider, prompt: '', workspacePath: '/tmp' }))
        .rejects.toThrow(/non-empty string/);
      expect(ptySpawnMock).not.toHaveBeenCalled();
    });

    it('throws when prompt is non-string', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      await expect(executeTuiRun({ runId: 'run-x', provider, prompt: 12345, workspacePath: '/tmp' }))
        .rejects.toThrow(/non-empty string/);
    });
  });

  describe('missing TUI binary', () => {
    // A PTY has no shell to say "command not found": node-pty's child fails
    // `execvp` and exits 1 with an EMPTY screen, so the output-driven
    // `detectMissingTuiBinary` probe never fires. Before the pre-spawn check,
    // an uninstalled CLI finalized as a bare "TUI exited with code 1" with no
    // provider attached — which is exactly what queued a CoS task titled
    // "Investigate AI provider failure: undefined (undefined)".
    it('reports the real cause through the run record instead of spawning', async () => {
      processEnvMocks.findCommandOnPath.mockReturnValue(null);
      const provider = { id: 'opencode-llama-tui', name: 'OpenCode', type: 'tui', command: 'opencode', defaultModel: 'dflash' };
      const onComplete = vi.fn();

      await executeTuiRun({ runId: 'run-missing', provider, prompt: 'do thing', workspacePath: TEST_WORKSPACE, onComplete });

      expect(ptySpawnMock).not.toHaveBeenCalled();
      expect(runnerMocks.failRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-missing',
        error: 'TUI command not found: opencode',
        exitCode: 127,
        identity: { providerId: 'opencode-llama-tui', providerName: 'OpenCode', model: 'dflash' },
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({ success: false, exitCode: 127 }));
    });

    it('probes the child PATH, not the server PATH — a provider may override it', async () => {
      processEnvMocks.findCommandOnPath.mockReturnValue(null);
      const provider = {
        id: 'codex', name: 'Codex', type: 'tui', command: 'codex',
        envVars: { PATH: '/opt/only-my-bin' },
      };

      await executeTuiRun({ runId: 'run-path', provider, prompt: 'do thing', workspacePath: TEST_WORKSPACE });

      expect(processEnvMocks.findCommandOnPath).toHaveBeenCalledWith('codex', expect.objectContaining({
        env: expect.objectContaining({ PATH: expect.stringContaining('/opt/only-my-bin') }),
      }));
    });

    it('leaves failure reporting on by default and off for a probe run', async () => {
      processEnvMocks.findCommandOnPath.mockReturnValue(null);
      const provider = { id: 'opencode-llama-tui', name: 'OpenCode', type: 'tui', command: 'opencode' };

      await executeTuiRun({ runId: 'run-default', provider, prompt: 'p', workspacePath: TEST_WORKSPACE });
      expect(runnerMocks.failRunRecord).toHaveBeenLastCalledWith(expect.objectContaining({ reportFailure: true }));

      await executeTuiRun({ runId: 'run-probe', provider, prompt: 'p', workspacePath: TEST_WORKSPACE, reportFailure: false });
      expect(runnerMocks.failRunRecord).toHaveBeenLastCalledWith(expect.objectContaining({ reportFailure: false }));
    });
  });

  describe('spawn failure', () => {
    it('wraps node-pty spawn errors with the offending command name', async () => {
      ptySpawnMock.mockImplementation(() => { throw new Error('ENOENT'); });
      const provider = { id: 'codex', type: 'tui', command: 'nonexistent-cli' };
      await expect(executeTuiRun({ runId: 'run-x', provider, prompt: 'do thing', workspacePath: '/tmp' }))
        .rejects.toThrow(/Failed to spawn TUI 'nonexistent-cli': ENOENT/);
    });
  });

  describe('startup hooks', () => {
    it('passes image paths as native Codex arguments and refuses missing images before spawn', async () => {
      const provider = { id: 'codex-tui', type: 'tui', command: 'codex', defaultModel: 'gpt-6-astra' };
      const imagePath = join(runsTmpDirRef.current, 'example image.png');
      await writeFile(imagePath, 'image fixture');
      const promise = executeTuiRun({
        runId: 'run-images', provider, prompt: 'Describe image',
        screenshots: [imagePath], workspacePath: TEST_WORKSPACE,
      });
      await vi.waitFor(() => expect(ptySpawnMock).toHaveBeenCalledTimes(1));
      const args = ptySpawnMock.mock.calls[0][1];
      expect(args.slice(args.indexOf('--image'), args.indexOf('--image') + 2)).toEqual(['--image', imagePath]);
      ptyInstances[0].emitExit({ exitCode: 0 });
      await promise;
      ptySpawnMock.mockClear();
      await expect(executeTuiRun({
        runId: 'run-missing-image', provider, prompt: 'Describe image',
        screenshots: [join(runsTmpDirRef.current, 'missing.png')], workspacePath: TEST_WORKSPACE,
      })).rejects.toThrow();
      expect(ptySpawnMock).not.toHaveBeenCalled();
    });

    it('disables Codex multi-agent fan-out for one-shot prompt runs', async () => {
      const provider = {
        id: 'codex-tui', type: 'tui', command: '/opt/homebrew/bin/codex', defaultModel: 'gpt-x',
      };
      const promise = executeTuiRun({
        runId: 'run-codex-one-shot', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE,
      });
      await flushAsync();

      const args = ptySpawnMock.mock.calls[0][1];
      expect(args).toContain('--disable');
      expect(args[args.indexOf('--disable') + 1]).toBe('multi_agent');

      ptyInstances[0].emitExit({ exitCode: 0 });
      await promise;
    });

    it('does not add Codex feature flags to other one-shot TUI providers', async () => {
      const provider = {
        id: 'claude-tui', type: 'tui', command: 'claude', defaultModel: 'claude-fable-5',
      };
      const promise = executeTuiRun({
        runId: 'run-claude-one-shot', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE,
      });
      await flushAsync();

      expect(ptySpawnMock.mock.calls[0][1]).not.toContain('--disable');

      ptyInstances[0].emitExit({ exitCode: 0 });
      await promise;
    });

    it('registers the PTY in the active-runs map and fires emitRunStarted with provider + defaultModel', async () => {
      const provider = {
        id: 'claude', type: 'tui', command: 'echo', defaultModel: 'claude-3.5',
      };
      const promise = executeTuiRun({ runId: 'run-A', provider, prompt: 'do thing big enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 60000 });
      await flushAsync();

      expect(ptySpawnMock).toHaveBeenCalledTimes(1);
      const pty = ptyInstances[0];
      expect(runnerMocks.registerActiveRun).toHaveBeenCalledWith('run-A', pty);
      expect(runnerMocks.emitRunStarted).toHaveBeenCalledWith({
        runId: 'run-A',
        provider,
        model: 'claude-3.5',
      });

      // Drive a clean exit so the run-Promise resolves.
      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('finalizes when the PTY exits during startup before the lifecycle is ready', async () => {
      const earlyExitPty = makeFakePty();
      earlyExitPty.onExit.mockImplementation((handler) => {
        earlyExitPty._exitHandler = handler;
        handler({ exitCode: 1, signal: null });
      });
      ptySpawnMock.mockReturnValueOnce(earlyExitPty);
      const onComplete = vi.fn();
      const provider = { id: 'codex', type: 'tui', command: 'codex' };

      await expect(executeTuiRun({
        runId: 'run-early-exit',
        provider,
        prompt: 'return a response long enough for the prompt guard',
        workspacePath: TEST_WORKSPACE,
        onComplete,
        timeout: 60000,
      })).resolves.toBeUndefined();

      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-early-exit',
        success: false,
        exitCode: 1,
        error: 'TUI exited with code 1',
        extras: expect.objectContaining({ completionReason: 'exit' }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({ success: false, exitCode: 1 }));
      expect(runnerMocks.unregisterActiveRun).toHaveBeenCalledWith('run-early-exit');
      expect(shellMocks.unregisterExternalSession).toHaveBeenCalledWith('run-early-exit', { exitCode: 1 });
    });

    it('registers a read-only Shell view (labelled by source) and tears it down on finish', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'claude', defaultModel: 'claude-fable-5' };
      const onReady = vi.fn();
      const promise = executeTuiRun({
        runId: 'run-view', provider, prompt: 'review this manuscript', workspacePath: TEST_WORKSPACE,
        label: 'pipeline-manuscript-completeness', onReady,
      });
      await flushAsync();

      expect(shellMocks.registerExternalSession).toHaveBeenCalledWith(
        'run-view',
        ptyInstances[0],
        expect.objectContaining({
          label: 'pipeline-manuscript-completeness',
          kind: 'tui-run',
          cwd: TEST_WORKSPACE,
        }),
      );
      expect(onReady).toHaveBeenCalledWith({
        runId: 'run-view',
        providerId: 'claude',
        providerName: 'claude',
        model: 'claude-fable-5',
        providerType: 'tui',
        shellReady: true,
      });
      expect(shellMocks.unregisterExternalSession).not.toHaveBeenCalled();

      ptyInstances[0].emitExit({ exitCode: 0 });
      await promise;
      expect(shellMocks.unregisterExternalSession).toHaveBeenCalledWith('run-view', { exitCode: 0 });
    });

    it('falls back to a command·model label when no source label is supplied', async () => {
      const provider = { id: 'codex', type: 'tui', command: 'codex', defaultModel: 'gpt-x' };
      const promise = executeTuiRun({ runId: 'run-nolabel', provider, prompt: 'do the thing', workspacePath: TEST_WORKSPACE });
      await flushAsync();
      expect(shellMocks.registerExternalSession).toHaveBeenCalledWith(
        'run-nolabel', ptyInstances[0], expect.objectContaining({ label: 'codex · gpt-x' }),
      );
      ptyInstances[0].emitExit({ exitCode: 0 });
      await promise;
    });

    it('merges provider.envVars and strips CLAUDECODE from the child env so a nested Claude Code TUI is not detected as nested', async () => {
      // Save + restore the original value: a PortOS-inside-Claude-Code dev
      // run starts the worker with CLAUDECODE already set, and an
      // unconditional `delete` would clobber the test of a sibling test.
      const originalClaudecode = Object.prototype.hasOwnProperty.call(process.env, 'CLAUDECODE')
        ? process.env.CLAUDECODE
        : undefined;
      process.env.CLAUDECODE = '1';
      try {
        const provider = {
          id: 'claude', type: 'tui', command: 'echo',
          envVars: { CUSTOM_PROVIDER_VAR: 'on' },
        };
        const promise = executeTuiRun({ runId: 'run-B', provider, prompt: 'p large enough to clear the guard', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 60000 });
        await flushAsync();

        const env = ptySpawnMock.mock.calls[0][2].env;
        expect(env.CLAUDECODE).toBeUndefined();
        expect(env.CUSTOM_PROVIDER_VAR).toBe('on');
        expect(env.TERM).toBe('xterm-256color');
        expect(env.COLORTERM).toBe('truecolor');

        ptyInstances[0].emitExit({ exitCode: 0 });
        await promise;
      } finally {
        if (originalClaudecode === undefined) delete process.env.CLAUDECODE;
        else process.env.CLAUDECODE = originalClaudecode;
      }
    });
  });

  describe('startup dialogs', () => {
    it('confirms the Claude folder-trust gate and waits for input readiness before pasting', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-claude-trust-gate', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('Is this a project you trust?\n1. Yes, I trust this folder\n2. No, exit\n');
      await vi.advanceTimersByTimeAsync(400);

      expect(pty.write).toHaveBeenCalledWith('\r');
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      // A blind fallback must not paste into a known startup dialog.
      await vi.advanceTimersByTimeAsync(11000);
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      // Claude's own bracketed-paste mode is the positive direct-PTY signal.
      // node-pty may split its raw control sequence across callbacks.
      pty.emitData('\x1b[?2004');
      pty.emitData('h');
      await vi.advanceTimersByTimeAsync(400);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('moves off Claude\'s highlighted decline choice before accepting trust', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-claude-decline-default', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('Quick safety check: Is this a project you created or one you trust?\n'
        + '❯ No, exit\n'
        + '  Yes, I trust this folder\n'
        + 'Enter to confirm · Esc to cancel\n');
      await vi.advanceTimersByTimeAsync(400);

      expect(pty.write).toHaveBeenCalledWith('\x1b[B\r');
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('declines Claude auto-mode and pastes only after dismissing the offer', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-claude-auto-mode', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData(
        '\x1b[?2004hMake auto mode your default permission mode?\n'
        + '1. Yes, set auto mode as my default permission mode\n'
        + "2. No, keep don't ask\n",
      );
      await vi.advanceTimersByTimeAsync(400);

      expect(pty.write).toHaveBeenCalledWith('\x1b[B\r');
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      await vi.advanceTimersByTimeAsync(400);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('disables Claude external imports before waiting for input readiness', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-claude-external-imports', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData(
        "This project's CLAUDE" + ".md imports files outside the current working directory.\n"
        + 'Never allow this for third-party repositories.\n'
        + 'External imports:\n'
        + '  /workspace-parent/AGENTS.md\n'
        + '1. Yes, allow external imports\n'
        + '2. No, disable external imports\n',
      );
      await vi.advanceTimersByTimeAsync(400);

      expect(pty.write).toHaveBeenCalledWith('\x1b[B\r');
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      // The dialog precedes Claude's composer. Paste only after Claude paints
      // the input box and enables bracketed-paste mode.
      pty.emitData('\x1b[?2004h');
      await vi.advanceTimersByTimeAsync(400);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it.each([
      {
        version: 'legacy',
        dialog: 'You are in /workspace/example\n'
          + 'Do you trust the contents of this directory? Working with untrusted contents comes with'
          + ' higher risk of prompt injection.\n'
          + '› 1. Yes, continue\n2. No, quit\nPress enter to continue\n',
        answer: '\r',
      },
      {
        version: '0.162.1 with Quit highlighted',
        dialog: 'Folder access\n/workspace/example\nTrustthisfolder?\n'
          + '1. Trust and continue\n› 2.Quit\nenter continue · esc quit\n',
        answer: '\x1b[A\r',
      },
    ])('confirms the Codex $version trust gate before its idle path can paste', async ({ dialog, answer }) => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'codex', type: 'tui', command: 'codex', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-codex-trust-gate', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData(dialog);
      // Past the idle threshold — the window the prompt used to be pasted in.
      await vi.advanceTimersByTimeAsync(2000);

      expect(pty.write).toHaveBeenCalledWith(answer);
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitData('OpenAI Codex ready\n');
      await vi.advanceTimersByTimeAsync(2000);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('declines Codex hook trust and pastes only after its selector clears', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'codex', type: 'tui', command: 'codex', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-codex-hook-review', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData(
        'Hooks need review\n'
        + '1 hook is new or changed.\n'
        + '1. Review hooks\n'
        + '2. Trust all and continue\n'
        + "3. Continue without trusting (hooks won't run)\n",
      );
      await vi.advanceTimersByTimeAsync(400);

      expect(pty.write).toHaveBeenCalledWith('\x1b[B\x1b[B\r');
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitData('OpenAI Codex ready\n');
      await vi.advanceTimersByTimeAsync(2000);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    // A non-Claude TUI keeps the idle fallback for DELIVERY, but a trust gate is
    // still answered first — every vendor's gate swallows the paste the same way,
    // and leaving it up only guarantees the prompt is lost (agent-671af38f).
    it('answers a trust gate for a non-Claude TUI, then delivers on the existing idle fallback', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'grok', type: 'tui', command: 'grok', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-non-claude-trust-text', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('Is this a project you trust?\n1. Yes, I trust this folder\n2. No, exit\n');
      await vi.advanceTimersByTimeAsync(2000);

      expect(pty.write).toHaveBeenCalledWith('\r');
      // No composer repaint followed the keystroke, so the idle clock restarted
      // from it — delivery still happens, via the blind PASTE_DEADLINE_MS
      // fallback that governs non-input-ready providers.
      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));
      pty.emitData('grok ready\n');
      await vi.advanceTimersByTimeAsync(2000);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('waits for the OpenCode composer and dismisses its update offer without confirming it', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'opencode', type: 'tui', command: 'opencode', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-opencode-update', provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();
      const pty = ptyInstances[0];
      pty.emitData('\x1bP+q4d73\x1b\\');
      await vi.advanceTimersByTimeAsync(15000);
      expect(pty.write).not.toHaveBeenCalled();
      pty.emitData('\x1b[?2004hAsk anything…\nUpdate Available esc\n'
        + 'A new release v9.9.9 is available. Would you like to\x1b[12;4H┃\n'
        + '        update now?\n┃ Ask\n┃ Buil     Skip Confirm\n');
      await vi.advanceTimersByTimeAsync(400);
      expect(pty.write.mock.calls.map(([data]) => data)).toEqual(['\x1b']);
      await vi.advanceTimersByTimeAsync(2000);
      expect(pty.write).toHaveBeenCalledTimes(1);
      pty.emitData('Ask anything…\n');
      await vi.advanceTimersByTimeAsync(1500);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));
      pty.emitData('[Pasted ~42 lines]');
      await vi.advanceTimersByTimeAsync(1000);
      expect(pty.write).toHaveBeenCalledWith('\r');
      pty.emitExit({ exitCode: 0 });
      await promise;
    });

    it('fails OpenCode startup on a rejected model instead of pasting into its replacement composer', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'opencode', type: 'tui', command: 'opencode', defaultModel: 'example-provider/example-model', tuiPromptDelayMs: 50 };
      const runId = 'run-opencode-model-rejected';
      const promise = executeTuiRun({
        runId, provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();
      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004hModel example-provider/exam');
      pty.emitData('ple-model\n┃ is not valid\nreplacement-provider/replacement-model\nAsk anything…\n');
      await vi.advanceTimersByTimeAsync(4000);
      await promise;

      expect(pty.write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: false,
        exitCode: 1,
        error: expect.stringContaining('example-provider/example-model'),
        extras: expect.objectContaining({
          completionReason: 'opencode-model-rejected',
          errorAnalysis: expect.objectContaining({
            category: 'model-not-found',
            affectedModel: 'example-provider/example-model',
            configuredModel: 'example-provider/example-model',
          }),
        }),
      }));
    });

    it('fails Claude startup after its input-readiness deadline instead of blind-pasting', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const runId = 'run-claude-not-ready';
      const promise = executeTuiRun({
        runId, provider, prompt: 'return one structured response',
        workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      ptyInstances[0].emitData('Claude Code is still starting\n');
      await vi.advanceTimersByTimeAsync(TUI_INPUT_READY_DEADLINE_MS + 500);
      await promise;

      expect(ptyInstances[0].write).not.toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: false,
        exitCode: 1,
        error: expect.stringContaining('did not present an input prompt'),
        extras: expect.objectContaining({ completionReason: 'tui-not-ready' }),
      }));
    });
  });

  describe('completion paths', () => {
    it('finishes with reason "idle-complete" once output stays idle past tuiOneShotIdleMs after the first response chunk', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = {
        id: 'claude', type: 'tui', command: 'echo',
        tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500,
      };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-idle', provider, prompt: 'do thing big enough to clear the prompt guard', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];

      // Banner output establishes firstOutputAt so the ready-watch can fire.
      pty.emitData('claude code ready> ');

      // Past tuiPromptDelayMs (50) + READY_IDLE_THRESHOLD_MS (1200) + readyTimer poll.
      await vi.advanceTimersByTimeAsync(2000);
      expect(pty.write).toHaveBeenCalledWith(expect.stringContaining('\x1b[200~'));

      // Past PASTE_TO_ENTER_FALLBACK_MS (3500) → '\r' submitted.
      await vi.advanceTimersByTimeAsync(4000);
      expect(pty.write).toHaveBeenCalledWith('\r');

      // First post-paste chunk arms idleWatchTimer (ticks every 1000ms).
      pty.emitData('model response chunk');
      await vi.advanceTimersByTimeAsync(1100);
      await flushAsync();

      await promise;
      expect(runnerMocks.unregisterActiveRun).toHaveBeenCalledWith('run-idle');
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-idle',
        success: true,
        exitCode: 0,
        extras: expect.objectContaining({ completionReason: 'idle-complete' }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
        success: true,
        exitCode: 0,
      }));
    });

    it('keeps an explicitly unbounded non-Codex inference alive through silence', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'example-tui', type: 'tui', command: 'echo', tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500 };
      const promise = executeTuiRun({ runId: 'run-unbounded-quiet', provider,
        prompt: 'do thing big enough to clear the prompt guard', workspacePath: TEST_WORKSPACE, timeout: 0 });
      await flushAsync();
      const pty = ptyInstances[0];
      pty.emitData('ready> ');
      await vi.advanceTimersByTimeAsync(6000);
      pty.emitData('Still reasoning');
      await vi.advanceTimersByTimeAsync(60 * 60 * 1000);
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();
      expect(pty.kill).not.toHaveBeenCalled();
      pty.emitExit({ exitCode: 0 });
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({ runId: 'run-unbounded-quiet', success: true }));
    });

    it('does not idle-complete a run whose screen still shows it thinking', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'claude-tui', type: 'tui', command: 'echo', tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500 };
      const runId = 'run-claude-silent-thinking';
      const promise = executeTuiRun({ runId, provider,
        prompt: 'write the creative direction to the response file', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();
      const pty = ptyInstances[0];
      pty.emitData('claude code ready> ');
      await vi.advanceTimersByTimeAsync(2000); // paste
      await vi.advanceTimersByTimeAsync(4000); // enter
      // The last paint before a long silent thinking stretch: spinner status
      // line, then the composer box and footer Claude Code draws beneath it.
      pty.emitData('✻ Pondering… (55s · ↓ 1.2k tokens · still thinking with medium effort)\n'
        + '╭────────────────────────╮\n│ >                      │\n╰────────────────────────╯\n  ? for shortcuts\n');

      await vi.advanceTimersByTimeAsync(10000);
      await flushAsync();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      seedResponseFile(runId, '{"logline":"x"}');
      await vi.advanceTimersByTimeAsync(1100);
      await vi.advanceTimersByTimeAsync(1100);
      await flushAsync();
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: true,
        output: '{"logline":"x"}',
        extras: expect.objectContaining({ completionReason: 'response-file' }),
      }));
    });

    it('does not reap a quiet Codex reasoning pass before its response file exists', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = {
        id: 'codex-tui', type: 'tui', command: 'codex',
        tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500,
      };
      const runId = 'run-codex-quiet-reasoning';
      const promise = executeTuiRun({
        runId,
        provider,
        prompt: 'reason carefully and write the complete structured response',
        workspacePath: TEST_WORKSPACE,
        timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('OpenAI Codex ready> ');
      await vi.advanceTimersByTimeAsync(2000); // paste
      await vi.advanceTimersByTimeAsync(4000); // enter
      pty.emitData('Working (0s • esc to interrupt)');

      // This is well beyond the configured 500ms idle fallback. A generic TUI
      // would have completed from its screen scrape, but Codex is still doing
      // real work and has not written the authoritative response yet.
      await vi.advanceTimersByTimeAsync(5000);
      await flushAsync();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      seedResponseFile(runId, '{"repaired":true}');
      await vi.advanceTimersByTimeAsync(1100);
      await vi.advanceTimersByTimeAsync(1100);
      await flushAsync();
      await promise;

      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: true,
        output: '{"repaired":true}',
        extras: expect.objectContaining({
          completionReason: 'response-file',
          usedResponseFile: true,
        }),
      }));
    });

    it('does NOT idle-complete while a Shell viewer is attached, then completes once they detach', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      // A human is watching this run in the Shell page.
      shellMocks.isExternalSessionAttached.mockReturnValue(true);
      const provider = {
        id: 'claude', type: 'tui', command: 'echo',
        tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500,
      };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-watched', provider, prompt: 'do thing big enough to clear the prompt guard', workspacePath: TEST_WORKSPACE, onComplete, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('claude code ready> ');
      await vi.advanceTimersByTimeAsync(2000); // paste
      await vi.advanceTimersByTimeAsync(4000); // enter
      pty.emitData('model response chunk');     // arms idleWatchTimer

      // Idle well past the threshold — but a viewer is attached, so the run must
      // NOT auto-complete.
      await vi.advanceTimersByTimeAsync(5000);
      await flushAsync();
      expect(onComplete).not.toHaveBeenCalled();
      expect(runnerMocks.unregisterActiveRun).not.toHaveBeenCalled();

      // Viewer detaches → next idle tick completes the run normally.
      shellMocks.isExternalSessionAttached.mockReturnValue(false);
      await vi.advanceTimersByTimeAsync(1100);
      await flushAsync();
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-watched',
        success: true,
        extras: expect.objectContaining({ completionReason: 'idle-complete' }),
      }));
    });

    it('completes with reason "response-file" once the model writes its response file — even while a viewer is attached', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      // A human is watching — idle-completion is paused, but the response file
      // is the model's explicit "done" signal and must complete regardless.
      // This is the regression guard for the manuscript-completeness run that
      // wrote tui-response.txt yet rode to the hard timeout because it was watched.
      shellMocks.isExternalSessionAttached.mockReturnValue(true);
      const provider = {
        id: 'claude', type: 'tui', command: 'claude',
        tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500,
      };
      const runId = 'run-respfile';
      const promise = executeTuiRun({ runId, provider, prompt: 'review this manuscript thoroughly enough to clear the guard', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004hclaude code ready> ');
      await vi.advanceTimersByTimeAsync(2000); // paste
      await vi.advanceTimersByTimeAsync(4000); // enter
      pty.emitData('model thinking…');          // arms idleWatchTimer

      // The model writes its COMPLETE response to the file the runner directed
      // it to (and, like Claude Code's TUI, does NOT exit afterward).
      seedResponseFile(runId, '{"issues":[]}');

      // First tick seeds the size-stability baseline; the second confirms it.
      await vi.advanceTimersByTimeAsync(1100);
      await vi.advanceTimersByTimeAsync(1100);
      await flushAsync();
      await promise;

      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: true,
        exitCode: 0,
        output: '{"issues":[]}',
        extras: expect.objectContaining({ completionReason: 'response-file', usedResponseFile: true }),
      }));
    });

    it('completes via the response file even when the TUI emits NO post-paste output (watcher is not gated on streamed output)', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      // Regression guard: the response-file watcher must run independently of
      // idleWatchTimer (which only arms after the first POST-PASTE output chunk).
      // A model that writes its file silently would otherwise hang until the
      // hard-timeout salvage despite the result already being on disk.
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const runId = 'run-silent-respfile';
      const promise = executeTuiRun({ runId, provider, prompt: 'do the task quietly then write the file', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];
      // Pre-paste banner lets the ready-watch paste — but NOTHING is emitted
      // after the paste, so idleWatchTimer never arms.
      pty.emitData('\x1b[?2004hclaude code ready> ');
      await vi.advanceTimersByTimeAsync(2000); // ready-watch pastes → response-file watcher starts
      await vi.advanceTimersByTimeAsync(4000); // enter submitted; still zero post-paste output

      seedResponseFile(runId, 'silent result body');

      await vi.advanceTimersByTimeAsync(1100); // poll 1: seed baseline
      await vi.advanceTimersByTimeAsync(1100); // poll 2: stable → complete
      await flushAsync();
      await promise;

      // Completed long before the 60s hard timeout, with no idle output to lean on.
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: true,
        exitCode: 0,
        output: 'silent result body',
        extras: expect.objectContaining({ completionReason: 'response-file', usedResponseFile: true }),
      }));
    });

    it('salvages the response file on hard timeout → success with reason "timeout-response-file" instead of a false failure + fallback', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const runId = 'run-tmo-salvage';
      // The model finished and wrote its file, but the TUI never exited and the
      // idle watcher was never armed (no post-paste chunk) — so only the hard
      // timeout remains to terminate the run. It must NOT throw the result away.
      seedResponseFile(runId, 'the completed review body');

      const promise = executeTuiRun({ runId, provider, prompt: 'a prompt long enough to clear the guard', workspacePath: TEST_WORKSPACE, timeout: 500 });
      await flushAsync();
      await vi.advanceTimersByTimeAsync(600); // hard timeout fires
      await flushAsync();
      await promise;

      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: true,
        exitCode: 0,
        output: 'the completed review body',
        extras: expect.objectContaining({ completionReason: 'timeout-response-file', usedResponseFile: true }),
      }));
    });

    it('finishes with reason "timeout" and exitCode 124 when the hard timeout fires before any completion', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const promise = executeTuiRun({ runId: 'run-timeout', provider, prompt: 'a prompt long enough to clear the guard', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 500 });
      await flushAsync();

      // No data emitted → no firstOutputAt → ready-watch never triggers paste
      // before the (short) hard timeout fires.
      await vi.advanceTimersByTimeAsync(600);
      await flushAsync();

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-timeout',
        success: false,
        exitCode: 124,
        error: expect.stringContaining('timed out'),
        extras: expect.objectContaining({ completionReason: 'timeout' }),
      }));
      // PTY was killed by finish() as part of cleanup.
      expect(ptyInstances[0].kill).toHaveBeenCalled();
    });

    it('still hard-times-out a watched run (the backstop is not paused while attached)', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      shellMocks.isExternalSessionAttached.mockReturnValue(true); // a viewer is watching
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const promise = executeTuiRun({ runId: 'run-tmo-watched', provider, prompt: 'a prompt long enough to clear the guard', workspacePath: TEST_WORKSPACE, timeout: 500 });
      await flushAsync();

      // The hard timeout fires even though a viewer is attached — only idle
      // auto-completion is paused while watched, not the max-time backstop.
      await vi.advanceTimersByTimeAsync(600);
      await flushAsync();
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-tmo-watched',
        success: false,
        exitCode: 124,
        extras: expect.objectContaining({ completionReason: 'timeout' }),
      }));
    });

    it('early-fails with reason "command-not-found" and exitCode 127 when "command not found" appears pre-paste', async () => {
      const provider = { id: 'codex', type: 'tui', command: 'no-such-tui' };
      const promise = executeTuiRun({ runId: 'run-missing', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 60000 });
      await flushAsync();

      // Shell banner echoing the missing-command error before paste.
      ptyInstances[0].emitData('zsh: command not found: no-such-tui');

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-missing',
        success: false,
        exitCode: 127,
        error: expect.stringContaining('TUI command not found: no-such-tui'),
        extras: expect.objectContaining({ completionReason: 'command-not-found' }),
      }));
    });

    it('stops a Codex policy refusal even when a response file is already available', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const runId = 'run-refusal';
      const provider = { id: 'codex', type: 'tui', command: 'codex', tuiPromptDelayMs: 50 };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId, provider, prompt: 'a prompt long enough to submit',
        workspacePath: TEST_WORKSPACE, onComplete, timeout: 60000 });
      await flushAsync();
      const pty = ptyInstances[0];
      pty.emitData('› Ask Codex to do anything\n? for shortcuts');
      await vi.advanceTimersByTimeAsync(6000);
      responseFiles.set(resolve(runsTmpDirRef.current, runId, 'tui-response.txt'), 'partial response');
      pty.emitData('Ordinary output');
      pty.emitData('\x1b[12;1H');
      pty.emitData('ⓘ This content can’t be shown');
      await promise;
      expect(pty.kill).toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        success: false, extras: expect.objectContaining({ completionReason: 'content-refusal',
          errorAnalysis: expect.objectContaining({ category: 'content-refusal' }),
          executionInterruption: { category: 'content-refusal', source: 'provider' },
        }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({ success: false }));
    });

    it('early-fails with reason "fallback-signal" when Claude switches to extra usage', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'claude' };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-extra-usage', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitData('Now using extra ');
      expect(ptyInstances[0].kill).not.toHaveBeenCalled();
      ptyInstances[0].emitData('usage\n');

      await promise;
      expect(ptyInstances[0].kill).toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-extra-usage',
        success: false,
        exitCode: 1,
        error: expect.stringContaining('Now using extra usage'),
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
        success: false,
        error: expect.stringContaining('Now using extra usage'),
        completionReason: 'fallback-signal',
      }));
    });

    it('uses the provider opt-in to send Claude low-priority once after a session-limit banner', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = {
        id: 'claude', type: 'tui', command: 'claude', lowPriorityOnUsageLimit: true, tuiPromptDelayMs: 50,
      };
      const promise = executeTuiRun({
        runId: 'run-low-priority', provider, prompt: 'complete this task', workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004h');
      await vi.advanceTimersByTimeAsync(300);
      pty.emitData('[Pasted text #1 +0 lines]');
      await vi.advanceTimersByTimeAsync(300);
      pty.emitData("\n⏺ You've hit your session limit · resets 6:00 PM");
      pty.emitData("\n⏺ You've hit your session limit · resets 6:00 PM");

      expect(pty.write).toHaveBeenCalledWith('/low-priority\r');
      expect(pty.write.mock.calls.filter(([keys]) => keys === '/low-priority\r')).toHaveLength(1);
      expect(pty.kill).not.toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      const taskPastes = () => pty.write.mock.calls.filter(([keys]) =>
        String(keys).startsWith('\x1b[200~') && String(keys).includes('complete this task')).length;
      expect(taskPastes()).toBe(1);
      await vi.advanceTimersByTimeAsync(1600);
      expect(taskPastes()).toBe(2);
      await vi.advanceTimersByTimeAsync(9000);
      expect(runnerMocks.finalizeRunRecord, 'an idle mode-command screen is not a completed response').not.toHaveBeenCalled();

      pty.emitData("\n⏺ You've hit your session limit · resets 6:00 PM");
      await flushAsync();
      await promise;
      expect(pty.kill).toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-low-priority',
        success: false,
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
    });

    it('presses Enter again when the paste chip sits unsubmitted, instead of idle-completing on it', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-unsubmitted', provider, prompt: 'complete this task', workspacePath: TEST_WORKSPACE, timeout: 600000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004h');
      await vi.advanceTimersByTimeAsync(300);
      pty.emitData('❯ [Pasted text #1 +113 lines]');
      await vi.advanceTimersByTimeAsync(3000);
      const enters = () => pty.write.mock.calls.filter(([keys]) => keys === '\r').length;
      const submitted = enters();
      expect(submitted).toBeGreaterThan(0);

      // Every submit Enter was ignored: nothing repaints past the chip.
      await vi.advanceTimersByTimeAsync(10_000);
      expect(runnerMocks.finalizeRunRecord, 'a quiet composer holding the chip is not an answer').not.toHaveBeenCalled();
      await vi.advanceTimersByTimeAsync(12_000);
      expect(enters()).toBe(submitted + 1);

      pty.emitData('\n✻ Thinking… (2s · esc to interrupt)');
      await vi.advanceTimersByTimeAsync(60_000);
      expect(enters(), 'a started turn gets no further Enters').toBe(submitted + 1);
      pty.emitExit({ exitCode: 0 });
      await flushAsync();
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({ runId: 'run-unsubmitted' }));
    });

    it('idle-completes a quick reply with no in-flight chrome without extra Enters', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-quick-reply', provider, prompt: 'complete this task', workspacePath: TEST_WORKSPACE, timeout: 600000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004h');
      await vi.advanceTimersByTimeAsync(300);
      pty.emitData('❯ [Pasted text #1 +113 lines]');
      await vi.advanceTimersByTimeAsync(5000);
      const enters = () => pty.write.mock.calls.filter(([keys]) => keys === '\r').length;
      const submitted = enters();

      pty.emitData('\nA child rebuilds wonder in a green ruin.');
      await vi.advanceTimersByTimeAsync(10_000);
      await promise;
      expect(enters()).toBe(submitted);
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-quick-reply', success: true, extras: expect.objectContaining({ completionReason: 'idle-complete' }),
      }));
    });

    it('falls back on Claude session-limit chrome when low-priority is not enabled', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const promise = executeTuiRun({
        runId: 'run-low-priority-off', provider, prompt: 'complete this task', workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004h');
      await vi.advanceTimersByTimeAsync(300);
      pty.emitData('[Pasted text #1 +0 lines]');
      await vi.advanceTimersByTimeAsync(300);
      pty.emitData("\n⏺ You've hit your session limit · resets 6:00 PM");
      await flushAsync();
      await promise;

      expect(pty.write).not.toHaveBeenCalledWith('/low-priority\r');
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-low-priority-off',
        success: false,
        error: expect.stringContaining('Claude Code session usage limit reached'),
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
    });

    // ── agy account-eligibility banner: a WAIT, not a verdict ─────────────────
    // The banner paints while agy's `loadCodeAssist` handshake is still retrying
    // and the CLI generates normally once it settles, so a self-clearing signal
    // arms a grace window instead of killing the PTY on sight.
    const ELIGIBILITY_BANNER =
      "We're finishing verifying your account eligibility. This usually takes a moment. Please try again shortly.";

    it('holds a run open for the eligibility banner and resumes when agy starts generating', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'antigravity', type: 'tui', command: 'agy', tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500 };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-eligibility-ok', provider, prompt: 'do thing big enough to clear the prompt guard', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete, timeout: 600000 });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData(ELIGIBILITY_BANNER);
      await vi.advanceTimersByTimeAsync(5000);
      // The old behavior killed the PTY within a second of the banner.
      expect(pty.kill).not.toHaveBeenCalled();

      // agy settles its handshake and paints its in-flight chrome.
      pty.emitData('Generating...\nesc to cancel');
      await vi.advanceTimersByTimeAsync(70000);
      await flushAsync();

      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalledWith(expect.objectContaining({
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
      vi.useRealTimers();
      pty.emitExit(0);
      await promise;
    });

    // The banner is the REJECTION of the submission — agy discards the prompt and
    // returns to an empty, idle composer — so a PASSIVE window can never see the
    // generation chrome it waits for, and its only reachable outcome is expiry.
    // Re-asking is both the only way out and what the banner itself instructs.
    it('re-submits the prompt while the eligibility window is open', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'antigravity', type: 'tui', command: 'agy', tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500 };
      const prompt = 'do thing big enough to clear the prompt guard';
      const promise = executeTuiRun({ runId: 'run-eligibility-retry', provider, prompt, workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: vi.fn(), timeout: 600000 });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('agy ready> ');
      await vi.advanceTimersByTimeAsync(5000); // first delivery
      const pastes = () => pty.write.mock.calls.filter(([chunk]) => String(chunk).includes(prompt)).length;
      expect(pastes()).toBe(1);

      pty.emitData(ELIGIBILITY_BANNER);
      pty.emitData('> ? for shortcuts');
      await vi.advanceTimersByTimeAsync(SELF_CLEARING_RESUBMIT_INTERVAL_MS + 1000);
      await flushAsync();
      expect(pastes()).toBe(2);
      expect(pty.write).toHaveBeenCalledWith('\r');

      // …and it stops re-asking the moment agy actually answers. The first
      // repaint lands inside the echo window and is discounted (it could be the
      // prompt we just pasted echoing back); agy repaints continuously, so the
      // next one is what closes the window.
      pty.emitData('Generating...');
      await vi.advanceTimersByTimeAsync(SELF_CLEARING_RESUBMIT_ECHO_MS);
      pty.emitData('Generating...');
      await vi.advanceTimersByTimeAsync(3 * SELF_CLEARING_RESUBMIT_INTERVAL_MS);
      await flushAsync();
      expect(pastes()).toBe(2);

      vi.useRealTimers();
      pty.emitExit(0);
      await promise;
    });

    it('falls back once the eligibility banner outlasts its grace window with no generation', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
      const provider = { id: 'antigravity', type: 'tui', command: 'agy', tuiPromptDelayMs: 50, tuiOneShotIdleMs: 500 };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-eligibility-stuck', provider, prompt: 'do thing big enough to clear the prompt guard', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete, timeout: 600000 });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData(ELIGIBILITY_BANNER);
      // Only idle composer chrome repaints — no sign of life. Notably this must
      // NOT idle-complete as success and scrape the banner as the response.
      pty.emitData('> ? for shortcuts');
      // Past the full grace window — every re-submission inside it went
      // unanswered too, so the fail-over is the correct verdict.
      await vi.advanceTimersByTimeAsync(130000);
      await flushAsync();

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-eligibility-stuck',
        success: false,
        exitCode: 1,
        error: expect.stringContaining('account eligibility'),
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
    });

    it('early-fails with reason "fallback-signal" when the model id is rejected (Bedrock invalid identifier) instead of idling to a bogus-scrape success', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'claude' };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-bad-model', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete, timeout: 60000 });
      await flushAsync();

      // Claude Code renders the terminal model-id rejection inline and then sits
      // idle — without the early-fail signal this would idle-complete as success
      // and scrape the error screen as the "response".
      ptyInstances[0].emitData('⏺ API Error (claude-opus-4-8): 400 The provided model identifier is invalid.. Try /model to switch to us.anthropic.claude-opus-4-1-20250805-v1:0.\n');

      await promise;
      expect(ptyInstances[0].kill).toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-bad-model',
        success: false,
        exitCode: 1,
        error: expect.stringContaining('model identifier is invalid'),
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
        success: false,
        completionReason: 'fallback-signal',
      }));
    });

    it('fails as a timeout after Claude exhausts its internal request retries instead of parsing the error screen as output', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'claude' };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-request-timeout', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete, timeout: 60000 });
      await flushAsync();

      // Retry banners are recoverable and must not be interrupted. The final
      // gutter-owned line is what Claude Code shows only after retry 10/10.
      ptyInstances[0].emitData('⎿ Request timed out · Retrying in 38s · attempt 9/10\n');
      expect(ptyInstances[0].kill).not.toHaveBeenCalled();
      ptyInstances[0].emitData('  ⎿\u00a0Requesttimedout\n');

      await promise;
      expect(ptyInstances[0].kill).toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-request-timeout',
        success: false,
        exitCode: 124,
        error: expect.stringContaining('timed out'),
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
        success: false,
        exitCode: 124,
        completionReason: 'fallback-signal',
      }));
    });

    it('keeps retrying when a PTY chunk boundary splits the retry banner right after "Request timed out"', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'claude' };
      const promise = executeTuiRun({ runId: 'run-split-retry', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];
      // Ink repaints the countdown on every tick and the tty delivers those
      // frames in sub-frame chunks, so a split inside the ~30-char window
      // between "out" and " · Retrying" is routine. Before #3715 this first
      // chunk ALONE finalized the run as exitCode 124 and burned a fallback
      // tier — killing the retry sequence the detector exists to protect.
      pty.emitData('  ⎿ Request timed out');
      await flushAsync();
      expect(pty.kill).not.toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      pty.emitData(' · Retrying in 38s · attempt 3/10\n');
      await flushAsync();
      expect(pty.kill).not.toHaveBeenCalled();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      // Retries do eventually exhaust — the genuinely terminal banner (its own
      // complete line) must still fail the run.
      pty.emitData('  ⎿ Request timed out\n');
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-split-retry',
        success: false,
        exitCode: 124,
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
    });

    it('flushes a held terminal banner at PTY exit rather than scraping the error screen as a success', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'claude' };
      const promise = executeTuiRun({ runId: 'run-exit-timeout', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];
      // No terminator yet, so the candidate is held rather than acted on.
      pty.emitData('  ⎿ Request timed out');
      await flushAsync();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      // Claude Code exits 0 with the error screen still up. Process exit is the
      // terminator the held candidate was waiting for.
      pty.emitExit({ exitCode: 0, signal: undefined });
      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-exit-timeout',
        success: false,
        exitCode: 124,
        extras: expect.objectContaining({ completionReason: 'fallback-signal' }),
      }));
    });

    it('salvages a settled response file when a fallback signal paints inside the size-stability window', async () => {
      vi.useFakeTimers({
        toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
      });
      const provider = { id: 'claude', type: 'tui', command: 'claude', tuiPromptDelayMs: 50 };
      const runId = 'run-signal-salvage';
      const promise = executeTuiRun({ runId, provider, prompt: 'write the review then finish up properly', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.emitData('\x1b[?2004hclaude code ready> ');
      await vi.advanceTimersByTimeAsync(2000); // paste → response-file watcher armed
      await vi.advanceTimersByTimeAsync(4000); // enter

      seedResponseFile(runId, 'the finished review body');
      // Poll 1 only seeds the size-stability baseline — the run is NOT finalized
      // yet even though the complete answer is already on disk.
      await vi.advanceTimersByTimeAsync(1100);
      // Let the async interval callback commit its baseline before racing it
      // against the fallback signal below on a loaded CI worker.
      await flushAsync();
      expect(runnerMocks.finalizeRunRecord).not.toHaveBeenCalled();

      // A follow-up provider request times out and paints the terminal banner
      // inside that ≥1s window. Failing here would discard the finished
      // response (resolveTuiResponseText only reads the file on success) and
      // re-run an expensive stage on a fallback provider.
      pty.emitData('\n  ⎿ Request timed out\n');
      await flushAsync();
      await promise;

      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId,
        success: true,
        exitCode: 0,
        output: 'the finished review body',
        extras: expect.objectContaining({
          completionReason: 'fallback-signal-response-file',
          usedResponseFile: true,
        }),
      }));
    });

    it('finishes with reason "exit" + exitCode 0 when the PTY closes cleanly', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const promise = executeTuiRun({ runId: 'run-exit', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitExit({ exitCode: 0 });

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-exit',
        success: true,
        exitCode: 0,
        error: null,
        extras: expect.objectContaining({ completionReason: 'exit' }),
      }));
    });

    it('still resolves the run promise exactly once when a step inside finish() throws synchronously', async () => {
      // unregisterExternalSession is invoked un-awaited inside finish()'s try
      // block, with no per-call try/catch of its own — unlike the PTY kill
      // (own try/catch) and finalizeRunRecord (own .catch()). If it throws,
      // finish()'s outer try/catch/finally must still guarantee `resolve()`
      // fires — otherwise executeTuiRun's promise hangs forever and any
      // caller awaiting it (pipeline stages, /runs) wedges.
      shellMocks.unregisterExternalSession.mockImplementationOnce(() => {
        throw new Error('boom: session registry corrupted');
      });
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const onComplete = vi.fn();
      const promise = executeTuiRun({ runId: 'run-finish-throws', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onComplete, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitExit({ exitCode: 0 });

      await expect(promise).resolves.toBeUndefined();
      expect(console.error).toHaveBeenCalledWith(expect.stringContaining('finish() failed'));
      // The throw happens before onComplete is reached in finish()'s normal
      // path, but resolving the inner promise alone is not enough: the sole
      // caller (executeProviderRunOnce) settles its OUTER promise only via
      // onComplete (→ safeReject) or a rejected promise. Since finish() always
      // resolves, the catch must still surface the failure through onComplete
      // with failure metadata, or the pipeline/central-prompt caller hangs
      // forever despite the inner promise settling.
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({
        success: false,
        error: expect.stringContaining('finish() failed'),
      }));
      expect(onComplete).toHaveBeenCalledTimes(1);
      // The PTY must still be torn down on the throw path — the failure we
      // report spins up a fallback provider in the real caller, and a
      // never-killed original PTY would run alongside it (two live runs).
      expect(ptyInstances[0].kill).toHaveBeenCalled();
    });

    it('does not re-invoke onComplete when onComplete itself throws inside finish()', async () => {
      // When the throw source is onComplete AFTER it has already been reached,
      // the catch must NOT call onComplete a second time — that would violate
      // the once-only completion contract and could emit a contradictory
      // success-then-failure. The run promise must still resolve exactly once.
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const onComplete = vi.fn(() => { throw new Error('boom: caller onComplete blew up'); });
      const promise = executeTuiRun({ runId: 'run-oncomplete-throws', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onComplete, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitExit({ exitCode: 0 });

      await expect(promise).resolves.toBeUndefined();
      expect(console.error).toHaveBeenCalledWith(expect.stringContaining('finish() failed'));
      // Reached exactly once (the normal-path call), never re-invoked by the catch.
      expect(onComplete).toHaveBeenCalledTimes(1);
    });

    it('finishes with reason "killed" and surfaces the signal in the error when the PTY is terminated', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const promise = executeTuiRun({ runId: 'run-killed', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitData('some screen output');
      ptyInstances[0].emitExit({ exitCode: null, signal: 'SIGTERM' });

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-killed',
        success: false,
        exitCode: 130,
        error: expect.stringContaining('SIGTERM'),
        extras: expect.objectContaining({ completionReason: 'killed' }),
      }));
    });

    it.each([
      { exitCode: null, signal: 'SIGTERM' },
      { exitCode: 143, signal: 0 },
      { exitCode: 0, signal: 0 },
    ])('finalizes an explicit stop as canceled for PTY exit %j', async (exit) => {
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const onComplete = vi.fn();
      runnerMocks.consumeRunStopRequested.mockReturnValueOnce(true);
      const promise = executeTuiRun({ runId: 'run-stopped', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onComplete, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitExit(exit);

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-stopped',
        success: false,
        error: expect.stringContaining('canceled'),
        extras: expect.objectContaining({ completionReason: 'canceled', canceled: true }),
      }));
      expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({ canceled: true }));
    });

    it('finalizes a host-shutdown signal as an interruption instead of a provider failure', async () => {
      const provider = { id: 'codex', type: 'tui', command: 'echo' };
      markHostShuttingDown();
      const promise = executeTuiRun({ runId: 'run-restart', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitExit({ exitCode: null, signal: 2 });

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-restart',
        success: false,
        error: expect.stringContaining('PortOS shutdown'),
        extras: expect.objectContaining({ completionReason: 'host-shutdown', canceled: true }),
      }));
    });

    it('finishes with a tail-bearing error message when the PTY exits non-zero with prior output', async () => {
      const provider = { id: 'claude', type: 'tui', command: 'echo' };
      const promise = executeTuiRun({ runId: 'run-nonzero', provider, prompt: 'a prompt long enough', workspacePath: TEST_WORKSPACE, onData: undefined, onComplete: undefined, timeout: 60000 });
      await flushAsync();

      ptyInstances[0].emitData('fatal: provider config malformed at line 42');
      ptyInstances[0].emitExit({ exitCode: 2 });

      await promise;
      expect(runnerMocks.finalizeRunRecord).toHaveBeenCalledWith(expect.objectContaining({
        runId: 'run-nonzero',
        success: false,
        exitCode: 2,
        error: expect.stringMatching(/TUI exited with code 2.*malformed/),
      }));
    });
  });

  // #7496. tuiPromptRunner spawns its OWN PTY directly — no hosting login shell —
  // so with a credentialBootstrap provider the PTY's direct child is the bootstrap
  // WRAPPER, and node-pty's `kill()` signals `this.pid` alone. A wrapper that
  // forks and does not forward the signal keeps the harness alive; node-pty then
  // never observes an exit, so the pty master never closes and the kernel's
  // terminal-hangup backstop never fires either. forkpty already makes the PTY
  // child a session leader whose descendants share its process group, so the group
  // signal is the exact reach this path needs.
  describe('executeTuiRun — credential-bootstrap process-group teardown', () => {
    const bootstrapProvider = {
      id: 'claude',
      type: 'tui',
      command: 'echo',
      credentialBootstrap: { command: 'token-cli', args: ['run'], argsSeparator: '--' },
    };

    let killSpy;
    beforeEach(() => {
      // Spy so the negative pid never reaches a real process group.
      killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
    });
    afterEach(() => { killSpy.mockRestore(); });

    it.skipIf(process.platform === 'win32')('signals the whole group when finish() tears a wrapped PTY down', async () => {
      const promise = executeTuiRun({
        runId: 'run-bootstrap-kill', provider: bootstrapProvider,
        prompt: 'a prompt long enough to clear the guard', workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.pid = 212121;
      expect(ptySpawnMock.mock.calls[0][0]).toBe('token-cli');

      // A non-zero exit drives finish(), whose cleanup kills the PTY.
      pty.emitExit({ exitCode: 2 });
      await promise;

      expect(killSpy).toHaveBeenCalledWith(-212121, 'SIGHUP');
      // The group signal landed, so killProcessTree never falls back to the
      // handle's own kill — the harness behind the wrapper is covered.
      expect(pty.kill).not.toHaveBeenCalled();
    });

    it.skipIf(process.platform === 'win32')('leaves an unwrapped PTY on the plain node-pty kill', async () => {
      const promise = executeTuiRun({
        runId: 'run-unwrapped-kill', provider: { id: 'claude', type: 'tui', command: 'echo' },
        prompt: 'a prompt long enough to clear the guard', workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.pid = 232323;
      pty.emitExit({ exitCode: 2 });
      await promise;

      expect(killSpy).not.toHaveBeenCalledWith(-232323, expect.anything());
      // SIGHUP is node-pty's own POSIX default for a bare kill(), so naming it
      // keeps this path byte-identical to the previous `ptyProcess.kill()`.
      expect(pty.kill).toHaveBeenCalledWith('SIGHUP');
    });

    it.skipIf(process.platform === 'win32')('registers a group-aware killable so /runs Stop reaches the harness, not just the wrapper', async () => {
      const promise = executeTuiRun({
        runId: 'run-bootstrap-stop', provider: bootstrapProvider,
        prompt: 'a prompt long enough to clear the guard', workspacePath: TEST_WORKSPACE, timeout: 60000,
      });
      await flushAsync();

      const pty = ptyInstances[0];
      pty.pid = 252525;
      const [, registered] = runnerMocks.registerActiveRun.mock.calls.at(-1);
      // The toolkit's vendored killProcessTree has no processGroup option and
      // reaches a non-ChildProcess killable through its own .kill().
      expect(registered).not.toBe(pty);
      expect(registered.pid).toBe(252525);
      registered.kill('SIGTERM');
      expect(killSpy).toHaveBeenCalledWith(-252525, 'SIGTERM');

      pty.emitExit({ exitCode: 0 });
      await promise;
    });
  });
});