subrouter-cli 0.0.0-stage → 0.1.0

package/test/steering-ui.test.ts

@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+test('live drafting, queued steering, permission prompts, cancellation and failed steering coexist', (t) => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'sub-steering-ui-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', String.raw`
+    import assert from 'node:assert/strict';
+    import fs from 'node:fs';
+    import path from 'node:path';
+    Object.defineProperty(process.stdin, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'rows', { value: 24 });
+    Object.defineProperty(process.stdout, 'columns', { value: 100 });
+    process.stdin.setRawMode = () => {};
+    process.chdir(process.env.HOME);
+    const { ui } = await import(${JSON.stringify(new URL('../src/ui.ts', import.meta.url).href)});
+    const { startRepl } = await import(${JSON.stringify(new URL('../src/repl.ts', import.meta.url).href)});
+    let status = '', queued = null;
+    const setStatus = ui.setStatus.bind(ui), setSteering = ui.setSteering.bind(ui);
+    ui.setStatus = (value) => { status = value; setStatus(value); };
+    ui.setSteering = (value, messages) => { queued = value; setSteering(value, messages); };
+    const printed = [], submitInput = ui.submitInput.bind(ui);
+    ui.submitInput = (prompt, text) => { printed.push(text); submitInput(prompt, text); };
+    const requests = [];
+    let releaseFirst, releaseFailure;
+    const client = {
+      listModels: async () => [{ id: 'openai/test' }], usage: async () => ({}),
+      chat: async (req, emit, signal) => {
+        requests.push(structuredClone(req));
+        const index = requests.length;
+        if (index === 1) {
+          emit({ kind: 'text', text: 'Before approval.' });
+          await new Promise((resolve) => { releaseFirst = resolve; });
+          return { message: { role: 'assistant', content: 'Before approval.', toolCalls: [
+            { id: 'write', name: 'write_file', arguments: { path: 'never-write.txt', content: 'no' }, argumentsJson: '{"path":"never-write.txt","content":"no"}' },
+          ] }, stopReason: 'tool_calls' };
+        }
+        if (index === 4) await new Promise((_resolve, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true }));
+        if (index === 6) await new Promise((resolve) => { releaseFailure = resolve; });
+        if (index === 7) throw new Error('temporary failure');
+        emit({ kind: 'text', text: 'Done.\n' });
+        return { message: { role: 'assistant', content: 'Done.\n' }, stopReason: 'stop' };
+      },
+    };
+    startRepl({ client, model: 'openai/test', config: { maxToolRounds: 25, maxOutputTokens: 8192, autoApprove: false } });
+    const key = (text) => process.stdin.emit('data', Buffer.from(text));
+    const until = async (predicate) => {
+      const deadline = Date.now() + 4000;
+      while (!predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5));
+      assert.ok(predicate());
+      await new Promise(setImmediate);
+    };
+    key('start\r'); await until(() => requests.length === 1);
+    key('use TypeScript\r'); key('keep it small\r');
+    assert.equal(queued, 2);
+    assert.deepEqual(printed, ['start']); // steering cannot interrupt the streamed text
+    key('/model openai/other\r');
+    await until(() => status === 'responding · ctrl+c stop');
+    assert.equal(queued, 2); // model changes apply next turn, not to the in-flight request
+    key('draft next');
+    releaseFirst(); await until(() => status === 'approval required');
+    key('n\r'); await until(() => status === 'ready');
+    assert.equal(requests.length, 2);
+    assert.deepEqual(requests[0].messages.map((m) => m.content), ['start']);
+    assert.deepEqual(requests[1].messages.map((m) => m.role), ['user', 'assistant', 'tool', 'user', 'user']);
+    assert.deepEqual(requests[1].messages.slice(-2).map((m) => m.content), ['use TypeScript', 'keep it small']);
+    assert.match(requests[1].messages[2].content, /denied/);
+    assert.equal(requests[1].model, 'openai/test');
+    assert.ok(!fs.existsSync('never-write.txt'));
+    assert.equal(queued, null);
+    key('\r'); await until(() => status === 'ready');
+    assert.equal(requests[2].messages.at(-1).content, 'draft next'); // permission prompt preserved the draft
+    assert.equal(requests[2].model, 'openai/other'); // next turn uses the selected model
+
+    key('cancel test\r'); await until(() => requests.length === 4);
+    key('queued retry\r'); key('unsent draft'); key('\x03'); await until(() => status === 'ready');
+    key('\r'); await until(() => status === 'ready');
+    assert.equal(requests[4].messages.at(-1).content, 'queued retry unsent draft');
+
+    key('failure test\r'); await until(() => requests.length === 6);
+    key('steer through failure\r'); releaseFailure(); await until(() => status === 'ready');
+    assert.equal(requests.length, 7);
+    key('\r'); await until(() => status === 'ready');
+    assert.equal(requests[7].messages.at(-1).content, 'steer through failure');
+    const sessions = path.join(process.env.HOME, '.config/subrouter-cli/sessions');
+    const records = fs.readdirSync(sessions).filter((f) => f.endsWith('.jsonl')).flatMap((f) => fs.readFileSync(path.join(sessions, f), 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse));
+    assert.deepEqual(records[0].messages.filter((m) => m.role === 'user').map((m) => m.content), ['start', 'use TypeScript', 'keep it small']);
+    key('/exit\r');
+  `], {
+    cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 15000,
+    env: { ...process.env, HOME: home, NO_COLOR: '' },
+  });
+  assert.equal(child.status, 0, child.stderr || String(child.error));
+});
+
+test('commands coexist with an image response, approvals take precedence, and clear/exit cancel safely', (t) => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'sub-live-command-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', String.raw`
+    import assert from 'node:assert/strict';
+    import fs from 'node:fs';
+    Object.defineProperty(process.stdin, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'rows', { value: 24 });
+    Object.defineProperty(process.stdout, 'columns', { value: 100 });
+    process.stdin.setRawMode = () => {};
+    process.chdir(process.env.HOME);
+    const { ui } = await import(${JSON.stringify(new URL('../src/ui.ts', import.meta.url).href)});
+    const { startRepl } = await import(${JSON.stringify(new URL('../src/repl.ts', import.meta.url).href)});
+    let status = '', release, activeSignal, panel = false;
+    const streamed = [];
+    const setStatus = ui.setStatus.bind(ui), stream = ui.streamText.bind(ui);
+    ui.setStatus = (value) => { status = value; setStatus(value); };
+    ui.streamText = (text) => { streamed.push(text); stream(text); };
+    const showPanel = ui.panel.bind(ui), closePanel = ui.closePanel.bind(ui);
+    ui.panel = (...args) => { panel = true; return showPanel(...args); };
+    ui.closePanel = () => { panel = false; closePanel(); };
+    const requests = [];
+    const client = {
+      listModels: async () => [{ id: 'openai/test' }, { id: 'openai/new' }], usage: async () => ({}),
+      chat: async (req, emit, signal) => {
+        requests.push(structuredClone(req));
+        const index = requests.length;
+        activeSignal = signal;
+        emit({ kind: 'text', text: index === 1 ? 'Image description arriving now' : 'Answer arriving now' });
+        if (index === 1) {
+          await new Promise((resolve) => { release = resolve; });
+          return { message: { role: 'assistant', content: 'Image description arriving now', toolCalls: [
+            { id: 'write', name: 'write_file', arguments: { path: 'no.txt', content: 'no' }, argumentsJson: '{"path":"no.txt","content":"no"}' },
+          ] }, stopReason: 'tool_calls' };
+        }
+        if (index === 4 || index === 6) await new Promise((_resolve, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true }));
+        return { message: { role: 'assistant', content: 'Answer arriving now' }, stopReason: 'stop', usage: { inputTokens: 10, outputTokens: 2 } };
+      },
+    };
+    const image = { name: 'clipboard.png', mediaType: 'image/png', data: 'iVBORw0KGgo=' };
+    startRepl({ client, model: 'openai/test', images: [image], config: { maxToolRounds: 25, maxOutputTokens: 8192, autoApprove: false } });
+    const key = (text) => process.stdin.emit('data', Buffer.from(text));
+    const until = async (predicate) => {
+      const deadline = Date.now() + 4000;
+      while (!predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5));
+      assert.ok(predicate()); await new Promise(setImmediate);
+    };
+    key('describe image\r'); await until(() => requests.length === 1);
+    assert.equal(requests[0].messages[0].images[0].name, 'clipboard.png');
+    assert.ok(streamed.join('').includes('Image description arriving now')); // visible before newline/finish/Ctrl+C
+    key('/model\r'); await until(() => status === 'choose model');
+    key('\x1b[B\r'); await until(() => status === 'responding · ctrl+c stop');
+    assert.equal(activeSignal.aborted, false);
+    key('/effort\r'); await until(() => status === 'choose effort');
+    key('\x1b[B\x1b[B\x1b[B\r'); await until(() => status === 'responding · ctrl+c stop');
+    key('make it smaller\r');
+    key('/usage\r'); await until(() => panel);
+    assert.equal(activeSignal.aborted, false);
+    release(); await until(() => status === 'approval required');
+    assert.equal(panel, false); // permission question preempts the open command
+    key('n\r'); await until(() => status === 'ready');
+    assert.equal(requests[1].model, 'openai/test');
+    assert.equal(requests[1].effort, 'auto');
+    assert.equal(requests[1].messages.at(-1).content, 'make it smaller');
+    assert.ok(!fs.existsSync('no.txt'));
+    key('next turn\r'); await until(() => status === 'ready');
+    assert.equal(requests[2].model, 'openai/new');
+    assert.equal(requests[2].effort, 'high');
+    key('will clear\r'); await until(() => requests.length === 4);
+    key('queued before clear\r');
+    key('/clear\r'); await until(() => status === 'ready');
+    assert.equal(activeSignal.aborted, true);
+    key('fresh\r'); await until(() => status === 'ready');
+    assert.deepEqual(requests[4].messages.map((m) => m.content), ['fresh']);
+    assert.equal(requests[4].messages[0].images, undefined);
+    key('will exit\r'); await until(() => requests.length === 6);
+    key('/exit\r'); await until(() => activeSignal.aborted);
+  `], { cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 15000, env: { ...process.env, HOME: home, NO_COLOR: '' } });
+  assert.equal(child.status, 0, child.stderr || String(child.error));
+  assert.match(child.stdout, /bye/);
+});

