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

package/src/__tests__/execution-workspace-view-model.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import {
+  countActiveBackgroundWorkspaceEntries,
+  formatExecutionDetailRecord,
+  formatExecutionWorkspaceEntryRow,
+  getDefaultBackgroundWorkspaceEntries,
+} from '../execution-workspace-view-model.js';
+
+function makeEntry(overrides: Partial<IExecutionWorkspaceEntry>): IExecutionWorkspaceEntry {
+  return {
+    id: 'task:agent_1',
+    sourceId: 'agent_1',
+    kind: 'background_task',
+    origin: { kind: 'slash_command', sessionId: 'session_1', commandName: 'agent' },
+    taskKind: 'agent',
+    status: 'running',
+    state: 'working',
+    title: 'Explore',
+    subtitle: 'general-purpose',
+    preview: 'Map the CLI state manager',
+    unread: false,
+    attention: 'none',
+    visibility: 'default',
+    updatedAt: '2026-05-09T00:00:00.000Z',
+    controls: ['select', 'cancel'],
+    ...overrides,
+  };
+}
+
+function makeSnapshot(entries: readonly IExecutionWorkspaceEntry[]): IExecutionWorkspaceSnapshot {
+  return {
+    sessionId: 'session_1',
+    selectedEntryId: 'main:session_1',
+    updatedAt: '2026-05-09T00:00:00.000Z',
+    entries,
+  };
+}
+
+describe('execution workspace view model', () => {
+  it('renders selected and inactive entries with radio markers', () => {
+    const row = formatExecutionWorkspaceEntryRow(makeEntry({ id: 'task:agent_1' }), {
+      selectedEntryId: 'task:agent_1',
+    });
+    const inactive = formatExecutionWorkspaceEntryRow(makeEntry({ id: 'task:process_1' }), {
+      selectedEntryId: 'task:agent_1',
+    });
+
+    expect(row.radio).toBe('●');
+    expect(row.title).toBe('Explore agent');
+    expect(row.subtitle).toBe('agent · general-purpose');
+    expect(row.statusLabel).toBe('running');
+    expect(inactive.radio).toBe('○');
+  });
+
+  it('filters default-visible background task entries for the compact panel', () => {
+    const snapshot = makeSnapshot([
+      makeEntry({ id: 'main:session_1', kind: 'main_thread', title: 'Main thread' }),
+      makeEntry({ id: 'task:agent_1', visibility: 'default' }),
+      makeEntry({ id: 'task:agent_2', visibility: 'collapsed' }),
+      makeEntry({ id: 'group:group_1', kind: 'background_group', visibility: 'default' }),
+    ]);
+
+    expect(getDefaultBackgroundWorkspaceEntries(snapshot).map((entry) => entry.id)).toEqual([
+      'task:agent_1',
+    ]);
+  });
+
+  it('counts active default-visible background tasks without treating collapsed tasks as active', () => {
+    const snapshot = makeSnapshot([
+      makeEntry({ id: 'task:queued', status: 'queued' }),
+      makeEntry({ id: 'task:running', status: 'running' }),
+      makeEntry({ id: 'task:permission', status: 'waiting_permission' }),
+      makeEntry({ id: 'task:done', status: 'completed' }),
+      makeEntry({ id: 'task:hidden', status: 'running', visibility: 'collapsed' }),
+    ]);
+
+    expect(countActiveBackgroundWorkspaceEntries(snapshot)).toBe(3);
+  });
+
+  it('bounds detail record text without parsing runner-specific output', () => {
+    const text = formatExecutionDetailRecord({
+      id: 'record_1',
+      kind: 'process_output',
+      text: ` ${'a'.repeat(180)} `,
+    });
+
+    expect(text).toHaveLength(163);
+    expect(text.endsWith('...')).toBe(true);
+  });
+});

package/src/__tests__/external-prompt-notice.test.tsx

