rovecode 0.4.0-beta.3 → 0.4.0

package/src/tui/cost.ts

@@ -0,0 +1,108 @@
+/** /cost note body (ports #5+#6), extracted from app.ts for the ADR-002 line cap.
+ *  Usage is priced PER MESSAGE at the model recorded in Message.origin —
+ *  a session that switched models mid-way is not silently re-priced at the current model.
+ *  Messages without an origin fall back to the current model WITH an explicit caveat; messages
+ *  whose model has no catalog pricing are excluded and flagged (cost becomes a lower bound).
+ *  Context health counts ALL parts (partsTokenText): tool calls/results dominate agentic
+ *  sessions, and a text-only count reads ~0% forever.
+ *  Port #44: the same math feeds the sextant usage panel through sessionUsage(). */
+
+import { partsTokenText } from "../core/loop.ts";
+import { ModelCatalog, ratesFor } from "../providers/catalog.ts";
+import { contextHealth, costUsdTiered, countTokens, countTokensIfLoaded } from "../core/usage.ts";
+import { estimateTokens } from "../core/context.ts";
+import { tokenScaleFor } from "../core/token-scale.ts";
+import type { Message } from "../core/types.ts";
+
+export interface UsageSummary {
+  inTok: number; outTok: number; cacheRead: number; cacheWrite: number;
+  /** USD over the priced messages; `priced`/`unpriced`/`noOrigin` say how much of the transcript it covers */
+  cost: number; priced: number; unpriced: number; noOrigin: number;
+  /** estimated prompt tokens, corrected towards the current model's own tokenizer, and the catalog's
+   *  window when it knows one. `estRaw` is the uncorrected count the correction was applied to, and
+   *  `counter` says which estimator produced it — both are estimates, with different measured errors
+   *  (core/token-scale.ts): "o200k" is countTokens (exact for OpenAI models), "chars" is estimateTokens
+   *  (chars/4, what compaction budgets with). The scale applied is the one measured for that counter. */
+  est: number; estRaw: number; counter: "o200k" | "chars"; scale: { scale: number; measured: boolean; note: string }; window?: number;
+}
+
+export interface SummarizeOptions {
+  /** "exact": count with o200k, loading its table if it is not resident (385–520 ms and ~136 MB the
+   *  first time — fine for /cost, which a person asked for). "cheap": o200k only if the table is already
+   *  resident, else chars/4 — for the sextant usage panel, which is computed at boot and after every
+   *  turn and must never be the reason the table loads. Default "exact". */
+  counter?: "exact" | "cheap";
+}
+
+export function summarizeUsage(messages: Message[], catalog: ModelCatalog, current: { provider: string; model: string }, opts: SummarizeOptions = {}): UsageSummary {
+  const u: UsageSummary = { inTok: 0, outTok: 0, cacheRead: 0, cacheWrite: 0, cost: 0, priced: 0, unpriced: 0, noOrigin: 0, est: 0, estRaw: 0, counter: "o200k", scale: { scale: 1, measured: false, note: "" } };
+  for (const m of messages) {
+    const usage = m.usage;
+    if (!usage) continue;
+    u.inTok += usage.input; u.outTok += usage.output;
+    u.cacheRead += usage.cacheRead ?? 0; u.cacheWrite += usage.cacheWrite ?? 0;
+    if (usage.input === 0 && usage.output === 0 && !usage.cacheRead && !usage.cacheWrite) continue; // nothing to price
+    if (!m.origin) u.noOrigin += 1;
+    const origin = m.origin ?? current;
+    const info = catalog.lookup(origin.provider, origin.model);
+    const n = { input: usage.input, output: usage.output, cacheRead: usage.cacheRead ?? 0, cacheWrite: usage.cacheWrite ?? 0 };
+    // the prompt this turn actually carried decides the rate on a tiered model: xAI and Google bill a
+    // prompt over 200k at the upper rate — xAI for the whole request. A flat model's breakdown is trivial.
+    const c = info?.pricing
+      ? costUsdTiered(n, ratesFor(info, n.input + n.cacheRead + n.cacheWrite))
+      : undefined;
+    if (c === undefined) u.unpriced += 1;
+    else { u.cost += c; u.priced += 1; }
+  }
+  const window = catalog.lookup(current.provider, current.model)?.contextWindow;
+  if (window) u.window = window;
+  const text = messages.map((m) => partsTokenText(m.parts)).join("\n");
+  const exact = opts.counter === "cheap" ? countTokensIfLoaded(text) : countTokens(text);
+  // Neither counter is this model's tokenizer (o200k is OpenAI's; chars/4 is nobody's). `rovecode context`
+  // has corrected for that since the factors were measured; this panel had not, so the live meter a user
+  // actually watches read up to 1.8x low on Claude 5 — the worst place for it, because this is the number
+  // you look at to decide whether there is room for another turn. Each counter gets ITS OWN measured
+  // factor: the chars/4 error is not the o200k error (token-scale.ts charScale).
+  const ts = tokenScaleFor(current);
+  if (exact !== null) {
+    u.counter = "o200k"; u.estRaw = exact;
+    u.scale = { scale: ts.scale, measured: ts.measured, note: ts.note };
+  } else {
+    u.counter = "chars"; u.estRaw = estimateTokens(text);
+    u.scale = { scale: ts.charScale, measured: ts.measured, note: ts.note };
+  }
+  u.est = Math.ceil(u.estRaw * u.scale.scale);
+  return u;
+}
+
+/** the sextant usage panel's numbers: cost = the priced lower bound (null until something is priced), context = the
+ *  estimate. Runs at boot and after every turn, so it is the "cheap" counter: the panel's "estimated context fill"
+ *  is chars/4 × the model's measured char factor until someone loads the o200k table (/cost, /context), and the
+ *  o200k figure from then on. Both are estimates; neither is ever presented as the provider's count — that is
+ *  drift() in core/context-report.ts, which counts exactly and compares against what the provider reported. */
+export function sessionUsage(messages: Message[], catalog: ModelCatalog, current: { provider: string; model: string }): { costUsd: number | null; contextTokens: number; counter: "o200k" | "chars" } {
+  const u = summarizeUsage(messages, catalog, current, { counter: "cheap" });
+  return { costUsd: u.priced > 0 ? u.cost : null, contextTokens: u.est, counter: u.counter };
+}
+
+export function buildCostNote(messages: Message[], catalog: ModelCatalog, current: { provider: string; model: string }): string {
+  const u = summarizeUsage(messages, catalog, current);
+  const health = u.window ? contextHealth(u.est, u.window) : undefined;
+  let costLine: string;
+  if (u.priced === 0 && u.unpriced > 0) {
+    costLine = `pricing unknown for ${current.provider}/${current.model}`;
+  } else {
+    costLine = `estimated cost: $${u.cost.toFixed(4)}`;
+    if (u.unpriced > 0) costLine += ` — ${u.unpriced} message${u.unpriced > 1 ? "s" : ""} unpriced (lower bound)`;
+    if (u.noOrigin > 0) costLine += ` — ${u.noOrigin} without origin priced at the current model`;
+  }
+  return [
+    `tokens: ${u.inTok} in / ${u.outTok} out · cache: ${u.cacheRead} read / ${u.cacheWrite} written`,
+    health
+      ? `context: ~${u.est} of ${u.window} (${Math.round(health.fraction * 100)}%${health.nearLimit ? " — near limit" : ""})`
+      : `context: ~${u.est} tokens (window unknown)`,
+    // a corrected number that does not say it was corrected is indistinguishable from a wrong one
+    ...(u.scale.scale !== 1 ? [`  ${u.counter === "o200k" ? "o200k counted" : "chars/4 estimated"} ${u.estRaw}, scaled ${u.scale.scale}× for ${current.model}`] : []),
+    costLine,
+  ].join("\n");
+}