package/test/steering.test.ts

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { runAgentTurn, type LoopOptions } from '../src/loop.ts';
+import type { ChatMessage, ChatRequest, AssistantTurn } from '../src/types.ts';
+
+const final = (text: string): AssistantTurn => ({ message: { role: 'assistant', content: text }, stopReason: 'stop', usage: { inputTokens: 10, outputTokens: 5 } });
+function harness(): { options: LoopOptions; queue: ChatMessage[]; requests: ChatRequest[] } {
+  const queue: ChatMessage[] = [], requests: ChatRequest[] = [];
+  const options: LoopOptions = {
+    client: { chat: async (req) => { requests.push(structuredClone(req)); return final('done'); } },
+    model: 'openai/test', system: 'system', history: [{ role: 'user', content: 'start' }],
+    tools: [], ask: async () => 'no', execute: async (call) => ({ toolCallId: call.id, content: 'done' }),
+    autoApprove: false, maxRounds: 3, maxTokens: 1024, signal: new AbortController().signal,
+    onEvent: () => {}, takeSteering: () => queue.splice(0),
+  };
+  return { options, queue, requests };
+}
+
+test('steering arriving during a final response continues the same turn in FIFO order', async () => {
+  const { options, queue, requests } = harness();
+  options.client.chat = async (req) => {
+    requests.push(structuredClone(req));
+    if (requests.length === 1) queue.push({ role: 'user', content: 'use TypeScript' }, { role: 'user', content: 'keep it small' });
+    return final(requests.length === 1 ? 'first answer' : 'steered answer');
+  };
+  const result = await runAgentTurn(options);
+  assert.equal(requests.length, 2);
+  assert.deepEqual(requests[0].messages.map((m) => m.content), ['start']);
+  assert.deepEqual(requests[1].messages.map((m) => m.content), ['start', 'first answer', 'use TypeScript', 'keep it small']);
+  assert.equal(options.history.at(-1)?.content, 'steered answer');
+  assert.deepEqual(result.usage, { inputTokens: 20, outputTokens: 10 });
+  assert.equal(result.rounds, 0);
+  assert.deepEqual(queue, []);
+});
+
+test('parallel tools and their results stay contiguous before steering is applied', async () => {
+  const { options, queue, requests } = harness();
+  const tools = ['a', 'b'].map((id) => ({ id, name: 'read_file', arguments: { path: id }, argumentsJson: JSON.stringify({ path: id }) }));
+  options.client.chat = async (req) => {
+    requests.push(structuredClone(req));
+    return requests.length === 1 ? { message: { role: 'assistant', content: '', toolCalls: tools }, stopReason: 'tool_calls' } : final('steered');
+  };
+  options.execute = async (call) => {
+    queue.push({ role: 'user', content: 'steer ' + call.id });
+    return { toolCallId: call.id, content: 'result ' + call.id };
+  };
+  await runAgentTurn(options);
+  assert.deepEqual(requests[1].messages.map((m) => m.role), ['user', 'assistant', 'tool', 'tool', 'user', 'user']);
+  assert.deepEqual(requests[1].messages.slice(2).map((m) => m.content), ['result a', 'result b', 'steer a', 'steer b']);
+});
+
+test('round limits leave unapplied steering in the queue rather than bypassing the cap', async () => {
+  const { options, queue } = harness();
+  options.maxRounds = 1;
+  options.client.chat = async () => ({ message: { role: 'assistant', content: '', toolCalls: [{ id: 'a', name: 'read_file', arguments: {}, argumentsJson: '{}' }] }, stopReason: 'tool_calls' });
+  options.execute = async (call) => { queue.push({ role: 'user', content: 'not consumed' }); return { toolCallId: call.id, content: 'ok' }; };
+  const result = await runAgentTurn(options);
+  assert.equal(result.stopReason, 'length');
+  assert.equal(queue[0].content, 'not consumed');
+});
+
+test('abort during a response leaves queued steering untouched', async () => {
+  const { options, queue } = harness();
+  const abort = new AbortController(); options.signal = abort.signal;
+  options.client.chat = async () => { queue.push({ role: 'user', content: 'retry me' }); abort.abort(); return final('partial'); };
+  await assert.rejects(runAgentTurn(options), { name: 'AbortError' });
+  assert.equal(queue[0].content, 'retry me');
+});

