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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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;
});
});
});