package/src/tui/info-cmd.ts

@@ -0,0 +1,144 @@
+/** TUI info commands, extracted from app.ts for the ADR-002 cap (wiring pass): /help /status
+ *  /cost /skills /memory /export read state and print a note; /todos (port #32) and /tasks
+ *  (port #26) surface the agent-maintained lists. Nothing here moves the session leaf — the
+ *  CALLER owns the swappable store/blocks and the status slice, so every read runs through
+ *  the injected ctx (same shape as session-cmd / checkpoints-cmd). */
+
+import type { Runtime } from "../cli/runtime.ts";
+import { exportSession } from "../cli/export.ts";
+import { describeSandbox } from "../core/sandbox-config.ts";
+import type { SessionStore } from "../core/session.ts";
+import { formatTaskList, isTerminal } from "../core/tasks.ts";
+import type { BlockStore } from "../memory/blocks.ts";
+import type { ModelCatalog } from "../providers/catalog.ts";
+import { loadTodos, renderTodos, todoStatusLabel } from "../tools/todo.ts";
+import { helpForCommands, type CustomCommand } from "./commands.ts";
+import { buildCostNote } from "./cost.ts";
+import type { Renderer, SlashCommand } from "./renderer.ts";
+import { join } from "node:path";
+
+export interface InfoStateSlice { provider: string; model: string; turns: number; tokensIn: number; tokensOut: number }
+
+export interface InfoCmdCtx {
+  renderer: Renderer;
+  /** the runtime slices the info commands read: cwd, config provenance, sandbox rung, skills, tasks */
+  rt: Pick<Runtime, "cwd" | "projectContext" | "sandbox" | "skillStore" | "tasks">;
+  /** <cwd>/.rovecode/sessions — todos.json lives under <sessionsDir>/<session id> */
+  sessionsDir: string;
+  /** the ACTIVE session store, read live (/sessions and a root /rewind swap it) */
+  store(): SessionStore;
+  /** the ACTIVE memory block store, read live (swapped with the session) */
+  blocks(): BlockStore;
+  /** provider/model/turns/tokens exactly as the status line shows them */
+  state: InfoStateSlice;
+  commands: { builtin: readonly SlashCommand[]; custom: readonly CustomCommand[] };
+  /** /cost pricing + context window (offline snapshot; `/cost refresh` is the TUI's one fetch) */
+  catalog: ModelCatalog;
+}
+
+/** /help topics in display order; a command with an unknown or missing group lands under "more" at the end */
+export const HELP_GROUP_ORDER: readonly string[] = ["start here", "session", "model & provider", "modes & safety", "files & history", "info"];
+
+/** /help — the built-ins grouped by topic (SlashCommand.group), one plain line each, then the "custom:" tail (port #30). */
+export function cmdHelp(ctx: InfoCmdCtx): void {
+  ctx.renderer.addSystemNote(groupedHelp(ctx.commands.builtin) + helpForCommands(ctx.commands.custom));
+}
+
+/** pure: the grouped body /help prints (tests read it without a renderer) */
+export function groupedHelp(builtin: readonly SlashCommand[]): string {
+  const groups = new Map<string, SlashCommand[]>();
+  for (const c of builtin) { const g = c.group !== undefined && HELP_GROUP_ORDER.includes(c.group) ? c.group : "more"; const l = groups.get(g) ?? []; l.push(c); groups.set(g, l); }
+  const order = [...HELP_GROUP_ORDER, "more"].filter((g) => groups.has(g));
+  return order.map((g) => `${g}\n` + groups.get(g)!.map((c) => `  /${c.name} — ${c.description}`).join("\n")).join("\n");
+}
+
+/** /status — provider/model/turns/tokens, the active executor rung + its origin (port #27), and
+ *  config provenance (port #8 HIGH-2: dropped/truncated sources must be visible). */
+export function cmdStatus(ctx: InfoCmdCtx): void {
+  const pc = ctx.rt.projectContext;
+  const cfgBits = pc.sources.map((s) => s.chars === 0 ? `${s.path} (dropped)` : s.truncated ? `${s.path} (truncated)` : s.path);
+  if (pc.skippedFiles > 0) cfgBits.push(`+${pc.skippedFiles} skipped (file cap)`);
+  const s = ctx.state;
+  ctx.renderer.addSystemNote(
+    `provider=${s.provider} model=${s.model} turns=${s.turns} tokens=${s.tokensIn}in/${s.tokensOut}out` +
+    `\nsandbox: ${describeSandbox(ctx.rt.sandbox)}` +
+    `\nconfig: ${cfgBits.length > 0 ? cfgBits.join(", ") : "(none)"}`,
+  );
+}
+
+/** /cost [refresh] — ports #5+#6: normalized usage (incl. cache traffic) priced per message at its
+ *  origin model; `refresh` re-fetches models.dev pricing (24h disk cache) — the live half is
+ *  user-invoked only, so the TUI stays network-free unless asked. */
+export function cmdCost(ctx: InfoCmdCtx, arg: string): void {
+  if (arg === "refresh") {
+    void ctx.catalog.refresh().then((ok) => ctx.renderer.addSystemNote(
+      ok ? "model catalog refreshed from models.dev" : "catalog refresh failed — using the offline snapshot",
+      ok ? "info" : "warn",
+    ));
+    return;
+  }
+  ctx.renderer.addSystemNote(buildCostNote(ctx.store().messages(), ctx.catalog, { provider: ctx.state.provider, model: ctx.state.model }));
+}
+
+/** /skills — installed skills, one `name — description` row each. */
+export function cmdSkills(ctx: InfoCmdCtx): void {
+  const rows = ctx.rt.skillStore.list().map((s) => `${s.name} — ${s.description}`);
+  ctx.renderer.addSystemNote(rows.length ? rows.join("\n") : "(no skills installed)");
+}
+
+/** /memory — the active session's memory blocks as the prompt sees them. */
+export function cmdMemory(ctx: InfoCmdCtx): void {
+  ctx.renderer.addSystemNote(ctx.blocks().renderForPrompt() || "(empty)");
+}
+
+/** /export [--json] [path] [--force] — port #38: write THIS session as markdown (raw JSONL with
+ *  --json), local only. Read-only over the store (exportSession re-reads from disk), so no busy
+ *  gate; a spaced path stays whole (every non-flag word joins the path). */
+export function cmdExport(ctx: InfoCmdCtx, arg: string): void {
+  try {
+    const words = arg.split(/\s+/).filter(Boolean);
+    const res = exportSession(ctx.sessionsDir, ctx.store().id, {
+      json: words.includes("--json"), force: words.includes("--force"),
+      out: words.filter((w) => !w.startsWith("-")).join(" ") || undefined, cwd: ctx.rt.cwd,
+    });
+    ctx.renderer.addSystemNote(`exported ${res.format} → ${res.path}`);
+  } catch (e) {
+    ctx.renderer.addSystemNote(e instanceof Error ? e.message : String(e), "error");
+  }
+}
+
+/** /todos — port #32: the agent-maintained list at <session>/todos.json as checkbox rows. A
+ *  corrupt file is a warning above the (empty) list, never a throw (loadTodos contract). */
+export function cmdTodos(ctx: InfoCmdCtx): void {
+  const { items, note } = loadTodos(join(ctx.sessionsDir, ctx.store().id));
+  if (note) ctx.renderer.addSystemNote(note, "warn");
+  ctx.renderer.addSystemNote(items.length > 0 ? renderTodos(items) : "(no todos — the agent maintains the list with todo_write)");
+}
+
+/** Status-bar label for the session's list ("todos 1/3"); undefined when empty, so the app omits
+ *  the key and plain surfaces never see a blank segment. */
+export function todoLabel(sessionDir: string): string | undefined {
+  return todoStatusLabel(loadTodos(sessionDir).items) || undefined;
+}
+
+/** /tasks [cancel <id>|cancel all] — port #26: the runtime TaskManager's snapshot (the same rows
+ *  as the tool's `list` action). Cancel acknowledges the REQUEST here; the "cancelled" line itself
+ *  arrives through the app's task subscription when the child run has actually settled (a queued
+ *  task settles at once, a running one when its aborted run returns) — one terminal note per task. */
+export function cmdTasks(ctx: InfoCmdCtx, arg: string): void {
+  const words = arg.split(/\s+/).filter(Boolean);
+  const tasks = ctx.rt.tasks;
+  if (words.length === 0) { ctx.renderer.addSystemNote(formatTaskList(tasks.list())); return; }
+  if (words[0] !== "cancel" || words.length !== 2) { ctx.renderer.addSystemNote("usage: /tasks [cancel <id>|cancel all]", "warn"); return; }
+  const id = words[1]!;
+  if (id === "all") {
+    const n = tasks.cancelAll();
+    ctx.renderer.addSystemNote(n === 0 ? "no queued or running tasks to cancel" : `cancelling ${n} task${n === 1 ? "" : "s"}`);
+    return;
+  }
+  const before = tasks.status(id);
+  if (!before) { ctx.renderer.addSystemNote(`unknown task '${id}' — list with /tasks`, "warn"); return; }
+  if (isTerminal(before.status)) { ctx.renderer.addSystemNote(`task ${id} already ${before.status}`); return; }
+  tasks.cancel(id);
+  ctx.renderer.addSystemNote(`cancelling task ${id} (${before.label})`);
+}

