@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/__tests__/sec-019-terminal-sanitizer.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, it } from 'vitest';
+
+import { renderMarkdown } from '../render-markdown.js';
+import {
+  createStreamingTerminalSanitizer,
+  sanitizeTerminalText,
+} from '../sanitize-terminal-text.js';
+
+/**
+ * SEC-019 (issue #2022) - untrusted text may not act on the terminal.
+ *
+ * Model output, tool output, file contents and plugin text reach Ink `<Text>`, and Ink passes control
+ * sequences through. These assert the property rather than the implementation: after sanitization the
+ * string contains no byte a terminal interprets as a command, and ordinary content is untouched.
+ */
+const ESC = String.fromCharCode(27);
+const BEL = String.fromCharCode(7);
+
+// Each entry is a real attack from the issue's impact list, not a synthetic control character, and
+// each carries the EXACT output expected from `'before' + payload + 'after'`.
+//
+// The exact string is the point. The first version of this table asserted only that no control byte
+// survived and that `before` was still there, and both held for a sanitizer that stripped a DCS
+// introducer and left `q#0;2;0;0;0` standing as visible text — the defect review found on PR #2212.
+// An assertion that a buggy implementation also satisfies is not a regression test.
+const C1 = (code: number): string => String.fromCharCode(code);
+const ATTACKS: Array<[string, string, string]> = [
+  ['OSC 52 clipboard write', ESC + ']52;c;aGVsbG8=' + BEL, 'beforeafter'],
+  ['OSC 52 with ST terminator', ESC + ']52;c;aGVsbG8=' + ESC + '\\', 'beforeafter'],
+  [
+    'OSC 8 deceptive hyperlink',
+    ESC + ']8;;https://evil.example' + BEL + 'click me' + ESC + ']8;;' + BEL,
+    // The visible half survives as ordinary text; only the target and its framing are gone, which is
+    // exactly the deception being removed — the link text was never the dangerous part.
+    'beforeclick meafter',
+  ],
+  ['OSC 0 window title', ESC + ']0;pwned' + BEL, 'beforeafter'],
+  ['CSI cursor move', ESC + '[10;10H', 'beforeafter'],
+  ['CSI erase display', ESC + '[2J', 'beforeafter'],
+  ['CSI private mode', ESC + '[?1049h', 'beforeafter'],
+  // ECMA-48 parameter bytes are 0x30-0x3F, which is `0123456789:;<=>?` — not the digits, `;` and
+  // `?` an author writes from memory. Every row below was left as visible text by that shorter
+  // class, and the first two are not exotic: colon-separated SGR is the standard truecolor form and
+  // the `<` report is what a terminal sends on every mouse event.
+  ['CSI truecolor SGR, colon form', ESC + '[38:2:255:0:0m', 'beforeafter'],
+  ['CSI SGR mouse report', ESC + '[<0;10;20M', 'beforeafter'],
+  ['CSI device attributes, > parameter', ESC + '[>c', 'beforeafter'],
+  ['CSI = parameter', ESC + '[=1h', 'beforeafter'],
+  ['8-bit CSI SGR mouse report', C1(0x9b) + '<0;10;20M', 'beforeafter'],
+  ['DCS', ESC + 'Pq#0;2;0;0;0' + ESC + '\\', 'beforeafter'],
+  ['APC', ESC + '_Ginline=1' + ESC + '\\', 'beforeafter'],
+  ['PM', ESC + '^payload' + ESC + '\\', 'beforeafter'],
+  ['SOS with BEL terminator', ESC + 'Xdata' + BEL, 'beforeafter'],
+  ['bare ESC', ESC, 'beforeafter'],
+  ['bare BEL', BEL, 'beforeafter'],
+  // The 8-bit spellings are the same sequences with a one-byte introducer. They are listed
+  // separately because an alternation that names only `ESC [` removes the introducer and leaves the
+  // parameters — the identical defect, reached by a different route.
+  ['8-bit CSI (C1)', C1(0x9b) + '2J', 'beforeafter'],
+  ['8-bit OSC with BEL', C1(0x9d) + '52;c;x' + BEL, 'beforeafter'],
+  ['8-bit OSC with 8-bit ST', C1(0x9d) + '52;c;x' + C1(0x9c), 'beforeafter'],
+  ['8-bit DCS', C1(0x90) + 'q#0;2;0;0;0' + C1(0x9c), 'beforeafter'],
+  ['8-bit APC', C1(0x9f) + 'Ginline=1' + C1(0x9c), 'beforeafter'],
+  ['8-bit PM', C1(0x9e) + 'payload' + C1(0x9c), 'beforeafter'],
+  ['lone 8-bit ST', C1(0x9c), 'beforeafter'],
+  // An unterminated sequence swallows what follows, which is what the terminal itself does.
+  ['unterminated OSC', ESC + ']52;c;dangling', 'before'],
+  ['unterminated 8-bit APC', C1(0x9f) + 'dangling', 'before'],
+  ['unterminated DCS', ESC + 'Pq#0;2;0;0;0', 'before'],
+];
+
+/** No byte a terminal reads as a command survives. */
+function hasTerminalControl(text: string): boolean {
+  for (const ch of text) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (ch === '\t' || ch === '\n') continue;
+    if (code <= 0x1f || code === 0x7f) return true;
+    if (code >= 0x80 && code <= 0x9f) return true;
+  }
+  return false;
+}
+
+describe('SEC-019 - a control sequence in untrusted text is neutralized', () => {
+  it.each(ATTACKS)('removes %s', (_label, payload, expected) => {
+    const out = sanitizeTerminalText('before' + payload + 'after');
+    // The exact output, not a property. `hasTerminalControl` is asserted as well because the two
+    // claims are different: one says the string is safe, the other says the whole sequence is gone.
+    expect(out).toBe(expected);
+    expect(hasTerminalControl(out), JSON.stringify(out)).toBe(false);
+  });
+
+  it('keeps the text after a TERMINATED sequence', () => {
+    const out = sanitizeTerminalText('before' + ESC + ']52;c;aGk=' + BEL + 'after');
+    expect(out).toBe('beforeafter');
+  });
+
+  it('swallows what follows an UNTERMINATED sequence, as a terminal would', () => {
+    // An unterminated OSC consumes subsequent bytes until a terminator arrives, so dropping the tail
+    // matches what the terminal itself does. Keeping it would print the payload's own text as if it
+    // were content, which is the deceptive half of OSC 8.
+    const out = sanitizeTerminalText('before' + ESC + ']52;c;dangling-and-then-some');
+    expect(out).toBe('before');
+  });
+
+  // The two cases below repeat rows of the table above under literal titles ON PURPOSE.
+  //
+  // `it.each` builds each case's title from a printf placeholder (`'removes %s'`), and the
+  // accidental-green floor reads added case titles out of the diff — where the only text present is
+  // `removes %s`, which matches no runtime title. Every `it.each` case is therefore invisible to it,
+  // so a suite built entirely from tables can supply no red proof at all. Measured on this branch:
+  // reversing the fix turned 5 `it.each` cases red and the floor still reported accidental-green.
+  //
+  // These two are the named proof for the defect review found on PR #2212, and they are the cases
+  // that must go red if anyone restores the introducer-only behaviour.
+
+  it('removes the whole DCS sequence, not only its two-character introducer', () => {
+    // The lazy-quantifier bug left this as 'beforeq#0;2;0;0;0after' while every "no control byte
+    // survives" assertion in the file stayed green.
+    const out = sanitizeTerminalText('before' + ESC + 'Pq#0;2;0;0;0' + ESC + '\\' + 'after');
+    expect(out).toBe('beforeafter');
+    expect(out).not.toContain('q#0');
+  });
+
+  it('removes a CSI carrying any ECMA-48 parameter byte, not only digits and ? and ;', () => {
+    // The shorter parameter class left `38:2:255:0:0m` and `<0;10;20M` standing as text: neither
+    // matched the CSI alternative, the two-character-escape alternative does not accept `[` as its
+    // second character, and the lone-control fallback took only the ESC.
+    for (const body of ['38:2:255:0:0m', '<0;10;20M', '>c', '=1h', ':::x']) {
+      expect(sanitizeTerminalText(`before${ESC}[${body}after`)).toBe('beforeafter');
+    }
+  });
+
+  it('removes the whole 8-bit sequence, not only its one-byte C1 introducer', () => {
+    // A terminal reads \x9b and `ESC [` as the same CSI. An alternation that names only the 7-bit
+    // spelling leaves the parameters standing: '2J' and '52;c;x' as visible text.
+    expect(sanitizeTerminalText('before' + C1(0x9b) + '2J' + 'after')).toBe('beforeafter');
+    expect(sanitizeTerminalText('before' + C1(0x9d) + '52;c;x' + BEL + 'after')).toBe(
+      'beforeafter',
+    );
+    expect(sanitizeTerminalText('before' + C1(0x9f) + 'Ginline=1' + C1(0x9c) + 'after')).toBe(
+      'beforeafter',
+    );
+  });
+
+  it('keeps tab and newline, which are content', () => {
+    expect(sanitizeTerminalText('a\tb\nc')).toBe('a\tb\nc');
+  });
+
+  it('normalizes CRLF and removes a bare CR, which is a cursor move', () => {
+    // Measured against a real terminal stream: Ink strips OSC 52 and CSI on its way out, and passes
+    // a bare `\r` through intact. `safe text\rEVIL` therefore prints EVIL over what the transcript
+    // said — the same "what you read is not what happened" attack as a deceptive hyperlink, with no
+    // escape sequence in it at all. The first version of this module kept CR as content.
+    expect(sanitizeTerminalText('safe text\rEVIL')).toBe('safe textEVIL');
+    expect(sanitizeTerminalText('a\r\nb\r\nc')).toBe('a\nb\nc');
+    expect(sanitizeTerminalText('trailing\r')).toBe('trailing');
+  });
+
+  it('leaves ordinary Unicode alone - the goal is what the TERMINAL acts on', () => {
+    const text = 'héllo 世界 🙂 café — “quoted”';
+    expect(sanitizeTerminalText(text)).toBe(text);
+  });
+
+  it('cannot be bypassed through a markdown code fence', () => {
+    // A fence is where an author expects raw text to survive verbatim, which is exactly why it is
+    // the first place an attacker would put an escape.
+    const out = renderMarkdown('```\n' + ESC + ']52;c;aGk=' + BEL + '\n```', { color: false });
+    expect(out).not.toContain(ESC + ']');
+    expect(out).not.toContain(BEL);
+  });
+
+  it('cannot be bypassed through a markdown link target', () => {
+    const out = renderMarkdown('[text](' + ESC + ']8;;https://evil.example' + BEL + ')', {
+      color: false,
+    });
+    expect(out).not.toContain(BEL);
+  });
+
+  it('cannot be bypassed through a diff block or a carriage return', () => {
+    const out = renderMarkdown('```diff\n- a' + ESC + '[2J\r+ b\n```', { color: false });
+    expect(out).not.toContain(ESC + '[2J');
+  });
+
+  it('still emits the colours the renderer generates AFTER sanitization', () => {
+    // The ordering is the design: sanitize the INPUT, never the output. If the sanitizer were moved
+    // to the output this goes red, because the repository's own diff colouring is ANSI too.
+    //
+    // A diff block rather than `**bold**`: bold comes from chalk, which disables itself off a TTY, so
+    // that assertion would be testing chalk's environment detection instead of this ordering.
+    const out = renderMarkdown('```diff\n- removed\n+ added\n```', { color: true });
+    expect(out, 'internally generated ANSI was stripped').toContain(ESC + '[');
+  });
+});
+
+describe('SEC-019 - a sequence split across streaming chunks is still removed', () => {
+  const PAYLOAD = 'A' + ESC + ']52;c;aGVsbG8=' + BEL + 'B';
+
+  // EVERY split point, not a sampled one: the issue asks for exactly this.
+  const SPLITS = Array.from({ length: PAYLOAD.length - 1 }, (_, i) => i + 1);
+
+  it.each(SPLITS)('split at %i', (at) => {
+    const s = createStreamingTerminalSanitizer();
+    const out = s.push(PAYLOAD.slice(0, at)) + s.push(PAYLOAD.slice(at)) + s.flush();
+    expect(hasTerminalControl(out), JSON.stringify(out)).toBe(false);
+    expect(out).toBe('AB');
+  });
+
+  // The 8-bit spelling has its own held-back tail in `INCOMPLETE_TAIL`, and a claim with no test is
+  // the thing this file exists to refuse. Same exhaustive split, different introducer.
+  const C1_PAYLOAD = 'A' + C1(0x9d) + '52;c;aGVsbG8=' + C1(0x9c) + 'B';
+  const C1_SPLITS = Array.from({ length: C1_PAYLOAD.length - 1 }, (_, i) => i + 1);
+
+  it.each(C1_SPLITS)('8-bit OSC split at %i', (at) => {
+    const s = createStreamingTerminalSanitizer();
+    const out = s.push(C1_PAYLOAD.slice(0, at)) + s.push(C1_PAYLOAD.slice(at)) + s.flush();
+    expect(out).toBe('AB');
+    expect(hasTerminalControl(out), JSON.stringify(out)).toBe(false);
+  });
+
+  it('holds back an incomplete tail rather than emitting its visible half', () => {
+    const s = createStreamingTerminalSanitizer();
+    // `ESC ]52;c;` alone is not yet dangerous and not yet safe to print — emitting `52;c;` as text
+    // would show the middle of a sequence while dropping the part that made it an escape.
+    expect(s.push('x' + ESC + ']52;c;')).toBe('x');
+    expect(s.push('aGk=' + BEL + 'y')).toBe('y');
+  });
+
+  it('flushes an escape that never completes, rather than leaking it', () => {
+    const s = createStreamingTerminalSanitizer();
+    expect(s.push('x' + ESC + ']52;c;dangling')).toBe('x');
+    expect(hasTerminalControl(s.flush())).toBe(false);
+  });
+
+  // A sequence that ENDED inside the chunk is not an incomplete tail, and treating it as one is a
+  // stall rather than a leak: `push` returns the text before it and holds everything after, so the
+  // trailing content does not appear until the next chunk or the flush. Found in review of PR #2212
+  // — the streaming table above splits an OSC and never puts a COMPLETE sequence mid-chunk, so it
+  // could not see this.
+
+  it('emits text that follows a DCS sequence already terminated inside the chunk', () => {
+    const s = createStreamingTerminalSanitizer();
+    expect(s.push('hello' + ESC + 'Pq#0;2;0;0;0' + ESC + '\\' + 'world')).toBe('helloworld');
+    expect(s.flush()).toBe('');
+  });
+
+  it('emits text that follows an 8-bit APC sequence already terminated inside the chunk', () => {
+    const s = createStreamingTerminalSanitizer();
+    expect(s.push('hello' + C1(0x9f) + 'Ginline=1' + C1(0x9c) + 'world')).toBe('helloworld');
+    expect(s.flush()).toBe('');
+  });
+
+  // Exhaustive splits for the DCS family too, not only OSC. The 7-bit and 8-bit bodies are the two
+  // branches that carry the lookahead, so they are the two that must survive every boundary.
+  const DCS_PAYLOAD = 'A' + ESC + 'Pq#0;2;0;0;0' + ESC + '\\' + 'B';
+  const DCS_SPLITS = Array.from({ length: DCS_PAYLOAD.length - 1 }, (_, i) => i + 1);
+
+  it.each(DCS_SPLITS)('DCS split at %i', (at) => {
+    const s = createStreamingTerminalSanitizer();
+    const out = s.push(DCS_PAYLOAD.slice(0, at)) + s.push(DCS_PAYLOAD.slice(at)) + s.flush();
+    expect(out).toBe('AB');
+  });
+
+  const APC8_PAYLOAD = 'A' + C1(0x9f) + 'Ginline=1' + C1(0x9c) + 'B';
+  const APC8_SPLITS = Array.from({ length: APC8_PAYLOAD.length - 1 }, (_, i) => i + 1);
+
+  it.each(APC8_SPLITS)('8-bit APC split at %i', (at) => {
+    const s = createStreamingTerminalSanitizer();
+    const out = s.push(APC8_PAYLOAD.slice(0, at)) + s.push(APC8_PAYLOAD.slice(at)) + s.flush();
+    expect(out).toBe('AB');
+  });
+
+  it('passes ordinary chunked text through unchanged', () => {
+    const s = createStreamingTerminalSanitizer();
+    expect(s.push('hello ') + s.push('world') + s.flush()).toBe('hello world');
+  });
+});

