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

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

@@ -0,0 +1,229 @@
+/**
+ * TUI-owned PTY harness (TEST-007; relocated internally by BOUNDARY-2655).
+ *
+ * One reusable pseudo-terminal driver for end-to-end tests. Spawns a process in a real PTY (via
+ * the prebuilt `@homebridge/node-pty-prebuilt-multiarch`, so Ink renders and reads input exactly as
+ * in a user terminal) and exposes per-key paced input plus marker/exit waiting. Two convenience
+ * spawners build on the core:
+ *
+ * - `spawnPty` — drive any command (e.g. the built robota CLI binary).
+ * - `spawnPtyFixture` — drive a TSX fixture through the `tsx/esm` import hook (no build step),
+ *   the pattern used for focused source-level E2E.
+ *
+ * Per-key pacing matters: a burst write is bundled by the terminal as a bracketed paste, which is the
+ * exact failure mode this harness exists to avoid.
+ */
+import { createRequire } from 'node:module';
+
+import { spawn } from '@homebridge/node-pty-prebuilt-multiarch';
+
+import { createPtyEnv } from './isolated-home.js';
+
+import type { IPty } from '@homebridge/node-pty-prebuilt-multiarch';
+
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[()][B0]|[\x00-\x08\x0b-\x1f]/g;
+
+const DEFAULT_PER_KEY_DELAY_MS = 35;
+const DEFAULT_WAIT_TIMEOUT_MS = 15_000;
+const DEFAULT_EXIT_TIMEOUT_MS = 10_000;
+const OUTPUT_TAIL_LENGTH = 2000;
+/** CORE-023: grace before escalating a lingering PTY child from SIGTERM to SIGKILL. */
+const PTY_KILL_GRACE_MS = 2000;
+
+export interface IPtyRunOptions {
+  command: string;
+  args: string[];
+  cwd: string;
+  /**
+   * Environment for the child. Defaults to {@link createPtyEnv} — a minimal env with an ISOLATED
+   * HOME. Build overrides with `createPtyEnv({ ... })` rather than by hand, so a caller cannot
+   * reintroduce the real `process.env.HOME` (which makes the suite depend on the host's `~`).
+   */
+  env?: NodeJS.ProcessEnv;
+  cols?: number;
+  rows?: number;
+}
+
+export interface IPtyRunSession {
+  /** Type text one key at a time (default 35ms/key — human-ish, avoids paste bundling). */
+  sendKeys(text: string, perKeyDelayMs?: number): Promise<void>;
+  /** Write bytes verbatim (no pacing) — for control sequences / single keystrokes. */
+  write(data: string): void;
+  /** Press Enter as a single keystroke (with small settle on either side). */
+  pressEnter(): Promise<void>;
+  /** Wait until the ANSI-stripped output matches; throws with a snapshot on timeout. */
+  waitFor(pattern: RegExp | string, timeoutMs?: number): Promise<void>;
+  /**
+   * Current length of the ANSI-stripped output — a mark for `waitForSince`/`snapshotSince`.
+   * The stripped output is CUMULATIVE (a transcript, not the current screen): a plain `waitFor`
+   * also matches old frames and the echo of your own typed input. Take a mark before acting, then
+   * assert only on what arrived after it.
+   */
+  outputOffset(): number;
+  /** Like `waitFor`, but matches only output that arrived after the `since` mark. */
+  waitForSince(since: number, pattern: RegExp | string, timeoutMs?: number): Promise<void>;
+  /** ANSI-stripped output that arrived after the `since` mark. */
+  snapshotSince(since: number): string;
+  /** Current ANSI-stripped output. */
+  snapshot(): string;
+  /** Current raw (un-stripped) output. */
+  raw(): string;
+  /** Wait for process exit; throws with a snapshot on timeout. */
+  expectExit(timeoutMs?: number): Promise<number>;
+  /** Force-kill / cleanup (no-op if already exited). */
+  dispose(): void;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function toRegExp(pattern: RegExp | string): RegExp {
+  if (pattern instanceof RegExp) return pattern;
+  // Escape regex metacharacters so a plain string is matched literally.
+  return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+}
+
+/** Spawn any command in a real PTY and return a driving session. */
+export function spawnPty(options: IPtyRunOptions): IPtyRunSession {
+  let output = '';
+  let exitCode: number | undefined;
+
+  const pty: IPty = spawn(options.command, options.args, {
+    name: 'xterm-256color',
+    cols: options.cols ?? 100,
+    rows: options.rows ?? 32,
+    cwd: options.cwd,
+    // HARNESS-025: the default HOME is a throwaway directory, never the developer's real one — a
+    // PTY child that reads `~/.robota` (or any user rc) must not make the suite machine-dependent.
+    env: options.env ?? createPtyEnv(),
+  });
+
+  pty.onData((data) => {
+    output += data;
+  });
+  pty.onExit(({ exitCode: code }) => {
+    exitCode = code;
+  });
+
+  const stripped = (): string => output.replace(ANSI_PATTERN, '');
+
+  return {
+    async sendKeys(text: string, perKeyDelayMs = DEFAULT_PER_KEY_DELAY_MS): Promise<void> {
+      for (const ch of text) {
+        pty.write(ch);
+        await sleep(perKeyDelayMs);
+      }
+    },
+    write(data: string): void {
+      pty.write(data);
+    },
+    async pressEnter(): Promise<void> {
+      await sleep(120);
+      pty.write('\r');
+      await sleep(120);
+    },
+    async waitFor(pattern: RegExp | string, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS): Promise<void> {
+      const regex = toRegExp(pattern);
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (regex.test(stripped())) return;
+        if (exitCode !== undefined && regex.test(stripped())) return;
+        await sleep(50);
+      }
+      throw new Error(
+        `PTY waitFor timeout (${timeoutMs}ms) for ${String(regex)}\n--- snapshot ---\n${stripped().slice(-OUTPUT_TAIL_LENGTH)}`,
+      );
+    },
+    outputOffset(): number {
+      return stripped().length;
+    },
+    async waitForSince(
+      since: number,
+      pattern: RegExp | string,
+      timeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
+    ): Promise<void> {
+      const regex = toRegExp(pattern);
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (regex.test(stripped().slice(since))) return;
+        await sleep(50);
+      }
+      throw new Error(
+        `PTY waitForSince timeout (${timeoutMs}ms) for ${String(regex)} after offset ${since}\n--- snapshot since mark ---\n${stripped().slice(since).slice(-OUTPUT_TAIL_LENGTH)}`,
+      );
+    },
+    snapshotSince(since: number): string {
+      return stripped().slice(since);
+    },
+    snapshot: stripped,
+    raw: (): string => output,
+    async expectExit(timeoutMs = DEFAULT_EXIT_TIMEOUT_MS): Promise<number> {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (exitCode !== undefined) return exitCode;
+        await sleep(50);
+      }
+      throw new Error(
+        `PTY process did not exit within ${timeoutMs}ms\n--- snapshot ---\n${stripped().slice(-OUTPUT_TAIL_LENGTH)}`,
+      );
+    },
+    dispose(): void {
+      if (exitCode !== undefined) return;
+      try {
+        pty.kill();
+      } catch {
+        // allow-fallback: process already exited — kill on a dead pty is a no-op by design
+      }
+      // CORE-023: mirror the killProcessTree escalation pattern — a child that ignores SIGTERM
+      // is force-killed after the grace window. Keep this test-local lifecycle implementation
+      // independent of @robota-sdk/agent-process.
+      const graceTimer = setTimeout(() => {
+        if (exitCode === undefined) {
+          try {
+            pty.kill('SIGKILL');
+          } catch {
+            // allow-fallback: process exited during the grace window — SIGKILL is a no-op
+          }
+        }
+      }, PTY_KILL_GRACE_MS);
+      graceTimer.unref?.();
+    },
+  };
+}
+
+export interface ISpawnFixtureOptions {
+  /** Extra argv passed to the fixture after its path (e.g. an output JSON path). */
+  argv?: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  cols?: number;
+  rows?: number;
+}
+
+let tsxEsmHookPath: string | undefined;
+function resolveTsxEsmHook(): string {
+  // Lazily resolved so built-CLI consumers (which never run a TSX fixture) don't require tsx.
+  tsxEsmHookPath ??= createRequire(import.meta.url).resolve('tsx/esm');
+  return tsxEsmHookPath;
+}
+
+/**
+ * Spawn a TSX fixture inside a PTY via the `tsx/esm` import hook (no build step). The fixture's own
+ * relative imports resolve from its absolute path; `cwd` controls module resolution for bare
+ * specifiers (point it at the package dir or repo root).
+ */
+export function spawnPtyFixture(
+  fixturePath: string,
+  options: ISpawnFixtureOptions,
+): IPtyRunSession {
+  return spawnPty({
+    command: process.execPath,
+    args: ['--import', resolveTsxEsmHook(), fixturePath, ...(options.argv ?? [])],
+    cwd: options.cwd,
+    ...(options.env ? { env: options.env } : {}),
+    ...(options.cols !== undefined ? { cols: options.cols } : {}),
+    ...(options.rows !== undefined ? { rows: options.rows } : {}),
+  });
+}