package/src/tui/mcp-cmd.ts

@@ -0,0 +1,128 @@
+/** /mcp — the MCP market inside the TUI, through the two cards the surface already has. `/mcp [query]`
+ *  opens the palette (Renderer.pickOne: the same box, keys and fuzzy filter as ⌃k) over the curated
+ *  shelf plus the registry's matches; Enter on a row → if the server has several launch forms, one more
+ *  pick; then the APPROVAL card (Renderer.askApproval) whose detail is the exact plan — command + args or
+ *  URL, source, publisher, version, the env NAMES, the file — and only a yes writes. Kept out of app.ts
+ *  (ADR-002 cap) like providers-cmd.ts.
+ *
+ *  Secrets: the TUI has no masked input, so nothing is ever asked here. An install that wants a key is
+ *  written with `${NAME}` (config.ts fills it from the environment at launch) and the closing note says
+ *  which names to export — or to run `rovecode mcp add <name>` on a shell, where the prompt is masked. */
+
+import type { Renderer, PickItem } from "./renderer.ts";
+import { installLabel, searchMarket, type MarketDeps, type MarketEntry } from "../mcp/market.ts";
+import { describePlan, fillPlan, namesWritten, planInstall, serverLine, writeServer, type McpScope } from "../mcp/market-install.ts";
+import { parseConfigFile } from "../mcp/config.ts";
+import { mcpTrustStatus, projectMcpFiles, trustMcpFile } from "../mcp/trust.ts";
+import { installLocalPackage, localLaunch, npxPackage } from "../mcp/local-package.ts";
+import { buildRecord, recordInstall } from "../market/manifest.ts";
+import { rovecodeHome } from "../providers/auth.ts";
+
+/** the subcommands the sextant offers after `/mcp ` (Enter completes the word, the name comes next) */
+export const MCP_SUBCOMMANDS = ["search", "info", "add", "remove", "list", "show", "trust", "untrust"] as const;
+export const MCP_COMMAND = { name: "mcp", choices: MCP_SUBCOMMANDS, choicesThen: "complete" as const, description: "Find and install an MCP server: /mcp [query] [--project] — the curated shelf, then the registry · /mcp trust approves this repo's MCP files", group: "modes & safety" };
+
+/** `/mcp trust` — one approval card per project MCP file: the file as preview, its servers as detail; a yes
+ *  records the file's current bytes as trusted (mcp/trust.ts), so the NEXT launch loads it */
+async function trustProjectFiles(ctx: McpCmdCtx, home: string): Promise<void> {
+  const files = projectMcpFiles(ctx.cwd);
+  if (files.length === 0) { ctx.renderer.addSystemNote("mcp: no project MCP files here (.rovecode/mcp.json, .mcp.json)"); return; }
+  const anySet = new Proxy({}, { get: () => "set" }) as Record<string, string>;
+  for (const file of files) {
+    if (mcpTrustStatus(home, file) === "trusted") { ctx.renderer.addSystemNote(`mcp: ${file} is already trusted as it is now`); continue; }
+    const warnings: string[] = [];
+    const lines = parseConfigFile(file, warnings, anySet).map(serverLine).concat(warnings.map((w) => `! ${w}`));
+    const answer = await ctx.renderer.askApproval("mcp trust", file, lines.join("\n") || "(no servers in it)");
+    if (answer === "deny") { ctx.renderer.addSystemNote(`mcp: ${file} stays untrusted — nothing in it loads`); continue; }
+    const r = trustMcpFile(home, file);
+    ctx.renderer.addSystemNote(r.ok ? `mcp: trusted ${file} — restart me to connect; an edit asks again` : `mcp: ${r.reason}`, r.ok ? "info" : "warn");
+  }
+}
+
+export interface McpCmdCtx {
+  renderer: Renderer;
+  cwd: string;
+  home?: string;
+  /** registry access — tests inject a fixture fetch or `offline` */
+  market?: MarketDeps;
+  /** how `npm install` runs for the install-once pick — tests inject one that writes a fake node_modules */
+  spawn?: import("../mcp/local-package.ts").Spawn;
+}
+
+const clip = (s: string, n: number): string => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+
+function pickItem(e: MarketEntry): PickItem {
+  const src = e.source === "curated" ? "curated" : `registry · ${e.publisher ?? "?"}`;
+  return { value: e.key, label: e.title ?? e.key, description: `${src}${e.status ? ` · ${e.status}` : ""} · ${clip(e.description, 60)}` };
+}
+
+export async function cmdMcp(ctx: McpCmdCtx, arg: string): Promise<void> {
+  const { renderer } = ctx;
+  const words = arg.split(/\s+/).filter(Boolean);
+  const scope: McpScope = words.includes("--project") ? "project" : "user";
+  const query = words.filter((w) => !w.startsWith("--")).join(" ");
+  const home = ctx.home ?? rovecodeHome();
+  if (words[0] === "trust") { await trustProjectFiles(ctx, home); return; }
+  const market: MarketDeps = { home, ...ctx.market };
+  const found = await searchMarket(query, market);
+  for (const n of found.notes) renderer.addSystemNote(`mcp: ${n}`, "warn");
+  if (found.entries.length === 0) { renderer.addSystemNote(`mcp: nothing matches "${query}" — the registry matches on the server's name`, "warn"); return; }
+  const key = await renderer.pickOne(found.entries.map(pickItem), query ? `mcp market · ${query}` : "mcp market");
+  if (key === null) return;
+  const entry = found.entries.find((e) => e.key === key);
+  if (!entry) return;
+  let pick = 0;
+  if (entry.installs.length > 1) {
+    const how = await renderer.pickOne(entry.installs.map((i, ix) => ({ value: String(ix), label: i.kind === "stdio" ? `run  ${installLabel(i)}` : `connect  ${i.url}` })), `${entry.title ?? entry.key} · how`);
+    if (how === null) return;
+    pick = Number(how);
+  }
+  // the install-once offer (mcp/local-package.ts) as one more pick, BEFORE the plan: the card the human
+  // approves is then the plan that runs. Esc here writes nothing; "as today" is the npx line unchanged.
+  const chosen = entry.installs[pick];
+  const offer = chosen !== undefined ? npxPackage(chosen) : undefined;
+  let local = false;
+  if (offer !== undefined && scope === "user") { // a project file is shared: install-once's absolute path has no place in it (planInstall refuses it too)
+    const how = await renderer.pickOne([
+      { value: "local", label: `install once — node starts it in ~0.4 s`, description: `runs npm install now: ${offer.spec}'s code lands under ~/.rovecode/mcp (typically 20–30 MB, one time); no network needed to start` },
+      { value: "npx", label: `run through npx at every start — as today`, description: `~2 s per start, re-resolves the package and asks the npm registry each time; nothing installed now` },
+    ], `${entry.title ?? entry.key} · how to start it`);
+    if (how === null) return;
+    local = how === "local";
+  }
+  const plan = planInstall(entry, { scope, cwd: ctx.cwd, home, pick, ...(local ? { local: true } : {}) });
+  if ("error" in plan) { renderer.addSystemNote(`mcp: ${plan.error}`, "warn"); return; }
+  // the approval card: title = what is being done, preview = the one line that runs, detail = the whole plan
+  // (for install-once the detail says, in words, that npm runs and code lands on this machine)
+  const answer = await renderer.askApproval("mcp add", `${plan.name} ← ${plan.local ? `node ${plan.local.pkg.spec} (installed once)` : installLabel(plan.install)}`, describePlan(plan, "env").join("\n"));
+  if (answer === "deny") { renderer.addSystemNote("mcp: nothing written"); return; }
+  // install-once: npm first; only its success reaches the file, and what landed goes on record
+  let launch: { command: string; args: string[] } | undefined;
+  let pkgRecord: NonNullable<Parameters<typeof buildRecord>[1]["package"]> | undefined;
+  if (plan.local) {
+    renderer.addSystemNote(`mcp: npm install ${plan.local.pkg.spec} → ${plan.local.prefix} …`);
+    const lr = await installLocalPackage(plan.local.pkg, plan.local.prefix, ctx.spawn ? { spawn: ctx.spawn } : {});
+    if (!lr.ok) { renderer.addSystemNote(`mcp: ${lr.error} — nothing written`, "error"); return; }
+    launch = localLaunch(lr.pkg, plan.local.pkg.rest);
+    pkgRecord = { name: lr.pkg.name, version: lr.pkg.version, prefix: plan.local.prefix, bin: lr.pkg.bin, missing: lr.pkg.missing,
+      ...(lr.pkg.integrity !== undefined ? { integrity: lr.pkg.integrity } : {}), ...(lr.pkg.resolved !== undefined ? { resolved: lr.pkg.resolved } : {}) };
+  }
+  let trusted: boolean | undefined;
+  const raw = fillPlan(plan, {}, launch); // no answers: required asks become ${NAME}, optional ones are left out — the file works without them
+  try {
+    // the card just approved this exact content: a project file is trusted as written (mcp/trust.ts)
+    trusted = writeServer(plan.file, plan.name, raw, scope === "project" ? { trustHome: home } : {}).trusted;
+  } catch (e) { renderer.addSystemNote(`mcp: ${e instanceof Error ? e.message : String(e)}`, "error"); return; }
+  renderer.addSystemNote(`mcp: added "${plan.name}" → ${plan.file}${trusted === true ? " (trusted as written)" : ""} — restart me to connect (servers are read once per process)`);
+  if (pkgRecord) {
+    recordInstall(buildRecord({ kind: "mcp", id: entry.key, source: entry.source, ...(entry.version !== undefined ? { version: entry.version } : {}) },
+      { scope, target: plan.file, package: pkgRecord, installedBy: "mcp add" }), { cwd: ctx.cwd, home });
+    renderer.addSystemNote(`mcp: installed ${pkgRecord.name} ${pkgRecord.version} once → ${plan.local!.prefix}${pkgRecord.integrity !== undefined ? " (integrity recorded in installed.json)" : ""}`);
+    if (pkgRecord.missing?.length) renderer.addSystemNote(`mcp: record incomplete: ${pkgRecord.missing.join("; ")}`, "warn");
+  }
+  if (trusted === false) renderer.addSystemNote("mcp: that file already held servers you have not approved, so it is NOT trusted yet — /mcp trust shows them", "warn");
+  // only the names the FILE now refers to: an optional ask that was left out is not something to go and set
+  const named = namesWritten(plan, raw);
+  if (named.length) renderer.addSystemNote(`mcp: set ${named.join(", ")} in your environment before the restart — or run \`rovecode mcp add ${entry.key}\` on a shell, which asks for them masked`, "warn");
+  if (plan.pending.length) renderer.addSystemNote(`mcp: fill in ${plan.pending.join(", ")} in that file's args before use`, "warn");
+}

