failproofai 1.0.0-beta.2 → 1.0.0-beta.3

package/src/hooks/hook-activity-store.ts

@@ -69,6 +69,45 @@ export interface HookActivityEntry {
   cwd?: string;
   permissionMode?: string;
   hookEventName?: string;
+  /**
+   * Set only on events evaluated while a session pause was active. Absent on
+   * every ordinary row and on every row written before pausing existed, so —
+   * like `matchedPolicies` — consumers must treat `undefined` as "not paused"
+   * rather than rendering it as unknown.
+   */
+  pausedBy?: string;
+  /** Epoch ms the pause lifts. Present iff `pausedBy` is. */
+  pauseExpiresAt?: number;
+  /**
+   * Where the policy that DECIDED came from. Absent when nothing decided (a
+   * plain allow) and on rows written before this existed — so, like
+   * `matchedPolicies`, `undefined` means "unknown", not "builtin".
+   */
+  policySource?: "builtin" | "custom" | "convention" | "cloud";
+  /** Cloud policy id of the decider. Present only when `policySource` is "cloud". */
+  cloudPolicyId?: string;
+  /** Immutable revision of that policy — the half of attribution that identifies WHICH version ran. */
+  cloudRevision?: number;
+  /**
+   * The cloud generation active when this event was evaluated, recorded on
+   * every row of a managed machine regardless of what decided. "What was
+   * deployed here" is a different question from "what decided", and only this
+   * distinguishes a rollout that changed no outcomes from one that never
+   * arrived.
+   */
+  cloudGeneration?: number;
+  /**
+   * What observe-mode policies WOULD have done, had they been enforcing. This
+   * record is the entire point of observe mode: without it the row is
+   * indistinguishable from one where the policy never matched, and the rollout
+   * being trialled is unmeasurable.
+   */
+  observed?: Array<{
+    policyId: string;
+    revision: number;
+    decision: "deny" | "instruct";
+    reason: string | null;
+  }>;
 }
 
 export interface HookActivityFilters {
@@ -77,6 +116,12 @@ export interface HookActivityFilters {
   policyName?: string;
   sessionId?: string;
   integration?: IntegrationType;
+  /**
+   * Filter by where the deciding policy came from. "Show me everything my
+   * organization's policies decided" is the question cloud rollout reporting
+   * is built on, and it is unanswerable without this.
+   */
+  source?: "builtin" | "custom" | "convention" | "cloud";
 }
 
 export interface HookActivityStats {
@@ -298,6 +343,11 @@ export function searchHookActivity(
       return false;
     }
     if (filters.integration && entry.integration !== filters.integration) return false;
+    // Rows written before attribution existed have no policySource. They are
+    // excluded from every source filter rather than guessed at — a wrong
+    // attribution is worse than a missing one when the point is proving which
+    // rollout decided something.
+    if (filters.source && entry.policySource !== filters.source) return false;
     return true;
   });
 

package/src/hooks/loader-utils.ts