package/src/__tests__/pty/terminal-handoff.ptytest.ts

@@ -0,0 +1,79 @@
+/**
+ * TERM-003 / TEST-007: real-binary terminal-handoff evidence.
+ *
+ * Runs in the dedicated PTY vitest project (vitest.pty.config.ts) against the BUILT robota binary
+ * (`pnpm --filter @robota-sdk/agent-cli build` first). Unlike the source-level fixture E2E
+ * (`terminal-handoff-pty-e2e` / `command-handoff-pty-e2e`), this drives the WHOLE user path —
+ * real CLI → real command pipeline → real `TerminalHandoffController` injected by `render.tsx` →
+ * `/shell` — through a real pseudo-terminal, simulating a user typing. It is automated
+ * user-execution-level proof: the child runs on the real terminal during the handoff and the TUI
+ * frame restores afterward (machine proxy for "no stale frame / clean resume").
+ */
+
+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';
+
+describe('terminal handoff through the real binary (TERM-003)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-handoff-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('TC-09: /shell runs a one-shot command on the real terminal and the TUI restores', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+
+    // Boot.
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // Run a one-shot shell command. A user-typed command is not permission-gated (that gate is for
+    // model/agent-invoked actions), so it runs directly through the handoff.
+    await session.sendKeys('/shell echo HANDOFF_REAL_OK');
+    await session.pressEnter();
+
+    // The child's output appears on the real (inherited) terminal during the handoff.
+    await session.waitFor(/HANDOFF_REAL_OK/, 20_000);
+
+    // The TUI reclaims the screen: the prompt frame redraws (clean resume, no hang).
+    await session.waitFor(/Type a message or \/help/, 20_000);
+  }, 60_000);
+
+  it('TC-04/TC-01: committed history (Static) is not re-printed after a /shell handoff (SCREEN-010 × TERM-002)', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // The startup banner is committed to the terminal scrollback via a single Ink <Static> (TC-01).
+    // Count its version line; if the handoff resume re-emitted committed history, it would re-print.
+    const versionRe = /v\d+\.\d+\.\d+/g;
+    const beforeCount = (session.snapshot().match(versionRe) ?? []).length;
+    expect(beforeCount).toBeGreaterThanOrEqual(1);
+
+    await session.sendKeys('/shell echo HANDOFF_OK');
+    await session.pressEnter();
+    await session.waitFor(/HANDOFF_OK/, 20_000);
+    await session.waitFor(/Type a message or \/help/, 20_000);
+
+    // SCREEN-010 keeps <Static> mounted at a stable tree position across suspend/resume, so the
+    // committed banner is NOT re-printed on return (TC-04).
+    const afterCount = (session.snapshot().match(versionRe) ?? []).length;
+    expect(afterCount).toBe(beforeCount);
+  }, 60_000);
+});

