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

package/src/sanitize-terminal-text.ts

@@ -0,0 +1,171 @@
+/**
+ * SEC-019 (issue #2022) - the one place untrusted text is made safe to put on a terminal.
+ *
+ * Model output, tool output, file contents and plugin text all reach Ink `<Text>`, and from there a
+ * terminal. What that terminal actually receives was MEASURED against a real stream rather than
+ * assumed, because the first version of this module assumed Ink passed everything through and that
+ * is not true:
+ *
+ *   stripped by Ink   OSC 52 (clipboard), OSC 0 (title), CSI erase/cursor/alt-screen, DCS, APC,
+ *                     8-bit CSI
+ *   REACHES the tty   SGR colour, OSC 8 hyperlink, a bare carriage return
+ *
+ * So through `<Text>` the live attack is a link whose visible text and target differ, and a `\r`
+ * that overwrites the line the transcript just printed. `useTerminalTitle` writes to stdout directly
+ * and is subject to none of Ink's filtering, so everything reaches the terminal there.
+ *
+ * ## Why sanitize the whole class when Ink removes most of it
+ *
+ * Because Ink's removal is INCIDENTAL. It falls out of slicing text for layout; it is in no
+ * contract, no test of Ink's asserts it, and a dependency upgrade can return the entire class
+ * without a line changing here. A boundary that rests on another project's implementation detail is
+ * a boundary in name. The two sequences that reach the terminal today prove the exposure is real;
+ * the ones Ink happens to remove are the reason this must not be scoped to them.
+ *
+ * ## Allowlist, not denylist
+ *
+ * Everything is passed through EXCEPT the control range, and inside that range exactly two
+ * characters survive - tab and newline. A denylist of "known dangerous sequences" is
+ * wrong for the same reason it is wrong for shell metacharacters: the set belongs to the terminal
+ * emulator, and a list written today is incomplete the next time one adds an escape.
+ *
+ * ## Ordering: sanitize BEFORE rendering, never after
+ *
+ * The renderer ADDS ANSI - colours, bold, code-block framing. Sanitizing its output would strip the
+ * repository's own presentation along with the attacker's. Sanitizing its input removes the escapes
+ * that arrived from outside and leaves the ones generated after. That ordering is the whole design,
+ * and it is why this is a function on the untrusted string rather than a filter on the rendered one.
+ *
+ * ## Streaming
+ *
+ * A sequence split across two deltas - `\x1b]5` then `2;c;...\x07` - is invisible to a sanitizer that
+ * sees each chunk alone. {@link createStreamingTerminalSanitizer} holds the incomplete tail back until
+ * the chunk that completes it arrives. The TUI's own stream path accumulates before rendering
+ * (`tui-state-manager` appends each delta to a buffer and renders the buffer), so the stateless
+ * function is sufficient THERE - but a caller that sanitizes per chunk needs the stateful one, and
+ * having only the stateless function available is how that caller would get it wrong.
+ */
+
+/**
+ * Tab and newline are content. Carriage return is NOT, and that is a correction.
+ *
+ * A bare `\r` returns the cursor to column zero, so `safe text\rEVIL` prints `EVIL` over what the
+ * transcript said — the same "what you read is not what happened" attack as a deceptive hyperlink,
+ * with no escape sequence involved. It was kept here as content in the first version of this module
+ * on the assumption that CR is a line ending; measurement against a real terminal stream showed a
+ * bare CR reaching it intact.
+ *
+ * `\r\n` IS a line ending, and is normalized to `\n` before the control filter runs, so a document
+ * written on Windows keeps its line structure and loses only the overwrite primitive.
+ */
+const KEPT_C0 = new Set(['\t', '\n']);
+
+/** `\r\n` is one line break written in two bytes; a `\r` that is not part of one is a cursor move. */
+const CRLF = /\r\n/g;
+
+/**
+ * One escape sequence, or a lone control character.
+ *
+ * The alternation is ordered longest-context-first so a two-character C1 introducer (`ESC ]`) is
+ * consumed as the start of its sequence rather than as a bare `ESC`, and every 8-bit C1 form is
+ * matched with its BODY before the lone-C1 alternative can take the introducer on its own.
+ *
+ * Each introducer appears in both spellings, because a terminal accepts both: `ESC ]` and the single
+ * byte `\x9d` are the same OSC. An alternation that removed only the 7-bit spelling would leave the
+ * 8-bit one's parameters standing as visible text.
+ *
+ *  - `\x1b][^\x07\x1b]*(?:\x07|\x1b\\)?`  OSC, terminated by BEL or ST - or unterminated at the end
+ *    of the input, which is the streaming case and must still be removed rather than left visible.
+ *  - `\x9d[^\x07\x1b\x9c]*(?:\x07|\x9c|\x1b\\)?`  the same, 8-bit introducer, with `\x9c` as a
+ *    third accepted terminator because 8-bit ST is one byte.
+ *  - `\x1b[P^_X][\s\S]*?(?:\x1b\\|\x07)`  DCS, PM, APC, SOS, terminated by ST or BEL. The
+ *    terminator is MANDATORY here, and that is the difference from the OSC alternative above. OSC's
+ *    body is `[^\x07\x1b]*`, which is greedy and cannot cross its own terminator, so an optional
+ *    terminator costs nothing. A DCS body is `[\s\S]*?`, which is lazy - and a lazy quantifier
+ *    followed by an OPTIONAL group prefers the empty match at every position, so the alternative
+ *    would consume the two-character introducer and nothing else, leaving `q#0;2;0;0;0` from a Sixel
+ *    sequence standing as visible text. Found in review of PR #2212, and the reason every case in
+ *    the test table now asserts the exact output rather than "no control byte survives" - the weaker
+ *    assertion holds for a sanitizer that strips only introducers.
+ *  - `\x1b[P^_X][\s\S]*$`  the same, unterminated at the end of the input. Written as its own
+ *    alternative rather than an optional terminator, for the reason directly above.
+ *  - `[\x90\x98\x9e\x9f][\s\S]*?(?:\x9c|\x1b\\|\x07)` and `[\x90\x98\x9e\x9f][\s\S]*$`
+ *    DCS/SOS/PM/APC again, 8-bit introducers, terminated and unterminated.
+ *  - `\x1b\[[0-?]*[ -/]*[@-~]`  CSI. The parameter class is the ECMA-48 range 0x30–0x3F written as
+ *    a range, not the digits-plus-`;`-plus-`?` an author reaches for from memory. That shorter class
+ *    omits `:`, `<`, `=` and `>`, and the omission is not academic: `ESC [ 38:2:255:0:0 m` is the
+ *    colon form of a truecolor SGR and `ESC [ < 0;10;20 M` is an SGR mouse report. Neither matched
+ *    any alternative, so the lone-control fallback took the ESC and left `38:2:255:0:0m` as visible
+ *    text. Found in review of PR #2212.
+ *  - `\x9b[0-?]*[ -/]*[@-~]`  the same, 8-bit introducer.
+ *  - `\x1b[@-Z\\-_]`  any other two-character escape.
+ *  - `[\x00-\x1f\x7f]`  a lone control character, including a bare ESC or BEL.
+ *  - `[\x80-\x9f]`  a lone C1 control that started no sequence any alternative above matched.
+ */
+const CONTROL_SEQUENCE =
+  // eslint-disable-next-line no-control-regex
+  /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x9d[^\x07\x1b\x9c]*(?:\x07|\x9c|\x1b\\)?|\x1b[P^_X][\s\S]*?(?:\x1b\\|\x07)|\x1b[P^_X][\s\S]*$|[\x90\x98\x9e\x9f][\s\S]*?(?:\x9c|\x1b\\|\x07)|[\x90\x98\x9e\x9f][\s\S]*$|\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b[@-Z\\-_]|[\x00-\x1f\x7f]|[\x80-\x9f]/g;
+
+/**
+ * The longest prefix of `text` that could still become a control sequence if more text arrived.
+ *
+ * "Could still become" is the whole contract, and the DCS/PM/APC/SOS bodies are where it is easy to
+ * lose. Written as a plain `[\s\S]*`, they match a sequence that is ALREADY terminated inside the
+ * chunk — `'hello' ESC P … ESC \ 'world'` anchors from the introducer to the end, so `world` is held
+ * back and does not appear until the next `push` or the `flush`. Nothing dangerous escapes, but
+ * ordinary text stops arriving, which for a streaming renderer is a stall.
+ *
+ * So each body excludes its own terminators through a negative lookahead: a sequence that has already
+ * ended is not an incomplete tail. The OSC and CSI branches need no such guard — `[^\x07\x1b]*`
+ * cannot cross BEL or ESC, and a CSI without its final byte is incomplete by construction. Found in
+ * review of PR #2212, one round after the same asymmetry was fixed in {@link CONTROL_SEQUENCE}: the
+ * two patterns describe the same grammar and have to be changed together.
+ */
+const INCOMPLETE_TAIL =
+  // eslint-disable-next-line no-control-regex
+  /(?:\x1b(?:\][^\x07\x1b]*|[P^_X](?:(?!\x1b\\|\x07)[\s\S])*|\[[0-?]*[ -/]*|)?|\x9d[^\x07\x1b\x9c]*|[\x90\x98\x9e\x9f](?:(?!\x9c|\x1b\\|\x07)[\s\S])*|\x9b[0-?]*[ -/]*)$/;
+
+/**
+ * `text` with every terminal control sequence removed, and tab/newline/carriage return preserved.
+ *
+ * Ordinary Unicode - including characters far outside ASCII - is untouched: the goal is to remove
+ * what the TERMINAL acts on, not to restrict what a document may say.
+ */
+export function sanitizeTerminalText(text: string): string {
+  return text
+    .replace(CRLF, '\n')
+    .replace(CONTROL_SEQUENCE, (match) => (KEPT_C0.has(match) ? match : ''));
+}
+
+/** A sanitizer that carries an incomplete escape across chunk boundaries. */
+export interface IStreamingTerminalSanitizer {
+  /** Sanitize one chunk, holding back any tail that could still become an escape. */
+  push(chunk: string): string;
+  /** Emit whatever is held back, sanitized. Call when the stream ends. */
+  flush(): string;
+}
+
+/**
+ * A stateful sanitizer for callers that sanitize each chunk as it arrives.
+ *
+ * The held-back tail is bounded by the incomplete-prefix pattern rather than by a byte count: a
+ * partial OSC can be arbitrarily long, and truncating the buffer would emit the middle of a sequence
+ * as visible text while dropping the part that made it dangerous.
+ */
+export function createStreamingTerminalSanitizer(): IStreamingTerminalSanitizer {
+  let pending = '';
+  return {
+    push(chunk: string): string {
+      const combined = pending + chunk;
+      const tail = INCOMPLETE_TAIL.exec(combined);
+      const holdFrom = tail && tail[0].length > 0 ? tail.index : combined.length;
+      pending = combined.slice(holdFrom);
+      return sanitizeTerminalText(combined.slice(0, holdFrom));
+    },
+    flush(): string {
+      const remaining = pending;
+      pending = '';
+      return sanitizeTerminalText(remaining);
+    },
+  };
+}

