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

package/src/__tests__/pty/screen-2670-prepark.ptytest.ts

@@ -0,0 +1,228 @@
+/**
+ * SCREEN-2670 TC-09 — the pre-write park on the BUILT robota binary, in a real PTY.
+ *
+ * A screen reader sees bytes and time, nothing else, so the claim is checked where both exist: the
+ * raw PTY stream is sampled every few milliseconds and each growth is stamped. A COMMIT the park
+ * released arrives as one growth (its chunks are written contiguously); the interval shows up as
+ * the gap between consecutive printable growths. The same fixture runs three ways — park 250 ms,
+ * park 0, mode off — so the interval is attributed to the park and not to the replay.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm build` first).
+ */
+
+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 FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const REPLAY_FIXTURE = join(FIXTURES, 'replay-conversation.jsonl');
+
+const WAIT_MS = 30_000;
+const CASE_TIMEOUT_MS = 120_000;
+/** The park under test — large against the frame cadence, small against the case budget. */
+const PARK_MS = 250;
+/** Sampling period; the gap resolution is twice this. */
+const SAMPLE_MS = 5;
+/** OS and PTY jitter allowance on the asserted interval. */
+const SLACK_MS = 60;
+/** Growths closer than this are one burst: a PTY read can split one contiguous write. */
+const COALESCE_MS = 30;
+
+/** Startup frames settle for this long before the keystroke is measured against a quiet stream. */
+const STARTUP_SETTLE_MS = 750;
+/* eslint-disable no-control-regex -- matching the escapes IS the point here */
+const OSC_133 = /\x1b\]133;[ABCD]\x07/g;
+const ESCAPES = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[()][A-Z0-9]|\x1b[=>]/g;
+/* eslint-enable no-control-regex */
+
+interface IGrowth {
+  at: number;
+  bytes: string;
+}
+
+/**
+ * Sample the raw stream from `since` (an offset taken BEFORE the action — the driver's key pacing
+ * means output can land before this loop starts) until `until` matches or the budget ends; return
+ * every growth stamped.
+ */
+interface IMark {
+  /** Index into the RAW stream (growth detection). */
+  raw: number;
+  /** The driver's mark into the STRIPPED transcript (pattern matching) — the two are not the same. */
+  stripped: number;
+}
+
+function markNow(session: IPtySession): IMark {
+  return { raw: session.raw().length, stripped: session.outputOffset() };
+}
+
+async function sampleUntil(
+  session: IPtySession,
+  since: IMark,
+  until: RegExp,
+  budgetMs: number,
+): Promise<IGrowth[]> {
+  const growths: IGrowth[] = [];
+  let seen = since.raw;
+  const deadline = Date.now() + budgetMs;
+  while (Date.now() < deadline) {
+    const raw = session.raw();
+    if (raw.length > seen) {
+      growths.push({ at: Date.now(), bytes: raw.slice(seen) });
+      seen = raw.length;
+    }
+    if (until.test(session.snapshotSince(since.stripped))) break;
+    await new Promise((resolve) => setTimeout(resolve, SAMPLE_MS));
+  }
+  return growths;
+}
+
+const visible = (bytes: string): string => bytes.replace(ESCAPES, '');
+
+/** Merge growths that landed within `COALESCE_MS` of each other — one contiguous write, one burst. */
+function bursts(growths: IGrowth[]): IGrowth[] {
+  const merged: IGrowth[] = [];
+  for (const growth of growths) {
+    const last = merged.at(-1);
+    if (last !== undefined && growth.at - last.at < COALESCE_MS) last.bytes += growth.bytes;
+    else merged.push({ ...growth });
+  }
+  return merged;
+}
+
+/**
+ * The marks travel through the owned path and keep their place. A replayed reply resolves inside
+ * one commit, so the turn's own B/C/D/A marks are not observable here (their ordering against a
+ * parked batch is pinned by the unit test); what this stream does carry is the mount-time
+ * prompt-start, which must precede the answer rather than surface inside the parked gap after it.
+ */
+function expectMarksOrderedWithTheTurn(raw: string): void {
+  const marks = [...raw.matchAll(OSC_133)].map((match) => ({
+    code: match[0],
+    at: match.index ?? 0,
+  }));
+  const answerAt = raw.indexOf('REPLAYED_ANSWER_42');
+  const promptStarts = marks.filter((mark) => mark.code.includes('133;A'));
+  expect(promptStarts.length).toBeGreaterThanOrEqual(1);
+  expect(promptStarts[0]?.at).toBeLessThan(answerAt);
+}
+
+/**
+ * One paced-free line: the echo commit (exempt) and the turn commit (parked) are provoked within
+ * milliseconds of each other, so the interval between them is the park and nothing else. The reply
+ * itself is replayed as a single chunk, so the turn is ONE commit — which is also what proves the
+ * chunks of a commit stay contiguous: the answer arrives inside one synchronized-output window.
+ */
+interface ITurnTiming {
+  typedAt: number;
+  echoAt: number;
+  answerAt: number;
+  answerBytes: string;
+}
+
+async function typeAndSubmit(session: IPtySession): Promise<ITurnTiming> {
+  const mark = markNow(session);
+  const sampling = sampleUntil(session, mark, /REPLAYED_ANSWER_42[\s\S]*Type a message/, WAIT_MS);
+  // Characters are paced (a single chunk would be read as a paste); the echo latency is measured
+  // from the LAST key, so the driver's per-key pacing is not charged to the park. Enter follows the
+  // last echo immediately, so the turn's commit is provoked within milliseconds of an exempt one.
+  await session.sendKeys('hell');
+  const typedAt = Date.now();
+  await session.sendKeys('o');
+  session.writeRaw('\r');
+  const growths = bursts(await sampling);
+  const echo = growths.find((g) => visible(g.bytes).includes('hello'));
+  const answer = growths.find((g) => visible(g.bytes).includes('REPLAYED_ANSWER_42'));
+  expect(echo, 'the echo of the typed line').toBeDefined();
+  expect(answer, 'the replayed answer').toBeDefined();
+  return {
+    typedAt,
+    echoAt: (echo as IGrowth).at,
+    answerAt: (answer as IGrowth).at,
+    answerBytes: (answer as IGrowth).bytes,
+  };
+}
+
+function spawnScenario(projectDir: string, mode: 'park' | 'zero' | 'off'): IPtySession {
+  const screenReader = mode === 'off' ? [] : ['--screen-reader'];
+  const prepark = mode === 'zero' ? '0' : String(PARK_MS);
+  return spawnTui({
+    projectDir,
+    homeDir: join(projectDir, 'home'),
+    args: ['--session-log', REPLAY_FIXTURE, ...screenReader, '--name', 'prepark-scenario'],
+    env: { ROBOTA_SCREEN_READER_STARTUP_QUIET_MS: '0', ROBOTA_SCREEN_READER_PREPARK_MS: prepark },
+  });
+}
+
+async function settled(session: IPtySession): Promise<void> {
+  await session.waitFor(/Type a message or \/help/, WAIT_MS);
+  await new Promise((resolve) => setTimeout(resolve, STARTUP_SETTLE_MS));
+}
+
+describe('SCREEN-2670 the pre-write park through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-prepark-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-09: the echo is not delayed, the turn commit waits the interval after it, its chunks are contiguous, and the marks stay in order',
+    async () => {
+      session = spawnScenario(projectDir, 'park');
+      await settled(session);
+
+      const timing = await typeAndSubmit(session);
+      // The keystroke's commit is exempt: its echo lands well inside the interval.
+      expect(timing.echoAt - timing.typedAt).toBeLessThan(PARK_MS - SLACK_MS);
+      // The turn's commit is parked: at least the interval after the previous printable release.
+      // Assumption: with a single-chunk replay the answer commit is the LAST printable commit of the
+      // turn's burst; only the last waiting batch is parked, so a later commit inside the interval
+      // would make this measure turn latency instead.
+      expect(timing.answerAt - timing.echoAt).toBeGreaterThanOrEqual(PARK_MS - SLACK_MS);
+      // And it arrived whole: the synchronized-output window opened and closed in one growth.
+      expect(timing.answerBytes).toContain('\x1b[?2026h');
+      expect(timing.answerBytes).toContain('\x1b[?2026l');
+      expectMarksOrderedWithTheTurn(session.raw());
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'TC-09: with the interval 0 no delay is injected',
+    async () => {
+      session = spawnScenario(projectDir, 'zero');
+      await settled(session);
+      const timing = await typeAndSubmit(session);
+      expect(timing.answerAt - timing.echoAt).toBeLessThan(PARK_MS - SLACK_MS);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'TC-09: with the mode off the park is absent — no interval, bordered UI as before',
+    async () => {
+      session = spawnScenario(projectDir, 'off');
+      await settled(session);
+      const timing = await typeAndSubmit(session);
+      expect(timing.answerAt - timing.echoAt).toBeLessThan(PARK_MS - SLACK_MS);
+      expect(session.snapshot()).toMatch(/[│─╭╮╰╯┌┐└┘]/u);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/screen-reader-mode.ptytest.ts

@@ -0,0 +1,228 @@
+/**
+ * CLI-2004 TC-11 / TC-12 — screen-reader mode on the BUILT robota binary, in a real PTY.
+ *
+ * This is the only level at which the claim can be checked. A screen reader has no `aria-live`: the
+ * ONLY channel to it is which bytes land in the terminal buffer, so a component test asserting on a
+ * frame is asserting on something the reader never sees. Here the transcript is the evidence.
+ *
+ * TC-11 pairs the positive with the DEFAULT-OFF proof deliberately: the same fixture, the same
+ * binary, one flag apart. Without the negative half, "no box-drawing characters" would also pass if
+ * the fixture happened to render none.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm build` first).
+ */
+
+import { mkdtempSync, rmSync, realpathSync, writeFileSync } 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 FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const REPLAY_FIXTURE = join(FIXTURES, 'replay-conversation.jsonl');
+
+/** Every box-drawing glyph the TUI draws chrome with, in one class. */
+const BOX_DRAWING = /[│─╭╮╰╯┌┐└┘]/u;
+
+/** OSC 133 prompt-start — the mark a terminal turns into jump-to-previous-turn. */
+const OSC_133_PROMPT_START = '\x1b]133;A';
+
+/** How long one `waitFor` may block, and how long a whole case may take, on a loaded CI runner. */
+const WAIT_MS = 30_000;
+const CASE_TIMEOUT_MS = 90_000;
+
+/**
+ * Mark the isolated HOME as already onboarded. TC-12 asserts on the FIRST line the process writes,
+ * and the first-run welcome is a separate concern with its own onboarding copy — a returning user
+ * is the case where "the first line confirms the mode" is the claim being made.
+ */
+function markOnboarded(homeDir: string): void {
+  writeFileSync(join(homeDir, '.robota', 'onboarded'), new Date().toISOString());
+}
+
+describe('CLI-2004 screen-reader mode through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-screenreader-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-11: --screen-reader emits no box-drawing chrome, role labels, and OSC 133 marks',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        args: ['--session-log', REPLAY_FIXTURE, '--screen-reader'],
+        // The waits are exercised by their own unit test; a real one here only slows the fixture.
+        env: { ROBOTA_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+      await session.sendKeys('hello');
+      await session.pressEnter();
+      await session.waitFor(/REPLAYED_ANSWER_42/, WAIT_MS);
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+
+      const snapshot = session.snapshot();
+      const raw = session.raw();
+
+      // The transcript is labelled by ROLE, not by vendor.
+      expect(snapshot).toContain('assistant:');
+      expect(snapshot).toContain('you:');
+      expect(snapshot).toContain('REPLAYED_ANSWER_42');
+
+      // Not one box-drawing character reaches the terminal.
+      expect(snapshot).not.toMatch(BOX_DRAWING);
+
+      // The turn boundary is marked for terminals that navigate by it.
+      expect(raw).toContain(OSC_133_PROMPT_START);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});
+
+describe('CLI-2004 the same fixture with the mode off', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-screenreader-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-11: the SAME fixture without the flag still renders the bordered UI (default-off)',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        args: ['--session-log', REPLAY_FIXTURE],
+        env: { ROBOTA_TURN_MARKS: '1' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+      await session.sendKeys('hello');
+      await session.pressEnter();
+      await session.waitFor(/REPLAYED_ANSWER_42/, WAIT_MS);
+
+      const snapshot = session.snapshot();
+
+      expect(snapshot).toMatch(BOX_DRAWING);
+      expect(snapshot).toContain('You:');
+      expect(snapshot).not.toContain('[Screen reader mode:');
+      expect(session.raw()).not.toContain(OSC_133_PROMPT_START);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});
+
+describe('Robota turn-mark override through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-turn-marks-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  for (const [label, env, expected] of [
+    ['WezTerm default', { TERM_PROGRAM: 'WezTerm' }, false],
+    ['WezTerm opt-in', { TERM_PROGRAM: 'WezTerm', ROBOTA_TURN_MARKS: '1' }, true],
+    ['TTY kill switch', { ROBOTA_TURN_MARKS: '0' }, false],
+  ] as const) {
+    it(
+      `${label} ${expected ? 'emits' : 'withholds'} OSC 133`,
+      async () => {
+        session = spawnTui({
+          projectDir,
+          homeDir: join(projectDir, 'home'),
+          args: ['--screen-reader'],
+          env: { ...env, ROBOTA_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+        });
+        await session.waitFor(/Type a message or \/help/, WAIT_MS);
+        expect(session.raw().includes(OSC_133_PROMPT_START)).toBe(expected);
+      },
+      CASE_TIMEOUT_MS,
+    );
+  }
+});
+
+describe('CLI-2004 the channel the mode was enabled through', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-screenreader-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-12: ROBOTA_SCREEN_READER=1 with no flag announces the env channel first',
+    async () => {
+      markOnboarded(join(projectDir, 'home'));
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        env: { ROBOTA_SCREEN_READER: '1', ROBOTA_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+
+      expect(session.snapshot().trimStart().startsWith('[Screen reader mode: on via env]')).toBe(
+        true,
+      );
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'TC-12: --screen-reader beats ROBOTA_SCREEN_READER=0 and says so',
+    async () => {
+      markOnboarded(join(projectDir, 'home'));
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        args: ['--screen-reader'],
+        env: { ROBOTA_SCREEN_READER: '0', ROBOTA_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+
+      expect(session.snapshot().trimStart().startsWith('[Screen reader mode: on via flag]')).toBe(
+        true,
+      );
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/settings-screen.ptytest.ts

@@ -0,0 +1,49 @@
+/**
+ * CMD-004 Phase 2 Stage C (TC-04): `/settings` still opens the settings screen — now rendered from
+ * the requester-routed `ui_intent` session event (the legacy `settings-tui-requested` effect
+ * branch is deleted from the TUI). Observed through a real PTY against the BUILT robota binary
+ * (`pnpm --filter @robota-sdk/agent-cli build`).
+ */
+
+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('/settings opens the settings screen via ui_intent (CMD-004 Stage C)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-settings-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('renders the transports settings screen and Esc returns to the prompt', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('/settings');
+    await session.pressEnter();
+
+    // The settings screen opened — from the ui_intent event, not a legacy effect branch.
+    await session.waitFor(/Settings › Transports/, 20_000);
+    expect(session.snapshot()).toContain('Settings › Transports');
+
+    // Esc closes the screen and returns to the idle prompt.
+    const mark = session.outputOffset();
+    session.pressEscape();
+    await session.waitForSince(mark, /Type a message or \/help/, 20_000);
+  }, 60_000);
+});

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

@@ -0,0 +1,120 @@
+/**
+ * TEST-007: self-test for the TUI-owned PTY harness (relocated internally by BOUNDARY-2655).
+ *
+ * Drives a trivial process (no fixture needed) through `spawnPty` to pin the harness contract:
+ * `waitFor` resolves on a printed marker, `expectExit` returns the real exit code, and
+ * `snapshot()`/`raw()` capture output. The terminal-handoff suites (in agent-ui-terminal) are the
+ * harness's real-world consumers; this guards the harness itself.
+ *
+ * HARNESS-025 adds the HOME-isolation contract: a PTY child must never receive the developer's real
+ * `HOME`, or the suite silently depends on whatever is in that home directory.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createIsolatedHome, createPtyEnv } from './isolated-home.js';
+import { spawnPty } from './spawn-pty.js';
+
+import type { IPtyRunSession } from './spawn-pty.js';
+
+const PACKAGE_DIR = fileURLToPath(new URL('../../..', import.meta.url));
+const sessions: IPtyRunSession[] = [];
+
+afterEach(() => {
+  for (const session of sessions.splice(0)) session.dispose();
+});
+
+describe('spawnPty harness self-test', () => {
+  it('waits for a marker and reports the real exit code', async () => {
+    const session = spawnPty({
+      command: process.execPath,
+      args: ['-e', 'process.stdout.write("MARKER_OK\\n"); setTimeout(() => process.exit(3), 50);'],
+      cwd: PACKAGE_DIR,
+      env: createPtyEnv(),
+    });
+    sessions.push(session);
+
+    await session.waitFor('MARKER_OK', 5_000);
+    expect(session.snapshot()).toContain('MARKER_OK');
+    expect(await session.expectExit(5_000)).toBe(3);
+  });
+
+  it('paces sent keys and reads them back from the child', async () => {
+    const session = spawnPty({
+      command: 'sh',
+      args: ['-c', 'IFS= read -r line; printf "ECHO:[%s]\\n" "$line"'],
+      cwd: PACKAGE_DIR,
+      env: createPtyEnv(),
+    });
+    sessions.push(session);
+
+    await session.sendKeys('abc', 10);
+    session.write('\r');
+    await session.waitFor('ECHO:[abc]', 5_000);
+    expect(await session.expectExit(5_000)).toBe(0);
+  });
+});
+
+describe('PTY HOME isolation', () => {
+  /** Ask the child to report the HOME it actually sees, so the assertion is on the child's view. */
+  function spawnHomeReporter(env?: NodeJS.ProcessEnv): IPtyRunSession {
+    const session = spawnPty({
+      command: 'sh',
+      args: ['-c', 'printf "CHILD_HOME:[%s]\\n" "$HOME"'],
+      cwd: PACKAGE_DIR,
+      ...(env ? { env } : {}),
+    });
+    sessions.push(session);
+    return session;
+  }
+
+  function readReportedHome(snapshot: string): string {
+    const match = /CHILD_HOME:\[([^\]]*)\]/.exec(snapshot);
+    if (match?.[1] === undefined) throw new Error(`child never reported HOME:\n${snapshot}`);
+    return match[1];
+  }
+
+  it('does not hand the real HOME to a child when no env is supplied', async () => {
+    const realHome = process.env['HOME'];
+    expect(
+      realHome,
+      'the test host must have a HOME for this assertion to mean anything',
+    ).toBeTruthy();
+
+    const session = spawnHomeReporter();
+    await session.waitFor('CHILD_HOME:[', 5_000);
+    await session.expectExit(5_000);
+
+    const childHome = readReportedHome(session.snapshot());
+    expect(childHome).not.toBe(realHome);
+    expect(childHome.startsWith(tmpdir())).toBe(true);
+  });
+
+  it('hands the child the isolated HOME built by createPtyEnv', async () => {
+    const env = createPtyEnv();
+    const session = spawnHomeReporter(env);
+    await session.waitFor('CHILD_HOME:[', 5_000);
+    await session.expectExit(5_000);
+
+    expect(readReportedHome(session.snapshot())).toBe(env['HOME']);
+    expect(env['HOME']).not.toBe(process.env['HOME']);
+  });
+
+  it('creates an EMPTY home directory, so no user config can leak in', () => {
+    const home = createIsolatedHome();
+    expect(existsSync(home)).toBe(true);
+    expect(readdirSync(home)).toEqual([]);
+    expect(home).not.toBe(process.env['HOME']);
+  });
+
+  it('lets an override customize the env without reintroducing the real HOME', () => {
+    const env = createPtyEnv({ EDITOR: 'sh /tmp/fake-editor.sh' });
+    expect(env['EDITOR']).toBe('sh /tmp/fake-editor.sh');
+    expect(env['TERM']).toBe('xterm-256color');
+    expect(env['PATH']).toBe(process.env['PATH']);
+    expect(env['HOME']).not.toBe(process.env['HOME']);
+  });
+});