@@ -0,0 +1,100 @@
+/**
+ * FLOW-2006 TC-05 — the provenance notice and the consumed-once prefill.
+ *
+ * The notice is what keeps a prompt the user never typed from reading like one they did, and the
+ * consumed-once rule is why a handoff remount cannot re-seed a prompt they already cleared.
+ */
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+import ExternalPromptNotice, {
+  externalPromptNotice,
+  EXTERNAL_PROMPT_NOTICE,
+  EXTERNAL_PROMPT_REVIEW_THRESHOLD,
+} from '../external-prompt-notice.js';
+
+const delay = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 20));
+
+describe('externalPromptNotice', () => {
+  it('labels a prompt, escalates a long one, and says nothing about an empty composer', () => {
+    expect(externalPromptNotice('hi')).toBe(EXTERNAL_PROMPT_NOTICE);
+    expect(externalPromptNotice('')).toBeUndefined();
+    const long = 'x'.repeat(EXTERNAL_PROMPT_REVIEW_THRESHOLD + 1);
+    const escalated = externalPromptNotice(long) ?? '';
+    expect(escalated).toContain(EXTERNAL_PROMPT_NOTICE);
+    expect(escalated).toContain(String(long.length));
+    expect(escalated).toContain('review');
+    // Exactly at the threshold is still the plain label.
+    expect(externalPromptNotice('x'.repeat(EXTERNAL_PROMPT_REVIEW_THRESHOLD))).toBe(
+      EXTERNAL_PROMPT_NOTICE,
+    );
+  });
+});
+
+describe('ExternalPromptNotice', () => {
+  it('renders the line while the prompt is there and nothing once it is gone', () => {
+    const withPrompt = render(<ExternalPromptNotice value="from a link" />);
+    expect(withPrompt.lastFrame()).toContain(EXTERNAL_PROMPT_NOTICE);
+    const cleared = render(<ExternalPromptNotice value="" />);
+    expect(cleared.lastFrame() ?? '').not.toContain(EXTERNAL_PROMPT_NOTICE);
+  });
+});
+
+/**
+ * The consumed-once contract and the provenance lifetime, driven through the REAL composer.
+ *
+ * A hand-copied stand-in would keep passing if `InputArea`'s own seeding changed — which is the one
+ * thing these assertions exist to catch — so every case below mounts the shipped component.
+ */
+describe('the prefill is consumed once, and the label belongs to that text', () => {
+  it('seeds the composer, tells the controller, and drops the label once the text changes', async () => {
+    const consume = vi.fn();
+    const { lastFrame, stdin } = render(
+      <InputArea
+        onSubmit={vi.fn()}
+        isDisabled={false}
+        initialValue="from a link"
+        consumeInitialValue={consume}
+        externalPromptOrigin
+      />,
+    );
+    await delay();
+    expect(lastFrame()).toContain('from a link');
+    expect(lastFrame()).toContain(EXTERNAL_PROMPT_NOTICE);
+    expect(consume).toHaveBeenCalledTimes(1);
+
+    // The user edits: what is in the composer is no longer what the link supplied, so the
+    // provenance line goes with it. A label that outlived the text would mark the user's own words.
+    stdin.write('!');
+    await delay();
+    expect(lastFrame()).toContain('from a link!');
+    expect(lastFrame() ?? '').not.toContain(EXTERNAL_PROMPT_NOTICE);
+  });
+
+  it('does not re-seed on the handoff remount, after the controller dropped the value', async () => {
+    const consume = vi.fn();
+    const remounted = render(
+      <InputArea
+        onSubmit={vi.fn()}
+        isDisabled={false}
+        initialValue={undefined}
+        consumeInitialValue={consume}
+        externalPromptOrigin
+      />,
+    );
+    await delay();
+    expect(remounted.lastFrame() ?? '').not.toContain(EXTERNAL_PROMPT_NOTICE);
+    expect(consume).not.toHaveBeenCalled();
+  });
+
+  it('never labels a prompt the user typed themselves', async () => {
+    const { lastFrame, stdin } = render(<InputArea onSubmit={vi.fn()} isDisabled={false} />);
+    await delay();
+    stdin.write('my own prompt');
+    await delay();
+    expect(lastFrame()).toContain('my own prompt');
+    expect(lastFrame() ?? '').not.toContain(EXTERNAL_PROMPT_NOTICE);
+  });
+});

package/src/__tests__/fixtures/command-handoff-driver.tsx