package/test/terminal-ui.test.ts

@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+test('commands require explicit approval in auto mode; steering stays normal and active commands are not interrupted', (t) => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'sub-terminal-ui-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', String.raw`
+    import assert from 'node:assert/strict';
+    import fs from 'node:fs';
+    Object.defineProperty(process.stdin, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'rows', { value: 24 });
+    Object.defineProperty(process.stdout, 'columns', { value: 100 });
+    process.stdin.setRawMode = () => {};
+    process.chdir(process.env.HOME);
+    const { ui } = await import(${JSON.stringify(new URL('../src/ui.ts', import.meta.url).href)});
+    const { LineInput } = await import(${JSON.stringify(new URL('../src/lineinput.ts', import.meta.url).href)});
+    const { startRepl } = await import(${JSON.stringify(new URL('../src/repl.ts', import.meta.url).href)});
+    const requests = [], prompts = [], messages = [], chat = [];
+    let status = '', requestCount = 0;
+    const setStatus = ui.setStatus.bind(ui), submit = ui.submitInput.bind(ui), say = ui.say.bind(ui);
+    ui.setStatus = (value) => { status = value; setStatus(value); };
+    ui.submitInput = (prompt, text) => { messages.push({ prompt, text }); submit(prompt, text); };
+    ui.say = (line) => { chat.push(line); say(line); };
+    const question = LineInput.prototype.question;
+    LineInput.prototype.question = function(prompt) { prompts.push(prompt); return question.call(this, prompt); };
+    const command = (id, text) => ({ id, name: 'run_command', arguments: { command: text, timeout_ms: 3000 }, argumentsJson: JSON.stringify({ command: text, timeout_ms: 3000 }) });
+    const longCommand = 'printf done > denied-marker; # ' + 'long '.repeat(30) + 'VISIBLE_SUFFIX';
+    const runningCommand = 'sleep 0.4; printf output; printf finished > completed-marker';
+    const client = {
+      listModels: async () => [{ id: 'openai/test' }], usage: async () => ({}),
+      chat: async (req, emit, signal) => {
+        requests.push(structuredClone(req)); requestCount++;
+        if (requestCount === 1 || requestCount === 3 || requestCount === 5) {
+          const index = requestCount;
+          const call = command('c' + index, index === 1 ? longCommand : index === 3 ? runningCommand : 'sleep 10; printf bad > cancelled-marker');
+          return { message: { role: 'assistant', content: '', toolCalls: [call] }, stopReason: 'tool_calls' };
+        }
+        emit({ kind: 'text', text: 'Done.\n' });
+        return { message: { role: 'assistant', content: 'Done.\n' }, stopReason: 'stop' };
+      },
+    };
+    startRepl({ client, model: 'openai/test', config: { apiKey: 'synthetic-protected-key', maxToolRounds: 25, maxOutputTokens: 8192, autoApprove: true } });
+    const key = (text) => process.stdin.emit('data', Buffer.from(text));
+    const until = async (predicate) => {
+      const deadline = Date.now() + 5000;
+      while (!predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5));
+      assert.ok(predicate()); await new Promise(setImmediate);
+    };
+    key('first\r'); await until(() => prompts.length === 1);
+    assert.ok(chat.some((line) => line.includes('VISIBLE_SUFFIX')));
+    assert.equal(prompts[0], 'Allow command [y/n]: ');
+    assert.ok(!prompts[0].includes('a = all'));
+    key('\r'); await until(() => status === 'ready'); // blank never approves a terminal command
+    assert.ok(!fs.existsSync('denied-marker'));
+    assert.match(requests[1].messages.find((message) => message.role === 'tool').content, /denied/);
+    key('second\r'); await until(() => prompts.length === 2);
+    key('y\r'); await until(() => status === 'running run_command · ctrl+c stop');
+    key('change the next step\r');
+    key('keep the current command running\r');
+    key('saved draft');
+    await until(() => status === 'ready');
+    assert.equal(fs.readFileSync('completed-marker', 'utf8'), 'finished');
+    const continuation = requests[3].messages;
+    const result = JSON.parse(continuation.find((message) => message.role === 'tool' && message.toolCallId === 'c3').content);
+    assert.equal(result.status, 'completed');
+    assert.equal(result.stdout, 'output');
+    assert.deepEqual(continuation.slice(-2).map((message) => message.content), ['change the next step', 'keep the current command running']);
+    assert.ok(messages.filter((message) => message.text === 'change the next step' || message.text === 'keep the current command running').every((message) => message.prompt === '❯ '));
+    assert.ok(!messages.some((message) => message.prompt.includes('steer:')));
+    assert.ok(!chat.includes(result.stdout)); // output is a tool result, never a raw progress print
+    key('\r'); await until(() => prompts.length === 3);
+    assert.equal(requests[4].messages.at(-1).content, 'saved draft');
+    key('y\r'); await until(() => status === 'running run_command · ctrl+c stop');
+    key('\x03'); await until(() => status === 'ready');
+    assert.ok(!fs.existsSync('cancelled-marker'));
+    key('after cancellation\r'); await until(() => status === 'ready');
+    const resumed = requests[5].messages;
+    assert.equal(resumed.filter((message) => message.role === 'tool' && message.toolCallId === 'c5').length, 1);
+    assert.equal(JSON.parse(resumed.find((message) => message.role === 'tool' && message.toolCallId === 'c5').content).status, 'cancelled');
+    key('/exit\r');
+  `], {
+    cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 15000,
+    env: { ...process.env, HOME: home, NO_COLOR: '' },
+  });
+  assert.equal(child.status, 0, child.stderr || String(child.error));
+  assert.ok(!child.stdout.includes('synthetic-protected-key'));
+});
+
+test('clear and exit abort approved terminal commands, and clear removes the old workflow', (t) => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'sub-terminal-controls-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', String.raw`
+    import assert from 'node:assert/strict';
+    import fs from 'node:fs';
+    Object.defineProperty(process.stdin, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'rows', { value: 24 });
+    Object.defineProperty(process.stdout, 'columns', { value: 100 });
+    process.stdin.setRawMode = () => {};
+    process.chdir(process.env.HOME);
+    const { ui } = await import(${JSON.stringify(new URL('../src/ui.ts', import.meta.url).href)});
+    const { LineInput } = await import(${JSON.stringify(new URL('../src/lineinput.ts', import.meta.url).href)});
+    const { startRepl } = await import(${JSON.stringify(new URL('../src/repl.ts', import.meta.url).href)});
+    let status = '', questions = 0, activeSignal;
+    const requests = [];
+    const setStatus = ui.setStatus.bind(ui), question = LineInput.prototype.question;
+    ui.setStatus = (value) => { status = value; setStatus(value); };
+    LineInput.prototype.question = function(prompt) { questions++; return question.call(this, prompt); };
+    const client = {
+      listModels: async () => [{ id: 'openai/test' }], usage: async () => ({}),
+      chat: async (req, emit, signal) => {
+        activeSignal = signal;
+        requests.push(structuredClone(req));
+        const args = { command: 'sleep 10; printf bad > never-finish', timeout_ms: 20000 };
+        return { message: { role: 'assistant', content: '', toolCalls: [{ id: 'c' + requests.length, name: 'run_command', arguments: args, argumentsJson: JSON.stringify(args) }] }, stopReason: 'tool_calls' };
+      },
+    };
+    startRepl({ client, model: 'openai/test', config: { apiKey: 'synthetic-key', maxToolRounds: 25, maxOutputTokens: 8192, autoApprove: true } });
+    const key = (text) => process.stdin.emit('data', Buffer.from(text));
+    const until = async (predicate) => {
+      const deadline = Date.now() + 5000;
+      while (!predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5));
+      assert.ok(predicate()); await new Promise(setImmediate);
+    };
+    key('first\r'); await until(() => questions === 1);
+    key('y\r'); await until(() => status === 'running run_command · ctrl+c stop');
+    key('queued before clear\r');
+    key('/clear\r'); await until(() => status === 'ready');
+    assert.equal(activeSignal.aborted, true);
+    assert.ok(!fs.existsSync('never-finish'));
+    key('fresh\r'); await until(() => questions === 2);
+    assert.deepEqual(requests[1].messages.map((message) => message.content), ['fresh']);
+    key('y\r'); await until(() => status === 'running run_command · ctrl+c stop');
+    key('/exit\r');
+    assert.equal(activeSignal.aborted, true);
+  `], { cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 15000, env: { ...process.env, HOME: home, NO_COLOR: '' } });
+  assert.equal(child.status, 0, child.stderr || String(child.error));
+  assert.ok(!fs.existsSync(path.join(home, 'never-finish')));
+});

