@specific.dev/spectest 0.4.0

package/src/terminal.ts

@@ -0,0 +1,740 @@
+// Interactive terminal handle for tests. Backed by `docker exec -it`
+// inside a `script(1)` PTY wrapper so the container program sees a real
+// TTY (line discipline, ANSI escapes, isatty(1) true) while the daemon
+// drives stdin/stdout through ordinary pipes.
+//
+// We feed every byte the PTY emits into two sinks:
+//   1. A headless `@xterm/headless` Terminal that maintains the rendered
+//      screen state (cursor, scrollback, alt-screen, attributes). This is
+//      what `waitFor`'s predicate evaluates against (and what the
+//      internal `rawScreen()` returns) — the analogue of evaluating
+//      against the DOM in a Browser session.
+//   2. The asciicast frame callback the daemon hooks up to a
+//      TerminalSessionRecord. Same recording format as before; the web
+//      UI replays it with asciinema-player.
+//
+// The one-shot `ctx.terminal(service, command, opts?)` API in `index.ts`
+// is built on top of this factory — it opens a Terminal, doesn't write
+// to stdin, waits for the process to exit, and closes. So everything
+// that flows through `ctx.terminal` flows through this code too.
+//
+// PTY-on-the-host trick: the daemon runs under systemd with no controlling
+// TTY, so `docker exec -it` (the docker CLI rejects -it when its own stdin
+// isn't a TTY) needs a PTY wrapper. `script -qfc 'CMD' /dev/null` allocates
+// a PTY for CMD; we set the slave's size with `stty rows R cols C` inside
+// the wrapped command so the container app sees the cols/rows the caller
+// asked for. `script(1)` ships in util-linux which is essential on Debian,
+// so it's present in the Freestyle base image without extra apt deps.
+
+import { Terminal as XtermHeadless } from "@xterm/headless";
+
+import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
+import type { EventReservation } from "./recorder.js";
+import type { TerminalStepAction } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+export interface TerminalOpts {
+  /** PTY column count. Defaults to 80. */
+  cols?: number;
+  /** PTY row count. Defaults to 24. */
+  rows?: number;
+  /** Extra env vars; merged onto the container's. `TERM` defaults to
+   * `xterm-256color`. */
+  env?: Record<string, string>;
+  /**
+   * Command to run inside the container. When omitted, opens an
+   * interactive login shell (`sh -l`) — what you want for the typical
+   * "send commands, inspect output" interactive flow.
+   *
+   * When set, the command is the entrypoint and the session ends when
+   * it exits. This is what the one-shot `ctx.terminal(...)` wrapper
+   * passes through.
+   */
+  command?: string;
+  /**
+   * Hard timeout for the whole session in ms. When the session is
+   * interactive (no `command`), this defaults to undefined (no timeout)
+   * and the daemon's test-level timeout is what trips. For one-shot
+   * runs, the wrapper supplies the test's default timeout.
+   */
+  timeoutMs?: number;
+}
+
+/** Result of the one-shot `ctx.terminal(...)` convenience. */
+export interface TerminalResult {
+  /** Full decoded PTY output (raw bytes, ANSI escapes included). Capped. */
+  output: string;
+  exitCode: number;
+  durationMs: number;
+  /** Opaque id linking to the persisted asciicast session. */
+  sessionId: string;
+}
+
+/**
+ * Interactive terminal handle. Operations are sequential per terminal —
+ * concurrent `send`/`waitFor` against the same handle has no well-defined
+ * meaning since both touch the same PTY/screen buffer. Open multiple
+ * terminals for parallel sessions.
+ */
+export interface Terminal {
+  /** PTY column count this terminal was opened with. */
+  readonly cols: number;
+  /** PTY row count this terminal was opened with. */
+  readonly rows: number;
+  /** Session id linking to the asciicast record. */
+  readonly sessionId: string;
+  /**
+   * Resolves when the underlying process ends — by `close()`, by the
+   * inner command exiting, or by timeout — to a `TerminalResult` with
+   * the full captured `output` and `exitCode`. Never rejects.
+   *
+   * The result is provenance-tagged against the `exit` step, so an
+   * `expect((await term.exited).output).toContain(...)` /
+   * `expect((await term.exited).exitCode).toBe(0)` nests under the
+   * terminal in the timeline. This is how you assert on a long-lived
+   * terminal's transcript — there is no separate `output()`/`screen()`
+   * getter (use `waitFor` to observe mid-session).
+   */
+  readonly exited: Promise<Wrapped<TerminalResult>>;
+  /** Exit code if the process has exited, else `undefined`. Non-blocking
+   *  peek; unlike `exited` it records no step and isn't tagged. */
+  readonly exitCode: number | undefined;
+
+  /** Write raw bytes to the PTY. No newline added. */
+  send(input: string): Promise<void>;
+  /** Convenience: `send(line + "\n")`. */
+  sendLine(line: string): Promise<void>;
+  /**
+   * Press a named key. Supported names: `Enter`, `Tab`, `Backspace`,
+   * `Escape`, `Up`/`Down`/`Left`/`Right`, `Home`, `End`, `PageUp`,
+   * `PageDown`, `Delete`, and `Ctrl+<letter>` (case-insensitive).
+   * Anything else is sent as the literal string.
+   */
+  press(key: string): Promise<void>;
+
+  /**
+   * Poll until `matcher` resolves truthy against the rendered screen.
+   * This is the primitive for observing terminal state — race-free
+   * (it polls until the condition holds rather than reading a snapshot
+   * that may not have rendered yet) and recorded as a tied step.
+   * `matcher` can be:
+   *   - a string  → matches when the screen contains it; resolves to
+   *     the string. The wait itself is the assertion (it throws on
+   *     timeout), so no extra `expect` is needed for "contains X".
+   *   - a regex   → matches on `.test`; resolves to the match array.
+   *   - a function → `fn(screen, output)` — any truthy return resolves
+   *     and becomes the (provenance-tagged) result, so you can extract
+   *     a value and `expect(...)` on it.
+   *
+   * `description` is a short human label that shows up in the event
+   * log so timelines don't fill with anonymous waits.
+   *
+   * Defaults: 5 s total timeout, 100 ms between polls. Throws on
+   * timeout.
+   */
+  waitFor(
+    description: string,
+    matcher: string,
+    opts?: { timeoutMs?: number; intervalMs?: number },
+  ): Promise<Wrapped<string>>;
+  waitFor(
+    description: string,
+    matcher: RegExp,
+    opts?: { timeoutMs?: number; intervalMs?: number },
+  ): Promise<Wrapped<RegExpMatchArray>>;
+  waitFor<T = unknown>(
+    description: string,
+    matcher: (screen: string, output: string) => T,
+    opts?: { timeoutMs?: number; intervalMs?: number },
+  ): Promise<Wrapped<NonNullable<Awaited<T>>>>;
+
+  /**
+   * Tear down. Writes Ctrl-D to stdin to nudge the shell out, then
+   * SIGKILLs after a grace period. Idempotent. Resolves to a
+   * `TerminalResult` (tagged against the `close` step) so you can assert
+   * on the transcript of a session that doesn't self-terminate. Optional
+   * — terminals are not auto-closed when a test ends.
+   */
+  close(): Promise<Wrapped<TerminalResult>>;
+}
+
+/**
+ * The concrete handle `openTerminal` returns. Extends the public
+ * `Terminal` with raw accessors the daemon uses internally to build
+ * `TerminalResult`s and event previews. Deliberately NOT on the public
+ * `Terminal` surface: test code observes via `waitFor` (race-free, tied)
+ * and reads the transcript from `exited`/`close`, never from an
+ * out-of-band, untracked getter.
+ */
+export interface InternalTerminal extends Terminal {
+  /** Cumulative raw PTY bytes since the session opened, capped. ANSI included. */
+  rawOutput(): string;
+  /** Rendered screen — visible rows joined by newlines, trailing
+   *  whitespace trimmed, cursor-position-aware (ANSI already applied). */
+  rawScreen(): string;
+}
+
+// Cap on cumulative output we keep in memory. The asciicast frames
+// grow separately (they live on the session record) and aren't bounded
+// here. Matches `TERMINAL_OUTPUT_CAP_BYTES` in daemon.ts.
+const OUTPUT_CAP_BYTES = 1024 * 1024;
+
+// Default scrollback for the headless emulator. Generous enough that
+// long output histories aren't lost between `screen()` calls, small
+// enough that the per-session memory cost stays bounded.
+const SCROLLBACK = 10_000;
+
+// Deadline for the TTY echo when recording a send/press step.
+//
+// Why we wait at all: `castTimeSec` is supposed to point at the cast
+// frame the user wants to see when they click the step. For
+// send/press, that's the frame containing the echo of what we typed.
+// The echo is a PTY round-trip (our pipe → script → container TTY →
+// kernel echo back → script → our pipe) that takes a few ms — at the
+// instant `writeStdin` returns, no frame yet exists that contains the
+// typed bytes. So we await the next ingested frame; that frame IS the
+// echo. This isn't a fixed delay — it resolves as soon as the echo
+// lands, typically <30ms.
+//
+// The timeout is a safety hatch only: if the program reads the input
+// without ever echoing (rare — would require either raw mode + no app
+// response, or a closed-fd condition), we don't want to hang the test.
+// In that case `castTimeSec` falls back to the write moment, which is
+// fine because there's no later echo frame for it to misalign with.
+const ECHO_WAIT_MS = 120;
+
+/** Sink for asciicast frames produced by this terminal. */
+export interface TerminalFrameSink {
+  pushFrame(tSec: number, data: string): void;
+  markClosed(): void;
+}
+
+export interface OpenTerminalArgs {
+  service: string;
+  opts?: TerminalOpts;
+  /** Asciicast frames go here; the daemon owns the session record. */
+  sink: TerminalFrameSink;
+  /** Session id (precomputed so the inline TerminalEvent can reference
+   * it before the session record is finished). */
+  sessionId: string;
+  /**
+   * When set, the daemon emits per-op events into the recorder under
+   * this session id. Mirrors `BrowserSessionRecorder.sessionId`.
+   * `null` disables per-op event recording (e.g. eval, where there's
+   * no active recorder).
+   */
+  recordEvents?: boolean;
+}
+
+/**
+ * Open a PTY-backed interactive terminal in a service container.
+ *
+ * The factory itself doesn't know about `TerminalSessionRecord`s — it
+ * just calls `sink.pushFrame` for every chunk it sees and `markClosed`
+ * when the session ends. The daemon owns the record and the sink.
+ */
+export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerminal> {
+  const { service, opts, sink, sessionId } = args;
+  const cols = opts?.cols ?? 80;
+  const rows = opts?.rows ?? 24;
+  const userEnv = opts?.env ?? {};
+  const term = userEnv.TERM ?? "xterm-256color";
+
+  // Build the inner docker exec invocation. With `-it` the container
+  // sees a real TTY and dockerd merges stderr into stdout, so we only
+  // need to drain one stream from the PTY.
+  const dockerArgs: string[] = ["exec", "-it"];
+  dockerArgs.push("-e", `TERM=${term}`);
+  dockerArgs.push("-e", `COLUMNS=${cols}`);
+  dockerArgs.push("-e", `LINES=${rows}`);
+  for (const [k, v] of Object.entries(userEnv)) {
+    if (k === "TERM") continue;
+    dockerArgs.push("-e", `${k}=${v}`);
+  }
+  dockerArgs.push(service);
+  if (opts?.command !== undefined) {
+    dockerArgs.push("sh", "-lc", opts.command);
+  } else {
+    // Login shell — gives the user a $PS1 prompt to drive interactively.
+    dockerArgs.push("sh", "-l");
+  }
+
+  // Quote the inner docker command for `script -c`. We pass it as a
+  // single shell string. `stty` sets the PTY slave's size to the
+  // requested cols/rows before exec'ing docker — without this, the
+  // container app would see whatever size script's parent had (often
+  // 80x24, but the daemon has none, so it's whatever util-linux picks
+  // as the fallback).
+  const inner = `stty rows ${rows} cols ${cols} 2>/dev/null; exec ${shellQuote(["docker", ...dockerArgs])}`;
+  // `script -q -f -c CMD /dev/null` runs CMD in a PTY (no preamble, flushed
+  // after each write, output discarded — we capture via stdout pipe).
+  const spawnArgs = ["script", "-qfc", inner, "/dev/null"];
+
+  const start = Date.now();
+  const proc = Bun.spawn(spawnArgs, {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // Headless screen model. `allowProposedApi` lets us call `buffer.active`
+  // safely (it's marked EXPERIMENTAL in the public typings).
+  const emu = new XtermHeadless({
+    cols,
+    rows,
+    scrollback: SCROLLBACK,
+    allowProposedApi: true,
+  });
+
+  let output = "";
+  let exited = false;
+  let exitCode: number | undefined;
+  let closed = false;
+  let resolveExit!: (code: number) => void;
+  const rawExited = new Promise<number>((res) => {
+    resolveExit = res;
+  });
+  // Cast time at the moment the process actually exited. Captured by
+  // the IIFE below so the `exit` step we record points the player at
+  // the very end of the visible session.
+  let exitCastTimeSec: number | undefined;
+
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  // Subscribers waiting for the next frame to arrive. Used by send /
+  // sendLine / press so the recorded `castTimeSec` lands on the echo's
+  // frame instead of microseconds before it.
+  const frameWaiters: Array<() => void> = [];
+  const ingest = (chunk: string): void => {
+    const t = (Date.now() - start) / 1000;
+    sink.pushFrame(t, chunk);
+    emu.write(chunk);
+    if (output.length < OUTPUT_CAP_BYTES) {
+      const room = OUTPUT_CAP_BYTES - output.length;
+      output += chunk.length > room ? chunk.slice(0, room) : chunk;
+    }
+    if (frameWaiters.length > 0) {
+      const fns = frameWaiters.splice(0, frameWaiters.length);
+      for (const fn of fns) fn();
+    }
+  };
+
+  /**
+   * Resolve when the next PTY frame is ingested, or after `timeoutMs`
+   * elapses — whichever comes first. Used to delay a send/press
+   * recording just long enough for the TTY echo to land on a frame, so
+   * the seek target lines up with the visible state of the screen.
+   */
+  const waitForNextFrame = (timeoutMs: number): Promise<void> => {
+    return new Promise<void>((resolve) => {
+      let done = false;
+      const finish = (): void => {
+        if (done) return;
+        done = true;
+        resolve();
+      };
+      frameWaiters.push(finish);
+      setTimeout(finish, timeoutMs);
+    });
+  };
+
+  const drainStream = async (
+    stream: ReadableStream<Uint8Array> | null | undefined,
+  ): Promise<void> => {
+    if (!stream) return;
+    const reader = stream.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        if (!value || value.byteLength === 0) continue;
+        const chunk = decoder.decode(value, { stream: true });
+        if (chunk.length === 0) continue;
+        ingest(chunk);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  };
+
+  // Drain stdout + stderr concurrently. `script` writes everything to
+  // stdout under `-t`, but we drain stderr anyway in case script(1)
+  // itself emits diagnostics there.
+  const stdout = proc.stdout as ReadableStream<Uint8Array> | null | undefined;
+  const stderr = proc.stderr as ReadableStream<Uint8Array> | null | undefined;
+  const drained = Promise.all([drainStream(stdout), drainStream(stderr)]);
+
+  // Race the optional session-level timeout. For interactive terminals
+  // we usually have no timeout; the wrapper for one-shot supplies one.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  if (opts?.timeoutMs && opts.timeoutMs > 0) {
+    timer = setTimeout(() => {
+      if (!exited) {
+        try {
+          proc.kill();
+        } catch {
+          /* ignore */
+        }
+      }
+    }, opts.timeoutMs);
+  }
+
+  // When the process exits, drain whatever's left and resolve `exited`.
+  // We don't await `drained` here — it's already running and will
+  // settle on its own; the explicit `await drained` happens in close().
+  (async () => {
+    const code = await proc.exited;
+    exited = true;
+    exitCode = code;
+    if (timer) clearTimeout(timer);
+    // Let `drained` finish so the final asciicast frames land before we
+    // mark the sink closed. drainStream is bounded by the OS pipe being
+    // closed when proc exits, so this won't hang.
+    try {
+      await drained;
+    } catch {
+      /* ignore */
+    }
+    // Record cast time AFTER drain, so the `exit` step we record below
+    // points the player at the very last frame (the program's final
+    // output before EOF).
+    exitCastTimeSec = (Date.now() - start) / 1000;
+    sink.markClosed();
+    resolveExit(code);
+  })();
+
+  // Helper to write raw bytes to the PTY. We treat stdin as binary
+  // pipes (Bun's `proc.stdin` is a Web `WritableStream<Uint8Array>` or
+  // a FileSink-like depending on the version — use the FileSink-style
+  // `write(string)` which both shapes accept).
+  const stdinWriter = proc.stdin as { write(s: string): unknown; flush?(): unknown } | undefined;
+  const writeStdin = async (data: string): Promise<void> => {
+    if (exited || closed || !stdinWriter) return;
+    stdinWriter.write(data);
+    try {
+      const r = stdinWriter.flush?.();
+      // FileSink.flush returns void | number; ignore the return.
+      void r;
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const renderScreen = (): string => {
+    const buf = emu.buffer.active;
+    const lines: string[] = [];
+    // We render only the visible viewport (cursor-position-aware): the
+    // typical mental model of "what does the user see right now".
+    const viewportTop = buf.viewportY;
+    for (let y = 0; y < emu.rows; y++) {
+      const line = buf.getLine(viewportTop + y);
+      lines.push(line ? line.translateToString(true) : "");
+    }
+    // Drop trailing empty lines so multi-line predicates aren't padded.
+    while (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+    return lines.join("\n");
+  };
+
+  const recordOpEvent = (
+    action: TerminalStepAction,
+    fields: Record<string, unknown>,
+    startedAt: number,
+    error?: string,
+    reservation?: EventReservation,
+  ): number | undefined => {
+    if (!args.recordEvents) return undefined;
+    const preview = truncateUtf8(renderScreen());
+    // Use the SAME clock the asciicast frames use (offset from `start`,
+    // which is captured at Bun.spawn). That way the UI seeks the player
+    // directly to this value with no frame arithmetic.
+    const castTimeSec = (Date.now() - start) / 1000;
+    // Return the event seq so callers can `wrap()` their result value
+    // against it — e.g. `expect(await term.waitFor(...))` then links its
+    // assertion to this step (sourceSeq) and the UI nests it here.
+    return recordTerminalStep({
+      sessionId,
+      service,
+      action,
+      castTimeSec,
+      durationMs: Date.now() - startedAt,
+      screenPreview: preview.value,
+      screenTruncated: preview.truncated,
+      error,
+      ...fields,
+    }, reservation);
+  };
+
+  // Assemble the public result shape (mirrors the one-shot
+  // `ctx.terminal(...)` TerminalResult) from current capture state.
+  const buildResult = (code: number): TerminalResult => ({
+    output,
+    exitCode: code,
+    durationMs: Date.now() - start,
+    sessionId,
+  });
+
+  // Memoised promise behind `term.exited`. Lazily constructed on first
+  // read so the `exit` step is only recorded if the test actually
+  // awaits exit — the one-shot wrapper internally uses `rawExited`
+  // directly and so skips the step (which is what we want; the one-shot
+  // already emits a `terminal` event covering the whole lifecycle).
+  let exitedAccessor: Promise<Wrapped<TerminalResult>> | undefined;
+  const getExited = (): Promise<Wrapped<TerminalResult>> => {
+    if (exitedAccessor) return exitedAccessor;
+    const resv = reserveEvent();
+    exitedAccessor = (async () => {
+      const code = await rawExited;
+      const result = buildResult(code);
+      // No recorder (eval/setup): there's no event to nest under, but we
+      // still wrap (with an undefined seq) so the accessor's wrapped type is
+      // honest at runtime — same as the one-shot `ctx.terminal`/`fetch` paths.
+      if (!args.recordEvents) {
+        return wrap(result, undefined) as unknown as Wrapped<TerminalResult>;
+      }
+      const preview = truncateUtf8(renderScreen());
+      const seq = recordTerminalStep({
+        sessionId,
+        service,
+        action: "exit",
+        castTimeSec: exitCastTimeSec ?? (Date.now() - start) / 1000,
+        durationMs: 0,
+        screenPreview: preview.value,
+        screenTruncated: preview.truncated,
+        exitCode: code,
+      }, resv);
+      // Tag the whole result against the exit step so assertions on
+      // `.output` / `.exitCode` nest under the terminal in the timeline.
+      return wrap(result, seq) as unknown as Wrapped<TerminalResult>;
+    })();
+    return exitedAccessor;
+  };
+
+  const handle: InternalTerminal = {
+    cols,
+    rows,
+    sessionId,
+    get exited() {
+      return getExited();
+    },
+    get exitCode() {
+      return exitCode;
+    },
+    async send(input) {
+      const t = Date.now();
+      const resv = reserveEvent();
+      const trunc = truncateUtf8(input);
+      try {
+        await writeStdin(input);
+        // Block until the echo of what we just wrote lands on a PTY
+        // frame. `writeStdin` returns the instant the bytes are in
+        // the pipe buffer; the kernel TTY echo takes a few ms to
+        // round-trip back through script + docker exec + our stdout
+        // pipe. Recording `castTimeSec` before that frame arrives
+        // would point the step's seek target at a screen state that
+        // doesn't yet show what was typed. The await resolves the
+        // moment that next frame is ingested — it's the mechanism,
+        // not a delay.
+        await waitForNextFrame(ECHO_WAIT_MS);
+        recordOpEvent("send", { text: trunc.value, textTruncated: trunc.truncated }, t, undefined, resv);
+      } catch (err) {
+        const e = err as Error;
+        recordOpEvent(
+          "send",
+          { text: trunc.value, textTruncated: trunc.truncated },
+          t,
+          e?.message ?? String(err),
+          resv,
+        );
+        throw err;
+      }
+    },
+    async sendLine(line) {
+      const t = Date.now();
+      const resv = reserveEvent();
+      const trunc = truncateUtf8(line);
+      try {
+        await writeStdin(line + "\n");
+        await waitForNextFrame(ECHO_WAIT_MS);
+        recordOpEvent("sendLine", { text: trunc.value, textTruncated: trunc.truncated }, t, undefined, resv);
+      } catch (err) {
+        const e = err as Error;
+        recordOpEvent(
+          "sendLine",
+          { text: trunc.value, textTruncated: trunc.truncated },
+          t,
+          e?.message ?? String(err),
+          resv,
+        );
+        throw err;
+      }
+    },
+    async press(key) {
+      const t = Date.now();
+      const resv = reserveEvent();
+      const bytes = keyToBytes(key);
+      try {
+        await writeStdin(bytes);
+        await waitForNextFrame(ECHO_WAIT_MS);
+        recordOpEvent("press", { key }, t, undefined, resv);
+      } catch (err) {
+        const e = err as Error;
+        recordOpEvent("press", { key }, t, e?.message ?? String(err), resv);
+        throw err;
+      }
+    },
+    rawOutput() {
+      return output;
+    },
+    rawScreen() {
+      return renderScreen();
+    },
+    async waitFor(
+      description: string,
+      matcher: string | RegExp | ((screen: string, output: string) => unknown),
+      waitOpts?: { timeoutMs?: number; intervalMs?: number },
+    ) {
+      const timeoutMs = waitOpts?.timeoutMs ?? 5_000;
+      const intervalMs = waitOpts?.intervalMs ?? 100;
+      const t = Date.now();
+      const resv = reserveEvent();
+      const deadline = t + timeoutMs;
+      let attempts = 0;
+      const check = (): unknown => {
+        attempts++;
+        const scr = renderScreen();
+        if (typeof matcher === "string") {
+          return scr.includes(matcher) ? matcher : null;
+        }
+        if (matcher instanceof RegExp) {
+          const m = scr.match(matcher);
+          return m ?? null;
+        }
+        return matcher(scr, output);
+      };
+      while (true) {
+        const v = check();
+        if (v) {
+          const seq = recordOpEvent("waitFor", { description, attempts, matched: true }, t, undefined, resv);
+          // Tag the matched value so an `expect(...)` on it links its
+          // assertion back to this waitFor step (sourceSeq) instead of
+          // rendering as an orphan sidebar row. Mirrors how http/db/exec
+          // results carry their op's seq. `as never` lets this single
+          // body satisfy the three overload return types.
+          return wrap(v, seq) as never;
+        }
+        if (Date.now() >= deadline) {
+          const err = `waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`;
+          recordOpEvent(
+            "waitFor",
+            { description, attempts, matched: false },
+            t,
+            err,
+            resv,
+          );
+          throw new Error(err);
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+      }
+    },
+    async close() {
+      // Use `rawExited` rather than `term.exited` everywhere we need a
+      // raw number internally — the public getter resolves to a wrapped
+      // result (and records an `exit` step on first read) which we don't
+      // want as a side-effect of internal teardown logic.
+      if (closed)
+        return buildResult(
+          exitCode ?? (await rawExited),
+        ) as unknown as Wrapped<TerminalResult>;
+      closed = true;
+      const t = Date.now();
+      const resv = reserveEvent();
+      // Polite first: send EOF (Ctrl-D). For a login shell this exits
+      // cleanly. For a long-running command it's a no-op and we fall
+      // through to SIGKILL.
+      try {
+        await writeStdin("\x04");
+      } catch {
+        /* ignore */
+      }
+      // Closing stdin signals EOF to the script wrapper too.
+      try {
+        (proc.stdin as { end?: () => void } | undefined)?.end?.();
+      } catch {
+        /* ignore */
+      }
+      // Grace period before forcibly killing.
+      const grace = 1_500;
+      const raced = await Promise.race([
+        rawExited,
+        new Promise<"timeout">((r) => setTimeout(() => r("timeout"), grace)),
+      ]);
+      if (raced === "timeout") {
+        try {
+          proc.kill();
+        } catch {
+          /* ignore */
+        }
+      }
+      const code = await rawExited;
+      const result = buildResult(code);
+      const seq = recordOpEvent("close", { exitCode: code }, t, undefined, resv);
+      // Tag the result against the close step so assertions on the
+      // transcript of a non-self-terminating session nest under it.
+      return wrap(result, seq) as unknown as Wrapped<TerminalResult>;
+    },
+  };
+
+  return handle;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Key name → byte sequence
+// ────────────────────────────────────────────────────────────────────────
+
+const KEY_MAP: Record<string, string> = {
+  enter: "\r",
+  return: "\r",
+  tab: "\t",
+  backspace: "\x7f",
+  delete: "\x1b[3~",
+  escape: "\x1b",
+  esc: "\x1b",
+  up: "\x1b[A",
+  down: "\x1b[B",
+  right: "\x1b[C",
+  left: "\x1b[D",
+  home: "\x1b[H",
+  end: "\x1b[F",
+  pageup: "\x1b[5~",
+  pagedown: "\x1b[6~",
+  space: " ",
+};
+
+function keyToBytes(key: string): string {
+  const norm = key.replace(/[\s_-]/g, "").toLowerCase();
+  if (KEY_MAP[norm] !== undefined) return KEY_MAP[norm];
+  // Ctrl+<letter>: ASCII control char 1-26.
+  const ctrl = key.match(/^ctrl[\s_+-]+([a-z])$/i);
+  if (ctrl) {
+    const letter = ctrl[1].toLowerCase();
+    const code = letter.charCodeAt(0) - "a".charCodeAt(0) + 1;
+    return String.fromCharCode(code);
+  }
+  // Fall back to the literal string — lets callers type a single
+  // character via `press("X")` even if it's not in the table.
+  return key;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Shell quoting for `script -c CMD`
+// ────────────────────────────────────────────────────────────────────────
+
+function shellQuote(argv: string[]): string {
+  return argv
+    .map((a) => {
+      if (a.length === 0) return "''";
+      if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a)) return a;
+      return `'${a.replace(/'/g, `'\\''`)}'`;
+    })
+    .join(" ");
+}