package/src/tui/modes-cmd.ts

@@ -0,0 +1,45 @@
+/** TUI glue for plan/act modes (port #20), extracted from app.ts for the ADR-002 cap.
+ *  Pure functions over the ModeManager + the app's mutable state slice. */
+
+import { ModeManager, applyModeRules, buildModeChangeEntry, modeSwitchOf, planModePromptSection, type AgentMode } from "../core/modes.ts";
+import type { SessionStore } from "../core/session.ts";
+import type { AgentDefinition, RunConfig } from "../core/types.ts";
+import type { Renderer } from "./renderer.ts";
+
+export interface ModeStateSlice { provider: string; model: string; mode: AgentMode; busy: boolean }
+
+/** /plan and /act — busy-gated toggle; updates the state slice from the mode's model slot. */
+export function togglePlanAct(modes: ModeManager, cmd: AgentMode, state: ModeStateSlice, renderer: Renderer, pushStatus: () => void): void {
+  if (state.busy) { renderer.addSystemNote("finish or interrupt the run first (Esc)", "warn"); return; }
+  const sw = modes.toggle(cmd);
+  if (!sw) { renderer.addSystemNote(`already in ${cmd} mode`); return; }
+  const cur = modes.modelFor();
+  state.mode = modes.mode; state.model = cur.model; state.provider = cur.provider;
+  renderer.addSystemNote(cmd === "plan" ? "plan mode: read-only tools — writes/shell/spawn denied by policy" : "act mode: full toolset restored");
+  pushStatus();
+}
+
+/** Run-start enforcement: plan mode appends read-only rules AFTER the base set
+ *  (last-match-wins overrides even yolo) and steers the system prompt. */
+export function applyModeToRun(modes: ModeManager, cfg: RunConfig, def: AgentDefinition): void {
+  cfg.permissionRules = applyModeRules(modes.mode, cfg.permissionRules);
+  if (modes.mode !== "plan") return;
+  delete cfg.verify; // plan mode changes nothing and runs nothing: the verify gate (core/verify-gate.ts) is off here, not merely idle
+  const base = def.systemPrompt;
+  def.systemPrompt = (v) => (typeof base === "function" ? base(v) : base) + "\n\n" + planModePromptSection();
+}
+
+/** MED-2: a pending mode switch must survive quit and session swaps, not just the
+ *  next submit — flush it as a durable entry so resume restores the last mode.
+ *  Round-trip cancellations have no pending switch, so nothing lands for them. */
+export function flushModeSwitch(modes: ModeManager, store: SessionStore): void {
+  const sw = modes.consumeSwitchNotice();
+  if (sw) store.append(buildModeChangeEntry(sw, store.messages().at(-1)?.id ?? null));
+}
+
+/** LOW-3: replay label for a system entry — mode switches render as a human line
+ *  ("mode → plan"), never the raw <mode_notice> XML the entry carries. */
+export function replayLabel(entry: unknown, text: string): string {
+  const sw = modeSwitchOf(entry);
+  return sw ? `mode → ${sw.to}` : text;
+}