package/test/terminal.test.ts

@@ -0,0 +1,229 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { test } from 'node:test';
+import { DEFAULT_COMMAND_TIMEOUT_MS, MAX_COMMAND_BYTES, MAX_COMMAND_TIMEOUT_MS, escapeTerminalText, executeCommand, sanitizeCommandOutput, validateCommand } from '../src/terminal.ts';
+
+const FAKE_KEY = 'synthetic-key-NOT-A-REAL-CREDENTIAL';
+const quote = (text: string): string => `'${text.replaceAll("'", "'\\''")}'`;
+const node = quote(process.execPath);
+
+async function fixture(code: string, run: (cwd: string, command: string) => Promise<void>): Promise<void> {
+  const cwd = await mkdtemp(join(tmpdir(), 'sub-terminal-test-'));
+  try {
+    await writeFile(join(cwd, 'fixture.cjs'), code);
+    await run(cwd, `${node} fixture.cjs`);
+  } finally { await rm(cwd, { recursive: true, force: true }); }
+}
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+async function assertGone(pid: number): Promise<void> {
+  for (let i = 0; i < 100 && alive(pid); i++) await delay(20);
+  assert.equal(alive(pid), false, `controlled fixture process ${pid} must be cleaned up`);
+}
+async function waitForFile(path: string): Promise<string> {
+  for (let i = 0; i < 100; i++) {
+    try { return await readFile(path, 'utf8'); } catch { await delay(10); }
+  }
+  throw new Error('Controlled fixture did not become ready');
+}
+
+test('validates byte size, secret-bearing commands, and integer timeouts without echoing input', () => {
+  assert.deepEqual(validateCommand('pwd', undefined), { command: 'pwd', timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS });
+  assert.equal(validateCommand('x'.repeat(MAX_COMMAND_BYTES), MAX_COMMAND_TIMEOUT_MS).timeoutMs, MAX_COMMAND_TIMEOUT_MS);
+  for (const command of [null, 1, {}, '', ' \n\t', 'a\0b', 'x'.repeat(MAX_COMMAND_BYTES + 1), 'é'.repeat(MAX_COMMAND_BYTES / 2 + 1)]) {
+    assert.throws(() => validateCommand(command, 1));
+  }
+  for (const timeout of [null, '1', 0, -1, 1.1, NaN, Infinity, MAX_COMMAND_TIMEOUT_MS + 1]) {
+    assert.throws(() => validateCommand('pwd', timeout));
+  }
+  assert.throws(() => validateCommand(`printf ${FAKE_KEY}`, 1, [FAKE_KEY]), (error: unknown) => {
+    assert.ok(error instanceof Error);
+    assert.ok(!error.message.includes(FAKE_KEY));
+    return true;
+  });
+  assert.equal(validateCommand('pwd', 1, ['']).command, 'pwd');
+});
+
+test('approval escaping is lossless and makes terminal controls and invisible text visible', () => {
+  assert.equal(escapeTerminalText('café 😀'), 'café 😀');
+  assert.equal(escapeTerminalText('a\n\t\r\x1b[2J\x00\x7f\u0085‮​\\n'), 'a\\n\\t\\r\\u001b[2J\\u0000\\u007f\\u0085\\u202e\\u200b\\\\n');
+  assert.equal(escapeTerminalText('\ud800
️'), '\\ud800\\u2028\\ufe0f');
+});
+
+test('captures both streams, exit status, cwd, and strips terminal controls', async () => {
+  await fixture(`process.stdout.write('hello\\n\\x1b[31mred\\x1b[0m\\r\\u202ehidden'); process.stderr.write('oops\\n'); process.exitCode = 7;`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000 });
+    assert.deepEqual(result, { status: 'failed', exit_code: 7, signal: null, stdout: 'hello\nredhidden', stderr: 'oops\n', truncated: false });
+    const success = await executeCommand({ command: 'printf "%s" "$PWD"', cwd, timeoutMs: 2000 });
+    assert.equal(success.status, 'completed');
+    assert.equal(success.stdout, await realpath(cwd));
+  });
+});
+
+test('only allowlisted environment variables reach the shell', async () => {
+  const name = 'SUB_TERMINAL_SYNTHETIC_SECRET';
+  process.env[name] = FAKE_KEY;
+  process.env.LC_SYNTHETIC_SECRET = FAKE_KEY;
+  try {
+    await fixture(`process.stdout.write(JSON.stringify({ keys: Object.keys(process.env), term: process.env.TERM }));`, async (cwd, command) => {
+      const result = await executeCommand({ command, cwd, timeoutMs: 2000 });
+      assert.equal(result.status, 'completed');
+      const env = JSON.parse(result.stdout);
+      assert.equal(env.term, 'dumb');
+      assert.ok(!env.keys.includes(name));
+      assert.ok(!env.keys.includes('LC_SYNTHETIC_SECRET'));
+      assert.ok(!env.keys.includes('SUBROUTER_API_KEY'));
+      assert.ok(!env.keys.includes('NODE_OPTIONS'));
+      // zsh adds bookkeeping variables; macOS adds __CF_USER_TEXT_ENCODING.
+      assert.ok(env.keys.every((key: string) => /^(?:PATH|HOME|USER|LOGNAME|TMPDIR|LANG|LC_[A-Za-z0-9_]+|TERM|PWD|OLDPWD|SHLVL|_|__CF_USER_TEXT_ENCODING)$/.test(key)), JSON.stringify(env.keys));
+    });
+  } finally { delete process.env[name]; delete process.env.LC_SYNTHETIC_SECRET; }
+});
+
+test('redacts secrets split between chunks on either stream and strips string controls', async () => {
+  await fixture(`const key = ${JSON.stringify(FAKE_KEY)};
+    process.stdout.write(key.slice(0, 9)); process.stderr.write(key.slice(0, 7));
+    setTimeout(() => { process.stdout.write(key.slice(9) + '\\x1b]0;misleading title\\x07OK\\x1bPprivate payload\\x1b\\\\'); process.stderr.write(key.slice(7)); }, 30);`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000, redactValues: [FAKE_KEY] });
+    assert.equal(result.stdout, '[REDACTED]OK');
+    assert.equal(result.stderr, '[REDACTED]');
+  });
+});
+
+test('redaction handles overlapping values and control-stripped secrets', async () => {
+  await fixture(`process.stdout.write('abcde a\\x1b[31mbcde');`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000, redactValues: ['abc', 'bcde'] });
+    assert.equal(result.stdout, '[REDACTED] [REDACTED]');
+  });
+});
+
+test('output is capped across streams and key prefixes at the truncation boundary are redacted', async () => {
+  await fixture(`process.stdout.write('x'.repeat(65536 - 11) + ${JSON.stringify(FAKE_KEY)} + 'overflow'); setInterval(() => {}, 1000);`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000, redactValues: [FAKE_KEY] });
+    assert.equal(result.status, 'output_limit');
+    assert.equal(result.truncated, true);
+    assert.equal(result.stdout, 'x'.repeat(65536 - 11) + '[REDACTED]');
+    assert.ok(!result.stdout.includes(FAKE_KEY.slice(0, 11)));
+  });
+  await fixture(`process.stdout.write('a'.repeat(40000)); setTimeout(() => { process.stderr.write('b'.repeat(40000)); setInterval(() => {}, 1000); }, 30);`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000 });
+    assert.equal(result.status, 'output_limit');
+    assert.equal(Buffer.byteLength(result.stdout) + Buffer.byteLength(result.stderr), 65536);
+  });
+});
+
+test('UTF-8 survives chunk boundaries and omits an incomplete code point at the cap', async () => {
+  await fixture(`const bytes = Buffer.from('é😀漢'); process.stdout.write(bytes.subarray(0, 3)); setTimeout(() => process.stdout.write(bytes.subarray(3)), 20);`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000 });
+    assert.equal(result.stdout, 'é😀漢');
+  });
+  await fixture(`process.stdout.write('x'.repeat(65535) + '😀');`, async (cwd, command) => {
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000 });
+    assert.equal(result.status, 'output_limit');
+    assert.equal(result.stdout, 'x'.repeat(65535));
+    assert.ok(!result.stdout.includes('�'));
+  });
+});
+
+test('already-aborted requests never spawn and invalid execution resolves structurally', async () => {
+  await fixture('', async (cwd) => {
+    const result = await executeCommand({ command: 'printf spawned > marker', cwd, timeoutMs: 1000, signal: AbortSignal.abort() });
+    assert.equal(result.status, 'cancelled');
+    await assert.rejects(readFile(join(cwd, 'marker')), { code: 'ENOENT' });
+    assert.equal((await executeCommand({ command: '\0', cwd, timeoutMs: 1 })).status, 'spawn_error');
+    const failed = await executeCommand({ command: 'true', cwd: join(cwd, FAKE_KEY), timeoutMs: 1000, redactValues: [FAKE_KEY] });
+    assert.equal(failed.status, 'spawn_error');
+    assert.ok(!failed.stderr.includes(FAKE_KEY));
+  });
+});
+
+test('timeout and abort terminate controlled process groups, including TERM-resistant processes', async () => {
+  await fixture(`process.on('SIGTERM', () => {}); require('node:fs').writeFileSync('ready', String(process.pid)); setInterval(() => {}, 1000);`, async (cwd, command) => {
+    const start = Date.now();
+    const promise = executeCommand({ command, cwd, timeoutMs: 250 });
+    const pid = Number(await waitForFile(join(cwd, 'ready')));
+    const result = await promise;
+    assert.equal(result.status, 'timed_out');
+    assert.equal(result.signal, 'SIGKILL');
+    assert.ok(Date.now() - start < 2000);
+    await assertGone(pid);
+  });
+  await fixture(`require('node:fs').writeFileSync('ready', String(process.pid)); setInterval(() => {}, 1000);`, async (cwd, command) => {
+    const controller = new AbortController();
+    const promise = executeCommand({ command, cwd, timeoutMs: 5000, signal: controller.signal });
+    const pid = Number(await waitForFile(join(cwd, 'ready')));
+    controller.abort(); controller.abort();
+    const result = await promise;
+    assert.equal(result.status, 'cancelled');
+    await assertGone(pid);
+  });
+});
+
+test('shell exit cleans up background pipe holders and keeps KILL escalation after shell exit', async () => {
+  await fixture(`process.on('SIGTERM', () => {}); require('node:fs').writeFileSync('ready', String(process.pid)); process.stdout.write('child-ready'); setInterval(() => {}, 1000);`, async (cwd, command) => {
+    const start = Date.now();
+    const result = await executeCommand({ command: `${command} & while [[ ! -f ready ]]; do /bin/sleep 0.01; done; exit 0`, cwd, timeoutMs: 3000 });
+    const pid = Number(await readFile(join(cwd, 'ready'), 'utf8'));
+    assert.equal(result.status, 'completed');
+    assert.equal(result.exit_code, 0);
+    assert.equal(result.stdout, 'child-ready');
+    assert.ok(Date.now() - start < 1500);
+    await assertGone(pid);
+  });
+});
+
+test('output sanitation exposes no protected values even after control normalization', () => {
+  assert.equal(sanitizeCommandOutput(`prefix ${FAKE_KEY} suffix`, [FAKE_KEY]), 'prefix [REDACTED] suffix');
+  assert.equal(sanitizeCommandOutput('safe\x1b]unfinished title‮'), 'safe');
+  assert.equal(sanitizeCommandOutput('prefix synthetic-key-', [FAKE_KEY], true), 'prefix [REDACTED]');
+  assert.equal(sanitizeCommandOutput('a​bc', ['a​bc']), '[REDACTED]');
+});
+
+test('an escaped controlled pipe holder cannot prevent bounded settlement', async () => {
+  const worker = `process.on('SIGTERM', () => {}); require('node:fs').writeFileSync('escaped-ready', String(process.pid)); setInterval(() => {}, 1000);`;
+  await fixture(`const child = require('node:child_process').spawn(process.execPath, ['-e', ${JSON.stringify(worker)}], { detached: true, stdio: 'inherit' }); child.unref();`, async (cwd, command) => {
+    let pid: number | undefined;
+    try {
+      const start = Date.now();
+      const promise = executeCommand({ command, cwd, timeoutMs: 2000 });
+      pid = Number(await waitForFile(join(cwd, 'escaped-ready')));
+      const result = await promise;
+      assert.equal(result.status, 'completed');
+      assert.ok(Date.now() - start < 1500);
+      assert.ok(alive(pid), 'a deliberately escaped group is outside the helper cleanup guarantee');
+    } finally {
+      if (pid && alive(pid)) process.kill(-pid, 'SIGKILL');
+      if (pid) await assertGone(pid);
+    }
+  });
+});
+
+test('abort during listener registration is observed', async () => {
+  await fixture('setInterval(() => {}, 1000);', async (cwd, command) => {
+    const controller = new AbortController();
+    const add = controller.signal.addEventListener.bind(controller.signal);
+    controller.signal.addEventListener = (...args: Parameters<typeof add>) => { controller.abort(); add(...args); };
+    const result = await executeCommand({ command, cwd, timeoutMs: 2000, signal: controller.signal });
+    assert.equal(result.status, 'cancelled');
+  });
+});
+
+test('abort listener is removed when execution settles', async () => {
+  await fixture('', async (cwd) => {
+    const controller = new AbortController();
+    let adds = 0, removes = 0;
+    const add = controller.signal.addEventListener.bind(controller.signal);
+    const remove = controller.signal.removeEventListener.bind(controller.signal);
+    controller.signal.addEventListener = (...args: Parameters<typeof add>) => { adds++; add(...args); };
+    controller.signal.removeEventListener = (...args: Parameters<typeof remove>) => { removes++; remove(...args); };
+    await executeCommand({ command: 'true', cwd, timeoutMs: 3000, signal: controller.signal });
+    assert.equal(adds, 1);
+    assert.equal(removes, 1);
+    controller.abort();
+  });
+});