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

package/src/__tests__/pty/ime-cursor.ptytest.ts

@@ -0,0 +1,187 @@
+/**
+ * CLI-062 — PTY regression for real-terminal-cursor positioning (the OS-IME evidence).
+ *
+ * Runs the BUILT CLI binary in a real pseudo-terminal and interprets the raw ANSI stream the
+ * way a terminal emulator (and the OS IME) does. Two geometries from the implementation contract
+ * (.design/investigations/2026-07-25-cli-062-ime-cursor-design.md):
+ *
+ *  - 24-row pty: while typing CJK, every `ESC[?25h` emitted after boot lands ON the input row at
+ *    the composition column — never the top region (the historical hardcoded-y:0 crash geometry).
+ *  - 5-row pty: the live frame fills the viewport (ink's fullscreen path, bottom-anchor
+ *    off-by-one) — invariant I2 must refuse to position: ZERO cursor-show sequences after boot.
+ *
+ * Assertions only cover the post-boot composition window: boot may legitimately show the cursor
+ * (spinners etc.), and teardown restores visibility — both are outside the invariant.
+ *
+ * The second describe block drives four boundary representatives through the real binary. The full
+ * terminal/override matrix remains exhaustive in terminal-capabilities.test.ts; process startup is
+ * reserved for supported-default, Terminal.app-default-off, force-on, and kill-switch boundaries.
+ */
+
+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 korean from '../__fixtures__/korean-text.json';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+import {
+  REPRESENTATIVE_IME_PTY_CELLS,
+  TERMINAL_PROFILES,
+  cellLabel,
+  expectedImeCursorEnabled,
+  profileEnv,
+} from '../helpers/terminal-profiles.js';
+import { interpretVtStream } from '../helpers/vt-cursor-interpreter.js';
+
+import type { IPtySession } from './pty-driver.js';
+import type { ICursorShowEvent } from '../helpers/vt-cursor-interpreter.js';
+
+const COLS = 80;
+const PROMPT_PLACEHOLDER = /Type a message or \/help/;
+const COMPOSITION = korean.greetingFirstTwoSyllables;
+/** The composition occupies 4 display columns; the prompt adds `> `. */
+const COMPOSITION_WIDTH = 4;
+/** Let ink's throttled (≤30fps) frame writes flush after the last keystroke. */
+const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 400));
+
+interface IProbeResult {
+  /** Cursor shows emitted after boot — the composition window the OS IME would act on. */
+  compositionShows: ICursorShowEvent[];
+  /** Screen row holding `> ` followed by the composition, or -1 when the composition never rendered. */
+  inputRow: number;
+  /** Column of the `> ` prompt on the input row, or -1. */
+  promptCol: number;
+}
+
+/**
+ * Boot the built binary in a pty of the given geometry, type CJK, and report the cursor shows the
+ * terminal would have acted on. Shared by the original two cases and by every matrix cell.
+ */
+async function probe(
+  projectDir: string,
+  rows: number,
+  env: Record<string, string>,
+  register: (session: IPtySession) => void,
+): Promise<IProbeResult> {
+  const session = spawnTui({
+    projectDir,
+    homeDir: join(projectDir, 'home'),
+    cols: COLS,
+    rows,
+    env,
+  });
+  register(session);
+  await session.waitFor(PROMPT_PLACEHOLDER);
+  await flush();
+
+  const bootMark = session.raw().length;
+  await session.sendKeys(COMPOSITION);
+  await session.waitFor(new RegExp(COMPOSITION));
+  await flush();
+
+  const vt = interpretVtStream(session.raw(), rows, COLS);
+  const inputRow = vt.screen.findIndex((line) => line.includes(`> ${COMPOSITION}`));
+  return {
+    compositionShows: vt.showEvents.filter((event) => event.offset >= bootMark),
+    inputRow,
+    promptCol: inputRow < 0 ? -1 : vt.screen[inputRow]!.indexOf('> '),
+  };
+}
+
+/** Every post-boot show sits on the input row at the composition column (the positive contract). */
+function expectPositionedOnInputRow(result: IProbeResult): void {
+  expect(result.compositionShows.length).toBeGreaterThan(0);
+  expect(result.inputRow).toBeGreaterThanOrEqual(0);
+  for (const event of result.compositionShows) {
+    // Never the top region (the Terminal.app SIGSEGV geometry), always the input row.
+    expect(event.row).toBe(result.inputRow);
+  }
+  expect(result.compositionShows.at(-1)!.col).toBe(result.promptCol + 2 + COMPOSITION_WIDTH);
+}
+
+describe('CLI-062 — IME hardware-cursor positioning through a real PTY', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-pty-ime-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('24-row pty: every post-boot cursor show lands on the input row at the composition column', async () => {
+    const result = await probe(projectDir, 24, {}, (s) => (session = s));
+    expectPositionedOnInputRow(result);
+  }, 60_000);
+
+  it('5-row pty (frame ≥ viewport, I2): zero cursor-show sequences during composition', async () => {
+    const result = await probe(projectDir, 5, {}, (s) => (session = s));
+    expect(result.compositionShows).toEqual([]);
+  }, 60_000);
+});
+
+/**
+ * Representative terminal boundaries, re-runnable through the real binary.
+ *
+ * PROVES, per cell: the built binary's observable cursor contract under exactly the environment
+ * that terminal exports — positioned on the input row when the capability gate says yes, and no
+ * cursor shown at all when it says no (Terminal.app's default-off I5 branch, and the
+ * `PRODUCT_IME_CURSOR=0` kill switch).
+ *
+ * DOES NOT PROVE, for a `documented` row: anything about that emulator's own rendering, its
+ * pre-edit display, or its OS IME. Terminal.app's historical Korean-IME SIGSEGV in particular is
+ * an Apple-side defect that can only be re-checked on macOS; it stays off by default (I5) until
+ * someone runs the macOS cells. tmux is additionally driven as a REAL emulator in
+ * ime-cursor-tmux.ptytest.ts, where the emulator reports its own cursor position back.
+ */
+describe('CLI-062 terminal matrix — observable cursor contract per terminal', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-pty-ime-matrix-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  for (const cell of REPRESENTATIVE_IME_PTY_CELLS) {
+    const profile = TERMINAL_PROFILES.find((candidate) => candidate.id === cell.profileId);
+    if (!profile) {
+      throw new Error(`Unknown representative terminal profile: ${cell.profileId}`);
+    }
+    const { override } = cell;
+    const enabled = expectedImeCursorEnabled(profile, override);
+    const verdict = enabled ? 'positions on the input row' : 'never shows the cursor';
+
+    it(`${cellLabel(profile, override)} → ${verdict}`, async () => {
+      const env = profileEnv(profile, override);
+
+      const wide = await probe(projectDir, 24, env, (s) => (session = s));
+      if (!enabled) {
+        expect(wide.compositionShows).toEqual([]);
+        return;
+      }
+      expectPositionedOnInputRow(wide);
+      await session?.disposeAsync();
+      session = undefined;
+
+      // I2, checked wherever the gate would otherwise allow positioning: a frame that fills the
+      // viewport is never positioned into, however capable the terminal is. (For a gated-off
+      // cell the 24-row probe above already proves nothing is ever shown.)
+      const narrow = await probe(projectDir, 5, env, (s) => (session = s));
+      expect(narrow.compositionShows).toEqual([]);
+    }, 90_000);
+  }
+});

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