package/src/__tests__/pty/tui-pty.ptytest.ts

@@ -0,0 +1,65 @@
+/**
+ * Real-PTY TUI suites (CLI-074 TC-07/08).
+ *
+ * Runs in the dedicated PTY vitest project (vitest.pty.config.ts) against the
+ * BUILT robota binary — `pnpm --filter @robota-sdk/agent-cli build` first.
+ */
+
+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';
+
+describe('TUI through a real PTY (CLI-074)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('TC-07: boots, opens slash autocomplete, and executes /help as a command', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+
+    // Boot: prompt + status bar render.
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // '/' opens the autocomplete dropdown listing commands.
+    await session.sendKeys('/');
+    await session.waitFor(/\/help\s+Show available commands/);
+
+    // Typing the rest at human key rate must stay a command, not a paste.
+    await session.sendKeys('help');
+    await session.pressEnter();
+    await session.waitFor(/Available commands|\/cost|\/clear/i, 20_000);
+    expect(session.snapshot()).not.toContain('[Pasted text');
+  }, 60_000);
+
+  it('TC-08: /exit confirms then reaches process exit within 10s', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('/exit');
+    await session.pressEnter();
+
+    // CMD-004: /exit now asks for confirmation; answer Yes (the default-highlighted option).
+    await session.waitFor(/Exit the session\?/);
+    await session.pressEnter();
+
+    const exitCode = await session.expectExit(10_000);
+    expect(exitCode).toBe(0);
+  }, 60_000);
+});

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

