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

package/src/__tests__/fork-attach.test.tsx

@@ -0,0 +1,235 @@
+/**
+ * CLI-1994 TC-08 / TC-09 — the `attach` control, and what it refuses.
+ *
+ * Attach is the only genuinely new user surface this item adds, and the whole of its meaning is that
+ * it is a VIEW switch: the terminal starts looking at the fork's own session record, and neither
+ * record is written or merged. So what these cases pin is the pair — which entries offer the
+ * control, and that selecting it switches this terminal onto the FORK's record — reporting the
+ * FORK's id — plus the three refusals, each of which must reach the operator with its reason rather
+ * than leaving the terminal pointed at nothing.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import ExecutionWorkspaceSwitcher, {
+  EXECUTION_WORKSPACE_ATTACH_HINT,
+} from '../ExecutionWorkspaceSwitcher.js';
+import { attachToForkedSession } from '../flows/fork-attach-flow.js';
+
+import type {
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+  TExecutionControl,
+} from '@robota-sdk/agent-interface-execution';
+
+const FORK_SESSION_ID = 'session_cli-1994-fork';
+
+function makeForkEntry(
+  overrides: Partial<IExecutionWorkspaceEntry> = {},
+): IExecutionWorkspaceEntry {
+  return {
+    id: 'task:agent_1',
+    sourceId: 'agent_1',
+    kind: 'background_task',
+    taskKind: 'agent',
+    origin: { kind: 'slash_command', sessionId: 'session_parent' },
+    status: 'running',
+    state: 'working',
+    title: 'experiment',
+    subtitle: 'general-purpose',
+    unread: false,
+    attention: 'none',
+    visibility: 'default',
+    updatedAt: '2026-09-07T00:00:00.000Z',
+    controls: ['select', 'cancel', 'attach'],
+    resumeSessionId: FORK_SESSION_ID,
+    ...overrides,
+  };
+}
+
+function makePlainEntry(): IExecutionWorkspaceEntry {
+  const { resumeSessionId: _dropped, ...entry } = makeForkEntry({
+    id: 'task:agent_2',
+    sourceId: 'agent_2',
+    title: 'plain job',
+    controls: ['select', 'cancel'],
+  });
+  return entry;
+}
+
+function makeSnapshot(entries: readonly IExecutionWorkspaceEntry[]): IExecutionWorkspaceSnapshot {
+  return {
+    sessionId: 'session_parent',
+    selectedEntryId: entries[0]?.id ?? '',
+    updatedAt: '2026-09-07T00:00:00.000Z',
+    entries: [...entries],
+  };
+}
+
+/** The store answer: which records still exist. */
+function storeWith(ids: readonly string[]): (sessionId: string) => boolean {
+  return (sessionId) => ids.includes(sessionId);
+}
+
+describe('attaching to a fork switches the view (CLI-1994 TC-08)', () => {
+  it('a forked entry switches to the FORK, not the parent', () => {
+    const switchSession = vi.fn();
+    const notify = vi.fn();
+
+    const outcome = attachToForkedSession(makeForkEntry(), {
+      hasSessionRecord: storeWith([FORK_SESSION_ID]),
+      switchSession,
+      notify,
+    });
+
+    expect(outcome).toEqual({ sessionId: FORK_SESSION_ID });
+    expect(switchSession).toHaveBeenCalledWith(FORK_SESSION_ID);
+    // A view switch, not a merge: the only thing that happened is the switch.
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  it('an entry with no resumeSessionId is not attachable and emits no intent', () => {
+    const switchSession = vi.fn();
+    const notify = vi.fn();
+
+    const intent = attachToForkedSession(makePlainEntry(), {
+      hasSessionRecord: storeWith([FORK_SESSION_ID]),
+      switchSession,
+      notify,
+    });
+
+    expect(intent).toBeUndefined();
+    expect(switchSession).not.toHaveBeenCalled();
+    expect(notify).toHaveBeenCalledWith(expect.stringContaining('not a forked session'));
+  });
+
+  it('the switcher offers the attach hint on a forked entry and calls onAttach for the `a` key', () => {
+    const onAttach = vi.fn();
+    const entry = makeForkEntry();
+    const { lastFrame, stdin } = render(
+      <ExecutionWorkspaceSwitcher
+        snapshot={makeSnapshot([entry])}
+        selectedEntryId={entry.id}
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onAttach={onAttach}
+      />,
+    );
+
+    expect(lastFrame()).toContain(EXECUTION_WORKSPACE_ATTACH_HINT.label);
+
+    stdin.write('a');
+
+    expect(onAttach).toHaveBeenCalledWith(entry);
+  });
+
+  it('an entry without the attach control neither offers the hint nor answers the key', () => {
+    const onAttach = vi.fn();
+    const entry = makePlainEntry();
+    const { lastFrame, stdin } = render(
+      <ExecutionWorkspaceSwitcher
+        snapshot={makeSnapshot([entry])}
+        selectedEntryId={entry.id}
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onAttach={onAttach}
+      />,
+    );
+
+    expect(lastFrame()).not.toContain(EXECUTION_WORKSPACE_ATTACH_HINT.label);
+
+    stdin.write('a');
+
+    expect(onAttach).not.toHaveBeenCalled();
+  });
+
+  it('`attach` is a member of TExecutionControl — every control list still accepts it', () => {
+    // The runtime half of the union change; the compile half is the package `typecheck` this suite
+    // is paired with in the spec's TC-08, which reaches every exhaustive switch over the union.
+    const controls: readonly TExecutionControl[] = [
+      'select',
+      'cancel',
+      'close',
+      'send',
+      'read_log',
+      'wait',
+      'attach',
+    ];
+    expect(controls).toContain('attach');
+    expect(makeForkEntry().controls).toContain('attach');
+  });
+});
+
+describe('attach refuses rather than stranding the terminal (CLI-1994 TC-09)', () => {
+  it.each(['completed', 'failed', 'cancelled'] as const)(
+    'a %s fork is refused with its status, and no intent is emitted',
+    (status) => {
+      const switchSession = vi.fn();
+      const notify = vi.fn();
+
+      const intent = attachToForkedSession(makeForkEntry({ status }), {
+        // The record is still there; the TASK being terminal is what refuses.
+        hasSessionRecord: storeWith([FORK_SESSION_ID]),
+        switchSession,
+        notify,
+      });
+
+      expect(intent).toBeUndefined();
+      expect(switchSession).not.toHaveBeenCalled();
+      expect(notify).toHaveBeenCalledWith(expect.stringContaining(status));
+    },
+  );
+
+  it('uses a host-supplied resume command for a terminal fork while a neutral host gets the session id', () => {
+    const entry = makeForkEntry({ status: 'completed' });
+    const neutral = vi.fn();
+    attachToForkedSession(entry, {
+      hasSessionRecord: storeWith([FORK_SESSION_ID]),
+      switchSession: vi.fn(),
+      notify: neutral,
+    });
+    expect(neutral.mock.calls[0]?.[0]).toContain(FORK_SESSION_ID);
+    expect(neutral.mock.calls[0]?.[0]).not.toContain('robota');
+
+    const product = vi.fn();
+    attachToForkedSession(entry, {
+      hasSessionRecord: storeWith([FORK_SESSION_ID]),
+      switchSession: vi.fn(),
+      notify: product,
+      formatResumeCommand: (id) => `robota --resume ${id}`,
+    });
+    expect(product.mock.calls[0]?.[0]).toContain(`robota --resume ${FORK_SESSION_ID}`);
+  });
+
+  it('a missing session record is refused, naming the record and the task status', () => {
+    const switchSession = vi.fn();
+    const notify = vi.fn();
+
+    const intent = attachToForkedSession(makeForkEntry({ status: 'running' }), {
+      hasSessionRecord: storeWith([]),
+      switchSession,
+      notify,
+    });
+
+    expect(intent).toBeUndefined();
+    expect(switchSession).not.toHaveBeenCalled();
+    const reason = notify.mock.calls[0]?.[0] as string;
+    expect(reason).toContain(FORK_SESSION_ID);
+    expect(reason).toContain('running');
+    expect(reason).toContain('no longer in the session store');
+  });
+
+  it('a live fork whose record exists is the ONLY case that switches', () => {
+    const switchSession = vi.fn();
+
+    attachToForkedSession(makeForkEntry({ status: 'waiting_permission' }), {
+      hasSessionRecord: storeWith([FORK_SESSION_ID]),
+      switchSession,
+      notify: vi.fn(),
+    });
+
+    expect(switchSession).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/helpers/terminal-profiles.ts

@@ -0,0 +1,152 @@
+/**
+ * CLI-062 — the terminal matrix, as data.
+ *
+ * The backlog item's remaining work was a *manual* matrix ("iTerm2 + Terminal.app
+ * ±ROBOTA_IME_CURSOR, kitty/WezTerm/Ghostty/Windows Terminal/tmux on real hardware"). This module
+ * converts it into something a machine re-runs: each row is the environment handshake a terminal
+ * emulator hands the program it launches, which is the ONLY channel through which the emulator's
+ * identity reaches our code (`supportsImeCursorPositioning()` reads `TERM_PROGRAM`).
+ *
+ * Two consumers share this table so the gate is never asserted in isolation from behaviour:
+ *  - `terminal-capabilities.test.ts` — what `supportsImeCursorPositioning()` returns per row.
+ *  - `pty/ime-cursor.ptytest.ts`     — what the REAL binary then does under a real pty per row.
+ *
+ * `provenance` is deliberately explicit about how each row's values were obtained. `measured`
+ * rows were captured by launching that emulator on the machine that recorded them and dumping the
+ * child environment; `documented` rows come from the vendor's documented behaviour because the
+ * emulator cannot run on Linux (macOS/Windows) or is not installed. A documented row still gives
+ * real coverage of OUR code — the branch it selects is exercised end-to-end — but it is NOT
+ * evidence about that emulator's own rendering or its OS IME, and must never be reported as such.
+ */
+
+export type TerminalProvenance = 'measured' | 'documented';
+
+export interface ITerminalProfile {
+  /** Stable id used in test names and in the backlog matrix table. */
+  id: string;
+  /** Human label for the matrix. */
+  label: string;
+  /** Environment the emulator exports to its child process. */
+  env: Readonly<Record<string, string>>;
+  /** How the env values above were obtained. */
+  provenance: TerminalProvenance;
+  /** Free-text provenance detail (version, capture method, or the vendor fact relied on). */
+  note: string;
+}
+
+export const TERMINAL_PROFILES: readonly ITerminalProfile[] = [
+  {
+    id: 'bare-tty',
+    label: 'bare TTY (no TERM_PROGRAM)',
+    env: { TERM: 'xterm-256color' },
+    provenance: 'measured',
+    note: 'Baseline: a pty that identifies nothing. This is also what the pty harness itself provides.',
+  },
+  {
+    id: 'ghostty',
+    label: 'Ghostty',
+    env: {
+      TERM: 'xterm-ghostty',
+      TERM_PROGRAM: 'ghostty',
+      TERM_PROGRAM_VERSION: '1.3.1',
+      COLORTERM: 'truecolor',
+    },
+    provenance: 'measured',
+    note: 'Captured from Ghostty 1.3.1 (Linux/GTK4) by launching it with `-e <env dump>`.',
+  },
+  {
+    id: 'gnome-terminal',
+    label: 'GNOME Terminal (VTE)',
+    env: { TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+    provenance: 'measured',
+    note: 'Captured from GNOME Terminal 3.52.0 / VTE 0.76.0; VTE sets no TERM_PROGRAM.',
+  },
+  {
+    id: 'tmux',
+    label: 'tmux (multiplexer)',
+    env: { TERM: 'tmux-256color', TERM_PROGRAM: 'tmux', TMUX: '/tmp/tmux-fixture,1,0' },
+    provenance: 'measured',
+    note: 'Captured from tmux 3.4 inside a real pane; tmux 3.4 sets TERM_PROGRAM=tmux. The real emulator is additionally driven end-to-end in pty/ime-cursor-tmux.ptytest.ts.',
+  },
+  {
+    id: 'kitty',
+    label: 'kitty',
+    env: { TERM: 'xterm-kitty', KITTY_WINDOW_ID: '1', COLORTERM: 'truecolor' },
+    provenance: 'documented',
+    note: 'kitty identifies itself via TERM=xterm-kitty + KITTY_WINDOW_ID and sets no TERM_PROGRAM.',
+  },
+  {
+    id: 'wezterm',
+    label: 'WezTerm',
+    env: { TERM: 'xterm-256color', TERM_PROGRAM: 'WezTerm', TERM_PROGRAM_VERSION: '20240203' },
+    provenance: 'documented',
+    note: 'WezTerm sets TERM_PROGRAM=WezTerm.',
+  },
+  {
+    id: 'windows-terminal',
+    label: 'Windows Terminal',
+    env: { TERM: 'xterm-256color', WT_SESSION: '00000000-0000-0000-0000-000000000000' },
+    provenance: 'documented',
+    note: 'Windows Terminal marks its sessions with WT_SESSION and sets no TERM_PROGRAM.',
+  },
+  {
+    id: 'iterm2',
+    label: 'iTerm2 (macOS)',
+    env: { TERM: 'xterm-256color', TERM_PROGRAM: 'iTerm.app', TERM_PROGRAM_VERSION: '3.5.0' },
+    provenance: 'documented',
+    note: 'macOS-only emulator: the env branch is exercised here, its rendering and its OS IME are not.',
+  },
+  {
+    id: 'apple-terminal',
+    label: 'Terminal.app (macOS)',
+    env: { TERM: 'xterm-256color', TERM_PROGRAM: 'Apple_Terminal', TERM_PROGRAM_VERSION: '455' },
+    provenance: 'documented',
+    note: 'macOS-only emulator, and the ONE profile that is off by default (invariant I5). The env branch is exercised here; the historical Korean-IME SIGSEGV can only be re-checked on macOS.',
+  },
+];
+
+/** `ROBOTA_IME_CURSOR` settings the matrix sweeps. `undefined` means the variable is absent. */
+export const IME_CURSOR_SETTINGS: readonly (string | undefined)[] = [undefined, '1', '0'];
+
+export const REPRESENTATIVE_IME_PTY_CELLS: readonly {
+  profileId: string;
+  override: string | undefined;
+}[] = [
+  { profileId: 'ghostty', override: undefined },
+  { profileId: 'apple-terminal', override: undefined },
+  { profileId: 'apple-terminal', override: '1' },
+  { profileId: 'ghostty', override: '0' },
+];
+
+/**
+ * The expected `supportsImeCursorPositioning()` verdict for a matrix cell, derived from the
+ * documented precedence (explicit override wins; Apple_Terminal is off by default; every other
+ * interactive TTY is on). Both the unit matrix and the pty matrix assert against this, so the
+ * capability detection and the observable behaviour can never drift apart silently.
+ */
+export function expectedImeCursorEnabled(
+  profile: ITerminalProfile,
+  override: string | undefined,
+): boolean {
+  if (override === '1') return true;
+  if (override === '0') return false;
+  return profile.env['TERM_PROGRAM'] !== 'Apple_Terminal';
+}
+
+/** Environment for a child process running "under" `profile` with the given override. */
+export function profileEnv(
+  profile: ITerminalProfile,
+  override: string | undefined,
+): Record<string, string> {
+  return {
+    ...profile.env,
+    ...(override === undefined ? {} : { ROBOTA_IME_CURSOR: override }),
+  };
+}
+
+/** Matrix label used in test names and in the backlog's evidence table. */
+export function cellLabel(profile: ITerminalProfile, override: string | undefined): string {
+  const setting =
+    override === undefined ? 'ROBOTA_IME_CURSOR unset' : `ROBOTA_IME_CURSOR=${override}`;
+  return `${profile.label} / ${setting}`;
+}

package/src/__tests__/helpers/vt-cursor-interpreter.ts

@@ -0,0 +1,175 @@
+/**
+ * Minimal VT interpreter for cursor-positioning assertions (CLI-062).
+ *
+ * Tracks the hardware cursor row/col on a rows x cols screen while consuming a raw ANSI stream,
+ * recording every DECTCEM show (`ESC[?25h`) event with the cursor cell it lands on and its byte
+ * offset in the stream. This is the same evidence a terminal emulator (and the OS IME) acts on —
+ * ported from the CLI-062 investigation PoC (.design/investigations/2026-07-25-cli-062-ime-cursor-design.md).
+ *
+ * Screen bookkeeping treats every printable as width 1 (wide-char display-column math is exercised
+ * by the production x computation, which the recorded `cursorTo` columns reflect directly).
+ * Understands: CR, LF, CUU/CUD/CUF/CUB (A/B/C/D), CNL/CPL (E/F), CHA (G), CUP (H/f), EL (K),
+ * ED (J, state-only), DECSET/DECRST ?25 (show/hide), OSC strings, and skips other escapes.
+ */
+
+// eslint-disable-next-line no-control-regex -- a VT interpreter parses control bytes by definition
+const CSI_PATTERN = /^\u001b\[([0-9;?]*)([A-Za-z])/;
+// eslint-disable-next-line no-control-regex -- a VT interpreter parses control bytes by definition
+const OSC_PATTERN = /^\u001b\][^\u0007\u001b]*(\u0007|\u001b\\)/;
+
+export interface ICursorShowEvent {
+  /** Screen row (0-based) the cursor was on when it was shown. */
+  row: number;
+  /** Screen column (0-based) the cursor was on when it was shown. */
+  col: number;
+  /** Byte offset of the show sequence in the interpreted stream (for since-mark filtering). */
+  offset: number;
+}
+
+export interface IVtInterpretation {
+  /** Final cursor row. */
+  row: number;
+  /** Final cursor column. */
+  col: number;
+  /** Final DECTCEM visibility. */
+  visible: boolean;
+  /** Screen contents (width-1 bookkeeping per printable). */
+  screen: string[];
+  /** Every `ESC[?25h` with the cell it landed on. */
+  showEvents: ICursorShowEvent[];
+  /** Number of scroll-ups that occurred (content pushed past the bottom row). */
+  scrolls: number;
+}
+
+interface IVtState {
+  row: number;
+  col: number;
+  visible: boolean;
+  screen: string[][];
+  scrolls: number;
+  showEvents: ICursorShowEvent[];
+}
+
+export function interpretVtStream(stream: string, rows: number, cols: number): IVtInterpretation {
+  const state: IVtState = {
+    row: 0,
+    col: 0,
+    visible: true,
+    screen: Array.from({ length: rows }, () => Array<string>(cols).fill(' ')),
+    scrolls: 0,
+    showEvents: [],
+  };
+
+  let i = 0;
+  while (i < stream.length) {
+    const ch = stream[i]!;
+    if (ch === '\r') {
+      state.col = 0;
+      i++;
+    } else if (ch === '\n') {
+      lineFeed(state, rows, cols);
+      state.col = 0;
+      i++;
+    } else if (ch === '\u001b') {
+      i += consumeEscape(state, stream, i, rows, cols);
+    } else {
+      if (ch >= ' ') {
+        state.screen[state.row]![state.col] = ch;
+        state.col = Math.min(cols - 1, state.col + 1);
+      }
+      i++;
+    }
+  }
+
+  return {
+    row: state.row,
+    col: state.col,
+    visible: state.visible,
+    screen: state.screen.map((line) => line.join('')),
+    showEvents: state.showEvents,
+    scrolls: state.scrolls,
+  };
+}
+
+function lineFeed(state: IVtState, rows: number, cols: number): void {
+  if (state.row === rows - 1) {
+    state.screen.shift();
+    state.screen.push(Array<string>(cols).fill(' '));
+    state.scrolls++;
+  } else {
+    state.row++;
+  }
+}
+
+/** Consume one escape sequence at `start`; returns its length in the stream. */
+function consumeEscape(
+  state: IVtState,
+  stream: string,
+  start: number,
+  rows: number,
+  cols: number,
+): number {
+  const csi = CSI_PATTERN.exec(stream.slice(start));
+  if (csi) {
+    const [full, params = '', cmd = ''] = csi;
+    applyCsi(state, params, cmd, start, rows, cols);
+    return full.length;
+  }
+  const osc = OSC_PATTERN.exec(stream.slice(start));
+  if (osc) {
+    return osc[0].length;
+  }
+  return 2;
+}
+
+function applyCsi(
+  state: IVtState,
+  params: string,
+  cmd: string,
+  offset: number,
+  rows: number,
+  cols: number,
+): void {
+  if (applyCursorMove(state, params, cmd, rows, cols)) return;
+  if (cmd === 'K') {
+    const from = params === '1' ? 0 : state.col;
+    const to = params === '1' ? state.col + 1 : cols;
+    for (let c = from; c < to; c++) state.screen[state.row]![c] = ' ';
+  } else if (cmd === 'h' && params === '?25') {
+    state.visible = true;
+    state.showEvents.push({ row: state.row, col: state.col, offset });
+  } else if (cmd === 'l' && params === '?25') {
+    state.visible = false;
+  }
+}
+
+/** Cursor-movement CSI commands; returns true when the command was one of them. */
+function applyCursorMove(
+  state: IVtState,
+  params: string,
+  cmd: string,
+  rows: number,
+  cols: number,
+): boolean {
+  const n = Number.parseInt(params === '' ? '1' : params, 10) || 1;
+  if (cmd === 'A') state.row = Math.max(0, state.row - n);
+  else if (cmd === 'B') state.row = Math.min(rows - 1, state.row + n);
+  else if (cmd === 'C') state.col = Math.min(cols - 1, state.col + n);
+  else if (cmd === 'D') state.col = Math.max(0, state.col - n);
+  else if (cmd === 'E') {
+    for (let k = 0; k < n; k++) lineFeed(state, rows, cols);
+    state.col = 0;
+  } else if (cmd === 'F') {
+    state.row = Math.max(0, state.row - n);
+    state.col = 0;
+  } else if (cmd === 'G') {
+    state.col = Math.min(cols - 1, n - 1);
+  } else if (cmd === 'H' || cmd === 'f') {
+    const [r = '1', c = '1'] = params.split(';');
+    state.row = Math.min(rows - 1, (Number.parseInt(r, 10) || 1) - 1);
+    state.col = Math.min(cols - 1, (Number.parseInt(c, 10) || 1) - 1);
+  } else {
+    return false;
+  }
+  return true;
+}

package/src/__tests__/history-clear-broadcast.test.ts

@@ -0,0 +1,66 @@
+/**
+ * CMD-004 Phase 2 Stage E — the TUI transcript follows the broadcast `history_cleared` event.
+ *
+ * Final carrier (spec decision): `conversation-history-cleared` becomes a BROADCAST session event,
+ * so a clear performed by ANY surface (a co-driving remote `/clear`, or any host-side
+ * `clearConversationHistory()` call) refreshes every attached transcript — pre-Stage-E the TUI only
+ * cleared from its OWN command result's legacy effect, so a remote clear left it stale.
+ *
+ * Runs the REAL TuiInteractionChannel over a real InteractiveSession (scripted provider) — no
+ * command-result path involved: the mutation alone must drive the transcript refresh.
+ */
+
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+const READY_DEADLINE_MS = 10_000;
+const POLL_MS = 25;
+
+async function waitUntil(predicate: () => boolean, deadlineMs = READY_DEADLINE_MS): Promise<void> {
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+  }
+  expect(predicate()).toBe(true);
+}
+
+describe('CMD-004 Stage E — history_cleared broadcast clears the TUI transcript', () => {
+  let channel: TuiInteractionChannel | undefined;
+
+  afterEach(async () => {
+    await channel?.stop();
+    channel = undefined;
+  });
+
+  it('a host-side conversation clear empties the transcript without any command-result path', async () => {
+    const scripted = createScriptedProvider([{ text: 'unused in this test' }]);
+    channel = new TuiInteractionChannel({
+      cwd: process.cwd(),
+      provider: scripted.provider,
+    });
+    await channel.start();
+    const session = channel.getSession();
+    await waitUntil(() => {
+      try {
+        session.getContextState();
+        return true;
+      } catch {
+        return false; // allow-fallback: session init is asynchronous; poll until it is ready
+      }
+    });
+
+    channel.stateManager.addEntry(messageToHistoryEntry(createSystemMessage('stale entry')));
+    expect(channel.stateManager.history.length).toBeGreaterThan(0);
+
+    // The HOST mutation (what a co-driving remote /clear ultimately executes) — the broadcast
+    // `history_cleared` event is the ONLY carrier that can refresh this surface's transcript.
+    session.clearConversationHistory();
+
+    await waitUntil(() => channel!.stateManager.history.length === 0, 3000);
+    expect(channel.stateManager.history).toEqual([]);
+  });
+});