package/src/screen-reader-announcement.ts

@@ -0,0 +1,52 @@
+/**
+ * CLI-2004 — the first line the process prints.
+ *
+ * Two mutually exclusive lines, and never more than one:
+ *  - the mode is ON  → `[Screen reader mode: on via flag|env|settings]`. It is the only
+ *    self-diagnostic in the design: when someone reports "I passed the flag and nothing changed",
+ *    this line says whether the mode is on and which input turned it on.
+ *  - the mode is OFF and the environment looks like a reader is present → one advisory line naming
+ *    the flag. That is the whole of this project's answer to the auto-detection question: opt-in
+ *    keeps determinism, and a false positive costs one line of text instead of reshaping a sighted
+ *    user's interface.
+ *
+ * Printed before Ink's first frame and never during a turn, so it cannot interleave with output a
+ * reader is consuming.
+ */
+
+/** Which input turned the mode on. Mirrors the CLI resolver's channel. */
+export type TScreenReaderChannel = 'flag' | 'env' | 'settings';
+
+export interface IScreenReaderAnnouncementInputs {
+  enabled: boolean;
+  channel?: TScreenReaderChannel | undefined;
+  /** True when the mode is off but the environment suggests a reader is running. */
+  hint?: boolean | undefined;
+}
+
+/** The confirmation / advisory line, or `undefined` when neither applies. Pure. */
+export function screenReaderAnnouncement(
+  inputs: IScreenReaderAnnouncementInputs,
+): string | undefined {
+  if (inputs.enabled) {
+    // A mode that is on always names a channel; `settings` is the lowest tier and the safe read
+    // when a caller enables the mode without saying how.
+    return `[Screen reader mode: on via ${inputs.channel ?? 'settings'}]`;
+  }
+  if (inputs.hint === true) {
+    return '[Screen reader mode: off — run with --screen-reader]';
+  }
+  return undefined;
+}
+
+/** Write the line (with its newline) when there is one. Silent otherwise. */
+export function writeScreenReaderAnnouncement(
+  inputs: IScreenReaderAnnouncementInputs,
+  write: (text: string) => void = (text) => {
+    process.stdout.write(text);
+  },
+): void {
+  const line = screenReaderAnnouncement(inputs);
+  if (line === undefined) return;
+  write(`${line}\n`);
+}

