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

package/src/__tests__/pty/flow-2006-deep-link.ptytest.ts

@@ -0,0 +1,291 @@
+/**
+ * FLOW-2006 TC-09 — the three user-execution scenarios on the BUILT binary.
+ *
+ * Scenario 1 runs in a real PTY: a link opens the trusted fixture repository with the prompt in the
+ * composer, unsent, labelled as external, and only Enter submits it. Scenarios 2 and 3 are process
+ * runs: every malformed or configuration-bearing link, and every untrusted or unrecorded target, is
+ * refused on stderr with a non-zero exit and no session.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm --filter @robota-sdk/agent-cli build` first).
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const ROBOTA_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/robota.cjs');
+const WAIT_MS = 20_000;
+const CASE_TIMEOUT_MS = 120_000;
+const PROMPT = 'Summarize the README in one sentence';
+
+interface IFixture {
+  root: string;
+  home: string;
+  trusted: string;
+  untrusted: string;
+  elsewhere: string;
+  env: NodeJS.ProcessEnv;
+}
+
+function writeProviderSettings(home: string): void {
+  const dir = join(home, '.robota');
+  mkdirSync(dir, { recursive: true });
+  // Skip the first-run welcome: it is an onboarding screen, not what this scenario observes.
+  writeFileSync(join(dir, 'onboarded'), new Date().toISOString(), 'utf8');
+  writeFileSync(
+    join(dir, 'settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'pty-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+}
+
+function initRepo(path: string, env: NodeJS.ProcessEnv): void {
+  mkdirSync(path, { recursive: true });
+  const run = (...args: string[]): void => {
+    execFileSync('git', args, { cwd: path, env, stdio: ['ignore', 'ignore', 'pipe'] });
+  };
+  run('init', '-q', '-b', 'main');
+  run('config', 'user.name', 'Robota Scenario');
+  run('config', 'user.email', 'scenario@example.invalid');
+  writeFileSync(join(path, 'README.md'), 'fixture\n');
+  run('add', '--', 'README.md');
+  run('commit', '-q', '-m', 'chore: fixture');
+}
+
+function makeFixture(): IFixture {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'robota-flow2006-')));
+  const home = join(root, 'home');
+  mkdirSync(home, { recursive: true });
+  writeProviderSettings(home);
+  const env: NodeJS.ProcessEnv = {
+    PATH: process.env['PATH'] ?? '',
+    HOME: home,
+    TERM: 'xterm-256color',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: join(home, 'gitconfig'),
+  };
+  writeFileSync(join(home, 'gitconfig'), '[commit]\n\tgpgsign = false\n');
+  const fixture: IFixture = {
+    root,
+    home,
+    trusted: join(root, 'trusted'),
+    untrusted: join(root, 'untrusted'),
+    elsewhere: join(root, 'elsewhere'),
+    env,
+  };
+  initRepo(fixture.trusted, env);
+  initRepo(fixture.untrusted, env);
+  mkdirSync(fixture.elsewhere, { recursive: true });
+  // Grant trust to the one repository a link is allowed to open.
+  const granted = spawnSync(process.execPath, [ROBOTA_BIN, 'trust', '--yes'], {
+    cwd: fixture.trusted,
+    env,
+    encoding: 'utf8',
+  });
+  if (granted.status !== 0) throw new Error(`trust --yes failed: ${granted.stderr}`);
+  return fixture;
+}
+
+function link(fixture: IFixture, extra = ''): string {
+  return `robota://open?v=1&prompt=${encodeURIComponent(PROMPT)}&cwd=${fixture.trusted}${extra}`;
+}
+
+/** Run `robota open <url>` as a process, headless — used for the refusal scenarios. */
+function openHeadless(
+  fixture: IFixture,
+  url: string,
+  cwd = fixture.elsewhere,
+): ReturnType<typeof spawnSync> {
+  return spawnSync(process.execPath, [ROBOTA_BIN, 'open', url], {
+    cwd,
+    env: { ...fixture.env, TERM: 'dumb' },
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+}
+
+/**
+ * What an interactive session leaves behind under HOME: one `peers/*.peer.json` per run. A refusal
+ * that started no session leaves this listing untouched, which is how the refusal scenarios prove
+ * "no session was started" without watching the process.
+ */
+function sessionRecords(home: string): readonly string[] {
+  try {
+    return readdirSync(join(home, '.robota', 'peers')).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** The trust store's bytes — a refused link must not add, remove or touch a grant. */
+function trustStoreDigest(home: string): string {
+  return createHash('sha256')
+    .update(readFileSync(join(home, '.robota', 'workspace-trust.json')))
+    .digest('hex');
+}
+
+/**
+ * Every malformed or configuration-bearing link, each paired with the word its refusal must name —
+ * the FIRST rule it breaks, so a refusal that merely says the link is invalid fails the case.
+ */
+function malformedLinks(fixture: IFixture): readonly (readonly [string, string])[] {
+  return [
+    [link(fixture, '&provider=anthropic'), 'provider'],
+    [link(fixture, `&prompt=${encodeURIComponent('second')}`), 'more than once'],
+    [`robota://open?prompt=hi&cwd=${fixture.trusted}`, 'no `v`'],
+    [`robota://open?v=2&prompt=hi&cwd=${fixture.trusted}`, 'version 1'],
+    [
+      `robota://open?v=1&prompt=${encodeURIComponent('/mode bypassPermissions')}&cwd=${fixture.trusted}`,
+      'not a command',
+    ],
+    ['robota://open?v=1&prompt=hi&cwd=relative/path', 'absolute'],
+    [`robota://open?v=1&prompt=hi&cwd=${fixture.trusted}/../untrusted`, '`..`'],
+    [`robota://open?v=1&prompt=hi&cwd=${join(fixture.root, 'absent')}`, 'does not exist'],
+  ];
+}
+
+describe('robota open through the real binary (FLOW-2006 TC-09)', () => {
+  let fixture: IFixture | undefined;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    fixture = makeFixture();
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    if (fixture) rmSync(fixture.root, { recursive: true, force: true });
+    fixture = undefined;
+  });
+
+  it(
+    'Scenario 1: the link opens the trusted repository with the prompt prefilled, inert and labelled',
+    async () => {
+      const current = fixture;
+      if (!current) throw new Error('fixture');
+      session = spawnTui({
+        projectDir: current.elsewhere,
+        homeDir: current.home,
+        args: ['open', link(current), '--name', 'flow2006'],
+      });
+
+      // The PREFILLED TEXT is the arrival signal, not the empty-composer placeholder (which never
+      // renders once there is text) and not `Idle` or the notice — both of those are already on the
+      // screen one frame before the composer itself is drawn.
+      await session.waitFor(new RegExp(PROMPT), WAIT_MS);
+      await session.waitFor(/Idle/, WAIT_MS);
+      const first = session.snapshot();
+      // The prompt is in the composer, the provenance is visible, and nothing was sent.
+      expect(first).toContain(PROMPT);
+      expect(first).toContain('Prompt from an external link');
+      expect(first).not.toMatch(/Thinking|Interrupting/);
+      // The link changed the directory: the status line names the fixture repository's branch.
+      expect(first).toContain('git: main');
+
+      // Enter submits exactly that text: it leaves the composer and becomes the user message.
+      const since = session.outputOffset();
+      await session.pressEnter();
+      await session.waitForSince(since, new RegExp(PROMPT), WAIT_MS);
+
+      const run = spawnSync('git', ['log', '--oneline'], {
+        cwd: current.trusted,
+        env: current.env,
+        encoding: 'utf8',
+      });
+      expect(run.stdout.trim().split('\n')).toHaveLength(1);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'Scenario 2: every malformed or configuration-bearing link is refused with no session',
+    () => {
+      const current = fixture;
+      if (!current) throw new Error('fixture');
+      const recordsBefore = sessionRecords(current.home);
+      const settingsBefore = readFileSync(join(current.home, '.robota', 'settings.json'), 'utf8');
+      const cases = malformedLinks(current);
+      for (const [url, expected] of cases) {
+        const result = openHeadless(current, url);
+        expect(result.status, url).toBe(1);
+        expect(`${result.stderr}`, url).toContain(expected);
+        expect(`${result.stdout}`, url).not.toContain('Type a message');
+      }
+      // A SECOND LINK after the first is refused — the argv-appending shape the platforms document.
+      const twoArgs = spawnSync(
+        process.execPath,
+        [ROBOTA_BIN, 'open', link(current), link(current)],
+        {
+          cwd: current.elsewhere,
+          env: { ...current.env, TERM: 'dumb' },
+          encoding: 'utf8',
+        },
+      );
+      expect(twoArgs.status).toBe(1);
+      expect(`${twoArgs.stderr}`).toContain('exactly one link');
+
+      // Nothing was started and nothing was configured: no session record appeared, and the
+      // settings the `/mode bypassPermissions` link tried to reach are byte-identical.
+      expect(sessionRecords(current.home)).toEqual(recordsBefore);
+      expect(readFileSync(join(current.home, '.robota', 'settings.json'), 'utf8')).toBe(
+        settingsBefore,
+      );
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'Scenario 3: an untrusted directory and an unrecorded slug are refused, and nothing is cloned',
+    () => {
+      const current = fixture;
+      if (!current) throw new Error('fixture');
+      const digestBefore = trustStoreDigest(current.home);
+      const untrusted = openHeadless(
+        current,
+        `robota://open?v=1&prompt=hi&cwd=${current.untrusted}`,
+      );
+      expect(untrusted.status).toBe(1);
+      expect(`${untrusted.stderr}`).toContain('robota trust --yes');
+
+      const slug = openHeadless(current, 'robota://open?v=1&prompt=hi&repo=nobody/not-a-clone');
+      expect(slug.status).toBe(1);
+      expect(`${slug.stderr}`).toContain('nobody/not-a-clone');
+      expect(`${slug.stderr}`).not.toContain('cloning');
+
+      // A refused link grants nothing and records nothing: the untrusted repository is still
+      // untrusted and the store is byte-identical to what it was before the two invocations.
+      const status = spawnSync(process.execPath, [ROBOTA_BIN, 'trust', 'status'], {
+        cwd: current.untrusted,
+        env: current.env,
+        encoding: 'utf8',
+      });
+      expect(`${status.stdout}`).toContain('untrusted');
+      expect(trustStoreDigest(current.home)).toBe(digestBefore);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

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

@@ -0,0 +1,165 @@
+/**
+ * CLI-062 — the one matrix cell where a REAL terminal emulator answers back.
+ *
+ * Every other cell reads the cursor out of the byte stream our own VT interpreter replays. tmux is
+ * a full, independent terminal emulator that can be driven headlessly AND queried: it runs the
+ * built robota binary in a real pane, receives the Korean keystrokes through its own input path,
+ * and then reports where ITS state machine put the hardware cursor
+ * (`#{cursor_x}` / `#{cursor_y}` / `#{cursor_flag}`). That makes this the strongest available
+ * confirmation short of macOS hardware: a second implementation agrees the cursor sits on the
+ * input row at the composition column — which is the cell an OS IME anchors its window to.
+ *
+ * Skipped when tmux is not installed; `ROBOTA_TMUX_BIN` overrides the binary. GitHub's ubuntu
+ * runner images ship tmux, so this runs in CI rather than quietly evaporating there.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const REPO_ROOT = resolve(__dirname, '../../../../..');
+const ROBOTA_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/robota.cjs');
+const COLS = 80;
+const COMPOSITION = '안녕';
+const COMPOSITION_WIDTH = 4;
+
+function resolveTmux(): string | undefined {
+  const override = process.env['ROBOTA_TMUX_BIN'];
+  if (override !== undefined && override !== '') return override;
+  const which = spawnSync('sh', ['-c', 'command -v tmux'], { encoding: 'utf8' });
+  const found = which.stdout.trim();
+  return found === '' ? undefined : found;
+}
+
+const TMUX = resolveTmux();
+
+interface ITmuxProbe {
+  cursorX: number;
+  cursorY: number;
+  /** tmux's own DECTCEM view: is the hardware cursor visible in the pane? */
+  cursorVisible: boolean;
+  pane: string[];
+}
+
+interface ITmuxRun {
+  root: string;
+  socket: string;
+}
+
+/** Run robota inside a real tmux pane and ask tmux where the cursor ended up. */
+function runInTmux(run: ITmuxRun, rows: number, imeCursor: string | undefined): ITmuxProbe {
+  const tmux = TMUX!;
+  const projectDir = join(run.root, 'proj');
+  const homeDir = join(run.root, 'home');
+  mkdirSync(join(homeDir, '.robota'), { recursive: true });
+  writeFileSync(
+    join(homeDir, '.robota/settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'tmux-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+
+  // A wrapper keeps the pane's env explicit (never inheriting real provider keys) while letting
+  // tmux itself set TERM/TERM_PROGRAM for the pane — the handshake under test.
+  const wrapper = join(run.root, 'wrap.sh');
+  const imeAssignment = imeCursor === undefined ? '' : `ROBOTA_IME_CURSOR=${imeCursor} `;
+  writeFileSync(
+    wrapper,
+    [
+      '#!/bin/sh',
+      `cd "${projectDir}"`,
+      `exec env -i PATH="$PATH" HOME="${homeDir}" TERM="$TERM" TERM_PROGRAM="$TERM_PROGRAM" ${imeAssignment}` +
+        `"${process.execPath}" "${ROBOTA_BIN}" --name tmux-fixture`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(wrapper, 0o755);
+
+  const tmuxCall = (...args: string[]): string =>
+    execFileSync(tmux, ['-S', run.socket, ...args], { encoding: 'utf8' });
+
+  tmuxCall('new-session', '-d', '-x', String(COLS), '-y', String(rows), wrapper);
+
+  const deadline = Date.now() + 40_000;
+  let pane = '';
+  while (Date.now() < deadline) {
+    pane = tmuxCall('capture-pane', '-p');
+    if (pane.includes('Type a message')) break;
+    sleepSync(250);
+  }
+  expect(pane, 'robota never reached the prompt inside tmux').toContain('Type a message');
+  sleepSync(400);
+
+  tmuxCall('send-keys', '-l', COMPOSITION);
+  sleepSync(1500);
+
+  const [x = '', y = '', flag = ''] = tmuxCall(
+    'display-message',
+    '-p',
+    '#{cursor_x} #{cursor_y} #{cursor_flag}',
+  )
+    .trim()
+    .split(' ');
+  return {
+    cursorX: Number.parseInt(x, 10),
+    cursorY: Number.parseInt(y, 10),
+    cursorVisible: flag === '1',
+    pane: tmuxCall('capture-pane', '-p').split('\n'),
+  };
+}
+
+/** Deliberate synchronous wait: tmux is driven through blocking CLI calls, not an event loop. */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+describe.skipIf(TMUX === undefined)(
+  'CLI-062 terminal matrix — tmux, a real emulator reporting its own cursor',
+  () => {
+    let run: ITmuxRun;
+
+    beforeEach(() => {
+      const root = realpathSync(mkdtempSync(join(tmpdir(), 'robota-tmux-ime-')));
+      run = { root, socket: join(root, 'sock') };
+    });
+
+    afterEach(() => {
+      if (TMUX !== undefined) {
+        spawnSync(TMUX, ['-S', run.socket, 'kill-server'], { stdio: 'ignore' });
+      }
+      rmSync(run.root, { recursive: true, force: true });
+    });
+
+    it('24-row pane: tmux reports the cursor VISIBLE on the input row at the composition column', () => {
+      const probe = runInTmux(run, 24, undefined);
+      const inputRow = probe.pane.findIndex((line) => line.includes(`> ${COMPOSITION}`));
+      expect(inputRow, `no input row in pane:\n${probe.pane.join('\n')}`).toBeGreaterThanOrEqual(0);
+
+      expect(probe.cursorVisible).toBe(true);
+      expect(probe.cursorY).toBe(inputRow);
+      expect(probe.cursorX).toBe(probe.pane[inputRow]!.indexOf('> ') + 2 + COMPOSITION_WIDTH);
+    }, 90_000);
+
+    it('5-row pane (frame ≥ viewport, I2): tmux reports the cursor hidden, never positioned', () => {
+      const probe = runInTmux(run, 5, undefined);
+      expect(probe.pane.some((line) => line.includes(`> ${COMPOSITION}`))).toBe(true);
+      expect(probe.cursorVisible).toBe(false);
+    }, 90_000);
+
+    it('ROBOTA_IME_CURSOR=0 kill switch: tmux reports the cursor hidden even at 24 rows', () => {
+      const probe = runInTmux(run, 24, '0');
+      const inputRow = probe.pane.findIndex((line) => line.includes(`> ${COMPOSITION}`));
+      expect(inputRow).toBeGreaterThanOrEqual(0);
+      expect(probe.cursorVisible).toBe(false);
+      expect(probe.cursorY).not.toBe(inputRow);
+    }, 90_000);
+  },
+);

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

@@ -0,0 +1,186 @@
+/**
+ * CLI-062 — PTY regression for real-terminal-cursor positioning (the OS-IME evidence).
+ *
+ * Runs the BUILT robota 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 { 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 = '안녕';
+/** `안녕` 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 `> 안녕`, 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(), 'robota-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
+ * `ROBOTA_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(), 'robota-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);
+  }
+});