@@ -0,0 +1,114 @@
+/**
+ * TEST-007 / TERM-003 + TERM-004 fixture: run the real `/shell` and `/editor` command executors
+ * through the real `TerminalHandoffController` on a real PTY.
+ *
+ * A real Ink app (input hooks below a suspend gate, like the App) provides the live handoff; a minimal
+ * host context wires the executors' three touch-points (`canHandoffTerminal` / `runWithTerminal` /
+ * `getCwd`) to the controller. The session command-pipeline integration is already covered by the
+ * framework functional tests with a fake handoff — this fixture exercises the one thing only a real
+ * terminal can: the controller releasing raw mode so the child (subshell / `$EDITOR`) owns the TTY,
+ * and `runWithTerminal` returning so the TUI resumes.
+ *
+ * argv: [mode ('shell'|'editor'), outputPath]. The `/shell` command text is fixed here rather than
+ * taken from argv: argv only selects the mode, so no process input becomes shell text.
+ *
+ * Markers: `@@READY canHandoff=…@@`, `@@CMD_DONE@@`, `@@INPUT_AFTER_HANDOFF …@@`. A JSON result
+ * `{ success, exitCode?, message }` is written to outputPath.
+ */
+import { writeFileSync } from 'node:fs';
+
+import { executeEditorCommand, executeShellCommand } from '@robota-sdk/agent-command';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+import { Box, Text, render, useInput } from 'ink';
+import React from 'react';
+
+import { useTerminalHandoffSuspension } from '../../hooks/useTerminalHandoffSuspension.js';
+import { TerminalHandoffController } from '../../terminal-handoff-controller.js';
+
+import type {
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+} from '@robota-sdk/agent-framework';
+
+const MODE = process.argv[2];
+const OUTPUT_PATH = process.argv[3];
+/** Reads one line from the handed-off terminal and echoes it back, proving the child owned the TTY. */
+const SHELL_COMMAND = 'IFS= read -r line; printf "SHELL_GOT:[%s]\\n" "$line"';
+
+const controller = new TerminalHandoffController();
+let resolveInputAfterHandoff: ((input: string) => void) | undefined;
+
+/** Minimal host context — the shell/editor executors only read these three members. */
+const context = {
+  canHandoffTerminal: (): boolean => controller.canHandoffTerminal,
+  runWithTerminal: <T,>(fn: () => Promise<T>): Promise<T> => controller.runWithTerminal(fn),
+  getCwd: (): string => process.cwd(),
+} satisfies ICommandHostTerminalHandoff & Pick<ICommandHostWorkspace, 'getCwd'>;
+
+function InputCapture(): React.ReactElement {
+  useInput((input) => resolveInputAfterHandoff?.(input));
+  return <Text>READY</Text>;
+}
+
+function CommandApp(): React.ReactElement {
+  const suspended = useTerminalHandoffSuspension(controller);
+  if (suspended) return <Box />;
+  return (
+    <Box>
+      <InputCapture />
+    </Box>
+  );
+}
+
+function marker(line: string): void {
+  process.stdout.write(`\r\n@@${line}@@\r\n`);
+}
+
+function writeResult(result: Record<string, string | number | boolean | undefined>): void {
+  if (OUTPUT_PATH) writeFileSync(OUTPUT_PATH, JSON.stringify(result), 'utf8');
+}
+
+async function main(): Promise<void> {
+  const instance = render(<CommandApp />);
+  controller.setInkInstance(instance);
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  marker(`READY canHandoff=${controller.canHandoffTerminal}`);
+
+  // ARCH-029: the fixture's `satisfies Pick<>` above is the honest part — it declares exactly the
+  // three members these executors read. The widening cast existed only because the executors demand
+  // the whole 46-member facade. S3's role ports remove the need to widen at all; until then the
+  // double supplies the rest so no cast is required.
+  const ctx = createTestCommandHost({ overrides: context });
+  const result =
+    MODE === 'editor'
+      ? await executeEditorCommand(ctx, '')
+      : await executeShellCommand(ctx, SHELL_COMMAND);
+
+  marker('CMD_DONE');
+  const inputAfterHandoff = await new Promise<string>((resolve) => {
+    resolveInputAfterHandoff = resolve;
+  });
+  marker(`INPUT_AFTER_HANDOFF ${inputAfterHandoff}`);
+  instance.unmount();
+  await new Promise((resolve) => setTimeout(resolve, 150));
+
+  writeResult({
+    success: result.success,
+    message: result.message,
+    exitCode: (result.data as { exitCode?: number } | undefined)?.exitCode,
+  });
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  process.exit(0);
+}
+
+process.on('uncaughtException', (error) => {
+  writeResult({ success: false, message: String(error) });
+  process.stdout.write(`\r\n@@ERROR ${String(error)}@@\r\n`);
+  process.exit(1);
+});
+
+void main().catch((error) => {
+  writeResult({ success: false, message: String(error) });
+  process.stdout.write(`\r\n@@ERROR ${String(error)}@@\r\n`);
+  process.exit(1);
+});

package/src/__tests__/fixtures/fake-editor.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# TEST-007 fake $EDITOR for the /editor PTY scenario.
+# Invoked as: sh fake-editor.sh <file>. Reads ONE line from the inherited terminal (proving the
+# editor runs on the real TTY under the handoff) and writes it as the file's contents, then exits 0.
+file="$1"
+IFS= read -r line
+printf '%s\n' "$line" > "$file"

package/src/__tests__/fixtures/terminal-handoff-driver.tsx