package/src/screen-reader-context.tsx

@@ -0,0 +1,32 @@
+/**
+ * CLI-2004 — the one place a component asks "is screen-reader mode on?".
+ *
+ * The mode is a single resolved boolean threaded from the CLI into `renderApp`, handed to Ink as
+ * `isScreenReaderEnabled` AND published here. Two sources of truth for one fact is the hazard this
+ * design accepts (Ink's option and this context); both are set from the same resolved value in
+ * `render.tsx`, and no component takes the mode as a prop from its parent — it reads it here — so a
+ * missed prop cannot silently leave one component in the wrong mode.
+ *
+ * Default `false`: a component rendered outside the provider (every existing test) behaves exactly
+ * as it does today.
+ */
+
+import React, { createContext, useContext } from 'react';
+
+const ScreenReaderContext = createContext<boolean>(false);
+
+/** Publish the resolved mode to the tree. */
+export function ScreenReaderProvider({
+  enabled,
+  children,
+}: {
+  enabled: boolean;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return <ScreenReaderContext.Provider value={enabled}>{children}</ScreenReaderContext.Provider>;
+}
+
+/** Read the resolved mode. `false` outside a provider. */
+export function useScreenReader(): boolean {
+  return useContext(ScreenReaderContext);
+}

package/src/screen-reader-labels.ts

@@ -0,0 +1,64 @@
+/**
+ * CLI-2004 — the screen-reader label vocabulary (SSOT).
+ *
+ * A screen reader has no equivalent of `aria-live`: the only channel to it is which characters land
+ * in the terminal buffer, in what order. A searchable prefix on every transcript line is therefore
+ * the whole of the "who is speaking" affordance, and it has to be stable enough to grep for.
+ *
+ * PROVIDER-INVARIANT BY CONSTRUCTION. The label derives from the message ROLE, never from the
+ * vendor behind it — `assistant:`, not the provider's product name — so the transcript reads
+ * identically under every `agent-provider-*`. `screenReaderLabelValues()` exists so a test can
+ * assert that negative mechanically instead of trusting review.
+ *
+ * All nine are lowercase. The reference this vocabulary is modelled on Title-Cases two of its nine;
+ * that split is not reproduced, because a reader announces case and the inconsistency is noise.
+ */
+
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+/** The nine label kinds. */
+export type TScreenReaderLabelKind =
+  | 'user'
+  | 'assistant'
+  | 'thinking'
+  | 'tool'
+  | 'toolError'
+  | 'error'
+  | 'warning'
+  | 'permissionRequired'
+  | 'cost';
+
+/** The label vocabulary. Every spoken prefix in the mode comes from exactly this map. */
+export const SCREEN_READER_LABELS: Readonly<Record<TScreenReaderLabelKind, string>> = {
+  user: 'you:',
+  assistant: 'assistant:',
+  thinking: 'thinking:',
+  tool: 'tool:',
+  toolError: 'tool error:',
+  error: 'error:',
+  warning: 'warning:',
+  permissionRequired: 'permission required:',
+  cost: 'cost:',
+};
+
+/** Every label value, for mechanical assertions over the vocabulary. */
+export function screenReaderLabelValues(): readonly string[] {
+  return Object.values(SCREEN_READER_LABELS);
+}
+
+/**
+ * Map a transcript message role onto the vocabulary. `system` speaks as `warning:` — it is the role
+ * the TUI already renders in the warning colour, and the mode may not lean on colour.
+ */
+export function screenReaderLabelForRole(role: TUniversalMessage['role']): string {
+  switch (role) {
+    case 'user':
+      return SCREEN_READER_LABELS.user;
+    case 'assistant':
+      return SCREEN_READER_LABELS.assistant;
+    case 'tool':
+      return SCREEN_READER_LABELS.tool;
+    case 'system':
+      return SCREEN_READER_LABELS.warning;
+  }
+}

package/src/screen-reader-pacing-context.tsx

@@ -0,0 +1,47 @@
+/**
+ * SCREEN-2670 — the one place a component reaches the owned write path.
+ *
+ * Mirrors `screen-reader-context.tsx`: the port is published from `render.tsx`, no component takes
+ * it as a prop from its parent, so a missed prop cannot silently leave one component writing past
+ * the queue. It also keeps a live writer handle out of the presentation tree, which declares itself
+ * free of channels, sessions and mutable state.
+ *
+ * Outside a provider (every existing test, and every run with the mode off) the port is inert:
+ * arming does nothing and writes go straight to the process's own stdout, exactly as today.
+ */
+
+import React, { createContext, useContext } from 'react';
+
+export interface IScreenReaderPacingPort {
+  /** Arm the echo flag for the batch the current keystroke's commit will open. */
+  armEchoRelease(): void;
+  /** Write a positional sequence (an OSC 133 mark) through the same ordered path. */
+  write(text: string): void;
+}
+
+const inertPort: IScreenReaderPacingPort = {
+  armEchoRelease(): void {},
+  write(text: string): void {
+    process.stdout.write(text);
+  },
+};
+
+const ScreenReaderPacingContext = createContext<IScreenReaderPacingPort>(inertPort);
+
+/** Publish the owned write path to the tree. */
+export function ScreenReaderPacingProvider({
+  port,
+  children,
+}: {
+  port: IScreenReaderPacingPort;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <ScreenReaderPacingContext.Provider value={port}>{children}</ScreenReaderPacingContext.Provider>
+  );
+}
+
+/** Read the port. Inert outside a provider. */
+export function useScreenReaderPacing(): IScreenReaderPacingPort {
+  return useContext(ScreenReaderPacingContext);
+}

package/src/screen-reader-pacing.ts

@@ -0,0 +1,178 @@
+/**
+ * CLI-2004 — the startup quiet period.
+ *
+ * A terminal has no `aria-live`. The ONLY way to influence what a reader announces is which bytes
+ * land in the buffer and WHEN, which is why this wait exists at all: it lets the reader finish
+ * speaking the confirmation line before the first prompt frame overwrites the region it is reading.
+ * A keypress ends it early.
+ *
+ * THE PRE-WRITE PARK (SCREEN-2670) is the second wait § Decision verdict (i) adopted. It lives in
+ * `screen-reader-stdout.ts`: an owned write path handed to Ink as `stdout`, which separates COMMITS
+ * in time so a diff-based reader's snapshot can fall between two of them. This module only resolves
+ * its interval. The default is PROVISIONAL: screen-reader mode runs Ink unthrottled, so no frame
+ * interval derives it, and the governing timescale — the reader's own sampling cadence — is not
+ * measurable from this harness. `50` matches the sole product precedent until it is measured
+ * against a real reader (recorded as an open item in this package's SPEC).
+ *
+ * The DEFAULT IS MEASURED AGAINST THIS RENDER LOOP, not copied: `DEFAULT_STARTUP_QUIET_MS` is the
+ * observed boot-to-first-prompt interval of this binary (~450 ms in the PTY harness) doubled, so the
+ * confirmation line is spoken before the prompt lands without the reference's 3 s stall, which is
+ * tuned to a heavier boot.
+ *
+ * The cap is a sanity bound, not policy: a value above it is clamped AND REPORTED. Nothing here
+ * silently substitutes a number — an unparseable value is refused with a note on stderr and the
+ * default stands (No-Fallback: the refusal is visible).
+ */
+
+/** Sanity bound on the startup quiet period (10 minutes). */
+export const STARTUP_QUIET_MS_MAX = 600_000;
+/** Boot-to-first-prompt of this binary, doubled. */
+export const DEFAULT_STARTUP_QUIET_MS = 900;
+
+/** Sanity bound on the pre-write park (5 seconds), matching the product precedent verdict (i) adopted. */
+export const PREPARK_MS_MAX = 5000;
+/** PROVISIONAL — taken to match the sole product precedent, pending measurement against a reader. */
+export const DEFAULT_PREPARK_MS = 50;
+
+/** The resolved pacing. `0` whenever the mode is off. */
+export interface IScreenReaderPacing {
+  startupQuietMs: number;
+  /** Interval parked in front of each printable commit after the first. `0` disables the park. */
+  preparkMs: number;
+}
+
+/** Raw timing choices supplied by the embedding host, with names for visible diagnostics. */
+export interface IScreenReaderPacingOverrides {
+  readonly startupQuiet?: { readonly raw: string | undefined; readonly label: string };
+  readonly prepark?: { readonly raw: string | undefined; readonly label: string };
+}
+
+export interface IResolvePacingInputs {
+  /** Screen-reader mode. Off ⇒ the wait is 0 regardless of host overrides. */
+  enabled: boolean;
+  /** Absent values use the renderer's numeric defaults; no environment is read here. */
+  overrides?: IScreenReaderPacingOverrides;
+  /** Where a clamp or a refusal is reported. Defaults to stderr. */
+  warn?: (message: string) => void;
+}
+
+function reportTo(warn: IResolvePacingInputs['warn']): (message: string) => void {
+  return (
+    warn ??
+    ((message: string): void => {
+      process.stderr.write(`${message}\n`);
+    })
+  );
+}
+
+/**
+ * Read the duration variable. Absent ⇒ the default. Non-numeric or negative ⇒ the default WITH a
+ * note (never a silent 0). Above the bound ⇒ the bound WITH a note. `0` is honoured exactly — it is
+ * the documented way to ask for no wait at all.
+ */
+function resolveDuration(
+  raw: string | undefined,
+  name: string,
+  fallback: number,
+  bound: number,
+  warn: (message: string) => void,
+): number {
+  if (raw === undefined || raw.trim() === '') return fallback;
+  const parsed = Number(raw.trim());
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
+    warn(
+      `${name}: ignoring "${raw}" — expected a whole number of milliseconds. Using ${fallback}.`,
+    );
+    return fallback;
+  }
+  if (parsed > bound) {
+    warn(`${name}: clamping ${parsed} to the ${bound} ms sanity bound.`);
+    return bound;
+  }
+  return parsed;
+}
+
+/** Resolve the wait once, at startup. */
+export function resolvePacing(inputs: IResolvePacingInputs): IScreenReaderPacing {
+  if (!inputs.enabled) return { startupQuietMs: 0, preparkMs: 0 };
+  const warn = reportTo(inputs.warn);
+  return {
+    startupQuietMs: resolveDuration(
+      inputs.overrides?.startupQuiet?.raw,
+      inputs.overrides?.startupQuiet?.label ?? 'startup quiet period',
+      DEFAULT_STARTUP_QUIET_MS,
+      STARTUP_QUIET_MS_MAX,
+      warn,
+    ),
+    preparkMs: resolveDuration(
+      inputs.overrides?.prepark?.raw,
+      inputs.overrides?.prepark?.label ?? 'pre-write park',
+      DEFAULT_PREPARK_MS,
+      PREPARK_MS_MAX,
+      warn,
+    ),
+  };
+}
+
+/** The one-shot keypress source that can settle the startup wait early. */
+export interface IKeypressSource {
+  once(event: 'data', listener: () => void): void;
+  off(event: 'data', listener: () => void): void;
+  resume?(): void;
+  pause?(): void;
+  /** Present on a TTY stdin. Without raw mode a lone key produces no `data` event. */
+  isTTY?: boolean;
+  setRawMode?(mode: boolean): void;
+}
+
+/**
+ * Put a TTY stdin into raw mode for the duration of the wait, returning the undo.
+ *
+ * Without this the promise below only settles on Enter: in canonical mode the terminal buffers a
+ * line, so "any keypress ends the wait" — which this package's SPEC states — would be false on a
+ * real terminal and true only against a synthetic source. Ink sets raw mode itself once it renders;
+ * this window closes before that, and restores whatever was set before.
+ */
+function withRawMode(keys: IKeypressSource | undefined): () => void {
+  if (keys?.isTTY !== true || typeof keys.setRawMode !== 'function') return (): void => {};
+  keys.setRawMode(true);
+  return (): void => {
+    keys.setRawMode?.(false);
+  };
+}
+
+/**
+ * Wait out the startup quiet period. Resolves at the deadline, or as soon as a key is pressed —
+ * whichever comes first. A `0` wait resolves without touching the keypress source at all.
+ *
+ * The keystroke that ends the wait is CONSUMED, which is the documented behaviour: the wait exists
+ * so the reader is not interrupted, and the key that says "I am ready" is the answer to it.
+ */
+export async function awaitStartupQuietPeriod(
+  ms: number,
+  keys?: IKeypressSource,
+): Promise<'elapsed' | 'keypress'> {
+  if (ms <= 0) return 'elapsed';
+  const restoreRawMode = withRawMode(keys);
+  return new Promise<'elapsed' | 'keypress'>((resolve) => {
+    const settle = (outcome: 'elapsed' | 'keypress'): void => {
+      restoreRawMode();
+      keys?.pause?.();
+      resolve(outcome);
+    };
+    const onKey = (): void => {
+      clearTimeout(timer);
+      settle('keypress');
+    };
+    const timer = setTimeout(() => {
+      if (keys !== undefined) keys.off('data', onKey);
+      settle('elapsed');
+    }, ms);
+    // Do not hold the process open on the pacing timer alone.
+    timer.unref?.();
+    if (keys !== undefined) {
+      keys.once('data', onKey);
+      keys.resume?.();
+    }
+  });
+}