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

package/src/__tests__/pty/isolated-home.ts

@@ -0,0 +1,64 @@
+/**
+ * Isolated HOME for PTY children (HARNESS-025).
+ *
+ * A PTY test that forwards the developer's real `HOME` runs its child against whatever happens to
+ * be in that home directory — a `~/.robota` settings file, a shell rc, an `$EDITOR` preference.
+ * The suite then passes or fails depending on the machine it runs on: green on CI (empty HOME),
+ * red on a developer box whose real config contradicts the fixture. That is the conditional flake
+ * this module removes.
+ *
+ * Every PTY child gets a throwaway directory instead. The directories are tracked and removed on
+ * process exit, so a test that forgets to dispose leaks nothing beyond the run.
+ *
+ * `packages/agent-ui-terminal/src/__tests__/pty/pty-driver.ts` already took an explicit
+ * `homeDir`; this generalizes that discipline to every `spawnPty` caller, including the default.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const createdHomes: string[] = [];
+let exitHookInstalled = false;
+
+function installExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on('exit', disposeIsolatedHomes);
+}
+
+/**
+ * Create a throwaway HOME directory for a PTY child and return its absolute path.
+ *
+ * The directory is empty: the child sees no `~/.robota`, no shell rc, no user preferences. Callers
+ * that need seeded content write it themselves after creating the directory.
+ */
+export function createIsolatedHome(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'robota-pty-home-'));
+  createdHomes.push(dir);
+  installExitHook();
+  return dir;
+}
+
+/** Remove every directory handed out by {@link createIsolatedHome}. Idempotent. */
+export function disposeIsolatedHomes(): void {
+  for (const dir of createdHomes.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Build the environment for a PTY child: an isolated HOME, the real PATH (the child still needs to
+ * find `sh`, `node`, …), and a known TERM.
+ *
+ * The environment is deliberately minimal rather than a copy of `process.env` — a PTY run must not
+ * inherit real provider API keys, and an explicit base makes every variable the child can see
+ * visible at the call site. Pass `overrides` for anything else the fixture needs (e.g. `EDITOR`).
+ */
+export function createPtyEnv(overrides: Readonly<NodeJS.ProcessEnv> = {}): NodeJS.ProcessEnv {
+  return {
+    PATH: process.env['PATH'] ?? '',
+    HOME: createIsolatedHome(),
+    TERM: 'xterm-256color',
+    ...overrides,
+  };
+}

package/src/__tests__/pty/org-policy.ptytest.ts

@@ -0,0 +1,71 @@
+/**
+ * Real-PTY organization-policy engineering regression scenario (CLI-083).
+ *
+ * Drives the built Robota CLI with an isolated HOME. Nothing injects a policy object into the
+ * command module: the refusal can only come from the shipped `loadOrgPolicy()` startup path. The
+ * update check is disabled so this isolated scenario performs no startup network request.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+function writeOrgPolicyFixture(homeDir: string): void {
+  const settingsDir = join(homeDir, '.robota');
+  mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(
+    join(settingsDir, 'settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'pty-dummy-key' },
+        openai: { type: 'openai', model: 'gpt-test-model', apiKey: 'pty-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+  writeFileSync(
+    join(settingsDir, 'org-policy.json'),
+    JSON.stringify({ allowedProviders: ['anthropic'], adminContact: 'ops@example.com' }),
+    'utf8',
+  );
+}
+
+describe('organization policy through the built CLI (CLI-083)', () => {
+  let projectDir: string;
+  let homeDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-pty-org-policy-')));
+    homeDir = join(projectDir, 'home');
+    writeOrgPolicyFixture(homeDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('blocks a provider switch forbidden only by the policy loaded from disk', async () => {
+    session = spawnTui({ projectDir, homeDir, args: ['--disable-update-check'] });
+    await session.waitFor(/Type a message or \/help/);
+
+    const since = session.outputOffset();
+    await session.sendKeys('/provider switch openai');
+    await session.pressEnter();
+
+    await session.waitForSince(
+      since,
+      /Provider "openai" is not allowed by your organization policy/,
+    );
+    expect(session.snapshotSince(since)).toContain('Allowed: anthropic');
+  }, 60_000);
+});

package/src/__tests__/pty/provider-setup.ptytest.ts

@@ -0,0 +1,61 @@
+/**
+ * Real-PTY provider-setup ask suite (CMD-004 TC-09 done-gate).
+ *
+ * Drives the BUILT robota binary through `/provider add` so the unified ask seam renders end-to-end on
+ * a real terminal: the provider command self-asks (via the injected `askHandler` → `TuiInteractionChannel.askUser`)
+ * and the TUI renders the request through `PendingActionPrompt`. Proves the masked secret field hides
+ * the typed API key on the real CLI — the User Execution evidence the done-gate requires (no human
+ * needed; the PTY drives the binary). Run via `pnpm --filter @robota-sdk/agent-ui-terminal test:pty`
+ * against a freshly built CLI.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const SECRET = 'topsecretapikey';
+
+describe('provider setup ask through a real PTY (CMD-004 TC-09)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-pty-provider-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('TC-09: /provider add asks the masked API-key field and never echoes the secret', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+    await session.waitFor(/Type a message or \/help/);
+
+    // The provider command self-asks; the first anthropic setup step is the masked API key.
+    await session.sendKeys('/provider add anthropic');
+    await session.pressEnter();
+    await session.waitFor(/Anthropic API key/);
+
+    // Type the secret at human key rate; the masked field must render `*`, not the plaintext.
+    await session.sendKeys(SECRET);
+    await session.waitFor(new RegExp(`\\*{${SECRET.length}}`));
+
+    const masked = session.snapshot();
+    expect(masked).not.toContain(SECRET);
+    expect(masked).toContain('*'.repeat(SECRET.length));
+
+    // Esc cancels the wizard (no settings write / restart effect); the secret stays off-screen.
+    session.pressEscape();
+    await session.waitFor(/Provider setup cancelled\./);
+    expect(session.snapshot()).not.toContain(SECRET);
+  }, 60_000);
+});

package/src/__tests__/pty/pty-driver.ts

@@ -0,0 +1,153 @@
+/**
+ * PTY TUI driver (CLI-074 TC-07/08).
+ *
+ * Built-CLI convenience over the shared `spawnPty` harness (TEST-007): spawns the built robota CLI in
+ * a real pseudo-terminal so Ink renders exactly as in a user terminal, with per-key paced input
+ * (expect(1)-style burst input gets bundled as a bracketed paste — the failure mode this driver
+ * exists to avoid). Test-only; lives in a dedicated vitest project (*.ptytest.ts).
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { spawnPty } from './spawn-pty.js';
+
+import type { IPtyRunSession } from './spawn-pty.js';
+
+const REPO_ROOT = resolve(__dirname, '../../../../..');
+const ROBOTA_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/robota.cjs');
+
+/**
+ * Signal the PTY child and await its ACTUAL exit before the caller removes the project dir.
+ * `dispose()` sends SIGTERM (then SIGKILL after the grace window) but returns synchronously;
+ * `expectExit()` resolves once the child has exited and **throws** if it has not within the timeout.
+ * Awaiting this closes the INFRA-026 race where a dying child writes `<projectDir>/.robota` between
+ * `rmSync`'s readdir and rmdir. A child that refuses to die fails the test loudly — the exit is awaited
+ * at the source, never masked by a removal fallback.
+ * Extracted so the compose is unit-testable with a fake session.
+ */
+export async function killAndAwaitExit(
+  session: Pick<IPtyRunSession, 'dispose' | 'expectExit'>,
+  timeoutMs?: number,
+): Promise<void> {
+  session.dispose();
+  await session.expectExit(timeoutMs);
+}
+
+/**
+ * Driving session for a built-CLI PTY run. Mirrors the historical `spawnTui` surface (kept for the
+ * existing `*.ptytest.ts` suites) on top of the shared `IPtyRunSession`.
+ */
+export interface IPtySession {
+  sendKeys(text: string, perKeyDelayMs?: number): Promise<void>;
+  pressEnter(): Promise<void>;
+  /** Send a raw Escape keystroke (cancels a pending Ink prompt). */
+  pressEscape(): void;
+  /**
+   * Write bytes verbatim, with no per-character pacing. An escape SEQUENCE must come this way:
+   * `sendKeys` paces character by character, so `\x1b[B` arrives as a lone Escape — which an
+   * overlay reads as "cancel" — followed by the literal text `[B` typed into the composer.
+   */
+  writeRaw(data: string): void;
+  waitFor(pattern: RegExp, timeoutMs?: number): Promise<void>;
+  /**
+   * Mark for `waitForSince`/`snapshotSince`. `snapshot()` is a CUMULATIVE transcript (old frames +
+   * the echo of your own typed input included) — take a mark before acting and assert on what
+   * arrived after it, or a pattern can match stale frames / your own prompt text.
+   */
+  outputOffset(): number;
+  /** Like `waitFor`, but only matches output that arrived after the `since` mark. */
+  waitForSince(since: number, pattern: RegExp, timeoutMs?: number): Promise<void>;
+  /** ANSI-stripped output that arrived after the `since` mark. */
+  snapshotSince(since: number): string;
+  snapshot(): string;
+  /** Raw (un-stripped) cumulative output — for cursor/escape-sequence assertions (CLI-062). */
+  raw(): string;
+  expectExit(timeoutMs?: number): Promise<number>;
+  kill(): void;
+  /**
+   * Teardown that awaits ACTUAL child exit: signals the PTY child (`kill()`/`dispose()`) then awaits
+   * `expectExit`, which resolves once the child has exited and **throws** if it has not within the
+   * timeout (default ≥ the SIGTERM→SIGKILL grace). Await this before removing the project dir so the
+   * dying child cannot write `<projectDir>/.robota` between `rmSync`'s readdir and rmdir (INFRA-026).
+   */
+  disposeAsync(timeoutMs?: number): Promise<void>;
+}
+
+export interface ISpawnTuiOptions {
+  /** Project cwd. The fixture provider profile lives in the isolated user HOME. */
+  projectDir: string;
+  /** Isolated HOME directory. */
+  homeDir: string;
+  cols?: number;
+  rows?: number;
+  /** Extra CLI args appended after the binary (e.g. `['--session-log', path]`). */
+  args?: readonly string[];
+  /**
+   * Extra environment variables merged over the driver's minimal base env
+   * (e.g. `{ NO_COLOR: '1' }` for the SCREEN-006 no-color scenario). The base stays
+   * explicit — real provider keys are never inherited into PTY runs.
+   */
+  env?: Readonly<Record<string, string>>;
+}
+
+export function writeTuiProviderSettings(projectDir: string): void {
+  // ARCH-042: a capabilityless built CLI is Restricted and must not read project settings. PTY
+  // fixtures therefore configure the host-owned user layer under the same isolated HOME that
+  // `spawnTui` derives from the fixture root.
+  const settingsDir = join(projectDir, 'home', '.robota');
+  mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(
+    join(settingsDir, 'settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        // Boot/slash/exit make zero model calls — the key is never used.
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'pty-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+}
+
+export function spawnTui(options: ISpawnTuiOptions): IPtySession {
+  mkdirSync(options.homeDir, { recursive: true });
+
+  // An explicit session name suppresses LLM auto-naming, which fires a provider call on the first
+  // user message — with a replay/scripted provider that call silently CONSUMES the next recorded
+  // response and desyncs the fixture (lesson 2026-07-02). Tests that assert naming pass their own.
+  const args = options.args ?? [];
+  const defaultedArgs = args.includes('--name') ? args : [...args, '--name', 'pty-fixture'];
+
+  const session: IPtyRunSession = spawnPty({
+    command: process.execPath,
+    args: [ROBOTA_BIN, ...defaultedArgs],
+    cwd: options.projectDir,
+    env: {
+      PATH: process.env['PATH'] ?? '',
+      HOME: options.homeDir,
+      TERM: 'xterm-256color',
+      // Never inherit real provider keys into PTY runs.
+      ...(options.env ?? {}),
+    },
+    ...(options.cols !== undefined ? { cols: options.cols } : {}),
+    ...(options.rows !== undefined ? { rows: options.rows } : {}),
+  });
+
+  return {
+    sendKeys: (text, perKeyDelayMs): Promise<void> => session.sendKeys(text, perKeyDelayMs),
+    pressEnter: (): Promise<void> => session.pressEnter(),
+    pressEscape: (): void => session.write('\x1b'),
+    writeRaw: (data): void => session.write(data),
+    waitFor: (pattern, timeoutMs): Promise<void> => session.waitFor(pattern, timeoutMs),
+    outputOffset: (): number => session.outputOffset(),
+    waitForSince: (since, pattern, timeoutMs): Promise<void> =>
+      session.waitForSince(since, pattern, timeoutMs),
+    snapshotSince: (since): string => session.snapshotSince(since),
+    snapshot: (): string => session.snapshot(),
+    raw: (): string => session.raw(),
+    expectExit: (timeoutMs): Promise<number> => session.expectExit(timeoutMs),
+    kill: (): void => session.dispose(),
+    disposeAsync: (timeoutMs): Promise<void> => killAndAwaitExit(session, timeoutMs),
+  };
+}

package/src/__tests__/pty/replay-conversation.ptytest.ts

@@ -0,0 +1,68 @@
+/**
+ * INFRA-018: deterministic conversation through the real binary via `--session-log` (replay).
+ *
+ * Runs in the PTY vitest project against the BUILT robota CLI. Boots with
+ * `--session-log <fixture>` so the INFRA-017 ReplayProvider answers from a recorded log (no model
+ * key, no network), sends a user message, and asserts the recorded assistant response renders and
+ * commits to `<Static>` scrollback while the input stays pinned — closing SCREEN-010 TC-02/03
+ * end-to-end on the real binary.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const FIXTURE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  'fixtures',
+  'replay-conversation.jsonl',
+);
+
+describe('replay conversation through the real binary (INFRA-018)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-replay-pty-')));
+    writeTuiProviderSettings(projectDir); // dummy provider profile so the CLI boots; key never used
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('TC-01/02/03: replays a recorded assistant turn — streams, commits to scrollback, input pinned', async () => {
+    session = spawnTui({
+      projectDir,
+      homeDir: join(projectDir, 'home'),
+      args: ['--session-log', FIXTURE],
+    });
+
+    // TC-01: boots with the replay provider (no model key used).
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // Send a user message → the framework calls the provider → ReplayProvider returns the recorded
+    // assistant response.
+    await session.sendKeys('hello');
+    await session.pressEnter();
+
+    // TC-02: the recorded assistant response renders and commits to scrollback.
+    await session.waitFor(/REPLAYED_ANSWER_42/, 20_000);
+
+    // TC-03: the input prompt re-renders at the bottom (live region) below the committed reply.
+    await session.waitFor(/Type a message or \/help/, 20_000);
+    const snap = session.snapshot();
+    expect(snap).toContain('REPLAYED_ANSWER_42');
+    expect(snap.lastIndexOf('Type a message')).toBeGreaterThan(snap.indexOf('REPLAYED_ANSWER_42'));
+  }, 60_000);
+});

package/src/__tests__/pty/screen-005-prompt-footers.ptytest.ts

@@ -0,0 +1,134 @@
+/**
+ * SCREEN-005 User Execution Test Scenarios — prompt footers and key-hint affordance on the BUILT
+ * robota binary in a real PTY (run by `test:pty`; requires `pnpm build:deps` first).
+ *
+ * Scenario 1: `/` opens the autocomplete → unified footer + `> ` indicator on the selected row.
+ * Scenario 2: a replayed model turn drives a CMD-004 ask in each shape (single-select,
+ *   multi-select with the dynamic `(min N)` segment, free-text) → all footers share the grammar.
+ * Scenario 3: a replayed Shell tool call opens the permission prompt → footer names the real keys
+ *   (`←→ Navigate · Enter Confirm`, no Esc); pressing Esc resolves nothing (documented hard-stop).
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+import { formatKeyHints } from '../../key-hint-footer.js';
+import { LIST_PICKER_DEFAULT_FOOTER_HINTS } from '../../ListPicker.js';
+import { getMultiSelectFooterHints } from '../../MultiSelectList.js';
+import { PERMISSION_PROMPT_FOOTER_HINTS } from '../../PermissionPrompt.js';
+import { SLASH_AUTOCOMPLETE_FOOTER_HINTS } from '../../SlashAutocomplete.js';
+import { TEXT_PROMPT_FOOTER_HINTS } from '../../TextPrompt.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const ASK_SHAPES_FIXTURE = join(FIXTURES, 'screen-005-ask-shapes.jsonl');
+const PERMISSION_FIXTURE = join(FIXTURES, 'screen-005-permission.jsonl');
+
+function escapeRegExp(text: string): RegExp {
+  return new RegExp(text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+}
+
+const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe('SCREEN-005 prompt footers through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-screen005-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('S1: slash autocomplete shows the unified footer and the > indicator on the selected row', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('/');
+    const expectedFooter = formatKeyHints(SLASH_AUTOCOMPLETE_FOOTER_HINTS);
+    await session.waitFor(escapeRegExp(expectedFooter), 20_000);
+
+    const frame = session.snapshot();
+    expect(frame).toContain(expectedFooter);
+    // The highlighted first row carries the selection indicator in front of the command name.
+    expect(frame).toMatch(/> \/\w+/);
+  }, 60_000);
+
+  it('S2: single-select, multi-select (dynamic min segment), and free-text asks share the grammar', async () => {
+    session = spawnTui({
+      projectDir,
+      homeDir: join(projectDir, 'home'),
+      args: ['--session-log', ASK_SHAPES_FIXTURE, '--name', 'shapes-fixture'],
+    });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('go');
+    await session.pressEnter();
+
+    // Shape 1 — single-select (ListPicker default footer).
+    await session.waitFor(/PICK_SINGLE/, 20_000);
+    await session.waitFor(escapeRegExp(formatKeyHints(LIST_PICKER_DEFAULT_FOOTER_HINTS)), 10_000);
+    expect(session.snapshot()).toContain('> Red'); // indicator on the highlighted option
+    await session.pressEnter(); // answer "Red"
+
+    // Shape 2 — multi-select: min segment shows until satisfiable, then drops.
+    await session.waitFor(/PICK_MULTI/, 20_000);
+    const unsatisfied = formatKeyHints(
+      getMultiSelectFooterHints({ canConfirm: false, minSelect: 1 }),
+    );
+    await session.waitFor(escapeRegExp(unsatisfied), 10_000);
+    const beforeToggle = session.outputOffset();
+    await session.sendKeys(' '); // toggle Alpha → selection satisfiable
+    const satisfied = formatKeyHints(getMultiSelectFooterHints({ canConfirm: true, minSelect: 1 }));
+    await session.waitForSince(beforeToggle, escapeRegExp(satisfied), 10_000);
+    await session.pressEnter(); // confirm
+
+    // Shape 3 — free-text (TextPrompt footer).
+    await session.waitFor(/TYPE_TEXT/, 20_000);
+    await session.waitFor(escapeRegExp(formatKeyHints(TEXT_PROMPT_FOOTER_HINTS)), 10_000);
+    await session.sendKeys('hello');
+    await session.pressEnter();
+
+    // The replayed follow-up proves every ask resolved through the shared-grammar prompts.
+    await session.waitFor(/ALL_SHAPES_DONE/, 20_000);
+  }, 60_000);
+
+  it('S3: permission prompt names the real keys and Esc resolves nothing (explicit hard-stop)', async () => {
+    session = spawnTui({
+      projectDir,
+      homeDir: join(projectDir, 'home'),
+      args: ['--session-log', PERMISSION_FIXTURE, '--name', 'perm-fixture'],
+    });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('go');
+    await session.pressEnter();
+
+    // The replayed Shell call needs approval in default permission mode → prompt renders.
+    await session.waitFor(/Permission Required/, 20_000);
+    const expectedFooter = formatKeyHints(PERMISSION_PROMPT_FOOTER_HINTS);
+    await session.waitFor(escapeRegExp(expectedFooter), 10_000);
+
+    // Esc is suppressed (a dismissal would be an implicit deny): nothing resolves, the prompt stays.
+    session.pressEscape();
+    await delay(500);
+    const afterEsc = session.snapshot();
+    expect(afterEsc).not.toContain('AFTER_PERMISSION_FLOW');
+    expect(afterEsc).toContain('Allow [y]'); // prompt still displayed, still unresolved
+
+    // Resolve explicitly (allow) → the tool runs and the turn continues.
+    await session.sendKeys('y');
+    await session.waitFor(/AFTER_PERMISSION_FLOW/, 20_000);
+  }, 60_000);
+});