@@ -0,0 +1,43 @@
+/**
+ * INFRA-026 TC-01 — `killAndAwaitExit` (the compose behind the PTY driver's `disposeAsync`) awaits
+ * ACTUAL child exit and rejects loudly on non-exit. Unit-level with a fake session (no real PTY), so
+ * it runs in the default vitest project rather than the `*.ptytest` built-CLI project.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { killAndAwaitExit } from './pty/pty-driver.js';
+
+describe('killAndAwaitExit (INFRA-026 teardown compose)', () => {
+  it('signals the child (dispose) then resolves once expectExit resolves', async () => {
+    const order: string[] = [];
+    const session = {
+      dispose: vi.fn(() => {
+        order.push('dispose');
+      }),
+      expectExit: vi.fn(async (): Promise<number> => {
+        order.push('expectExit');
+        return 0;
+      }),
+    };
+
+    await expect(killAndAwaitExit(session, 1000)).resolves.toBeUndefined();
+
+    expect(session.dispose).toHaveBeenCalledTimes(1);
+    expect(session.expectExit).toHaveBeenCalledWith(1000);
+    // dispose must be signalled BEFORE we await exit.
+    expect(order).toEqual(['dispose', 'expectExit']);
+  });
+
+  it('rejects (does not swallow) when the child does not exit within the timeout', async () => {
+    const session = {
+      dispose: vi.fn(),
+      expectExit: vi.fn(async (): Promise<number> => {
+        throw new Error('PTY process did not exit within 1000ms');
+      }),
+    };
+
+    await expect(killAndAwaitExit(session, 1000)).rejects.toThrow(/did not exit/);
+    // Still signalled the child — the failure is a loud teardown defect, not a masked one.
+    expect(session.dispose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/real-cursor-positioning.test.tsx

@@ -0,0 +1,263 @@
+/**
+ * CLI-062 — real-terminal-cursor positioning through ink's actual interactive render path.
+ *
+ * Renders CjkTextInput inside a TransportTUI-shaped harness against a fake TTY stdout
+ * (`interactive: true`), then interprets the raw ANSI stream with the same VT logic a terminal
+ * emulator (and the OS IME) applies. This is the component-level half of the CLI-062 contract
+ * (.design/investigations/2026-07-25-cli-062-ime-cursor-design.md): the hardware cursor must be
+ * shown ON the input row at the composition column, track CJK width growth, disappear when the
+ * input is unfocused (I4), propagate `undefined` on unmount (I4), and the production code must
+ * write NOTHING to the real process streams (the PoC row-accounting lesson, I3).
+ *
+ * The host override opts the capability gate in explicitly — the vitest process has no TTY,
+ * so the default gate would (correctly) refuse.
+ */
+
+import { EventEmitter } from 'node:events';
+
+import chalk from 'chalk';
+import { Box, Text, render } from 'ink';
+import React, { useState } from 'react';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { interpretVtStream } from './helpers/vt-cursor-interpreter.js';
+import CjkTextInput from '../CjkTextInput.js';
+import { TerminalCapabilitiesProvider } from '../terminal-capabilities-context.js';
+
+const COLS = 60;
+const ROWS = 24;
+const PROMPT = '> ';
+
+class FakeTtyStdout extends EventEmitter {
+  readonly isTTY = true;
+  readonly columns = COLS;
+  readonly rows = ROWS;
+  private chunks: string[] = [];
+  write = (chunk: string, callback?: () => void): boolean => {
+    this.chunks.push(String(chunk));
+    callback?.();
+    return true;
+  };
+  stream(): string {
+    return this.chunks.join('');
+  }
+}
+
+class FakeStdin extends EventEmitter {
+  readonly isTTY = true;
+  private pending: string | null = null;
+  setEncoding(): void {}
+  setRawMode(): void {}
+  resume(): void {}
+  pause(): void {}
+  ref(): void {}
+  unref(): void {}
+  read(): string | null {
+    const data = this.pending;
+    this.pending = null;
+    return data;
+  }
+  send(data: string): void {
+    this.pending = data;
+    this.emit('readable');
+    this.emit('data', data);
+  }
+}
+
+function Harness({
+  focus = true,
+  bannerLines = 1,
+}: {
+  focus?: boolean;
+  /** Rows rendered above the input — the layout the measured y must follow. */
+  bannerLines?: number;
+}): React.ReactElement {
+  const [value, setValue] = useState('');
+  return (
+    <Box flexDirection="column">
+      {Array.from({ length: bannerLines }, (_, index) => (
+        <Text key={index}>banner line {index}</Text>
+      ))}
+      <Box>
+        <Text>{PROMPT}</Text>
+        <CjkTextInput value={value} onChange={setValue} availableWidth={COLS - 2} focus={focus} />
+      </Box>
+      <Text>status line</Text>
+    </Box>
+  );
+}
+
+interface IScenario {
+  stdout: FakeTtyStdout;
+  stdin: FakeStdin;
+  unmount: () => void;
+}
+
+function renderScenario(focus?: boolean, bannerLines?: number): IScenario {
+  const stdout = new FakeTtyStdout();
+  const stdin = new FakeStdin();
+  const instance = render(
+    <TerminalCapabilitiesProvider overrides={{ imeCursorPositioning: true }}>
+      <Harness
+        {...(focus === undefined ? {} : { focus })}
+        {...(bannerLines === undefined ? {} : { bannerLines })}
+      />
+    </TerminalCapabilitiesProvider>,
+    {
+      // Cast: ink wants real process streams; the fakes implement the parts its render loop uses.
+      stdout: stdout as unknown as NodeJS.WriteStream,
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      interactive: true,
+      exitOnCtrlC: false,
+      patchConsole: false,
+    },
+  );
+  return { stdout, stdin, unmount: instance.unmount };
+}
+
+/** Ink throttles frames (≤30fps) and React effects settle asynchronously — allow both to flush. */
+const settle = (): Promise<void> => new Promise((r) => setTimeout(r, 120));
+
+const INPUT_ROW = 1; // banner is row 0, input row is row 1 in the harness frame
+
+describe('CLI-062 — real cursor positioning (interactive ink render)', () => {
+  const ORIGINAL_CHALK_LEVEL = chalk.level;
+
+  beforeAll(() => {
+    chalk.level = 3; // make the drawn inverse cursor observable in bytes, so suppression is provable
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+    chalk.level = ORIGINAL_CHALK_LEVEL;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('shows the hardware cursor on the input row at the composition column and tracks CJK growth', async () => {
+    const stdoutSpy = vi.spyOn(process.stdout, 'write');
+    const stderrSpy = vi.spyOn(process.stderr, 'write');
+
+    const { stdout, stdin, unmount } = renderScenario();
+    await settle();
+
+    stdin.send('안녕');
+    await settle();
+
+    const afterTwo = interpretVtStream(stdout.stream(), ROWS, COLS);
+    const showsAfterTwo = afterTwo.showEvents;
+    expect(showsAfterTwo.length).toBeGreaterThan(0);
+    // Every show lands on the input row (never the banner/top region — the crash geometry).
+    for (const event of showsAfterTwo) {
+      expect(event.row).toBe(INPUT_ROW);
+    }
+    // Composition column: '> ' (2 cols) + 안녕 (2 wide chars = 4 cols).
+    expect(showsAfterTwo.at(-1)).toMatchObject({ row: INPUT_ROW, col: 6 });
+
+    stdin.send('하'); // one more wide char → +2 columns
+    await settle();
+
+    const afterThree = interpretVtStream(stdout.stream(), ROWS, COLS);
+    expect(afterThree.showEvents.at(-1)).toMatchObject({ row: INPUT_ROW, col: 8 });
+
+    // Drawn-cursor suppression: before the first measurement the fallback legitimately draws the
+    // inverse block (I1: no guessed rows), but from the first positioned show onward the hardware
+    // cursor and the inverse block must never coexist.
+    const firstShowOffset = afterThree.showEvents[0]!.offset;
+    expect(stdout.stream().slice(firstShowOffset)).not.toContain('\u001b[7m');
+
+    // I3/PoC lesson: the production path writes NOTHING to the real process streams.
+    expect(stdoutSpy).not.toHaveBeenCalled();
+    expect(stderrSpy).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  /**
+   * SIGSEGV regression guard, as a test rather than an argument.
+   *
+   * The Terminal.app Korean-IME crash was root-caused to `setCursorPosition({x, y: 0})` — a
+   * CONSTANT row that pointed the hardware cursor at the logo area. The mechanical statement that
+   * the bug class is gone is not "the literal is absent from the source" but "the emitted row is a
+   * function of the layout": move the input box down and the positioned row must move with it. A
+   * hardcoded `y: 0` — or any other constant — cannot satisfy both halves of this test.
+   */
+  it('SIGSEGV guard: the positioned row FOLLOWS the layout, so a constant y (the y:0 bug) is unrepresentable', async () => {
+    const rowsSeen: number[] = [];
+    for (const bannerLines of [1, 4]) {
+      const { stdout, stdin, unmount } = renderScenario(true, bannerLines);
+      await settle();
+      stdin.send('안녕');
+      await settle();
+
+      const vt = interpretVtStream(stdout.stream(), ROWS, COLS);
+      expect(vt.showEvents.length, `banner=${bannerLines}`).toBeGreaterThan(0);
+      const row = vt.showEvents.at(-1)!.row;
+      // The input box starts immediately below the banner, so its measured row IS bannerLines.
+      expect(row, `banner=${bannerLines}`).toBe(bannerLines);
+      // ...and never the top of the frame while any banner occupies it (the crash geometry).
+      expect(row, `banner=${bannerLines}`).toBeGreaterThan(0);
+      rowsSeen.push(row);
+      unmount();
+      await settle();
+    }
+    // Two different layouts must yield two different rows — a constant cannot pass both.
+    expect(new Set(rowsSeen).size).toBe(2);
+  });
+
+  it('I4: unfocused input never positions the cursor (and keeps the fallback drawn-cursor path off)', async () => {
+    const { stdout, stdin, unmount } = renderScenario(false);
+    await settle();
+    stdin.send('x'); // ignored — not focused
+    await settle();
+
+    const vt = interpretVtStream(stdout.stream(), ROWS, COLS);
+    expect(vt.showEvents).toEqual([]);
+    unmount();
+  });
+
+  it('I4: blur withdraws the position (no shows after focus loss) and unmount leaves the cursor visible', async () => {
+    const stdout = new FakeTtyStdout();
+    const stdin = new FakeStdin();
+    const instance = render(
+      <TerminalCapabilitiesProvider overrides={{ imeCursorPositioning: true }}>
+        <Harness />
+      </TerminalCapabilitiesProvider>,
+      {
+        stdout: stdout as unknown as NodeJS.WriteStream,
+        stdin: stdin as unknown as NodeJS.ReadStream,
+        interactive: true,
+        exitOnCtrlC: false,
+        patchConsole: false,
+      },
+    );
+    await settle();
+    stdin.send('안');
+    await settle();
+    expect(interpretVtStream(stdout.stream(), ROWS, COLS).showEvents.length).toBeGreaterThan(0);
+
+    // Blur: the guard fails → setCursorPosition(undefined) → ink hides the hardware cursor and
+    // emits NO further positioned shows (the I4 fallback path).
+    instance.rerender(
+      <TerminalCapabilitiesProvider overrides={{ imeCursorPositioning: true }}>
+        <Harness focus={false} />
+      </TerminalCapabilitiesProvider>,
+    );
+    await settle();
+    const afterBlurMark = stdout.stream().length;
+    stdin.send('x'); // ignored — not focused; also must not resurrect the cursor
+    await settle();
+    const blurShows = interpretVtStream(stdout.stream(), ROWS, COLS).showEvents.filter(
+      (event) => event.offset >= afterBlurMark,
+    );
+    expect(blurShows).toEqual([]);
+
+    // Unmount: useCursor's cleanup propagates `undefined`; ink's teardown restores a bare,
+    // visible cursor (never a freshly positioned one).
+    instance.unmount();
+    await settle();
+    expect(interpretVtStream(stdout.stream(), ROWS, COLS).visible).toBe(true);
+  });
+});