package/src/__tests__/sec-019-tool-label-render.test.tsx

@@ -0,0 +1,207 @@
+/**
+ * SEC-019 (issue #2022) — what actually reaches the terminal, measured rather than assumed.
+ *
+ * ## The oracle, and why it is not `lastFrame()`
+ *
+ * The first version of this file asserted against `ink-testing-library`'s `lastFrame()`. That is not
+ * what the terminal receives. Ink strips most control sequences on its way out — a side effect of
+ * slicing text for layout, not a documented guarantee — so a frame assertion is green whether the
+ * code sanitizes or not, for every sequence Ink happens to remove. Mutation exposed it: removing the
+ * sanitization from three call sites left every frame-based case passing.
+ *
+ * So these tests render through REAL Ink into a fake TTY and read the bytes it writes.
+ *
+ * ## What Ink removes and what it does not — measured on this dependency version
+ *
+ *   stripped   OSC 52 (clipboard), OSC 0 (title), CSI erase/cursor/alt-screen, DCS, APC, 8-bit CSI
+ *   REACHES    SGR colour, OSC 8 hyperlink, a bare carriage return
+ *
+ * The two that reach are the live attack surface through `<Text>`: a link whose visible text and
+ * target differ, and a CR that overwrites the line the transcript just printed. `useTerminalTitle`
+ * writes to stdout directly and is subject to none of Ink's filtering.
+ *
+ * The sanitizer covers the whole class anyway, and the reason is the measurement itself: Ink's
+ * stripping is incidental. It is not in Ink's contract, no test of Ink's asserts it, and a dependency
+ * upgrade can return the entire class silently. A security boundary that rests on another project's
+ * implementation detail is a boundary in name.
+ */
+
+import { render as inkRender, Text } from 'ink';
+import React from 'react';
+import { Writable } from 'node:stream';
+import { describe, expect, it } from 'vitest';
+
+import { createToolMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+
+import MessageList from '../MessageList.js';
+import StreamingIndicator from '../StreamingIndicator.js';
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+const ESC = String.fromCharCode(27);
+const BEL = String.fromCharCode(7);
+
+/** OSC 8 renders a link whose visible text and target differ — and Ink passes it through. */
+const LINK_MARKER = 'pwn-link-marker-8f3a';
+const DECEPTIVE_LINK = `${ESC}]8;;https://evil.example/${LINK_MARKER}${BEL}`;
+/** A bare CR returns the cursor to column zero and overwrites what was printed. */
+const OVERWRITE = `\rpwn-overwrite-4c1e`;
+/** Stripped by this Ink version; included because the sanitizer must not depend on that. */
+const CLIPBOARD_WRITE = `${ESC}]52;c;cG93bmVk${BEL}`;
+const ERASE_DISPLAY = `${ESC}[2J`;
+
+const POISON = `${CLIPBOARD_WRITE}${DECEPTIVE_LINK}${ERASE_DISPLAY}${OVERWRITE}`;
+
+/** The markers whose presence in the byte stream proves the payload reached the terminal. */
+function carriesPayload(stream: string): boolean {
+  return (
+    stream.includes(LINK_MARKER) ||
+    // The CR immediately before the marker, not the marker alone: once the CR is gone the words are
+    // ordinary content and printing them is correct. Asserting on the text would have failed a
+    // correct sanitizer, which is the mirror of asserting on nothing.
+    stream.includes(OVERWRITE) ||
+    stream.includes('52;c;cG93bmVk') ||
+    stream.includes(`${ESC}]52`) ||
+    stream.includes(`${ESC}[2J`)
+  );
+}
+
+/** Every byte Ink writes for one render, through a stream that claims to be a terminal. */
+async function streamOf(element: React.ReactElement): Promise<string> {
+  const chunks: string[] = [];
+  const stdout = new Writable({
+    write(chunk, _encoding, done) {
+      chunks.push(String(chunk));
+      done();
+    },
+  }) as unknown as NodeJS.WriteStream;
+  Object.assign(stdout, { isTTY: true, columns: 80, rows: 24 });
+  const app = inkRender(element, { stdout, patchConsole: false });
+  await new Promise((resolve) => setTimeout(resolve, 40));
+  app.unmount();
+  return chunks.join('');
+}
+
+const toolEntry = (content: string): IHistoryEntry =>
+  messageToHistoryEntry(
+    createToolMessage(content, { toolCallId: 'call-1', name: `Read${POISON}` }),
+  );
+
+const eventEntry = (id: string, type: string, data: unknown): IHistoryEntry =>
+  ({ id, timestamp: new Date(), category: 'event', type, data }) as unknown as IHistoryEntry;
+
+describe('SEC-019 — the terminal stream carries no payload from poisoned session data', () => {
+  it('the oracle is not vacuous: an unsanitized render DOES leak', async () => {
+    // Without this the whole file passes for a `carriesPayload` that always answers false, and for
+    // an Ink that removed everything. It also pins WHY this module exists: if this case ever goes
+    // green, Ink's own behaviour changed and the threat model needs re-reading — that is a signal
+    // worth a failing test, not a false alarm.
+    const stream = await streamOf(<Text>{`before${POISON}after`}</Text>);
+    expect(carriesPayload(stream), JSON.stringify(stream)).toBe(true);
+  });
+
+  it('MessageList: structured tool summary branch (the branch review found unguarded)', async () => {
+    const stream = await streamOf(
+      <MessageList history={[toolEntry(JSON.stringify([{ line: 'read ok' }]))]} />,
+    );
+    expect(stream).toContain('Read');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('MessageList: plain-text tool branch', async () => {
+    const stream = await streamOf(<MessageList history={[toolEntry(`not json ${POISON}`)]} />);
+    expect(stream).toContain('Read');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('MessageList: the tool-summary event label, name and first argument both', async () => {
+    const stream = await streamOf(
+      <MessageList
+        history={[
+          eventEntry('evt-1', 'tool-summary', {
+            tools: [
+              {
+                toolName: `Read${POISON}`,
+                firstArg: `file.ts${POISON}`,
+                isRunning: false,
+                result: 'success',
+              },
+            ],
+            summary: `✓ Read(file.ts)${POISON}`,
+          }),
+        ]}
+      />,
+    );
+    expect(stream).toContain('Read');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('MessageList: an event entry message (skill activation, memory topic)', async () => {
+    const stream = await streamOf(
+      <MessageList
+        history={[
+          eventEntry('evt-2', 'skill-activation', {
+            message: `Invoking plugin skill: ${POISON}`,
+          }),
+        ]}
+      />,
+    );
+    expect(stream).toContain('Invoking plugin skill');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('MessageList: an event entry that carries content instead of message', async () => {
+    const stream = await streamOf(
+      <MessageList history={[eventEntry('evt-3', 'note', { content: `note ${POISON}` })]} />,
+    );
+    expect(stream).toContain('note');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('MessageList: the tool-summary fallback lines, taken when the entry lists no tools', async () => {
+    const stream = await streamOf(
+      <MessageList
+        history={[eventEntry('evt-4', 'tool-summary', { summary: `line one ${POISON}\nline two` })]}
+      />,
+    );
+    expect(stream).toContain('line one');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('MessageList: command output preview lines, which are raw stdout', async () => {
+    const stream = await streamOf(
+      <MessageList
+        history={[
+          eventEntry('evt-5', 'tool-summary', {
+            tools: [
+              {
+                toolName: 'Shell',
+                firstArg: 'ls',
+                result: 'error',
+                toolResultData: JSON.stringify({ exitCode: 1, stdout: `oops ${POISON}` }),
+              },
+            ],
+            summary: '',
+          }),
+        ]}
+      />,
+    );
+    expect(stream).toContain('oops');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('StreamingIndicator: the live tool line, name and first argument both', async () => {
+    const tools = [
+      { toolName: `Read${POISON}`, firstArg: `file.ts${POISON}`, isRunning: true },
+    ] as unknown as IToolState[];
+    const stream = await streamOf(<StreamingIndicator text="" activeTools={tools} />);
+    expect(stream).toContain('Read');
+    expect(carriesPayload(stream)).toBe(false);
+  });
+
+  it('StreamingIndicator: the streamed assistant text', async () => {
+    const stream = await streamOf(<StreamingIndicator text={`hello ${POISON}`} activeTools={[]} />);
+    expect(carriesPayload(stream)).toBe(false);
+  });
+});

package/src/__tests__/selection-flow.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applySelectionInput,
+  createSelectionFlowState,
+  getDirectionalSelectionInputAction,
+  getVerticalSelectionInputAction,
+} from '../flows/selection-flow.js';
+
+describe('selection flow', () => {
+  it('Given first item selected When previous is applied Then selection stays bounded', () => {
+    const result = applySelectionInput(createSelectionFlowState(), 'previous', { itemCount: 3 });
+
+    expect(result.state.selectedIndex).toBe(0);
+    expect(result.effect).toEqual({ type: 'none' });
+  });
+
+  it('Given last item selected When next is applied Then selection stays bounded', () => {
+    const state = { selectedIndex: 2, scrollOffset: 0, resolved: false };
+
+    const result = applySelectionInput(state, 'next', { itemCount: 3 });
+
+    expect(result.state.selectedIndex).toBe(2);
+  });
+
+  it('Given wrapping selection When previous from first is applied Then it wraps to last', () => {
+    const result = applySelectionInput(createSelectionFlowState(), 'previous', {
+      itemCount: 3,
+      wrap: true,
+    });
+
+    expect(result.state.selectedIndex).toBe(2);
+  });
+
+  it('Given max visible window When moving below viewport Then scroll offset follows', () => {
+    const state = applySelectionInput(createSelectionFlowState(), 'next', {
+      itemCount: 4,
+      maxVisible: 2,
+    }).state;
+
+    const result = applySelectionInput(state, 'next', { itemCount: 4, maxVisible: 2 });
+
+    expect(result.state).toMatchObject({ selectedIndex: 2, scrollOffset: 1 });
+  });
+
+  it('Given selected item When select is applied Then selected index is emitted once', () => {
+    const state = { selectedIndex: 1, scrollOffset: 0, resolved: false };
+
+    const selected = applySelectionInput(state, 'select', { itemCount: 3 });
+    const ignored = applySelectionInput(selected.state, 'select', { itemCount: 3 });
+
+    expect(selected.effect).toEqual({ type: 'select', index: 1 });
+    expect(ignored.effect).toEqual({ type: 'none' });
+  });
+
+  it('Given raw key info When mapped Then vertical and directional actions are produced', () => {
+    expect(getVerticalSelectionInputAction({ downArrow: true })).toBe('next');
+    expect(getVerticalSelectionInputAction({ escape: true })).toBe('cancel');
+    expect(getDirectionalSelectionInputAction({ leftArrow: true })).toBe('previous');
+    expect(getDirectionalSelectionInputAction({ rightArrow: true })).toBe('next');
+  });
+});

package/src/__tests__/session-event-notices.test.tsx

@@ -0,0 +1,31 @@
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import SessionEventNotices from '../SessionEventNotices.js';
+
+describe('SessionEventNotices', () => {
+  it('renders deterministic plan, context, and branch notices', () => {
+    const { lastFrame } = render(
+      <SessionEventNotices
+        notices={[
+          { id: '1', event: 'plan_event', message: 'Plan plan approved' },
+          {
+            id: '2',
+            event: 'context_file_refreshed',
+            message: 'Context refreshed: AGENTS.md',
+          },
+          {
+            id: '3',
+            event: 'branch_event',
+            message: 'Branch branch switched: main @ turn-0001',
+          },
+        ]}
+      />,
+    );
+
+    expect(lastFrame()).toContain('Plan plan approved');
+    expect(lastFrame()).toContain('Context refreshed: AGENTS.md');
+    expect(lastFrame()).toContain('Branch branch switched: main @ turn-0001');
+  });
+});

package/src/__tests__/session-init-poller.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createSessionInitPoller } from '../flows/session-init-poller.js';
+
+describe('createSessionInitPoller', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('TC-04: calls onReady and stops once the check succeeds', () => {
+    const onReady = vi.fn();
+    const onFailure = vi.fn();
+    let ready = false;
+    const poller = createSessionInitPoller({
+      check: () => {
+        if (!ready) throw new Error('InteractiveSession not initialized. Call submit().');
+      },
+      intervalMs: 200,
+      timeoutMs: 15000,
+      onReady,
+      onFailure,
+    });
+    poller.start();
+    vi.advanceTimersByTime(600);
+    expect(onReady).not.toHaveBeenCalled();
+    ready = true;
+    vi.advanceTimersByTime(200);
+    expect(onReady).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(2000);
+    expect(onReady).toHaveBeenCalledTimes(1);
+    expect(onFailure).not.toHaveBeenCalled();
+  });
+
+  it('TC-04: benign not-initialized errors poll until timeout, then fail with timeout kind', () => {
+    const onReady = vi.fn();
+    const onFailure = vi.fn();
+    const poller = createSessionInitPoller({
+      check: () => {
+        throw new Error('InteractiveSession not initialized. Call submit().');
+      },
+      intervalMs: 200,
+      timeoutMs: 1000,
+      onReady,
+      onFailure,
+    });
+    poller.start();
+    vi.advanceTimersByTime(900);
+    expect(onFailure).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(400);
+    expect(onFailure).toHaveBeenCalledTimes(1);
+    expect(onFailure.mock.calls[0]?.[0]).toMatchObject({ kind: 'timeout' });
+    expect(onReady).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(2000);
+    expect(onFailure).toHaveBeenCalledTimes(1);
+  });
+
+  it('TC-04: a real error fails immediately with the error attached', () => {
+    const onFailure = vi.fn();
+    const poller = createSessionInitPoller({
+      check: () => {
+        throw new Error('ENOENT: session store unreadable');
+      },
+      intervalMs: 200,
+      timeoutMs: 15000,
+      onReady: vi.fn(),
+      onFailure,
+    });
+    poller.start();
+    vi.advanceTimersByTime(200);
+    expect(onFailure).toHaveBeenCalledTimes(1);
+    expect(onFailure.mock.calls[0]?.[0]).toMatchObject({ kind: 'error' });
+    expect(String((onFailure.mock.calls[0]?.[0] as { error: Error }).error.message)).toContain(
+      'ENOENT',
+    );
+    vi.advanceTimersByTime(2000);
+    expect(onFailure).toHaveBeenCalledTimes(1);
+  });
+
+  it('stop() cancels polling without callbacks', () => {
+    const onReady = vi.fn();
+    const onFailure = vi.fn();
+    const poller = createSessionInitPoller({
+      check: () => {
+        throw new Error('InteractiveSession not initialized.');
+      },
+      intervalMs: 200,
+      timeoutMs: 1000,
+      onReady,
+      onFailure,
+    });
+    poller.start();
+    vi.advanceTimersByTime(400);
+    poller.stop();
+    vi.advanceTimersByTime(5000);
+    expect(onReady).not.toHaveBeenCalled();
+    expect(onFailure).not.toHaveBeenCalled();
+  });
+});