rovecode 0.4.0-beta.2 → 0.4.0

package/src/cli/output.ts

@@ -0,0 +1,382 @@
+/** PORT #35 — machine-readable output for `rovecode run`: --output text | json | ndjson.
+ *
+ *  Ported shape decisions (pi @ 853a80d, packages/coding-agent/src):
+ *  - modes/print-mode.ts:108-111 — `--mode json` writes ONE JSON line per session event
+ *    (`JSON.stringify(toJsonEvent(event)) + "\n"` through writeRawStdout); the RPC protocol
+ *    frames its output identically (modes/rpc/rpc-mode.ts:60-62, :355-356). rovecode's ndjson mode
+ *    emits every RunEvent VERBATIM that way (no reformatting: the loop's events are already
+ *    deltas — pi's toJsonEvent only strips its cumulative partials, json-event.ts:40-45) and
+ *    closes with one {type:"result", …} line.
+ *  - core/output-guard.ts:45-70 takeOverStdout — outside the interactive TUI process.stdout.write
+ *    is redirected to stderr and only the raw writer bound BEFORE the takeover reaches fd 1
+ *    (installed for every appMode !== "interactive", main.ts:633-636). guardStdout below is that
+ *    guard; Bun's console.log does not route through process.stdout.write, so console.log/info/
+ *    debug are redirected too. stdout purity is structural, not a discipline. cmdRun installs it
+ *    right after parseOutputMode — BEFORE bootRuntime, whose session_open hooks may print — and
+ *    hands the sink the raw writer it bound first (fix-wave 4 MED-C); the sink's own install below
+ *    serves embedders that pass process.stdout itself.
+ *  - print-mode.ts:139-156 — text mode prints only the final assistant text; error/aborted →
+ *    message on stderr, exit 1 (:145-147); signals exit 128+n (:57-61: 143 SIGTERM, 129 SIGHUP).
+ *    rovecode keeps its text mode byte-identical to the pre-port cmdRun (progress lines + summary on
+ *    stdout) and maps an ABORTED run to 130 by the same 128+signal convention: the sink's signal
+ *    aborts on the first SIGINT and rides into LoopDeps.signal (port #21), so Ctrl-C ends the run
+ *    "stopped" with a well-formed result instead of a hard kill (Windows: exit 0xC000013A, no output).
+ *
+ *  Result schema (json: the ONLY stdout line; ndjson: the LAST line, with type:"result"):
+ *    status     "done" | "stopped" | "error" | "budget" — run_end.status ("error" when the loop
+ *               ended without a run_end)
+ *    summary    run_end.summary: the final assistant text, or the error text
+ *    sessionId  run_start.sessionId (null if never seen) — the store under .rovecode/sessions
+ *    model      { provider, model } requested
+ *    origin     { provider, model } that SERVED the last turn (router fallback may differ), or null
+ *    usage      { input, output, cacheRead, cacheWrite } summed over the run's assistant messages
+ *    costUsd    number, or null when any usage-bearing turn has no catalog pricing (mock, unknown
+ *               models) — an honest unknown, never a silent lower bound (core/usage.ts costUsd)
+ *    toolCalls  [{ tool, ok, ms? }] in event order, one entry per ISSUED call — keyed per
+ *               `<turn>:<callId>`, so a call id a provider reuses across turns (the SSE adapter's
+ *               `tc<idx>` fallback, providers/stream.ts) is one entry PER TURN, the telemetry/otel.ts
+ *               rovecode.tool_calls count (LOW-B, #39); ms absent for calls that never executed
+ *               (permission_denied / truncated / not_found → ok:false)
+ *    durationMs sink construction → finish
+ *    exitCode   the process exit code below
+ *  Exit codes: 0 done · 1 error / budget / no run_end · 2 usage error (bad --output value; also
+ *  the startup-error class, port #27) · 130 stopped (the run was aborted: SIGINT). Text mode keeps
+ *  its 0 done / 1 otherwise, plus 130 for the (newly reachable) aborted run. */
+
+import { format } from "node:util";
+import type { Message, ModelRef, RunEvent, RunOutstanding, StreamFn } from "../core/types.ts";
+import { outstandingClause, type LoopDeps } from "../core/loop.ts";
+import type { Runtime } from "./runtime.ts";
+import { costUsd, type PricingRow } from "../core/usage.ts";
+import { ModelCatalog } from "../providers/catalog.ts";
+import { VALUE_FLAGS } from "./dispatch.ts";
+
+export type OutputMode = "text" | "json" | "ndjson";
+export const OUTPUT_MODES: readonly OutputMode[] = ["text", "json", "ndjson"];
+export type RunEndStatus = Extract<RunEvent, { type: "run_end" }>["status"];
+type RunEnd = { status: RunEndStatus; summary: string; outstanding?: RunOutstanding };
+
+export interface RunResult {
+  status: RunEndStatus;
+  summary: string;
+  sessionId: string | null;
+  model: { provider: string; model: string };
+  origin: { provider: string; model: string } | null;
+  usage: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  costUsd: number | null;
+  toolCalls: { tool: string; ok: boolean; ms?: number }[];
+  durationMs: number;
+  exitCode: number;
+}
+
+export interface Writer { write(chunk: string): unknown }
+
+/** ModelCatalog.lookup's shape — tests inject fixed pricing. */
+export interface PricingSource { lookup(provider: string, model: string): { pricing?: PricingRow } | undefined }
+
+export interface OutputSinkOptions {
+  stdout: Writer;
+  stderr: Writer;
+  /** requested model → result.model, and the pricing fallback for origin-less messages */
+  model: ModelRef;
+  /** live view of the run's session store; read at finish (usage, origin, tool names) */
+  messages: () => Message[];
+  catalog?: PricingSource;
+  /** SIGINT hookup seam; returns the uninstaller. Default: process.once("SIGINT"). */
+  onInterrupt?: (handler: () => void) => () => void;
+}
+
+export interface OutputSink {
+  readonly mode: OutputMode;
+  /** aborts on the first SIGINT — thread into LoopDeps.signal so the run ends "stopped" (130) */
+  readonly signal: AbortSignal;
+  onEvent(ev: RunEvent): void;
+  /** After the loop settles: writes the text summary / the json result / the ndjson result line
+   *  and returns the exit code. No `end` = the loop ended without run_end → status "error", 1. */
+  finish(end?: RunEnd): number;
+  /** Uninstalls the stdout guard (installed for json/ndjson over the REAL process.stdout; a no-op
+   *  otherwise) so console.log / process.stdout.write reach fd 1 again — for embedders and tests.
+   *  cmdRun never calls it: hooks.close()/mcp.close() run AFTER finish and may still print, so the
+   *  guard must hold until process.exit. */
+  close(): void;
+}
+
+// ---------- argv ----------
+
+const USAGE = "--output <mode>: text (default) | json | ndjson";
+
+const usageExit = (msg: string): never => {
+  process.stderr.write(`error: ${msg} — ${USAGE}\n`);
+  return process.exit(2);
+};
+
+function isOutputMode(v: string): v is OutputMode {
+  return (OUTPUT_MODES as readonly string[]).includes(v);
+}
+
+/** `--output <mode>` or `--output=<mode>`, anywhere in argv (dispatch.ts VALUE_FLAGS keeps the
+ *  value from being taken for the command). Missing or unknown value → one-line stderr usage
+ *  error, exit 2 (the usage/startup-error class; `fail` is injectable for tests). Last one wins.
+ *  cmdRun calls this FIRST — before bootRuntime — so a usage error leaves no trace: no
+ *  .rovecode/sessions/<id> (meta.json, memory dir), no sandbox probe, no MCP children to reap. */
+export function parseOutputMode(argv: readonly string[], fail: (msg: string) => never = usageExit): OutputMode {
+  const args = argv.slice(2);
+  let mode: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--output") {
+      const v = args[++i];
+      if (v === undefined || v.startsWith("-")) return fail("--output needs a value");
+      mode = v;
+    } else if (a.startsWith("--output=")) {
+      mode = a.slice("--output=".length);
+    }
+  }
+  if (mode === undefined) return "text";
+  return isOutputMode(mode) ? mode : fail(`unknown --output mode "${mode}"`);
+}
+
+/** The one-shot prompt words for cmdRun. parseCli's `rest` keeps a POST-command value flag's
+ *  value (its contract — owners drop their own, like cmdAuth's --key and export.ts's --out), so
+ *  `rovecode run "hi" --output json` arrives as rest ["hi", "json"]. The token that followed --output
+ *  is removed by POSITION, never by value (a prompt may legitimately contain the word "json"). A
+ *  pre-command --output value never enters rest; a dangling --output is parseOutputMode's error. */
+export function runPromptWords(cli: { cmd: string; rest: string[] }, argv: readonly string[]): string[] {
+  const words = cli.cmd === "run" ? [...cli.rest] : [cli.cmd, ...cli.rest]; // bare prompt keeps cmd as word 0
+  const args = argv.slice(2);
+  const isFlag = (a: string) => a.startsWith("-");
+  const cmdIdx = args.findIndex((a, i) => !isFlag(a) && !(i > 0 && VALUE_FLAGS.has(args[i - 1]!)));
+  if (cmdIdx === -1) return words;
+  // words = the non-flag tokens from `from` on; a value's word index = the non-flag tokens before it.
+  // EVERY value flag's value, not only --output's: `rovecode run "hi" --max-turns 1` used to send the prompt
+  // "hi 1" — the ceiling's number rode into the words because only --output dropped its own.
+  const from = cli.cmd === "run" ? cmdIdx + 1 : cmdIdx;
+  const drop: number[] = [];
+  args.forEach((a, oi) => {
+    const value = args[oi + 1];
+    if (!VALUE_FLAGS.has(a) || oi < cmdIdx || value === undefined || isFlag(value)) return;
+    drop.push(args.slice(from, oi + 1).filter((t) => !isFlag(t)).length);
+  });
+  for (const k of drop.reverse()) words.splice(k, 1); // descending: earlier indexes stay valid
+  return words;
+}
+
+// ---------- piped stdin (`git diff | rovecode run "review this"`) ----------
+
+/** What a pipe on stdin handed us, or "" — never from a terminal, and never waited on forever.
+ *
+ *  The one hazard: stdin that is not a TTY and not a pipe anybody writes to — a child spawned with an
+ *  inherited-but-idle handle, an agent's own bash tool running `rovecode run`. `readFileSync(0)` there
+ *  blocks until something closes the handle, which may be never. So the first byte gets a deadline
+ *  (default 3 s): nothing by then means nothing is coming, a note says so, and the run proceeds with the
+ *  prompt alone. A producer that HAS started is read to EOF however long it takes — the deadline is on the
+ *  first byte, not the whole stream. Bounded at `maxChars` (1 MB of text) with a note, because a 200 MB log
+ *  piped in by accident should not become one 200 MB prompt. */
+export async function readPipedStdin(
+  stdin: NodeJS.ReadableStream & { isTTY?: boolean; pause?: () => unknown; resume?: () => unknown },
+  opts: { firstByteMs?: number; maxChars?: number; note?: (line: string) => void } = {},
+): Promise<string> {
+  if (stdin.isTTY === true) return "";
+  const firstByteMs = opts.firstByteMs ?? 3_000;
+  const maxChars = opts.maxChars ?? 1_000_000;
+  return new Promise<string>((resolve) => {
+    const chunks: Buffer[] = [];
+    let got = false, done = false;
+    const finish = (): void => {
+      if (done) return;
+      done = true; clearTimeout(timer);
+      const text = Buffer.concat(chunks).toString("utf8");
+      if (text.length > maxChars) opts.note?.(`stdin: ${text.length.toLocaleString("en-US")} characters piped in — kept the first ${maxChars.toLocaleString("en-US")}`);
+      resolve(text.slice(0, maxChars));
+    };
+    const timer = setTimeout(() => {
+      if (got || done) return;
+      opts.note?.(`stdin: not a terminal, but nothing arrived in ${firstByteMs / 1000} s — ignored (pipe your input, or pass --no-stdin)`);
+      try { stdin.pause?.(); } catch { /* nothing to pause */ }
+      finish();
+    }, firstByteMs);
+    stdin.on("data", (c: Buffer | string) => { got = true; chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)); });
+    stdin.on("end", finish);
+    stdin.on("close", finish);
+    stdin.on("error", finish);
+    try { stdin.resume?.(); } catch { finish(); }
+  });
+}
+
+/** The prompt with the piped text under it as a fenced block. The fence grows until it cannot occur inside the
+ *  text (a diff of a markdown file carries ``` of its own). No words → "Here is the input:" introduces the
+ *  block, so the model is never handed a bare fence. Empty pipe → the prompt unchanged. */
+export function withPipedInput(prompt: string, piped: string): string {
+  const text = piped.replace(/\r\n?/g, "\n").replace(/\n+$/, "");
+  if (text.length === 0) return prompt;
+  let fence = "```";
+  while (text.includes(fence)) fence += "`";
+  const head = prompt.trim().length > 0 ? prompt.trim() : "Here is the input:";
+  return `${head}\n\n${fence}\n${text}\n${fence}`;
+}
+
+// ---------- stdout guard (pi core/output-guard.ts:45-70) ----------
+
+/** Redirect every stray stdout writer — console.log/info/debug (Bun writes them natively, not via
+ *  process.stdout.write) and process.stdout.write itself — to `stderr`, so only a writer bound
+ *  BEFORE the guard can reach fd 1. Returns the restorer. */
+export function guardStdout(stderr: Writer): { restore(): void } {
+  const saved = { log: console.log, info: console.info, debug: console.debug, write: process.stdout.write };
+  const toErr = (...args: unknown[]): void => { stderr.write(`${format(...args)}\n`); };
+  console.log = toErr; console.info = toErr; console.debug = toErr;
+  process.stdout.write = ((chunk: string | Uint8Array): boolean => {
+    stderr.write(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+  return {
+    restore() {
+      console.log = saved.log; console.info = saved.info; console.debug = saved.debug;
+      process.stdout.write = saved.write;
+    },
+  };
+}
+
+// ---------- exit codes ----------
+
+/** 0 done · 130 stopped (loop.ts yields "stopped" ONLY on abort — :133/:219/:302) · 1 otherwise. */
+export function exitCodeFor(status: RunEndStatus | undefined): number {
+  if (status === "done") return 0;
+  if (status === "stopped") return 130;
+  return 1;
+}
+
+// ---------- sink ----------
+
+const installSigint = (handler: () => void): (() => void) => {
+  // once: the first Ctrl-C aborts the run (a well-formed result follows); the second is the
+  // platform default again (hard exit), so a signal-deaf tool cannot hold the terminal hostage
+  try { process.once("SIGINT", handler); } catch { return () => {}; }
+  return () => { try { process.off("SIGINT", handler); } catch { /* already gone */ } };
+};
+
+/** one issued call; `id` = the provider's call id (the store's tool_call part id — the name fallback) */
+type CallRecord = { id: string; tool?: string; ok: boolean; ms?: number };
+
+export function createOutputSink(mode: OutputMode, opts: OutputSinkOptions): OutputSink {
+  const t0 = Date.now();
+  // bind the raw writer BEFORE guarding: the guard turns process.stdout.write into a stderr relay
+  const real = opts.stdout === process.stdout;
+  const out: Writer = real ? { write: process.stdout.write.bind(process.stdout) } : opts.stdout;
+  const guard = mode !== "text" && real ? guardStdout(opts.stderr) : null;
+  const ac = new AbortController();
+  const uninstall = (opts.onInterrupt ?? installSigint)(() => ac.abort());
+  let sessionId: string | null = null;
+  let baseline = 0; // store length at run_start — only THIS run's messages are accounted
+  let turn = 0; // the issuing turn: a turn's tool events follow its turn_end (loop.ts:232 → :295)
+  // issued calls by `<turn>:<callId>` in event order (the telemetry/otel.ts toolKey idiom): a call id a
+  // provider reuses across turns is one call PER TURN, never a merge — keyed by callId alone, `same`
+  // issued by 3 turns was ONE toolCall while rovecode.tool_calls said 3 (LOW-B, #39)
+  const calls = new Map<string, CallRecord>();
+  const call = (id: string): CallRecord => {
+    const key = `${turn}:${id}`;
+    const c = calls.get(key) ?? { id, ok: false };
+    calls.set(key, c);
+    return c;
+  };
+  // human progress: stdout in text mode (byte-identical to the pre-port console.log lines),
+  // stderr in json mode (a terminal user still sees progress; stdout stays the one object),
+  // nothing extra in ndjson mode (the event stream IS the progress)
+  const human = (line: string): void => {
+    if (mode === "text") out.write(`${line}\n`);
+    else if (mode === "json") opts.stderr.write(`${line}\n`);
+  };
+  return {
+    mode, signal: ac.signal,
+    onEvent(ev) {
+      if (mode === "ndjson") out.write(`${JSON.stringify(ev)}\n`);
+      if (ev.type === "run_start") { sessionId = ev.sessionId; baseline = opts.messages().length; }
+      else if (ev.type === "turn_start") turn = ev.turn;
+      else if (ev.type === "tool_execution_start") {
+        call(ev.callId).tool = ev.tool;
+        human(`→ ${ev.tool} ${String(JSON.stringify(ev.args)).slice(0, 100)}`);
+      } else if (ev.type === "tool_execution_end") {
+        Object.assign(call(ev.callId), { ok: ev.ok, ms: ev.durationMs });
+        human(`← ${ev.ok ? "ok" : "FAIL"} ${ev.output.slice(0, 200).replace(/\n/g, " ⏎ ")}`);
+      } else if (ev.type === "tool_call_failed") {
+        call(ev.callId).ok = false;
+      } else if (ev.type === "verify") {
+        // the verify gate, in the same two-line shape as a tool call: what runs, then how it ended
+        human(ev.state === "running" ? `→ verify ${ev.command.slice(0, 100)}` : `← ${ev.state === "passed" ? "ok" : "FAIL"} verify ${ev.detail ?? ev.state}`);
+      }
+    },
+    finish(end) {
+      uninstall();
+      const exitCode = exitCodeFor(end?.status);
+      if (mode === "text") {
+        if (end) out.write(`\n${end.summary}\n`);
+        // "done" is the model's silence, not a verdict: one clause says what the transcript says was left
+        // (a failed call never recovered, an unanswered question, open todos). A run that only answered a
+        // question carries no `outstanding` at all and prints exactly the bytes it always did.
+        if (end?.status === "done" && end.outstanding) {
+          const clause = outstandingClause(end.outstanding);
+          if (clause !== null) out.write(`done · ${clause}\n`);
+        }
+        return exitCode;
+      }
+      const result = summarize(
+        end ?? { status: "error", summary: "stream ended without run_end" }, exitCode, sessionId, opts.model,
+        opts.messages().slice(baseline), [...calls.values()], opts.catalog ?? new ModelCatalog(), Date.now() - t0,
+      );
+      out.write(`${JSON.stringify(mode === "json" ? result : { type: "result", ...result })}\n`);
+      return exitCode;
+    },
+    close() { guard?.restore(); },
+  };
+}
+
+// ---------- run deps ----------
+
+/** cmdRun's LoopDeps, built in one place so the wiring is unit-testable (LOW-2): the runtime's
+ *  registry/store/tools, guard (port #4), cwd (port #26) and hooks (port #29), with the sink's
+ *  SIGINT signal (port #21) — the fields agentLoop reads. Same object literal cmdRun used to inline,
+ *  evaluated at the same argument position (tools listed at call time). */
+export function buildRunDeps(rt: Pick<Runtime, "registry" | "store" | "guard" | "planReminder" | "cwd" | "hooks">, stream: StreamFn, sink: Pick<OutputSink, "signal">): LoopDeps {
+  return { stream, registry: rt.registry, store: rt.store, tools: rt.registry.list().map((t) => t.schema), guard: rt.guard, planReminder: rt.planReminder, cwd: rt.cwd, signal: sink.signal, hooks: rt.hooks };
+}
+
+function summarize(
+  end: RunEnd, exitCode: number, sessionId: string | null, model: ModelRef, msgs: Message[],
+  calls: CallRecord[], catalog: PricingSource, durationMs: number,
+): RunResult {
+  const assistants = msgs.filter((m) => m.role === "assistant");
+  const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let cost: number | null = 0;
+  for (const m of assistants) {
+    const u = m.usage;
+    if (!u) continue;
+    const n = { input: u.input, output: u.output, cacheRead: u.cacheRead ?? 0, cacheWrite: u.cacheWrite ?? 0 };
+    usage.input += n.input; usage.output += n.output; usage.cacheRead += n.cacheRead; usage.cacheWrite += n.cacheWrite;
+    if (cost === null || (n.input === 0 && n.output === 0 && n.cacheRead === 0 && n.cacheWrite === 0)) continue;
+    // priced PER MESSAGE at the model that served it (Message.origin — the tui/cost.ts idiom)
+    const o = m.origin ?? model;
+    const pricing = catalog.lookup(o.provider, o.model)?.pricing;
+    const c = pricing ? costUsd(n, pricing) : undefined;
+    cost = c === undefined ? null : cost + c;
+  }
+  // names for calls that never started (denied/truncated/not_found) come from the tool_call parts, paired
+  // by OCCURRENCE — the n-th record with a call id ↔ the n-th part carrying it (one part per issued call),
+  // so a reused id names each turn's own call rather than the last part that mentioned the id
+  const names = new Map<string, string[]>();
+  for (const m of assistants) for (const p of m.parts) if (p.kind === "tool_call") names.set(p.id, [...(names.get(p.id) ?? []), p.tool]);
+  const nth = new Map<string, number>();
+  const served = assistants.at(-1)?.origin;
+  return {
+    status: end.status, summary: end.summary, sessionId,
+    // what "done" left behind (core/loop.ts assessOutstanding): failed tool calls in the last turn, an
+    // unanswered ask_user, successful edit/write count, open todos, whether the finish check asked once
+    ...(end.outstanding ? { outstanding: end.outstanding } : {}),
+    model: { provider: model.provider, model: model.model },
+    origin: served ? { provider: served.provider, model: served.model } : null,
+    usage, costUsd: cost,
+    toolCalls: calls.map((c) => {
+      const n = nth.get(c.id) ?? 0; nth.set(c.id, n + 1);
+      return { tool: c.tool ?? names.get(c.id)?.[n] ?? "unknown", ok: c.ok, ...(c.ms !== undefined ? { ms: c.ms } : {}) };
+    }),
+    durationMs, exitCode,
+  };
+}

package/src/cli/repl.ts

@@ -0,0 +1,172 @@
+/** Interactive agent chat (omp/claude-code style): persistent session, streaming
+ *  output, y/n/a approvals, slash commands. Bare `rovecode` drops here. */
+
+import readline from "node:readline";
+import { agentLoop } from "../core/loop.ts";
+import { resetTurnFailureCount } from "../memory/tools.ts";
+import type { ApprovalFn, RunEvent } from "../core/types.ts";
+import type { AskFn } from "../tools/ask-user.ts";
+import { bootRuntime, NO_PROVIDER_HINT } from "./runtime.ts";
+import { modeSwitchNote } from "../core/voice.ts";
+import { SandboxConfigError, describeSandbox } from "../core/sandbox-config.ts";
+
+export interface ReplState {
+  yolo: boolean;
+  provider: string;
+  model: string;
+  turns: number;
+  tokensIn: number;
+  tokensOut: number;
+}
+
+function ask(rl: readline.Interface, q: string): Promise<string> {
+  return new Promise((res) => rl.question(q, (a) => res(a.trim().toLowerCase())));
+}
+
+/** port #33: the `--plain` asker behind ask_user — `--plain` HAS a human (the y/n/a approvals prove
+ *  it), headless surfaces leave the tool unbound and it fails closed. Numbered options plus free text
+ *  when allowed: a number picks, other text is the typed answer, an empty line declines (null). Piped
+ *  stdin is fine — it just consumes the next line. The run's abort resolves null AND is handed to
+ *  rl.question itself (WIRE-1 LOW): an aborted question's callback is DISARMED, so the user's next
+ *  line is a normal `line` event again instead of being swallowed by the dead callback. `out` is
+ *  console.log; tests capture it. */
+export function readlineAsker(rl: readline.Interface, out: (line: string) => void = console.log): AskFn {
+  return (q, signal) => new Promise((resolve) => {
+    const options = q.options ?? [];
+    const free = q.allowFreeText !== false;
+    out(`\n  question: ${q.question}`);
+    options.forEach((o, i) => out(`    ${i + 1}) ${o}`));
+    const hint = [options.length > 0 ? `1-${options.length}` : "", free ? "text" : ""].filter(Boolean).join(" or ");
+    const onAbort = (): void => { resolve(null); };
+    signal.addEventListener("abort", onAbort, { once: true });
+    rl.question(`  answer [${hint}; empty = decline]: `, { signal }, (line) => {
+      signal.removeEventListener("abort", onAbort);
+      const a = line.trim();
+      const n = Number(a);
+      if (a === "") resolve(null);
+      else if (Number.isInteger(n) && n >= 1 && n <= options.length) resolve({ choice: n - 1, label: options[n - 1] });
+      else if (free) resolve({ text: a });
+      else { out("  (not one of the options — declined)"); resolve(null); }
+    });
+  });
+}
+
+export async function runRepl( /* eslint-disable-line complexity */
+  opts: { yolo?: boolean; model?: string } = {},
+): Promise<void> {
+  // port #27: sandbox misconfig / unavailable configured rung → one-line startup error, exit 2
+  const rt = await bootRuntime().catch((e: unknown): never => {
+    if (e instanceof SandboxConfigError) { console.error(`error: ${e.message}`); process.exit(2); }
+    throw e;
+  });
+
+  const state: ReplState = {
+    yolo: opts.yolo ?? process.env.ROVECODE_YOLO === "1",
+    provider: "mock",
+    model: opts.model ?? process.env.ROVECODE_MODEL ?? "",
+    turns: 0, tokensIn: 0, tokensOut: 0,
+  };
+
+  // the registry is live: `rovecode provider add …` / `rovecode auth set …` from another terminal is
+  // picked up on the next line — no restart and no ad-hoc base-url prompt here
+  const stream = rt.stream ?? undefined;
+  const adoptDefault = (): void => {
+    const d = rt.providers.defaultRef();
+    if (d !== null) { state.provider = d.provider; state.model = state.model || d.model || "gpt-4o-mini"; }
+  };
+  adoptDefault();
+  if (state.provider === "mock") console.log(NO_PROVIDER_HINT);
+  rt.hooks.onWarning((w) => console.error(`hooks: ${w}`)); // port #29: load + runtime hook notes → stderr (cmdRun idiom)
+
+  console.log(`◆ rovecode here — plain chat with ${state.provider}/${state.model}`);
+  console.log(`session ${rt.sessionId.slice(0, 8)} in ${rt.cwd}`);
+  console.log(modeSwitchNote(state.yolo));
+  console.log(`commands: /exit /new /yolo /model <provider/model> /status /skills /memory`);
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: "rovecode> " });
+
+  rt.setAskUser(readlineAsker(rl)); // port #33: ask_user over the same readline (readlineAsker above)
+
+  const approval: ApprovalFn = async (req) => {
+    const argPreview = JSON.stringify(req.revisedArgs).slice(0, 140);
+    console.log(`\n  approval needed: ${req.tool} ${argPreview}`);
+    const a = await ask(rl, "  allow? [y]es / [a]lways / [n]o: ");
+    return a === "a" ? "always" : a === "n" || a === "" ? "deny" : "once";
+  };
+
+  rl.prompt();
+
+  // port #21: one AbortController per run — Ctrl+C mid-run aborts the in-flight
+  // fetch/tools for real (abort first, then return() settles the generator); idle
+  // Ctrl+C keeps its old meaning (close the repl)
+  let running: { ac: AbortController; gen: AsyncGenerator<RunEvent> } | null = null;
+  rl.on("SIGINT", () => {
+    if (running) { running.ac.abort(); void running.gen.return(undefined as never); console.log("\n  [interrupted]"); }
+    else rl.close();
+  });
+
+  rl.on("line", async (line) => {
+    const text = line.trim();
+    if (!text) { rl.prompt(); return; }
+    if (text === "/exit" || text === "/quit") { rl.close(); return; }
+    if (text === "/yolo") { state.yolo = !state.yolo; console.log(modeSwitchNote(state.yolo)); rl.prompt(); return; }
+    if (text === "/status") { console.log(`provider=${state.provider} model=${state.model} turns=${state.turns} tokens=${state.tokensIn}in/${state.tokensOut}out\nsandbox: ${describeSandbox(rt.sandbox)}`); rl.prompt(); return; }
+    if (text === "/skills") { for (const s of rt.skillStore.list()) console.log(`  ${s.name.padEnd(20)} ${s.description}`); rl.prompt(); return; }
+    if (text === "/memory") { console.log(rt.blockStore.renderForPrompt() || "(empty)"); rl.prompt(); return; }
+    if (text.startsWith("/model ")) {
+      const ref = rt.providers.resolveSelector(text.slice(7), state.provider);
+      if ("error" in ref) console.log(ref.error); else { state.provider = ref.provider; state.model = ref.model; console.log(`model → ${ref.provider}/${ref.model}`); }
+      rl.prompt(); return;
+    }
+    if (text === "/new") { rt.store.branch(rt.store.messages()[0]?.id ?? ""); console.log("branched to session start"); rl.prompt(); return; }
+
+    const reason = rt.noProviderReason(); // live — a provider added since boot is picked up here
+    if (!stream || reason !== null) { console.log(reason ?? "no provider stream"); rl.prompt(); return; }
+    if (state.provider === "mock") adoptDefault();
+
+    const def = rt.buildDef({ provider: state.provider, model: state.model });
+
+    const ac = new AbortController();
+    rt.tasks.bindRun(ac.signal); // port #26: Ctrl-C (ac.abort above) also cancels the background tasks this run started
+    // port #29: hooks ride the deps like every surface; port #26: the runtime's ONE steering queue (not a
+    // fresh one) so background-task completion notes — and any hook-pushed steer — reach the next turn
+    const gen = agentLoop(def, text, {}, rt.buildCfg(state.yolo, approval), { stream, registry: rt.registry, store: rt.store, tools: rt.registry.list().map((t) => t.schema), guard: rt.guard, planReminder: rt.planReminder, cwd: rt.cwd, signal: ac.signal, hooks: rt.hooks }, rt.steering);
+    running = { ac, gen };
+    try {
+      let live = "";
+      for await (const ev of gen) {
+        if (ev.type === "turn_start") { resetTurnFailureCount(); state.turns++; }
+        if (ev.type === "message_update") { process.stdout.write(ev.delta); live += ev.delta; }
+        if (ev.type === "tool_execution_start") { console.log(`\n  → ${ev.tool} ${JSON.stringify(ev.args).slice(0, 120)}`); }
+        if (ev.type === "tool_execution_end") { console.log(`  ← ${ev.ok ? "ok" : "FAIL"} ${ev.output.slice(0, 160).replace(/\n/g, " ⏎ ")}`); }
+        if (ev.type === "run_end") {
+          if (!live.trim()) console.log(ev.summary);
+          else console.log();
+          if (ev.status !== "done") console.log(`  [${ev.status}]`);
+        }
+      }
+      for (const n of rt.drainRouterNotes()) console.log(`  [${n}]`); // port #14 fallback advances
+      for (const m of rt.store.messages()) if (m.usage) { state.tokensIn += m.usage.input; state.tokensOut += m.usage.output; }
+    } catch (e) {
+      console.log(`error: ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      running = null;
+    }
+    rl.prompt();
+  });
+
+  // every quit path lands here (Ctrl+D, /exit, /quit, idle Ctrl+C → rl.close()), so this is the ONE exit
+  rl.on("close", async () => {
+    // port #29: a run still in flight dies with the surface (abort, then let its generator settle) BEFORE
+    // session_close fires once — after in-flight on_event taps drained (hooks.close() waits for them)
+    if (running) { running.ac.abort(); await running.gen.return(undefined as never).catch(() => {}); }
+    // port #26: quitting leaves no background children — their runs (and subprocess trees) die
+    // now and settle, bounded, before the process goes (same policy as cmdRun's exit())
+    rt.tasks.cancelAll();
+    await rt.tasks.drain(2_000);
+    await rt.hooks.close().catch(() => {});
+    void rt.mcp?.close().catch(() => {}); // kill MCP child processes (TUI does the same in app.ts)
+    console.log(`\nbye — session ${rt.sessionId.slice(0, 8)} saved (${state.turns} turns, ${state.tokensIn}in/${state.tokensOut}out tokens)`);
+    process.exit(0);
+  });
+}

package/src/cli/resume.ts

@@ -0,0 +1,32 @@
+/** Which session `rovecode` reopens at boot, from argv.
+ *
+ *  Three spellings, one rule — an explicit id always wins:
+ *    rovecode --resume <id>     that session (a unique prefix resolves in the TUI, session-cmd.ts resolveBootSession)
+ *    rovecode --resume          the newest session that holds something
+ *    rovecode --continue        the same — the flag every CLI that got this right converged on
+ *  `--resume` followed by another flag (`rovecode --resume --yolo`) is `--resume` with no id, never "resume the
+ *  session named --yolo". With nothing to continue from, the answer is undefined and the TUI starts fresh, as
+ *  it always did; that is the honest outcome, not an error. */
+
+import { newestSession } from "../core/session.ts";
+
+export interface ResumeRequest {
+  /** the id or prefix the user named */
+  id?: string;
+  /** `--continue`, or `--resume` with no id: reopen the newest non-empty session */
+  newest: boolean;
+}
+
+export function parseResume(argv: readonly string[]): ResumeRequest {
+  const ix = argv.indexOf("--resume");
+  const arg = ix !== -1 ? argv[ix + 1] : undefined;
+  const id = arg !== undefined && !arg.startsWith("-") ? arg : undefined;
+  return { ...(id !== undefined ? { id } : {}), newest: id === undefined && (ix !== -1 || argv.includes("--continue")) };
+}
+
+/** The session id to boot with, or undefined for a fresh one. */
+export function resolveResume(argv: readonly string[], sessionsDir: string): string | undefined {
+  const r = parseResume(argv);
+  if (r.id !== undefined) return r.id;
+  return r.newest ? newestSession(sessionsDir)?.id : undefined;
+}