@@ -0,0 +1,97 @@
+/**
+ * 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 `~/state` 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 `~/state`, 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(), 'agent-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 {
+  const home = typeof overrides.HOME === 'string' ? overrides.HOME : createIsolatedHome();
+  return {
+    PATH: process.env['PATH'] ?? '',
+    HOME: home,
+    TERM: 'xterm-256color',
+    ...fixtureProductEnvironment(home),
+    ...overrides,
+  };
+}
+
+/** Product identity and state roots for the compiled CLI's isolated PTY fixtures. */
+export function fixtureProductEnvironment(home: string): Record<string, string> {
+  const id = 'fixture-agent';
+  const stateRoot = join(home, 'state');
+  return {
+    PRODUCT_ID: id,
+    PRODUCT_DISPLAY_NAME: 'Fixture Agent',
+    PRODUCT_CLI_NAME: id,
+    PRODUCT_ENV_PREFIX: 'FIXTURE_AGENT_',
+    PRODUCT_PACKAGE_SCOPE: '@fixture-agent',
+    PRODUCT_APP_ID: 'org.example.fixture-agent',
+    PRODUCT_PROTOCOL_SCHEME: id,
+    PRODUCT_TELEMETRY_SERVICE_NAME: `${id}.agent`,
+    PRODUCT_DAEMON_NAMESPACE: `${id}.daemon`,
+    PRODUCT_DESKTOP_EXECUTABLE: `${id}-runtime`,
+    PRODUCT_MCP_CLIENT_NAME: `${id}-client`,
+    PRODUCT_MODEL_TOOL_PREFIX: 'fixture_agent_command_',
+    PRODUCT_PROMPT_TAG: 'fixture_agent_references',
+    PRODUCT_EDITOR_TEMP_PREFIX: `${id}-editor-`,
+    PRODUCT_USER_STATE_DIR: stateRoot,
+    PRODUCT_PROJECT_STATE_DIR: '.fixture-agent',
+    PRODUCT_CACHE_DIR: join(stateRoot, 'cache'),
+    PRODUCT_LOG_DIR: join(stateRoot, 'logs'),
+    PRODUCT_BROWSER_NAMESPACE: `${id}.browser`,
+    PRODUCT_BROWSER_CREDENTIAL_DATABASE: `${id}-credentials`,
+    PRODUCT_CREDENTIAL_SERVICE: `org.example.${id}.credentials`,
+    PRODUCT_CRYPTO_NAMESPACE: `${id}.crypto`,
+    SECURITY_MASTER_KEY_DERIVATION_PATH: '[123,0]',
+  };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Real-PTY organization-policy engineering regression scenario (CLI-083).
+ *
+ * Drives the built Fixture Agent 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, 'state');
+  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(), 'agent-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 CLI 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(), 'agent-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,155 @@
+/**
+ * PTY TUI driver (CLI-074 TC-07/08).
+ *
+ * Built-CLI convenience over the shared `spawnPty` harness (TEST-007): spawns the built 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 { fixtureProductEnvironment } from './isolated-home.js';
+
+import type { IPtyRunSession } from './spawn-pty.js';
+
+const REPO_ROOT = resolve(__dirname, '../../../../..');
+const AGENT_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/agent.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 under the selected state root 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 under the selected state root 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', 'state');
+  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: [AGENT_BIN, ...defaultedArgs],
+    cwd: options.projectDir,
+    env: {
+      PATH: process.env['PATH'] ?? '',
+      HOME: options.homeDir,
+      TERM: 'xterm-256color',
+      ...fixtureProductEnvironment(options.homeDir),
+      // 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 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(), 'agent-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);
+});