@@ -0,0 +1,90 @@
+/**
+ * TEST-007 / TERM-002 fixture: real-terminal handoff under a PTY.
+ *
+ * Renders a real Ink app that takes raw mode (useInput) BELOW a suspend gate — exactly like the real
+ * App — and uses the real `TerminalHandoffController` + `useTerminalHandoffSuspension`. It performs an
+ * actual handoff: `runWithTerminal` spawns a child that reads ONE line from the inherited terminal and
+ * echoes it. If Ink released raw mode on suspend, the child receives the driver's keystrokes; after
+ * the child exits, `runWithTerminal` must RETURN and the App must resume.
+ *
+ * Driven by `terminal-handoff-pty-e2e.test.ts`. Markers the harness keys off: `@@READY@@`,
+ * `@@HANDOFF_STARTED@@`, `CHILD_GOT:[...]`, `@@RESUMED exit=N@@`. A JSON result is written to argv[0].
+ */
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+
+import { Box, Text, render, useInput } from 'ink';
+import React from 'react';
+
+import { useTerminalHandoffSuspension } from '../../hooks/useTerminalHandoffSuspension.js';
+import { TerminalHandoffController } from '../../terminal-handoff-controller.js';
+
+const OUTPUT_PATH = process.argv[2];
+const controller = new TerminalHandoffController();
+
+/** Input-bearing subtree: useInput lives BELOW the suspend gate, so it unmounts (Ink releases raw
+ *  mode) while suspended — mirrors the real App. */
+function InputCapture(): React.ReactElement {
+  useInput(() => {});
+  return <Text>READY</Text>;
+}
+
+function HandoffApp(): React.ReactElement {
+  const suspended = useTerminalHandoffSuspension(controller);
+  if (suspended) return <Box />;
+  return (
+    <Box>
+      <InputCapture />
+    </Box>
+  );
+}
+
+function marker(line: string): void {
+  process.stdout.write(`\r\n@@${line}@@\r\n`);
+}
+
+function writeResult(result: Record<string, string | number | boolean>): void {
+  if (OUTPUT_PATH) writeFileSync(OUTPUT_PATH, JSON.stringify(result), 'utf8');
+}
+
+async function main(): Promise<void> {
+  const instance = render(<HandoffApp />);
+  controller.setInkInstance(instance);
+
+  // Wait for the App to mount + register its suspend hooks.
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  const canHandoff = controller.canHandoffTerminal;
+  marker(`READY canHandoff=${canHandoff}`);
+
+  const exitCode = await controller.runWithTerminal(async () => {
+    marker('HANDOFF_STARTED');
+    return await new Promise<number>((resolve) => {
+      const child = spawn('sh', ['-c', 'IFS= read -r line; printf "CHILD_GOT:[%s]\\n" "$line"'], {
+        stdio: 'inherit',
+      });
+      child.on('exit', (code) => resolve(code ?? 0));
+    });
+  });
+
+  // If runWithTerminal returned, the App resumed (finally → resume ran). Confirm with a marker.
+  marker(`AFTER_HANDOFF exit=${exitCode}`);
+  instance.unmount();
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  marker(`RESUMED exit=${exitCode}`);
+
+  writeResult({ canHandoff, exitCode, returned: true });
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  process.exit(0);
+}
+
+process.on('uncaughtException', (error) => {
+  writeResult({ error: String(error), returned: false });
+  process.stdout.write(`\r\n@@ERROR ${String(error)}@@\r\n`);
+  process.exit(1);
+});
+
+void main().catch((error) => {
+  writeResult({ error: String(error), returned: false });
+  process.stdout.write(`\r\n@@ERROR ${String(error)}@@\r\n`);
+  process.exit(1);
+});

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('agent');
+
+    const product = vi.fn();
+    attachToForkedSession(entry, {
+      hasSessionRecord: storeWith([FORK_SESSION_ID]),
+      switchSession: vi.fn(),
+      notify: product,
+      formatResumeCommand: (id) => `agent --resume ${id}`,
+    });
+    expect(product.mock.calls[0]?.[0]).toContain(`agent --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__/grant-history-reaches-the-session.test.ts

@@ -0,0 +1,31 @@
+/**
+ * #3189 — the run's external-event grant history reaches every session the TUI builds. It is created
+ * once per run so a session switch replays no spent token and resets no rate; dropped on the way
+ * (the render projection copies field by field, and a spread skips the excess-property check), each
+ * session would open its grants with an empty history.
+ */
+
+import { createExternalEventGrantHistory } from '@robota-sdk/agent-framework';
+import { describe, expect, it } from 'vitest';
+
+import { toChannelOptions } from '../render.js';
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+
+import type { IRenderOptions } from '../render.js';
+
+describe('#3189: the grant history survives the TUI projection', () => {
+  it('carries the same history instance into every session it builds', () => {
+    const history = createExternalEventGrantHistory();
+    const options = {
+      cwd: '/work',
+      provider: {} as never,
+      externalEventGrantHistory: history,
+    } as unknown as IRenderOptions;
+
+    const first = buildTuiSessionOptions(toChannelOptions(options, undefined));
+    const switchedTo = buildTuiSessionOptions(toChannelOptions(options, 'session-b'));
+
+    expect(first.externalEventGrantHistory).toBe(history);
+    expect(switchedTo.externalEventGrantHistory).toBe(history);
+  });
+});