package/src/tui/overlays.ts

@@ -0,0 +1,97 @@
+/** Overlay bodies for PiTuiRenderer: the port #24 approval diff card and the port #33 question
+ *  card. Each is a pi-tui Component that routes keys to the SelectList (or Input) it wraps, so
+ *  the renderer's overlay lifecycle (show → settle → hide → refocus editor) is shared and the
+ *  wrapped list's bindings are untouched. Only pi-renderer.ts, this module and theme.ts may
+ *  import from vendor/pi-tui. */
+
+import {
+	type Component,
+	Input,
+	type SelectList,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "../../vendor/pi-tui/src/index.ts";
+import { pal, st } from "./theme.ts";
+
+/** One overlay row: leading space, clipped to width-2, padded so the right gutter stays clean. */
+export function fitLine(s: string, width: number): string {
+	const t = truncateToWidth(s, width - 2, "…");
+	return ` ${t}${" ".repeat(Math.max(0, width - 1 - visibleWidth(t)))}`;
+}
+
+/** Port #24: body of an edit/write approval overlay — title, the bounded unified diff
+ *  (+ green, - red, headers/@@ dim), a spacer, then the verdict list. Keys go straight
+ *  to the list, so verdicts and bindings are identical to the plain approval overlay. */
+const MORE_RE = /^… \+(\d+) more line/;
+export class ApprovalCard implements Component {
+	constructor(
+		private readonly title: string,
+		private readonly diff: string[],
+		private readonly list: SelectList,
+		private readonly rows: () => number,
+	) {}
+	handleInput(data: string): void { this.list.handleInput(data); }
+	invalidate(): void { this.list.invalidate(); }
+	render(width: number): string[] {
+		// physical bound: title, list and some transcript must stay visible. previewDiff already
+		// clipped logically — fold its marker's count into ours rather than stacking two markers.
+		const max = Math.max(4, this.rows() - 12);
+		let lines = this.diff;
+		if (lines.length > max) {
+			const tail = MORE_RE.exec(lines[lines.length - 1]!);
+			const hidden = lines.length - max + (tail ? Number(tail[1]) - 1 : 0);
+			lines = [...lines.slice(0, max), `… +${hidden} more line${hidden === 1 ? "" : "s"}`];
+		}
+		return [fitLine(pal.warn(this.title), width), ...lines.map((l, i) => fitLine(paintDiff(l, i), width)), " ".repeat(width), ...this.list.render(width)];
+	}
+}
+
+function paintDiff(line: string, idx: number): string {
+	if ((idx === 0 && line.startsWith("--- ")) || (idx === 1 && line.startsWith("+++ "))) return st.dim(line);
+	const c = line[0];
+	return c === "+" ? pal.ok(line) : c === "-" ? pal.err(line) : c === " " ? line : st.dim(line);
+}
+
+/** SelectList value of the "type an answer…" entry — can never collide with an option index. */
+export const FREE_TEXT = "\u0000free-text";
+
+/** SelectList value of the "skip this question" entry: the NON-destructive decline (resolves null →
+ *  the tool reports "user declined to answer"), so a busy run — where Escape means "stop the run" —
+ *  can still be left unanswered without killing it (port #33 critic LOW). Same escape idiom as
+ *  FREE_TEXT: an option index can never look like this. */
+export const SKIP_QUESTION = "\u0000skip-question";
+
+/** Port #33: body of a question overlay — title, the wrapped question (bounded by the terminal),
+ *  a spacer, then either the option list (options + the free-text entry + skip) or a one-line
+ *  Input for a typed answer, each with a key hint. Keys route to whichever is active; the renderer
+ *  wires the list/input callbacks (select, submit, escape) and flips `typing`. */
+export class QuestionCard implements Component {
+	private typing: boolean;
+	readonly input = new Input();
+	constructor(
+		private readonly question: string,
+		private readonly list: SelectList,
+		private readonly optionCount: number,
+		private readonly freeText: boolean,
+		private readonly rows: () => number,
+		/** true while a run is in flight — decides what Escape means in the hint */
+		private readonly busy: () => boolean,
+	) { this.typing = optionCount === 0; } // no options: straight to the input
+	get isTyping(): boolean { return this.typing; }
+	setTyping(on: boolean): void { this.typing = on; }
+	handleInput(data: string): void { if (this.typing) this.input.handleInput(data); else this.list.handleInput(data); }
+	invalidate(): void { this.list.invalidate(); this.input.invalidate(); }
+	render(width: number): string[] {
+		const bodyRows = this.typing ? 1 : this.optionCount + (this.freeText ? 1 : 0) + 1; // + the skip entry
+		// physical bound: title, body, hint and some transcript must stay visible
+		const max = Math.max(2, this.rows() - 9 - bodyRows);
+		let lines = wrapTextWithAnsi(this.question, width - 2);
+		if (lines.length > max) lines = [...lines.slice(0, max - 1), st.dim(`… +${lines.length - max + 1} more lines`)];
+		const esc = this.busy() ? "Esc stop the run" : "Esc skip";
+		const body = this.typing
+			? [fitLine(this.input.render(width - 2)[0] ?? "", width), fitLine(st.dim(this.optionCount > 0 ? "Enter sends · Esc back to the options" : `Enter sends · ${esc}`), width)]
+			: [...this.list.render(width), fitLine(st.dim(`↑↓ choose · Enter answer · ${esc}`), width)];
+		return [fitLine(pal.warn("question"), width), ...lines.map((l) => fitLine(l, width)), " ".repeat(width), ...body];
+	}
+}