@@ -77,8 +77,9 @@ export async function resolveLocalImport(
 export async function createEsmShim(
   distIndex: string,
   distUrl: string,
+  tmpSuffix = TMP_SUFFIX,
 ): Promise<{ shimPath: string; shimUrl: string }> {
-  const shimPath = distIndex + ".__failproofai_esm_shim__.mjs";
+  const shimPath = `${distIndex}${tmpSuffix}.shim.mjs`;
   const shimCode = [
     `import _cjs from '${distUrl}';`,
     `export const customPolicies = _cjs.customPolicies;`,
@@ -101,6 +102,7 @@ export async function rewriteFileTree(
   entryPath: string,
   distUrl: string | null,
   distIndex: string | null,
+  tmpSuffix = TMP_SUFFIX,
 ): Promise<string[]> {
   const queue: string[] = [entryPath];
   const visited = new Set<string>();
@@ -108,7 +110,7 @@ export async function rewriteFileTree(
 
   let esmShimUrl: string | null = null;
   if (distIndex && distUrl) {
-    const shim = await createEsmShim(distIndex, distUrl);
+    const shim = await createEsmShim(distIndex, distUrl, tmpSuffix);
     tmpFiles.push(shim.shimPath);
     esmShimUrl = shim.shimUrl;
   }
@@ -148,7 +150,7 @@ export async function rewriteFileTree(
         if (!visited.has(resolved) && !queue.includes(resolved)) {
           queue.push(resolved);
         }
-        let relPath = relative(dir, resolved + TMP_SUFFIX).split("\\").join("/");
+        let relPath = relative(dir, resolved + tmpSuffix).split("\\").join("/");
         if (!relPath.startsWith(".")) relPath = "./" + relPath;
         rewrites.set(specifier, relPath);
       }
@@ -163,7 +165,7 @@ export async function rewriteFileTree(
       code = code.replace(new RegExp(`"${escaped}"`, "g"), `"${replacement}"`);
     }
 
-    const tmpPath = filePath + TMP_SUFFIX;
+    const tmpPath = filePath + tmpSuffix;
     await writeFile(tmpPath, code, "utf-8");
     tmpFiles.push(tmpPath);
   }

package/src/hooks/policy-types.ts

@@ -80,8 +80,36 @@ export interface LlmConfig {
   model?: string;
 }
 
+/**
+ * The collector's non-secret settings. The ingest credential deliberately does
+ * NOT live here: this file is written with a bare `writeFileSync`, so it
+ * inherits the umask and lands at 0664 inside a 0775 `~/.failproofai/` — an API
+ * key here would be readable by every local user. It lives in
+ * `~/.failproofai/ingest.json` at 0600 instead.
+ *
+ * Read by the Rust daemon (`crates/fpai-collect/src/config.rs`); the field
+ * names must stay in step with the `Settings` struct there.
+ */
+export interface CollectorConfig {
+  /**
+   * Ship agent session transcripts. Defaults to false and is a SEPARATE opt-in
+   * from configuring a key, because transcripts carry prompts, file contents
+   * and whatever was pasted into a terminal.
+   */
+  sessions?: boolean;
+  /** Ship hook activity. Carries decisions and tool names, never file contents. */
+  hooks?: boolean;
+  /** `decisions` keeps every deny/instruct exact and aggregates the ~99% allows. */
+  hooksVerbosity?: "all" | "decisions" | "off";
+  redact?: "minimal" | "off";
+  /** Label stamped on every event. Must not contain a comma — ingest skips those lines. */
+  environment?: string;
+}
+
 export interface HooksConfig {
   enabledPolicies: string[];
+  /** Collector settings; see {@link CollectorConfig}. Absent means unconfigured. */
+  collector?: CollectorConfig;
   llm?: LlmConfig;
   policyParams?: Record<string, Record<string, unknown>>;
   /** Explicit custom policy files, loaded in array order. */
@@ -98,6 +126,13 @@ export interface HooksConfig {
    * Only ever written explicitly as `false`.
    */
   customPoliciesEnabled?: boolean;
+  /**
+   * Upper bound, in ms, on how long `failproofai config --pause` may suspend
+   * enforcement. Only ever LOWERS the built-in 8h ceiling — a value above it is
+   * clamped back down, because a ceiling a project can raise is not a ceiling.
+   * Absent means the built-in ceiling applies.
+   */
+  maxPauseMs?: number;
   /**
    * Record of the convention policies (`.failproofai/policies/*policies.mjs`)
    * discovered at this scope the last time a failproofai command ran.

package/src/hooks/session-pause-cli.ts

@@ -0,0 +1,157 @@
+/**
+ * `failproofai config --pause | --resume | --status`.
+ *
+ * Lives on `config` rather than as its own verb because `config` is the single
+ * place this product configures anything. The state it writes is NOT config
+ * though — see session-pause.ts for why a pause must never reach a file that
+ * gets committed.
+ */
+import {
+  PAUSE_CEILING_MS,
+  clearPause,
+  formatDuration,
+  listActivePauses,
+  parsePauseDuration,
+  readActivePause,
+  resolveSessionForCwd,
+  writePause,
+  type ActivePause,
+} from "./session-pause";
+import { readMergedHooksConfig } from "./hooks-config";
+
+export interface PauseCommandOptions {
+  action: "pause" | "resume" | "status";
+  /** Raw `--pause <duration>` argument, if any. */
+  duration?: string;
+  /** Explicit `--session <id>`. */
+  sessionId?: string;
+  /** `--all`. */
+  all?: boolean;
+  cwd?: string;
+  now?: number;
+}
+
+export interface PauseCommandResult {
+  exitCode: number;
+  lines: string[];
+  /** For telemetry; never the session id itself. */
+  affected: number;
+}
+
+/**
+ * The ceiling, after any config lowering. A project may tighten this; nothing
+ * may loosen it, so a config asking for 24h still gets 8h.
+ */
+export function effectiveCeilingMs(cwd?: string): number {
+  try {
+    const configured = readMergedHooksConfig(cwd).maxPauseMs;
+    if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) {
+      return Math.min(configured, PAUSE_CEILING_MS);
+    }
+  } catch {
+    // An unreadable config must not remove the ceiling.
+  }
+  return PAUSE_CEILING_MS;
+}
+
+function describe(pause: ActivePause, now: number): string {
+  const remaining = formatDuration(Math.max(0, pause.expiresAt - now));
+  const at = new Date(pause.expiresAt).toLocaleTimeString();
+  const where = pause.cwd ? ` · ${pause.cwd}` : "";
+  return `  ${pause.sessionId}  ${remaining} left (until ${at})${where}`;
+}
+
+export function runPauseCommand(opts: PauseCommandOptions): PauseCommandResult {
+  const now = opts.now ?? Date.now();
+  const cwd = opts.cwd ?? process.cwd();
+
+  if (opts.action === "status") {
+    const active = listActivePauses(now);
+    if (active.length === 0) {
+      return { exitCode: 0, lines: ["Enforcement is active — nothing is paused."], affected: 0 };
+    }
+    return {
+      exitCode: 0,
+      lines: [
+        `Enforcement paused for ${active.length} session${active.length === 1 ? "" : "s"}:`,
+        ...active.map((p) => describe(p, now)),
+        "",
+        "Cloud-managed policies keep enforcing regardless.",
+        "Resume early with: failproofai config --resume",
+      ],
+      affected: active.length,
+    };
+  }
+
+  if (opts.action === "resume") {
+    if (opts.all) {
+      const active = listActivePauses(now);
+      let cleared = 0;
+      for (const pause of active) if (clearPause(pause.sessionId)) cleared++;
+      return {
+        exitCode: 0,
+        lines: [cleared === 0 ? "Nothing was paused." : `Resumed enforcement for ${cleared} session(s).`],
+        affected: cleared,
+      };
+    }
+    const sessionId = opts.sessionId ?? resolveSessionForCwd(cwd, undefined, now);
+    if (!sessionId) {
+      return { exitCode: 0, lines: ["Nothing was paused for this directory."], affected: 0 };
+    }
+    const cleared = clearPause(sessionId);
+    return {
+      exitCode: 0,
+      lines: [cleared ? "Enforcement resumed." : "Nothing was paused for that session."],
+      affected: cleared ? 1 : 0,
+    };
+  }
+
+  // pause
+  let durationMs: number;
+  try {
+    durationMs = parsePauseDuration(opts.duration, effectiveCeilingMs(cwd));
+  } catch (err) {
+    return { exitCode: 1, lines: [err instanceof Error ? err.message : String(err)], affected: 0 };
+  }
+
+  const sessionId = opts.sessionId ?? resolveSessionForCwd(cwd, undefined, now);
+  if (!sessionId) {
+    // Deliberately an error, not a guess. Pausing the wrong session would leave
+    // the user believing enforcement is off while it is on, or vice versa.
+    return {
+      exitCode: 1,
+      lines: [
+        "No recent agent session found for this directory.",
+        "",
+        "A pause applies to one agent session, and the session id only appears once",
+        "an agent has run at least one tool call here. Either run your agent first,",
+        "or name the session explicitly:",
+        "",
+        "  failproofai config --pause --session <id>",
+        "",
+        "Session ids are listed in the dashboard's activity view.",
+      ],
+      affected: 0,
+    };
+  }
+
+  const existing = readActivePause(sessionId, now);
+  const pause = writePause({ sessionId, durationMs, cwd, setBy: "cli", now });
+  const until = new Date(pause.expiresAt).toLocaleTimeString();
+
+  return {
+    exitCode: 0,
+    lines: [
+      existing
+        ? `Enforcement pause extended · ${formatDuration(durationMs)} · resumes at ${until}`
+        : `Enforcement paused · ${formatDuration(durationMs)} · resumes at ${until}`,
+      "",
+      "  Builtin, custom and convention policies are suspended for this session.",
+      "  Cloud-managed policies keep enforcing.",
+      "",
+      "It lifts on its own — no action needed. To end it early:",
+      "  failproofai config --resume",
+    ],
+    affected: 1,
+  };
+}

package/src/hooks/session-pause.ts

@@ -0,0 +1,236 @@
+/**
+ * Per-session enforcement pause — the state behind `failproofai config --pause`.
+ *
+ * A pause suspends LOCAL policy (builtins, explicit custom, convention) for one
+ * agent session, for a bounded time. It is deliberately NOT configuration:
+ *
+ *  - Config is persistent, merged across project/local/global, and routinely
+ *    committed to git. A paused enforcement state written there would outlive
+ *    the session that asked for it and travel to everyone who checks out the
+ *    branch — enforcement silently off for a whole team.
+ *  - So pause state lives here, under `~/.failproofai/state/sessions/`, owner-
+ *    only, keyed by session, and carrying an absolute expiry.
+ *
+ * Disk is the source of truth rather than the daemon: most machines have no
+ * daemon at all, and even where one exists the CLI that writes a pause is a
+ * different process from the hook that reads it. A daemon may cache this; it
+ * must not own it.
+ *
+ * Expiry is evaluated at READ time against the clock, never by a sweeper. A
+ * stale file is therefore inert rather than dangerous — the failure mode worth
+ * engineering against is not "the pause didn't work", it is "the pause silently
+ * never ended".
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+import { writeJsonAtomically } from "../../lib/atomic-write";
+import { getAllHookActivityEntries } from "./hook-activity-store";
+
+const SCHEMA_VERSION = 1;
+
+/** Default when `--pause` is given no duration. */
+export const PAUSE_DEFAULT_MS = 30 * 60_000;
+
+/**
+ * Hard ceiling. Config may lower this, never raise it — a ceiling a project
+ * could raise is not a ceiling, and the whole point is that a forgotten pause
+ * costs little.
+ */
+export const PAUSE_CEILING_MS = 8 * 60 * 60_000;
+
+export interface ActivePause {
+  sessionId: string;
+  /** Epoch ms. */
+  pausedAt: number;
+  /** Epoch ms. Always finite — there is no unbounded pause. */
+  expiresAt: number;
+  /** Free-form provenance, e.g. "cli". Recorded so the activity log can say who. */
+  setBy: string;
+  /** Where it was issued from, for `--status` and for cwd-based resolution. */
+  cwd?: string;
+}
+
+interface StoredPause extends ActivePause {
+  schemaVersion: number;
+}
+
+export function pauseStateDir(): string {
+  const override = process.env.FAILPROOFAI_STATE_DIR;
+  if (override) return resolve(override, "sessions");
+  return join(homedir(), ".failproofai", "state", "sessions");
+}
+
+/**
+ * Filename is a digest of the session id, not the id itself.
+ *
+ * Session ids come from twelve different agent CLIs and are not a format we
+ * control — Hermes and OpenClaw mint their own, and nothing stops one
+ * containing a path separator or `..`. Hashing sidesteps the entire class
+ * rather than trying to enumerate what is safe; the real id is stored inside
+ * the file, so `--status` and `--all` still report it.
+ */
+function pauseFilePath(sessionId: string): string {
+  const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
+  return join(pauseStateDir(), `${digest}.json`);
+}
+
+/**
+ * Parse `10m` / `2h` / `90s`, or a bare integer read as minutes.
+ *
+ * Refuses anything over the ceiling rather than silently clamping: someone
+ * typing `--pause 12h` has a expectation about how long enforcement is off,
+ * and quietly giving them 8h is worse than telling them no.
+ */
+export function parsePauseDuration(input: string | undefined, ceilingMs = PAUSE_CEILING_MS): number {
+  if (input === undefined || input === "") return Math.min(PAUSE_DEFAULT_MS, ceilingMs);
+
+  const match = /^(\d+)\s*(s|m|h)?$/i.exec(input.trim());
+  if (!match) {
+    throw new Error(
+      `Invalid duration ${JSON.stringify(input)}. Use e.g. 30m, 2h, 90s (a bare number means minutes).`,
+    );
+  }
+  const value = Number(match[1]);
+  const unit = (match[2] ?? "m").toLowerCase();
+  const ms = unit === "s" ? value * 1000 : unit === "h" ? value * 3_600_000 : value * 60_000;
+
+  if (ms <= 0) throw new Error("Duration must be greater than zero.");
+  if (ms > ceilingMs) {
+    throw new Error(`Duration ${input} exceeds the maximum pause of ${formatDuration(ceilingMs)}.`);
+  }
+  return ms;
+}
+
+/** Human-readable, for CLI output and log reasons. */
+export function formatDuration(ms: number): string {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours}h` : `${hours}h${rest}m`;
+}
+
+function parseStored(raw: unknown): StoredPause | null {
+  if (!raw || typeof raw !== "object") return null;
+  const p = raw as Partial<StoredPause>;
+  if (p.schemaVersion !== SCHEMA_VERSION) return null;
+  if (typeof p.sessionId !== "string" || p.sessionId.length === 0) return null;
+  if (!Number.isFinite(p.pausedAt) || !Number.isFinite(p.expiresAt)) return null;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sessionId: p.sessionId,
+    pausedAt: p.pausedAt as number,
+    expiresAt: p.expiresAt as number,
+    setBy: typeof p.setBy === "string" ? p.setBy : "unknown",
+    ...(typeof p.cwd === "string" ? { cwd: p.cwd } : {}),
+  };
+}
+
+/**
+ * The active pause for a session, or null.
+ *
+ * Never throws: this is called on the hook path, and a malformed or unreadable
+ * state file must mean "enforcement is ON" rather than crashing the evaluation.
+ * Failing toward enforcement is the only safe direction here.
+ */
+export function readActivePause(sessionId: string | undefined, now = Date.now()): ActivePause | null {
+  if (!sessionId) return null;
+  try {
+    const path = pauseFilePath(sessionId);
+    if (!existsSync(path)) return null;
+    const stored = parseStored(JSON.parse(readFileSync(path, "utf8")));
+    if (!stored) return null;
+    if (stored.expiresAt <= now) return null; // expired — inert, not dangerous
+    const { schemaVersion: _ignored, ...pause } = stored;
+    return pause;
+  } catch {
+    return null;
+  }
+}
+
+export function writePause(opts: {
+  sessionId: string;
+  durationMs: number;
+  cwd?: string;
+  setBy?: string;
+  now?: number;
+}): ActivePause {
+  const now = opts.now ?? Date.now();
+  const pause: ActivePause = {
+    sessionId: opts.sessionId,
+    pausedAt: now,
+    expiresAt: now + opts.durationMs,
+    setBy: opts.setBy ?? "cli",
+    ...(opts.cwd ? { cwd: opts.cwd } : {}),
+  };
+  mkdirSync(pauseStateDir(), { recursive: true, mode: 0o700 });
+  writeJsonAtomically(pauseFilePath(opts.sessionId), { schemaVersion: SCHEMA_VERSION, ...pause });
+  return pause;
+}
+
+/** Returns true if a pause file was removed. */
+export function clearPause(sessionId: string): boolean {
+  const path = pauseFilePath(sessionId);
+  if (!existsSync(path)) return false;
+  try {
+    rmSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every pause that has not yet expired, newest first. Expired files are ignored. */
+export function listActivePauses(now = Date.now()): ActivePause[] {
+  const dir = pauseStateDir();
+  if (!existsSync(dir)) return [];
+  const out: ActivePause[] = [];
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const stored = parseStored(JSON.parse(readFileSync(join(dir, name), "utf8")));
+      if (!stored || stored.expiresAt <= now) continue;
+      const { schemaVersion: _ignored, ...pause } = stored;
+      out.push(pause);
+    } catch {
+      // A single unreadable file must not hide every other pause from --status.
+    }
+  }
+  return out.sort((a, b) => b.pausedAt - a.pausedAt);
+}
+
+/**
+ * The session to act on when the user names none.
+ *
+ * Whoever types the command has no session id — it exists only inside the hook
+ * payload. But every hook event already records `sessionId` alongside `cwd` and
+ * a timestamp, so the most recent session seen in this directory is derivable
+ * from data we already write. Returns null when nothing recent matches, so the
+ * caller can say so instead of guessing at a stranger's session.
+ */
+export function resolveSessionForCwd(cwd: string, maxAgeMs = 12 * 3_600_000, now = Date.now()): string | null {
+  let best: { sessionId: string; timestamp: number } | null = null;
+  let entries;
+  try {
+    entries = getAllHookActivityEntries();
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.sessionId || entry.cwd !== cwd) continue;
+    if (now - entry.timestamp > maxAgeMs) continue;
+    if (!best || entry.timestamp > best.timestamp) {
+      best = { sessionId: entry.sessionId, timestamp: entry.timestamp };
+    }
+  }
+  return best?.sessionId ?? null;
+}

package/src/hooks/tui.ts

@@ -643,3 +643,118 @@ export function multiSelect<T>(opts: MultiSelectOptions<T>): Promise<T[] | null>
           ),
   });
 }
+
+// ── promptText (single line, optionally masked) ───────────────────────────────
+
+export interface PromptTextOptions {
+  message: string;
+  /** Shown dimmed under the prompt. */
+  hint?: string;
+  /** Used when the user submits an empty line. */
+  defaultValue?: string;
+  /**
+   * Render `•` instead of the typed characters. For credentials: the wizard is
+   * routinely run while screen-sharing, and a pasted key would otherwise sit in
+   * the scrollback of every recording of that session.
+   */
+  mask?: boolean;
+  /** Return an error string to reject and re-ask, or null to accept. */
+  validate?: (value: string) => string | null;
+  stdin?: TTYIn;
+  stdout?: TTYOut;
+}
+
+/**
+ * Read one line. Resolves `null` on Ctrl-C / Escape, which every caller in the
+ * wizard treats as "cancel the whole run" — consistent with selectOne.
+ *
+ * Falls back to a plain non-TTY read so `failproofai config` still works when
+ * driven from a pipe or a test, the same way the other prompts do.
+ */
+export function promptText(opts: PromptTextOptions): Promise<string | null> {
+  const stdin: TTYIn = opts.stdin ?? process.stdin;
+  const stdout: TTYOut = opts.stdout ?? process.stdout;
+  const c = paint(colorsEnabled(stdout));
+
+  const accept = (raw: string): { ok: true; value: string } | { ok: false; error: string } => {
+    const value = raw.trim() || opts.defaultValue || "";
+    const error = opts.validate?.(value) ?? null;
+    return error ? { ok: false, error } : { ok: true, value };
+  };
+
+  if (!stdin.isTTY) {
+    // Non-TTY: read whatever is piped, validate once, no re-ask loop (there is
+    // no one to re-ask).
+    return new Promise((resolve) => {
+      let buf = "";
+      const onData = (chunk: Buffer | string) => {
+        buf += String(chunk);
+        if (buf.includes("\n")) done();
+      };
+      const done = () => {
+        stdin.removeListener("data", onData);
+        stdin.removeListener("end", done);
+        const r = accept(buf.split("\n")[0] ?? "");
+        resolve(r.ok ? r.value : null);
+      };
+      stdin.on("data", onData);
+      stdin.on("end", done);
+    });
+  }
+
+  return new Promise((resolve) => {
+    let value = "";
+    const draw = (error?: string) => {
+      const shown = opts.mask ? "•".repeat(value.length) : value;
+      const hint = opts.hint ? `  ${c.dim(opts.hint)}` : "";
+      const err = error ? `\n  ${c.warn(error)}` : "";
+      stdout.write(`\r\x1b[2K${c.bold(opts.message)} ${shown}${hint}${err}`);
+      if (err) stdout.write("\x1b[1A");
+    };
+    draw();
+
+    readline.emitKeypressEvents(stdin);
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode?.(true);
+    stdin.resume();
+
+    const cleanup = () => {
+      stdin.removeListener("keypress", onKey);
+      stdin.setRawMode?.(wasRaw ?? false);
+      stdin.pause();
+      stdout.write("\n");
+    };
+
+    function onKey(str: string | undefined, key: readline.Key): void {
+      if (!key) return;
+      if ((key.ctrl && (key.name === "c" || key.name === "d")) || key.name === "escape") {
+        cleanup();
+        resolve(null);
+        return;
+      }
+      if (key.name === "return" || key.name === "enter") {
+        const r = accept(value);
+        if (r.ok) {
+          cleanup();
+          resolve(r.value);
+        } else {
+          draw(r.error);
+        }
+        return;
+      }
+      if (key.name === "backspace") {
+        value = value.slice(0, -1);
+        draw();
+        return;
+      }
+      // Ignore control keys; accept any printable character, including a
+      // bracketed paste arriving as one chunk.
+      if (str && !key.ctrl && !key.meta) {
+        value += str;
+        draw();
+      }
+    }
+
+    stdin.on("keypress", onKey);
+  });
+}