@azure-id/orc 0.56.1 → 1.1.0

package/bin/webui/api.js

@@ -1,1163 +1,1201 @@
-"use strict";
-/**
- * api.js — the /api router for `orc ui`.
- *
- * THE ONE ARCHITECTURAL RULE: this file never re-implements CLI logic. Every
- * endpoint spawns `node bin/cli.js <cmd> --json` and forwards the parsed
- * object. That makes UI/CLI drift structurally impossible — the UI *is* the
- * CLI — and it means every write inherits the CLI's validators, the LEGACY_KEYS
- * aliasing, the shadowing announcements and the fable5_effort frontmatter
- * rewrite for free, with zero duplicated logic.
- *
- * The alternative (requiring cli.js as a library) is off the table: cli.js ends
- * with a bare IIFE, has no require.main guard, prints and process.exit()s
- * directly, and is pinned by contract tokens with binFiles: ["bin/cli.js"].
- *
- * It also never RUNS a lane and never calls a model API. Since v0.43.4 there is
- * exactly one deliberate exception to "never spawns claude": the Experiment
- * panel can open a TERMINAL with `claude` in it and then forget about it (see
- * `launchClaude`). No model output ever flows back through this server, no
- * session is proxied, no API key is held — the panel is still not an AI client.
- */
-
-const { spawn, spawnSync } = require("child_process");
-const fs = require("fs");
-const os = require("os");
-const path = require("path");
-const fixtures = require("./fixtures/index.js");
-
-const CLI = path.join(__dirname, "..", "cli.js");
-
-// A single-user localhost panel re-reads the same command several times while
-// one page renders. A short TTL collapses that without ever showing stale data
-// across a user action: every mutation clears the cache outright.
-const READ_TTL_MS = 2500;
-const chr10 = String.fromCharCode(10);
-const CLI_TIMEOUT_MS = 30_000;
-
-const cache = new Map();
-
-function cacheKey(argv) {
-  return argv.join("\u0000");
-}
-
-function clearCache() {
-  cache.clear();
-}
-
-// ── running the CLI ─────────────────────────────────────────────────────────
-
-// Several commands use a NON-ZERO exit as a normal answer, not a failure:
-// `pattern status` (1 = absent, 2 = unknown key), `gotcha list` (1 = none),
-// `wiki impact` (2 = delta, 3 = full), `pr stack status` (1 = not ready),
-// `doctor` (1 = issues found), `resume` (1 = nothing waiting). So the exit code
-// is DATA here, never an error condition — a run counts as failed only when it
-// produced no parseable object.
-// `input` (v0.50.0) is stdin for the child, and it exists for exactly one
-// caller: the connection test, which takes a pasted API key on line 1 and an
-// optional passphrase on line 2. It is a parameter rather than a second spawn
-// helper because a secret must travel the SAME path everything else does —
-// never argv (world-readable in a process list), never a temp file, never a log
-// line. Nothing here ever echoes it back, and `command` below is built from
-// argv alone.
-function runCli(argv, ctx, { json = false, input = undefined } = {}) {
-  const args = [...argv];
-  if (json) args.push("--json");
-  // Always target the project explicitly: the server's cwd is not a reliable
-  // way to reach the same .claude the launching command resolved.
-  if (ctx.projectRoot) args.push("--dir", ctx.projectRoot);
-  // ORC_NO_UPDATE_CHECK exists here to protect the --json contract: most
-  // commands end with `maybeNudge()`, which prints an "update available" line to
-  // STDOUT and would sit beside the object this parses.
-  //
-  // `version` and `changelog` are the exceptions, and forcing the flag on them
-  // was a real bug: neither nudges, and for both the check IS the payload — so
-  // the panel asked whether an update existed with the check switched off and
-  // was told `check_disabled: true` forever. A blanket env var silenced the one
-  // command whose entire job is to answer that question.
-  const CHECKS_UPDATES = argv[0] === "version" || argv[0] === "changelog";
-  const env = { ...process.env, NO_COLOR: "1" };
-  if (!CHECKS_UPDATES) env.ORC_NO_UPDATE_CHECK = "1";
-  const r = spawnSync(process.execPath, [CLI, ...args], {
-    encoding: "utf8",
-    timeout: CLI_TIMEOUT_MS,
-    windowsHide: true,
-    env,
-    input,
-  });
-  const stdout = r.stdout || "";
-  let data = null;
-  try {
-    data = JSON.parse(stdout);
-  } catch (_) {}
-  return {
-    ok: data !== null,
-    exit_code: r.status === null ? -1 : r.status,
-    data,
-    stderr: (r.stderr || "").trim(),
-    stdout: data === null ? stdout.trim() : "",
-    command: "orc " + argv.join(" "),
-  };
-}
-
-// The one-line reason a read failed, in the CLI's own words. `crashed` is the
-// envelope the CLI itself emits when a `--json` route throws (v0.49.2); anything
-// else is a command that wrote nothing parseable at all.
-function readFailReason(out) {
-  const first = (out.stderr || out.stdout || "")
-    .split(chr10)
-    .map((l) => l.trim())
-    .filter(Boolean)[0];
-  const tail = first ? " \u2014 " + first : "";
-  return `${out.command} produced no JSON (exit ${out.exit_code})${tail}`;
-}
-
-function readCli(argv, ctx) {
-  const key = cacheKey([ctx.projectRoot || "", ...argv]);
-  const hit = cache.get(key);
-  if (hit && Date.now() - hit.at < READ_TTL_MS) return hit.value;
-  const value = runCli(argv, ctx, { json: true });
-  cache.set(key, { at: Date.now(), value });
-  return value;
-}
-
-// ── jobs (the mutation half) ────────────────────────────────────────────────
-// SINGLE-FLIGHT: one mutation at a time, process-wide. The client goes
-// read-only while a job runs, so a second one is a bug, not a race to win.
-// Output accumulates in memory and the client polls /api/job — which is what
-// makes `orc update` and `orc upgrade` show their real output as it happens
-// instead of a spinner and a verdict.
-
-let job = null;
-let jobSeq = 0;
-
-function jobView() {
-  if (!job) return { id: null, running: false };
-  return {
-    id: job.id,
-    command: job.command,
-    running: job.running,
-    exit_code: job.exit_code,
-    output: job.output,
-    started_ms: job.started_ms,
-    // THE PANEL IS SERVING CODE THAT THIS JOB MAY HAVE JUST REPLACED. Reported
-    // only on a job that SUCCEEDED and whose action is declared as touching the
-    // install — a failed upgrade changed nothing, so restarting after one would
-    // be motion with no reason. The client acts on it; the server does not
-    // restart itself, so the job's output survives long enough to be read.
-    restart_pending: !!(job.restart_ui && !job.running && job.exit_code === 0),
-  };
-}
-
-function startJob(argv, ctx, opts) {
-  if (job && job.running) return { error: "busy", job: jobView() };
-  const args = [...argv];
-  if (ctx.projectRoot) args.push("--dir", ctx.projectRoot);
-  const id = ++jobSeq;
-  job = {
-    id,
-    command: "orc " + argv.join(" "),
-    running: true,
-    exit_code: null,
-    output: "",
-    started_ms: Date.now(),
-    restart_ui: !!(opts && opts.restartUi),
-  };
-  const child = spawn(process.execPath, [CLI, ...args], {
-    windowsHide: true,
-    env: { ...process.env, NO_COLOR: "1" },
-  });
-  const append = (buf) => {
-    job.output += buf.toString("utf8");
-    // A runaway job must not grow the server's heap without bound.
-    if (job.output.length > 400_000) job.output = job.output.slice(-400_000);
-  };
-  child.stdout.on("data", append);
-  child.stderr.on("data", append);
-  child.on("error", (e) => {
-    job.output += "\n" + String(e.message);
-    job.exit_code = -1;
-    job.running = false;
-  });
-  child.on("close", (code) => {
-    job.exit_code = code === null ? -1 : code;
-    job.running = false;
-    clearCache(); // every panel refetches against the new truth
-  });
-  return { job: jobView() };
-}
-
-// ── the endpoint table ──────────────────────────────────────────────────────
-// READS map a route to CLI argv. WRITES are separate and POST-only — a GET can
-// never mutate, so a prefetch, a bookmark or a browser retry is always safe.
-
-const READS = {
-  "/api/version": () => ["version"],
-  "/api/changelog": () => ["changelog"],
-  "/api/where": () => ["where"],
-  "/api/doctor": () => ["doctor"],
-  "/api/config": () => ["config", "list"],
-  "/api/config/profiles": () => ["config", "profile"],
-  "/api/config/recommend": () => ["config", "recommend"],
-  "/api/runs": (q) => ["run", "list", "--limit", String(Math.min(200, Number(q.limit) || 40))],
-  "/api/run": (q) => ["run", "show", String(q.slug || "")],
-  "/api/wiki": () => ["wiki", "status"],
-  "/api/wiki/impact": () => ["wiki", "impact"],
-  // v0.46.0. Every one is a READ with an exit-code contract, so the exit code is
-  // DATA here exactly like `pattern status` and `wiki impact` above: pact 0/1/2/3,
-  // boundary 0/1/2/3, handoff 0/1, budget 0/1/2/3, aftermath 0/1/2/3,
-  // wiki plan 0/1/2/3, wiki debt 0/1/3, export --check 0/1.
-  "/api/wiki/plan": () => ["wiki", "plan"],
-  "/api/wiki/debt": () => ["wiki", "debt"],
-  "/api/wiki/usage": () => ["wiki", "usage"],
-  // v0.49.1 — the wiki's CONTENTS, not only its temperature. All three are
-  // READS whose exit code is DATA (docs 0/1/3, show 0/2/3, coverage 0/1), and
-  // `coverage` deliberately has no threshold: nothing branches on it, here or
-  // anywhere else. `--body` is opt-in and one artifact at a time — the
-  // /api/doc/section precedent.
-  "/api/wiki/docs": () => ["wiki", "docs"],
-  "/api/wiki/show": (q) => ["wiki", "show", String(q.doc || ""), ...(q.body ? ["--body"] : [])],
-  "/api/wiki/coverage": () => ["wiki", "coverage"],
-  // The pattern file is injected LITERALLY into every executor slice, and until
-  // now nothing would show you a line of it. Same 0/1/2 contract `pattern
-  // status` has had since v0.34.8.
-  "/api/pattern/show": (q) => ["pattern", "show", String(q.lang || ""), ...(q.body ? ["--body"] : [])],
-  "/api/gotcha/show": (q) => ["gotcha", "show", String(q.id || "")],
-  "/api/gotchas/archived": () => ["gotcha", "list", "--archived"],
-  // Preview-then-apply: A COUNT IS NOT CONSENT. The Apply button stays disabled
-  // until this has been fetched, and it names every entry eviction would touch.
-  "/api/gotcha/prune/preview": () => ["gotcha", "prune", "--dry-run"],
-  "/api/pact": () => ["pact", "status"],
-  "/api/boundary": (q) => (q.path ? ["boundary", "status", String(q.path)] : ["boundary", "status"]),
-  "/api/handoff": () => ["handoff", "surfaces"],
-  "/api/budget/rates": () => ["budget", "rates"],
-  // A forecast takes a PLAN PATH. The browser sends a path the folder picker
-  // produced; the server passes it straight to the CLI and never opens the file
-  // itself — /api/fs/list stays a directory LISTER, and widening it to read a
-  // plan would be the one change that turns this panel into a file reader.
-  "/api/budget/forecast": (q) => ["budget", "forecast", String(q.plan || "")],
-  "/api/budget/actual": (q) => ["budget", "actual", String(q.slug || "")],
-  "/api/aftermath": (q) => (q.since ? ["aftermath", "status", "--since", String(q.since)] : ["aftermath", "status"]),
-  "/api/export": () => ["export", "--check"],
-  // v0.47.0 — /orc-challenge. Same shape: every one is a READ whose exit code is
-  // DATA (list 0/1/3, status 0/1/2/3, diff 0/1/2/3, lint 0/1/2), and the panel
-  // derives nothing from them — not the state word, not the iteration order, not
-  // the pass decision, not the expected revision path.
-  "/api/challenge": () => ["challenge", "list"],
-  "/api/challenge/one": (q) => ["challenge", "status", String(q.slug || "")],
-  "/api/challenge/show": (q) => [
-    "challenge",
-    "show",
-    String(q.slug || ""),
-    ...(q.iteration ? ["--iteration", String(q.iteration)] : []),
-  ],
-  "/api/challenge/diff": (q) => ["challenge", "diff", String(q.slug || "")],
-  // v0.49.1 — the council. `roles` is STATIC (it works with no cycle at all),
-  // and it is the ONE catalogue: the panel names no lens, no class and no
-  // disposition itself, exactly as it names no flow step. `council` is 0 set /
-  // 1 unset / 3 unknown, and UNSET is an ANSWER, not an error.
-  "/api/challenge/roles": (q) => ["challenge", "roles", ...(q.kind ? ["--kind", String(q.kind)] : [])],
-  "/api/challenge/council": (q) => ["challenge", "council", String(q.slug || "")],
-  "/api/challenge/lint": (q) => [
-    "challenge",
-    "lint",
-    String(q.path || ""),
-    ...(q.template ? ["--template", String(q.template)] : []),
-  ],
-  // v0.48.0 — /orc-doc. Same shape again: every one is a READ whose exit code is
-  // DATA (list 0, status 0/1/2, map 0/2, plan 0/1, lint 0/1/2), and the panel
-  // derives nothing from them — not the section order, not a line range, not a
-  // state word, not the batching, not a lint rule name. It draws what the CLI
-  // computed.
-  //
-  // `/api/doc/section` is the ONE route that returns any of the document's
-  // prose, it returns exactly ONE section, and only on an explicit Reveal click.
-  // The rule this lane lives by is that nothing HOLDS the document — not that
-  // the text is secret — and the panel renders it as DOM through `renderMd`,
-  // never as HTML.
-  "/api/doc": () => ["doc", "list"],
-  "/api/doc/one": (q) => ["doc", "status", String(q.slug || "")],
-  "/api/doc/show": (q) => ["doc", "show", String(q.slug || "")],
-  "/api/doc/section": (q) => ["doc", "show", String(q.slug || ""), "--section", String(q.section || "")],
-  "/api/doc/map": (q) => ["doc", "map", String(q.slug || "")],
-  "/api/doc/lint": (q) => [
-    "doc",
-    "lint",
-    String(q.slug || ""),
-    ...(q.target ? ["--target", String(q.target)] : []),
-  ],
-  "/api/doc/plan": (q) => ["doc", "plan", String(q.slug || ""), "--role", String(q.role || "write")],
-  "/api/doc/templates": () => ["doc", "templates"],
-  "/api/doc/targets": () => ["doc", "targets"],
-  // v0.48.1 — the score, the drift report and the memory surface. Every one is
-  // a subprocess of the real command: the panel decides nothing about the
-  // pipeline order, nothing about which drift classes exist, and nothing about
-  // which journal rows are the user's own words.
-  //
-  // There is deliberately NO route for `orc doc log`: the SKILL records a
-  // request, because the skill is what took one. A panel that could write a
-  // journal entry could write one nobody said.
-  // v0.49.0 — the SECTION FILES. This is the one read that works before a
-  // single compile has ever run, because the files ARE the progress.
-  "/api/doc/parts": (q) => ["doc", "parts", String(q.slug || "")],
-  "/api/doc/next": (q) => ["doc", "next", String(q.slug || "")],
-  "/api/doc/audit": (q) => ["doc", "audit", String(q.slug || "")],
-  "/api/doc/journal": (q) => ["doc", "journal", String(q.slug || "")],
-  "/api/doc/context": (q) => ["doc", "context", String(q.slug || "")],
-  "/api/doc/extra": (q) => ["doc", "extra", String(q.slug || "")],
-  // v0.49.2 — the project's own house rules, the frozen set of one document,
-  // the run map and the cost report. All four are READS; the panel decides
-  // nothing about a priority, an order, a wave shape or a number.
-  "/api/doc/rules": () => ["doc", "rules"],
-  "/api/doc/rules/one": (q) => ["doc", "rules", String(q.slug || "")],
-  "/api/doc/forecast": (q) => ["doc", "forecast", String(q.slug || "")],
-  "/api/doc/cost": (q) => ["doc", "cost", String(q.slug || "")],
-  // v0.50.0 — `orc extra`. Every one is a READ, and every one is a subprocess of
-  // the real command: the panel decides nothing about a provider, a model id, a
-  // verification state, a band or a price. It renders what the CLI computed.
-  //
-  // There is deliberately NO read that returns a credential. `orc extra list`
-  // and `orc extra show` go through `redactProfile`, which is an ALLOW-LIST, so
-  // a field added later that carries a secret has to be let through on purpose.
-  "/api/extra": () => ["extra", "list"],
-  "/api/extra/providers": () => ["extra", "providers"],
-  "/api/extra/show": (q) => ["extra", "show", String(q.profile || "")],
-  "/api/extra/models": (q) => ["extra", "models", String(q.profile || "")],
-  // v0.51.0 — the LOCAL TOOLS read, and the credential-route read. Both are the
-  // real commands, so the panel decides nothing about an install command, a
-  // platform, a version floor or which of three credential routes applies.
-  // `tools` exits 1 when no tool is ready, which is exit-code-as-DATA like
-  // `pattern status` — never an error.
-  "/api/extra/tools": () => ["extra", "tools"],
-  "/api/extra/keyhelp": (q) => ["extra", "keyhelp", String(q.profile || "")],
-  "/api/extra/route": () => ["extra", "route"],
-  // v0.55.0 — THE POSITIONS, the non-scored half of routing. It exits 1 when
-  // nothing routes, which is exit-code-as-DATA like `pattern status` — an empty
-  // result is an ANSWER and it still returns its whole object.
-  "/api/extra/role": () => ["extra", "role", "list"],
-  // v0.52.0 (D6) — WHICH LANE a band governs, computed through the same
-  // resolver every dispatch uses. The panel renders it and derives nothing:
-  // a band with no lane attached is not a routing decision.
-  "/api/extra/lanes": () => ["extra", "lanes"],
-  // `stats` exits 1 with a real object when no foreign dispatch has been traced
-  // yet, and `rates` exits 1 when a pair has no price — both are exit-code-as-
-  // DATA, like `pattern status` and `wiki impact`, never an error.
-  "/api/extra/stats": (q) => (q.since ? ["extra", "stats", "--since", String(q.since)] : ["extra", "stats"]),
-  "/api/extra/rates": () => ["extra", "rates"],
-  "/api/extra/doctor": () => ["extra", "doctor"],
-  // v0.54.0 — RECOVERY. Both are FREE reads (zero model tokens), which is why
-  // both are real buttons; `resume-slice` and the dispatch that follows it cost
-  // money and are copy-able commands instead. `reconcile` exits 0-4 as an
-  // exit-code-as-DATA contract like `pattern status`, so no state here is an
-  // error — including `in-flight`, which is a REFUSAL the panel must render as
-  // one rather than as a dead control.
-  "/api/extra/journal": () => ["extra", "journal", "list"],
-  "/api/extra/reconcile": (q) => ["extra", "reconcile", String(q.task || "")],
-  "/api/extra/journal/prune/preview": () => ["extra", "journal", "prune", "--dry-run"],
-  "/api/patterns": () => ["pattern", "status"],
-  "/api/gotchas": () => ["gotcha", "list"],
-  "/api/stats": (q) => (q.since ? ["stats", "--since", String(q.since)] : ["stats"]),
-  "/api/diy": () => ["diy", "show"],
-  "/api/crosslink": () => ["crosslink", "list"],
-  "/api/crosslink/kinds": () => ["crosslink", "kinds"],
-  "/api/mocks": () => ["mock", "list"],
-  "/api/mock": (q) => ["mock", "show", String(q.slug || "")],
-  "/api/stack": (q) => (q.slug ? ["pr", "stack", "status", String(q.slug)] : ["pr", "stack", "status"]),
-};
-
-// v0.46.0 writes. THE LINE THIS PANEL DOES NOT CROSS: a button exists only for an
-// action that costs NO model tokens. `orc pact check` runs the ledger's own cheap
-// proofs (a test, a command, a grep the user wrote); `orc handoff set` edits one
-// graded surface; `orc export` compiles files already on disk. Every one is
-// deterministic and every one is a real CLI command.
-//
-// The conversational half of each lane — reconciling a promise, deciding a
-// verdict, walking somebody through a change — costs model tokens, so the panel
-// COPIES those commands and never runs them. A test greps this object to make
-// sure no lane name ever appears inside it.
-const WRITES = {
-  "/api/config/set": (b) => ["config", "set", String(b.key), String(b.value)],
-  "/api/config/reset": (b) => (b.key ? ["config", "reset", String(b.key)] : ["config", "reset"]),
-  "/api/config/profile": (b) => ["config", "profile", String(b.name)],
-  "/api/diy/set": (b) => ["diy", "set", String(b.key), String(b.value)],
-  "/api/diy/compile": () => ["diy", "compile"],
-  // The bootstrap the TTY composer offers as its first question, and the one
-  // piece of DIY the panel had no way to reach (v0.44.0). `--force` is what
-  // makes it an ANSWER rather than an error on an already-configured project:
-  // `orc diy init` refuses to overwrite without it. That is destructive, so the
-  // UI confirms with the preset's own diff and the exact command on screen.
-  // An empty name is the wizard's "full-lane defaults" — a real invocation,
-  // not a synthesised one.
-  "/api/diy/preset": (b) => {
-    const argv = ["diy", "init", "--force"];
-    if (b.name) argv.push("--preset", String(b.name));
-    return argv;
-  },
-  "/api/wiki/sync": () => ["wiki", "sync"],
-  "/api/wiki/usage/rebuild": () => ["wiki", "usage", "--rebuild"],
-  "/api/gotcha/prune": () => ["gotcha", "prune"],
-  "/api/pact/check": (b) => (b.id ? ["pact", "check", String(b.id)] : ["pact", "check"]),
-  "/api/pact/sync": () => ["pact", "sync"],
-  // The surface id, the key and the value all come from the browser — and all
-  // three are validated by the CLI, which refuses a RED surface, an unknown id,
-  // a key that does not already exist, and a write at all when handoff_write is
-  // false. There is no second idea of a safe edit anywhere in this panel.
-  "/api/handoff/set": (b) => ["handoff", "set", String(b.id), String(b.key), String(b.value)],
-  "/api/budget/calibrate": () => ["budget", "calibrate"],
-  // v0.47.0. All three are FREE and deterministic, so all three get a button.
-  // Running an ITERATION costs model tokens, so it is a copy-able command and
-  // there is deliberately no route for it here. `accept` and `rebut` both refuse
-  // without a reason — the CLI decides that, not the form.
-  "/api/challenge/accept": (b) => ["challenge", "accept", String(b.slug), String(b.id), String(b.reason || "")],
-  "/api/challenge/rebut": (b) => ["challenge", "rebut", String(b.slug), String(b.id), String(b.reason || "")],
-  "/api/challenge/report": (b) => ["challenge", "report", String(b.slug)],
-  // v0.49.1. Both are FREE and both REFUSE without a reason, so both are
-  // buttons. There is deliberately NO route for `council --set`: changing the
-  // roster mid-cycle is a decision with a recorded reason that the LANE takes in
-  // the conversation — the same reasoning that keeps `orc doc log` and
-  // `orc doc mode` off the panel. Adopting a premise needs a goals FILE, which
-  // the panel must not invent, so that one stays a copy-able command too.
-  "/api/challenge/premise": (b) => [
-    "challenge", "premise", String(b.slug), String(b.id), "--dismiss", "--reason", String(b.reason || ""),
-  ],
-  "/api/challenge/opportunity": (b) => [
-    "challenge", "opportunity", String(b.slug), String(b.id), b.take ? "--take" : "--drop", "--reason", String(b.reason || ""),
-  ],
-  // v0.48.0. `assemble` — now `compile` — is the ONE /orc-doc write that costs
-  // nothing: it concatenates section files that are already on disk, in an order
-  // the outline already fixed. Writing a section, checking one and editing one
-  // all cost model tokens, so they are copy-able commands and there is
-  // deliberately no route for any of them.
-  "/api/doc/assemble": (b) => ["doc", "assemble", String(b.slug)],
-  // v0.49.0. Both free, both non-destructive: `compile` rebuilds the artifact
-  // from disk, and `migrate` never deletes document.md and refuses what it
-  // cannot parse. `orc doc mode` deliberately has NO route — it is a USER
-  // decision the skill asks (the `orc doc log` precedent).
-  "/api/doc/compile": (b) => {
-    const argv = ["doc", "compile", String(b.slug)];
-    if (b.partial) argv.push("--partial");
-    return argv;
-  },
-  "/api/doc/migrate": (b) => ["doc", "migrate", String(b.slug)],
-  // v0.48.1. Shipping is a DECISION, so it is a write — and `--where` has no
-  // default here either, because the CLI refuses without it and the panel must
-  // never invent an argument the human path demands.
-  "/api/doc/ship": (b) => {
-    const argv = ["doc", "ship", String(b.slug), "--where", String(b.where || "")];
-    if (b.note) argv.push("--note", String(b.note));
-    if (b.force) argv.push("--force", "--reason", String(b.reason || ""));
-    return argv;
-  },
-  "/api/doc/unship": (b) => ["doc", "unship", String(b.slug), "--reason", String(b.reason || "")],
-  // v0.49.5 — the house-rule ledger is a PLAIN TEXT config, so the panel writes
-  // it the way a text config is written: the whole file, once, from one
-  // textarea. `set-all` is the only write route it needs — the per-priority
-  // `set`/`add`/`clear` commands stay a CLI convenience, and `--reset` still has
-  // no route because throwing away a project's standing rules is a CLI act.
-  //
-  // Every validator is still the CLI's. The panel has no second idea of what a
-  // house rule looks like, and the argv is a plain array, so a multi-line value
-  // needs no escaping and no temp file.
-  "/api/doc/rules/setAll": (b) => ["doc", "rules", "set-all", "--text", String(b.text || "")],
-  "/api/doc/rules/sync": (b) => ["doc", "rules", String(b.slug), "--sync"],
-  // v0.52.0 (D9) — per document, because a document's voice is the deliverable.
-  // The CLI owns the resolution order and the shadowing announcement; the panel
-  // renders both and decides neither.
-  "/api/doc/extra/set": (b) => ["doc", "extra", String(b.slug), "--set", String(b.mode)],
-  // v0.49.2. Closing a run is FREE, deterministic, reversible, and it DELETES
-  // NOTHING — `RESUME.md` is moved aside, not removed. The CLI refuses without a
-  // reason, so the form does not have to: there is one idea of a valid close and
-  // it lives in `bin/cli.js`.
-  "/api/run/close": (b) => ["run", "close", String(b.slug), "--reason", String(b.reason || "")],
-  "/api/run/reopen": (b) => ["run", "reopen", String(b.slug)],
-  // v0.50.0 — `orc extra`. Adding a connection writes a PROFILE and nothing
-  // else: no key, no route, no change to how anything builds. Removing one
-  // REFUSES without a reason — the same rule the promise ledger retires an
-  // invariant under — and names the route rows it drops, so the form does not
-  // have to: there is one idea of a valid removal and it lives in bin/cli.js.
-  //
-  // The routing table (W12). Both are STAGED in the panel and applied one at a
-  // time in staged order, so a refused row never aborts the rest — and the CLI
-  // is still what refuses an overlap, an unverified profile or a bad band spec,
-  // BY NAME. There is deliberately no `--key <value>` anywhere, because the CLI
-  // refuses it BY NAME — argv is world-readable. A pasted key travels on the
-  // connection test's STDIN and nowhere else.
-  "/api/extra/add": (b) => {
-    const argv = ["extra", "add", String(b.name), "--provider", String(b.provider), "--engine", String(b.engine)];
-    if (b.region && b.region !== "default") argv.push("--region", String(b.region));
-    if (b.base_url) argv.push("--base-url", String(b.base_url));
-    if (b.anthropic_base_url) argv.push("--anthropic-base-url", String(b.anthropic_base_url));
-    if (b.cli_bin) argv.push("--cli", String(b.cli_bin));
-    if (b.cli_agent) argv.push("--cli-agent", String(b.cli_agent));
-    // v0.52.0 — the THIRD credential source, checked FIRST. A local tool that
-    // already holds its own credential needs no key from ORC at all, and the
-    // panel forcing such a profile into the vault is what locked a run that had
-    // no business having a passphrase. ORC never writes another tool's
-    // credential store; `--tool-auth` is how that is said out loud.
-    if (b.tool_auth) argv.push("--tool-auth");
-    else if (b.vault) argv.push("--key-stdin");
-    else if (b.env_key) argv.push("--env-key", String(b.env_key));
-    return argv;
-  },
-  "/api/extra/remove": (b) => ["extra", "remove", String(b.name), "--reason", String(b.reason || "")],
-  // v0.52.0 — forgetting a saved passphrase carries no secret, so it is an
-  // ordinary argv write. SAVING one does, and has its own handler below: the
-  // passphrase travels on STDIN and `--passphrase <value>` is refused BY NAME in
-  // the CLI, so there is no argv path on either side.
-  "/api/extra/session/forget": (b) => ["extra", "session", String(b.profile), "--forget"],
-  "/api/extra/route/set": (b) => {
-    const argv = ["extra", "route", "set", String(b.band), String(b.target)];
-    if (b.small_model) argv.push("--small-model", String(b.small_model));
-    if (b.max_turns) argv.push("--max-turns", String(b.max_turns));
-    return argv;
-  },
-  "/api/extra/route/rm": (b) => ["extra", "route", "rm", String(b.band)],
-  // A slot is a POINT, not an interval, so there is no overlap to refuse and
-  // `set` on an occupied one REPLACES — which is why the panel confirms it and
-  // names what it replaces. A count is not consent.
-  "/api/extra/role/set": (b) => {
-    const argv = ["extra", "role", "set", String(b.slot), String(b.target)];
-    if (b.small_model) argv.push("--small-model", String(b.small_model));
-    if (b.max_turns) argv.push("--max-turns", String(b.max_turns));
-    return argv;
-  },
-  "/api/extra/role/rm": (b) => ["extra", "role", "rm", String(b.slot)],
-  // v0.51.0 — running the install in the USER'S OWN TERMINAL. It is a POST
-  // because it launches something; it writes no config, stores no state and
-  // never elevates. A launch that could not happen comes back exit 0 carrying
-  // the command to paste (the `openBrowser` rule), so there is no failure path
-  // that leaves the card without an answer.
-  "/api/extra/install": (b) => {
-    const argv = ["extra", "install", String(b.provider)];
-    if (b.manager) argv.push("--manager", String(b.manager));
-    return argv;
-  },
-  // A live model list is a FREE re-read of the provider's own catalogue, and a
-  // per-model test is the PAID rung scoped to one id — the only thing that tells
-  // a LISTED model from a WORKING one.
-  "/api/extra/models/refresh": (b) => ["extra", "models", String(b.profile), "--refresh"],
-  // Preview-then-apply, and the preview NAMES EVERY DIRECTORY — a count is not
-  // consent. Only a journal whose every attempt closed `done` 30+ days ago is
-  // ever a candidate, so this can never delete the record of a dispatch that
-  // never reported back.
-  "/api/extra/journal/prune": () => ["extra", "journal", "prune"],
-  "/api/crosslink/remove": (b) => ["crosslink", "remove", String(b.name)],
-  // The UI assembles no YAML. It hands the CLI the same arguments the
-  // interactive prompt collects, and every rejection the user sees is the
-  // CLI's own validator speaking — there is no second idea of a valid slug,
-  // a valid kind or a valid edge target anywhere in this panel.
-  "/api/crosslink/add": (b) => {
-    const argv = ["crosslink", "add", String(b.name), String(b.repo_path), "--kinds", String(b.kinds)];
-    if (b.direction) argv.push("--direction", String(b.direction));
-    if (b.via) argv.push("--via", String(b.via));
-    if (b.target) argv.push("--target", String(b.target));
-    return argv;
-  },
-};
-
-// Maintenance: the safety-critical panel. Each action is a PAIR — a read-only
-// preview and the apply that the preview is consent for. The apply route can
-// never be reached without the UI having fetched the preview first, and the
-// exact command is part of the preview payload so it is always visible in the
-// confirmation, and always typeable by hand instead.
-// `restarts_ui` — DOES THIS ACTION REPLACE WHAT THE PANEL IS SERVING?
-//
-// `orc upgrade` installs a new package over the one this process is running
-// from, and `orc update` / `--prune` / `doctor --fix` rewrite the payload every
-// panel reads. Node loaded bin/webui at require time and `STATIC` is a one-time
-// walk at boot, so neither is visible until the server is replaced — which used
-// to mean stop the server, re-run `orc ui`, open the new URL. The flag is
-// DECLARED per action rather than inferred, because "this command changed the
-// code under me" is not something a command's output can be read for.
-//
-// `update-global` is deliberately FALSE: it re-copies the payload into
-// ~/.claude, which is not what this server is running and not what any panel
-// here reads.
-const MAINTENANCE = {
-  update: {
-    apply: ["update"],
-    restarts_ui: true,
-    label: "Re-copy this package's payload over the installed one",
-    // `orc doctor --json` already itemises exactly what an update would change
-    // (version skew, missing files, orphans) — a preview with no second engine.
-    preview: ["doctor"],
-  },
-  prune: {
-    apply: ["update", "--prune"],
-    restarts_ui: true,
-    label: "Update AND delete ORC-named orphans from a pre-manifest install",
-    preview: ["doctor"],
-    // A count is not consent for a deletion: the UI must name every file, and
-    // doctor's findings carry `paths` for exactly the two orphan findings.
-    names_files: true,
-  },
-  fix: {
-    apply: ["doctor", "--fix"],
-    restarts_ui: true,
-    label: "Apply every fix orc doctor found (= update + prune + settings re-merge)",
-    preview: ["doctor"],
-  },
-  upgrade: {
-    apply: ["upgrade"],
-    restarts_ui: true,
-    label: "Fetch the LATEST package from the network, then apply it",
-    preview: ["version"],
-    network: true,
-  },
-  // v0.46.0 — the portable export. It belongs on Maintenance by the v0.43.6 rule
-  // (a caution routes to the panel that can CLEAR it): `export-stale` is cleared
-  // by `orc export`, which is a CLI write this panel can run. Its preview is the
-  // `--check` report, which names WHICH source drifted — a count of stale sources
-  // would not be consent to overwrite a committed file.
-  export: {
-    apply: ["export"],
-    label: "Recompile AGENTS.md from the wiki, patterns, PACT.md and boundary cards",
-    preview: ["export", "--check"],
-  },
-  // ADVANCED (v0.44.0) — the one action on this panel that does not target the
-  // project. Every other route pins `--dir <projectRoot>`; `--global` outranks
-  // `--dir` in `resolveClaudeDir`, so this pair reaches ~/.claude and its
-  // preview reports on the same place it would write.
-  //
-  // It is here because a stale GLOBAL install is a real failure this panel
-  // already REPORTS (the persistent banner, and doctor's global-skew finding)
-  // and previously could not act on — the fix was "go type it in a terminal".
-  // It stays boxed off as advanced, and it is still the only global reach the
-  // panel has: config is never written globally, because config does not merge
-  // and a global write would silently outrank the file every panel here edits.
-  "update-global": {
-    apply: ["update", "--global"],
-    label: "Re-copy this package's payload over the GLOBAL install in ~/.claude",
-    preview: ["doctor", "--global"],
-    advanced: true,
-  },
-};
-
-// ── the Experiment panel ────────────────────────────────────────────────────
-//
-// THE BOUNDARY MOVES EXACTLY ONE STEP, AND NO FURTHER. `orc ui` still renders
-// no model output, proxies no session and holds no API key — it does not become
-// an AI client. What it gains is a HANDOFF: it can open a terminal, in this
-// project, with `claude` running in it, and then forget about it. The spawned
-// process is not a child this server manages, reads or reports on; it is the
-// same detached-launch mechanism `openBrowser()` has always used.
-//
-// The lanes are a SERVER-SIDE catalog and the browser sends only an id. No
-// string typed in a browser ever reaches a shell — the cwd is always the
-// server's own projectRoot, and an unknown id is a 400. That constraint is the
-// only reason a launch button is safe on a write surface at all.
-const LANES = [
-  { id: "orc", cmd: "/orc", what: "Full pipeline: intake → plan → scored parallel waves → review → verify → ship." },
-  { id: "orc-quick", cmd: "/orc-quick", what: "Ask for anything. Look → ask once → do, and it always asks which agent." },
-  { id: "orc-mini", cmd: "/orc-mini", what: "One executor, smoke gate, ship. No full review or verify phase." },
-  { id: "orc-fast", cmd: "/orc-fast", what: "Fastest lane. Needs a fresh wiki AND a cached pattern, or it falls back." },
-  { id: "orc-ultra", cmd: "/orc-ultra", what: "Maximum rigor: an advisor plus three judgment gates. Cost accepted." },
-  { id: "orc-plan", cmd: "/orc-plan", what: "Turn a request or analyst spec into a grounded task plan. Plan only." },
-  { id: "orc-analyze", cmd: "/orc-analyze", what: "Turn a document or a vague requirement into code-grounded requirements." },
-  { id: "orc-wiki", cmd: "/orc-wiki", what: "Build or refresh the project wiki. Expensive; always asks first." },
-  { id: "orc-pattern", cmd: "/orc-pattern", what: "Learn this project's real code conventions and cache them per language." },
-  { id: "orc-verify", cmd: "/orc-verify", what: "Verify the git-modified changes in the working tree. Read-only." },
-  { id: "orc-learn", cmd: "/orc-learn", what: "Generate per-feature onboarding docs. Local and git-ignored." },
-  { id: "orc-retro", cmd: "/orc-retro", what: "Mine the behavior traces for calibration. Read-only, report-only." },
-];
-
-// ── the folder picker ───────────────────────────────────────────────────────
-//
-// The THIRD endpoint with no CLI behind it (after /api/learn's shipped content
-// and /api/experiment's lane catalog), and for the same reason: there is no
-// `orc` command that lists directories, so there is nothing to shell. It exists
-// because a crosslink repo path typed by hand is the one field in this panel
-// where a typo is invisible until the edge silently resolves to nothing — the
-// CLI then saves it as a PENDING edge and you find out much later.
-//
-// It is a DIRECTORY LISTER and nothing more, and the limits are the design:
-//   · directory names only — never a file list, never file contents, never a
-//     stat beyond "does .git / .claude/wiki exist here";
-//   · dotfolders are hidden (`.git`, `node_modules` and friends are noise here);
-//   · it reads, it never writes, and no path it is handed can reach a shell;
-//   · a path that cannot be read is an ANSWER (`error`), never a 500.
-// Nothing is copied out of the folders it lists, so a wrong click costs a
-// re-click. The browser is already loopback + token gated; this adds no reach
-// beyond what the person at the keyboard already has.
-const FS_LIST_MAX = 400;
-
-function fsList(dir, ctx) {
-  const target = path.resolve(dir || ctx.projectRoot || os.homedir());
-  let entries;
-  try {
-    entries = fs.readdirSync(target, { withFileTypes: true });
-  } catch (e) {
-    return { path: target, error: String(e.code || e.message), dirs: [] };
-  }
-  const dirs = [];
-  for (const e of entries) {
-    if (dirs.length >= FS_LIST_MAX) break;
-    if (!e.isDirectory() || e.name.startsWith(".") || e.name === "node_modules") continue;
-    const full = path.join(target, e.name);
-    dirs.push({
-      name: e.name,
-      path: full,
-      // The two facts that decide whether a folder is worth linking at all.
-      // Both are a single existsSync — nothing inside either one is read.
-      is_repo: fs.existsSync(path.join(full, ".git")),
-      has_wiki: fs.existsSync(path.join(full, ".claude", "wiki")),
-    });
-  }
-  dirs.sort((a, b) => a.name.localeCompare(b.name));
-  const parent = path.dirname(target);
-  return {
-    path: target,
-    parent: parent === target ? null : parent, // null AT a filesystem root
-    sep: path.sep,
-    home: os.homedir(),
-    project_root: ctx.projectRoot || null,
-    is_project_root: !!ctx.projectRoot && path.resolve(ctx.projectRoot) === target,
-    // What the crosslink config actually stores. Computed here rather than in
-    // the browser because only the server knows the real path separator, and a
-    // Windows path assembled with "/" is the kind of thing that works until it
-    // does not.
-    relative: ctx.projectRoot ? path.relative(ctx.projectRoot, target).split(path.sep).join("/") || "." : null,
-    truncated: dirs.length >= FS_LIST_MAX,
-    dirs,
-  };
-}
-
-// Open a terminal running `claude` in the project root. Best-effort and never
-// fatal — a failed launch is reported so the user can copy the command instead,
-// which is why the command is always on screen anyway.
-function launchClaude(ctx) {
-  const cwd = ctx.projectRoot;
-  let cmd, args;
-  if (process.platform === "win32") {
-    // `start` needs an empty title argument first, or a quoted path becomes it.
-    cmd = "cmd";
-    args = ["/c", "start", "", "cmd", "/k", "claude"];
-  } else if (process.platform === "darwin") {
-    cmd = "osascript";
-    args = ["-e", `tell application "Terminal" to do script "cd ${JSON.stringify(cwd).slice(1, -1)} && claude"`, "-e", 'tell application "Terminal" to activate'];
-  } else {
-    cmd = "x-terminal-emulator";
-    args = ["-e", "claude"];
-  }
-  try {
-    const child = spawn(cmd, args, { cwd, detached: true, stdio: "ignore", windowsHide: false });
-    child.unref();
-    return { ok: true };
-  } catch (e) {
-    return { ok: false, error: String(e && e.message) };
-  }
-}
-
-// ── request handling ────────────────────────────────────────────────────────
-
-function json(res, status, obj) {
-  const body = JSON.stringify(obj);
-  res.writeHead(status, {
-    "content-type": "application/json; charset=utf-8",
-    "cache-control": "no-store",
-    // Belt and braces on top of the loopback + token checks in serve.js.
-    "x-content-type-options": "nosniff",
-  });
-  res.end(body);
-}
-
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    let raw = "";
-    req.on("data", (c) => {
-      raw += c;
-      if (raw.length > 64_000) reject(new Error("body too large"));
-    });
-    req.on("end", () => {
-      if (!raw) return resolve({});
-      try {
-        resolve(JSON.parse(raw));
-      } catch (_) {
-        reject(new Error("body is not JSON"));
-      }
-    });
-    req.on("error", reject);
-  });
-}
-
-// The Overview panel needs four commands at once. Doing that in one request
-// keeps the first paint to a single round trip.
-function overview(ctx) {
-  const doctor = readCli(["doctor"], ctx);
-  const runs = readCli(["run", "list", "--limit", "200"], ctx);
-  const waiting = runs.data ? runs.data.runs.filter((r) => r.status === "waiting") : [];
-  return {
-    where: readCli(["where"], ctx).data,
-    doctor: doctor.data,
-    wiki: readCli(["wiki", "status"], ctx).data,
-    patterns: readCli(["pattern", "status"], ctx).data,
-    runs_total: runs.data ? runs.data.total : 0,
-    // Rows, not bare slugs (v0.49.2). The Overview card has an age column and
-    // rendered it empty because the payload never carried the number — and the
-    // "mark as done" button needs the slug beside a real timestamp to be worth
-    // showing at all.
-    waiting: waiting.map((r) => ({ slug: r.slug, updated_ms: r.updated_ms, lane: r.lane || null })),
-    diy: readCli(["diy", "show"], ctx).data,
-    // v0.46.0 chips. Each is the CLI's OWN answer — the panel repeats the state
-    // words and never derives them. A chip with nothing to say still renders its
-    // good state, so "healthy" and "not measured" never look the same.
-    pact: readCli(["pact", "status"], ctx).data,
-    boundary: readCli(["boundary", "status"], ctx).data,
-    wiki_debt: readCli(["wiki", "debt"], ctx).data,
-    // v0.54.0 — foreign dispatches that never reported back. Money spent and
-    // work half-done that nothing will look at again unless somebody is told.
-    // It is a FINDING, never a stop, and the Overview never resumes one.
-    extra_journal: readCli(["extra", "journal", "list"], ctx).data,
-  };
-}
-
-async function handleApi(req, res, url, ctx) {
-  const route = url.pathname;
-  const q = Object.fromEntries(url.searchParams);
-
-  // Liveness. The page pings this every 15s; no ping from any client for the
-  // grace window and the server exits, so a closed tab does not leave a write
-  // surface holding a valid token.
-  if (route === "/api/ping") {
-    ctx.onHeartbeat();
-    return json(res, 200, { ok: true, job: jobView() });
-  }
-
-  // sendBeacon on beforeunload — a best-effort fast path to the same shutdown
-  // the heartbeat timeout would reach a minute later.
-  if (route === "/api/bye") {
-    ctx.onBye();
-    return json(res, 200, { ok: true });
-  }
-
-  if (route === "/api/meta") {
-    return json(res, 200, {
-      project_root: ctx.projectRoot,
-      fixtures: ctx.fixtures,
-      version: ctx.version,
-      port: ctx.port,
-      idle_minutes: ctx.idleMinutes,
-      started_ms: ctx.startedMs,
-    });
-  }
-
-  if (route === "/api/job") return json(res, 200, jobView());
-
-  // Fixture mode short-circuits every data route: canned JSON, no project, no
-  // spawn. This is what makes the STALE chip and the unhealthy doctor panel
-  // designable on a machine where everything is green (see the plan, §9).
-  if (ctx.fixtures) {
-    if (req.method !== "GET") {
-      // Almost every mutation answers "nothing ran", which is the honest reply
-      // in a mode that runs nothing. The ONE exception is the connection test:
-      // its two outcomes are states the Extra panel is largely about, and a
-      // state with no fixture is a state nobody has ever looked at. A canned
-      // answer carries `data` and NOT the `fixture` flag, so the panel renders
-      // the real result shape — the command string is what says it was canned.
-      let body = {};
-      try {
-        body = await readBody(req);
-      } catch (_) {}
-      const canned = fixtures.post(route, body);
-      if (canned)
-        return json(res, 200, {
-          ok: true,
-          exit_code: canned.exit_code,
-          data: canned.data,
-          command: "(fixtures — nothing ran)",
-        });
-      return json(res, 200, { ok: true, fixture: true, command: "(fixtures — nothing ran)" });
-    }
-    const canned = fixtures.get(route, q);
-    if (canned === undefined) return json(res, 404, { error: "no fixture for " + route });
-    return json(res, 200, { ok: true, exit_code: 0, data: canned, fixture: true });
-  }
-
-  if (req.method === "GET") {
-    if (route === "/api/overview") return json(res, 200, { ok: true, exit_code: 0, data: overview(ctx) });
-    if (route === "/api/learn") {
-      // The only endpoint with no CLI behind it: the onboarding topics are
-      // static content already shipped as a module, so spawning to read them
-      // would be ceremony with a cost.
-      const { SECTIONS } = require("../onboarding-content.js");
-      return json(res, 200, { ok: true, exit_code: 0, data: { sections: SECTIONS } });
-    }
-    // The mocked runs (v0.46.x). Same shape as /api/learn above and for the
-    // same reason: this is static content that ships inside this package, so
-    // spawning a subprocess to read files sitting next to this one would be
-    // ceremony with a cost. `orc mock-run` reads the identical module, so the
-    // terminal and the panel cannot disagree.
-    if (route === "/api/mockruns") {
-      return json(res, 200, { ok: true, exit_code: 0, data: require("../mockrun-catalog.js").catalogue() });
-    }
-    if (route === "/api/mockrun") {
-      const doc = require("../mockrun-catalog.js").get(String(q.slug || ""));
-      if (!doc) return json(res, 200, { ok: true, exit_code: 1, data: { slug: String(q.slug || ""), found: false } });
-      return json(res, 200, { ok: true, exit_code: 0, data: { ...doc, found: true } });
-    }
-    if (route === "/api/fs/list") {
-      return json(res, 200, { ok: true, exit_code: 0, data: fsList(q.path, ctx) });
-    }
-    if (route === "/api/experiment") {
-      return json(res, 200, {
-        ok: true,
-        exit_code: 0,
-        data: {
-          lanes: LANES,
-          project_root: ctx.projectRoot,
-          platform: process.platform,
-          // Fixture mode must never spawn a real terminal on a machine that has
-          // no project — the button says so instead of lying about it.
-          can_launch: !ctx.fixtures,
-        },
-      });
-    }
-    if (route === "/api/maintenance") {
-      const actions = Object.entries(MAINTENANCE).map(([id, m]) => ({
-        id,
-        label: m.label,
-        command: "orc " + m.apply.join(" "),
-        network: !!m.network,
-        names_files: !!m.names_files,
-        advanced: !!m.advanced,
-        restarts_ui: !!m.restarts_ui,
-      }));
-      return json(res, 200, { ok: true, exit_code: 0, data: { actions } });
-    }
-    if (route === "/api/maintenance/preview") {
-      const m = MAINTENANCE[String(q.action)];
-      if (!m) return json(res, 400, { error: "unknown action" });
-      const probe = readCli(m.preview, ctx);
-      return json(res, 200, {
-        ok: true,
-        exit_code: 0,
-        data: {
-          action: String(q.action),
-          label: m.label,
-          command: "orc " + m.apply.join(" "),
-          network: !!m.network,
-          names_files: !!m.names_files,
-          advanced: !!m.advanced,
-          // Said in the confirmation, not discovered afterwards. A panel that
-          // reloads itself without warning reads as a crash.
-          restarts_ui: !!m.restarts_ui,
-          preview_command: "orc " + m.preview.join(" "),
-          preview: probe.data,
-          // Only the UI can know a run is mid-flight; updating changes the
-          // skills that run would resume into.
-          waiting_runs: (readCli(["run", "list", "--limit", "200"], ctx).data || { runs: [] }).runs
-            .filter((r) => r.status === "waiting")
-            .map((r) => r.slug),
-          dirty_tree: m.network ? isDirtyTree(ctx) : false,
-        },
-      });
-    }
-    const build = READS[route];
-    if (!build) return json(res, 404, { error: "unknown endpoint " + route });
-    const out = readCli(build(q), ctx);
-    // v0.49.2 — a read that produced no parseable object still has to SAY why.
-    // The body already carried `stderr` and `stdout`; nothing named `error`, so
-    // the client fell through to "request failed (500)" and one corrupt ledger
-    // looked like a broken panel. The reason the CLI printed is what is shown.
-    return json(res, out.ok ? 200 : 500, out.ok ? out : { ...out, error: readFailReason(out) });
-  }
-
-  if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
-
-  let body;
-  try {
-    body = await readBody(req);
-  } catch (e) {
-    return json(res, 400, { error: e.message });
-  }
-
-  // The handoff. It takes NO command from the browser: the lane id is looked up
-  // in the server's own catalog and is used only to echo back what to type. The
-  // process spawned is always a bare `claude` in the server's own projectRoot,
-  // so there is no path by which browser input reaches a shell.
-  if (route === "/api/experiment/launch") {
-    if (ctx.fixtures) return json(res, 400, { error: "fixture mode never launches anything real" });
-    const lane = body.lane ? LANES.find((l) => l.id === String(body.lane)) : null;
-    if (body.lane && !lane) return json(res, 400, { error: "unknown lane" });
-    const r = launchClaude(ctx);
-    if (!r.ok) return json(res, 500, { error: "could not open a terminal: " + r.error });
-    return json(res, 200, {
-      ok: true,
-      // What to type once it is open. The UI shows this; the server never runs it.
-      type_this: lane ? lane.cmd : null,
-      cwd: ctx.projectRoot,
-    });
-  }
-
-  // v0.50.0 — THE CONNECTION TEST, and the one place this panel does something
-  // model-shaped. It is a DIAGNOSTIC in the same family as `orc doctor`: rung 1
-  // lists models and costs nothing, rung 2 sends a one-token completion and
-  // costs a fraction of a cent, and the CLI decides which — never this file.
-  //
-  // It is POST because it MUTATES: a green test writes `verified_at` onto the
-  // profile, and a red one on a never-verified profile REMOVES that profile
-  // (the CLI's own test-first-then-store lifecycle). A GET that did that would
-  // be reachable by a prefetch.
-  //
-  // A pasted key arrives in the BODY and leaves on the child's STDIN — line 1
-  // the key, an optional line 2 the passphrase that encrypts it. It is never in
-  // argv, never written here, and never echoed back: the response is the CLI's
-  // own `--json` object, which carries no credential by construction.
-  if (route === "/api/extra/ping") {
-    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
-    const profile = String(body.profile || "");
-    if (!profile) return json(res, 400, { error: "missing argument" });
-    const argv = ["extra", "ping", profile];
-    // v0.51.0 — the PAID rung, opt-in and never a default. The panel quotes what
-    // it costs before the button; the CLI is what decides the rung and what it
-    // reports back.
-    if (body.live) argv.push("--live");
-    if (body.model) argv.push("--model", String(body.model));
-    let input;
-    if (body.key) {
-      // A NEW key: line 1 the key, an optional line 2 the passphrase that stores
-      // it after a green test.
-      argv.push("--key-stdin");
-      input = String(body.key) + chr10 + String(body.passphrase || "") + chr10;
-    } else if (body.passphrase) {
-      // A STORED key: the passphrase decrypts it into the CLI's memory for the
-      // probe. The two flags are mutually exclusive and the CLI refuses them
-      // together BY NAME, so this branch is an `else if` rather than a guess.
-      argv.push("--passphrase-stdin");
-      input = String(body.passphrase) + chr10;
-    }
-    const out = runCli(argv, ctx, { json: true, input });
-    clearCache();
-    // `ok` here is "did the CLI answer at all". Whether the CONNECTION worked is
-    // `data.ok` and the exit code, which are the CLI's answer and are passed
-    // through untouched — a failed probe is DATA, not a server error.
-    return json(res, out.ok ? 200 : 500, out.ok
-      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
-      : { ...out, error: readFailReason(out) });
-  }
-
-  // v0.51.0 — F5's answer, scoped to ONE model id. A model that is LISTED can
-  // still be DEAD upstream, so a dropdown is a list of what is OFFERED and never
-  // a list of what WORKS. This is POST because it spends money.
-  if (route === "/api/extra/models/test") {
-    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
-    const profile = String(body.profile || "");
-    const model = String(body.model || "");
-    if (!profile || !model) return json(res, 400, { error: "missing argument" });
-    const argv = ["extra", "models", profile, "--test", model];
-    let input;
-    if (body.passphrase) {
-      argv.push("--passphrase-stdin");
-      input = String(body.passphrase) + chr10;
-    }
-    const out = runCli(argv, ctx, { json: true, input });
-    clearCache();
-    return json(res, out.ok ? 200 : 500, out.ok
-      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
-      : { ...out, error: readFailReason(out) });
-  }
-
-  // v0.52.0 — SAVING THE PASSPHRASE WITH A DEADLINE. The CLI tests it against
-  // the vault before it stores anything (test first, then store), validates the
-  // TTL against the same closed set the config key publishes, and answers with
-  // the DATE. This route composes nothing: it hands over a profile, a number of
-  // days, and a passphrase on stdin.
-  if (route === "/api/extra/session/save") {
-    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
-    const profile = String(body.profile || "");
-    const ttl = String(body.ttl_days || "");
-    if (!profile || !ttl) return json(res, 400, { error: "missing argument" });
-    const out = runCli(["extra", "session", profile, "--save", "--ttl", ttl], ctx, {
-      json: true,
-      input: String(body.passphrase || "") + chr10,
-    });
-    clearCache();
-    return json(res, out.ok ? 200 : 500, out.ok
-      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
-      : { ...out, error: readFailReason(out) });
-  }
-
-  // v0.50.0 — proving a passphrase, which is the ONE action that clears the
-  // vault's countdown. It NEVER yields the key: `orc extra unlock` answers one
-  // question with a yes or a no, and its `attempt N of 10` message is the whole
-  // point of the feature, so it is passed back verbatim.
-  if (route === "/api/extra/unlock") {
-    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
-    const profile = String(body.profile || "");
-    if (!profile) return json(res, 400, { error: "missing argument" });
-    const out = runCli(["extra", "unlock", profile], ctx, {
-      json: true,
-      input: String(body.passphrase || "") + chr10,
-    });
-    clearCache();
-    return json(res, out.ok ? 200 : 500, out.ok
-      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
-      : { ...out, error: readFailReason(out) });
-  }
-
-  // Hand the panel over to a fresh process on the SAME port and token, so the
-  // open tab only has to reload. POST-only like every other mutation, and it is
-  // a mutation: the process answering the next request is not this one.
-  //
-  // The CLIENT asks for this — never the job's own close handler. The job's
-  // output lives in this process's memory, so restarting the instant a command
-  // finished would destroy the record of what it did before anyone read it.
-  if (route === "/api/ui/restart") {
-    if (ctx.fixtures)
-      return json(res, 400, { ok: false, reason: "fixtures", error: "fixture mode serves canned data; there is nothing to restart into." });
-    if (job && job.running) return json(res, 409, { ok: false, reason: "busy", error: "a command is still running.", job: jobView() });
-    const out = typeof ctx.restart === "function" ? ctx.restart() : { ok: false, reason: "unsupported" };
-    // A failed handover is NOT fatal and never takes the running panel down:
-    // the old server keeps serving, and the client is told to do it by hand.
-    return json(res, out.ok ? 200 : 500, out);
-  }
-
-  if (route === "/api/maintenance/apply") {
-    const m = MAINTENANCE[String(body.action)];
-    if (!m) return json(res, 400, { error: "unknown action" });
-    const started = startJob(m.apply, ctx, { restartUi: !!m.restarts_ui });
-    if (started.error) return json(res, 409, started);
-    return json(res, 200, { ok: true, ...started });
-  }
-
-  const build = WRITES[route];
-  if (!build) return json(res, 404, { error: "unknown endpoint " + route });
-  if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
-  let argv;
-  try {
-    argv = build(body);
-  } catch (_) {
-    return json(res, 400, { error: "bad request body" });
-  }
-  if (argv.some((a) => a === "undefined" || a === "null" || a === ""))
-    return json(res, 400, { error: "missing argument" });
-  const out = runCli(argv, ctx);
-  clearCache();
-  // A write's exit code is a REAL failure signal (validators exit 1), unlike a
-  // read's — so it is reported as such, with the CLI's own message.
-  return json(res, 200, {
-    ok: out.exit_code === 0,
-    exit_code: out.exit_code,
-    command: out.command,
-    // Writes print human text, not JSON — that IS the confirmation to show.
-    output: (out.stdout + (out.stderr ? "\n" + out.stderr : "")).trim(),
-  });
-}
-
-// `orc upgrade` replaces the package while your working tree may hold changes.
-// Worth a warning before, not a surprise after.
-function isDirtyTree(ctx) {
-  try {
-    const r = spawnSync("git", ["status", "--porcelain"], {
-      cwd: ctx.projectRoot,
-      encoding: "utf8",
-      windowsHide: true,
-      timeout: 5000,
-    });
-    return r.status === 0 && !!(r.stdout || "").trim();
-  } catch (_) {
-    return false;
-  }
-}
-
-module.exports = { handleApi, clearCache, READS, WRITES, MAINTENANCE };
+"use strict";
+/**
+ * api.js — the /api router for `orc ui`.
+ *
+ * THE ONE ARCHITECTURAL RULE: this file never re-implements CLI logic. Every
+ * endpoint spawns `node bin/cli.js <cmd> --json` and forwards the parsed
+ * object. That makes UI/CLI drift structurally impossible — the UI *is* the
+ * CLI — and it means every write inherits the CLI's validators, the LEGACY_KEYS
+ * aliasing and the shadowing announcements for free, with zero duplicated
+ * logic.
+ *
+ * The alternative (requiring cli.js as a library) is off the table: cli.js ends
+ * with a bare IIFE, has no require.main guard, prints and process.exit()s
+ * directly, and is pinned by contract tokens with binFiles: ["bin/cli.js"].
+ *
+ * It also never RUNS a lane and never calls a model API. Since v0.43.4 there is
+ * exactly one deliberate exception to "never spawns claude": the Experiment
+ * panel can open a TERMINAL with `claude` in it and then forget about it (see
+ * `launchClaude`). No model output ever flows back through this server, no
+ * session is proxied, no API key is held — the panel is still not an AI client.
+ */
+
+const { spawn, spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const fixtures = require("./fixtures/index.js");
+
+const CLI = path.join(__dirname, "..", "cli.js");
+
+// A single-user localhost panel re-reads the same command several times while
+// one page renders. A short TTL collapses that without ever showing stale data
+// across a user action: every mutation clears the cache outright.
+const READ_TTL_MS = 2500;
+const chr10 = String.fromCharCode(10);
+const CLI_TIMEOUT_MS = 30_000;
+
+const cache = new Map();
+
+function cacheKey(argv) {
+  return argv.join("\u0000");
+}
+
+function clearCache() {
+  cache.clear();
+}
+
+// ── running the CLI ─────────────────────────────────────────────────────────
+
+// Several commands use a NON-ZERO exit as a normal answer, not a failure:
+// `pattern status` (1 = absent, 2 = unknown key), `gotcha list` (1 = none),
+// `wiki impact` (2 = delta, 3 = full), `pr stack status` (1 = not ready),
+// `doctor` (1 = issues found), `resume` (1 = nothing waiting). So the exit code
+// is DATA here, never an error condition — a run counts as failed only when it
+// produced no parseable object.
+// `input` (v0.50.0) is stdin for the child, and it exists for exactly one
+// caller: the connection test, which takes a pasted API key on line 1 and an
+// optional passphrase on line 2. It is a parameter rather than a second spawn
+// helper because a secret must travel the SAME path everything else does —
+// never argv (world-readable in a process list), never a temp file, never a log
+// line. Nothing here ever echoes it back, and `command` below is built from
+// argv alone.
+function runCli(argv, ctx, { json = false, input = undefined } = {}) {
+  const args = [...argv];
+  if (json) args.push("--json");
+  // Always target the project explicitly: the server's cwd is not a reliable
+  // way to reach the same .claude the launching command resolved.
+  if (ctx.projectRoot) args.push("--dir", ctx.projectRoot);
+  // ORC_NO_UPDATE_CHECK exists here to protect the --json contract: most
+  // commands end with `maybeNudge()`, which prints an "update available" line to
+  // STDOUT and would sit beside the object this parses.
+  //
+  // `version` and `changelog` are the exceptions, and forcing the flag on them
+  // was a real bug: neither nudges, and for both the check IS the payload — so
+  // the panel asked whether an update existed with the check switched off and
+  // was told `check_disabled: true` forever. A blanket env var silenced the one
+  // command whose entire job is to answer that question.
+  const CHECKS_UPDATES = argv[0] === "version" || argv[0] === "changelog";
+  const env = { ...process.env, NO_COLOR: "1" };
+  if (!CHECKS_UPDATES) env.ORC_NO_UPDATE_CHECK = "1";
+  const r = spawnSync(process.execPath, [CLI, ...args], {
+    encoding: "utf8",
+    timeout: CLI_TIMEOUT_MS,
+    windowsHide: true,
+    env,
+    input,
+  });
+  const stdout = r.stdout || "";
+  let data = null;
+  try {
+    data = JSON.parse(stdout);
+  } catch (_) {}
+  return {
+    ok: data !== null,
+    exit_code: r.status === null ? -1 : r.status,
+    data,
+    stderr: (r.stderr || "").trim(),
+    stdout: data === null ? stdout.trim() : "",
+    command: "orc " + argv.join(" "),
+  };
+}
+
+// The one-line reason a read failed, in the CLI's own words. `crashed` is the
+// envelope the CLI itself emits when a `--json` route throws (v0.49.2); anything
+// else is a command that wrote nothing parseable at all.
+function readFailReason(out) {
+  const first = (out.stderr || out.stdout || "")
+    .split(chr10)
+    .map((l) => l.trim())
+    .filter(Boolean)[0];
+  const tail = first ? " \u2014 " + first : "";
+  return `${out.command} produced no JSON (exit ${out.exit_code})${tail}`;
+}
+
+function readCli(argv, ctx) {
+  const key = cacheKey([ctx.projectRoot || "", ...argv]);
+  const hit = cache.get(key);
+  if (hit && Date.now() - hit.at < READ_TTL_MS) return hit.value;
+  const value = runCli(argv, ctx, { json: true });
+  cache.set(key, { at: Date.now(), value });
+  return value;
+}
+
+// ── jobs (the mutation half) ────────────────────────────────────────────────
+// SINGLE-FLIGHT: one mutation at a time, process-wide. The client goes
+// read-only while a job runs, so a second one is a bug, not a race to win.
+// Output accumulates in memory and the client polls /api/job — which is what
+// makes `orc update` and `orc upgrade` show their real output as it happens
+// instead of a spinner and a verdict.
+
+let job = null;
+let jobSeq = 0;
+
+function jobView() {
+  if (!job) return { id: null, running: false };
+  return {
+    id: job.id,
+    command: job.command,
+    running: job.running,
+    exit_code: job.exit_code,
+    output: job.output,
+    started_ms: job.started_ms,
+    // THE PANEL IS SERVING CODE THAT THIS JOB MAY HAVE JUST REPLACED. Reported
+    // only on a job that SUCCEEDED and whose action is declared as touching the
+    // install — a failed upgrade changed nothing, so restarting after one would
+    // be motion with no reason. The client acts on it; the server does not
+    // restart itself, so the job's output survives long enough to be read.
+    restart_pending: !!(job.restart_ui && !job.running && job.exit_code === 0),
+  };
+}
+
+function startJob(argv, ctx, opts) {
+  if (job && job.running) return { error: "busy", job: jobView() };
+  const args = [...argv];
+  if (ctx.projectRoot) args.push("--dir", ctx.projectRoot);
+  const id = ++jobSeq;
+  job = {
+    id,
+    command: "orc " + argv.join(" "),
+    running: true,
+    exit_code: null,
+    output: "",
+    started_ms: Date.now(),
+    restart_ui: !!(opts && opts.restartUi),
+  };
+  const child = spawn(process.execPath, [CLI, ...args], {
+    windowsHide: true,
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+  const append = (buf) => {
+    job.output += buf.toString("utf8");
+    // A runaway job must not grow the server's heap without bound.
+    if (job.output.length > 400_000) job.output = job.output.slice(-400_000);
+  };
+  child.stdout.on("data", append);
+  child.stderr.on("data", append);
+  child.on("error", (e) => {
+    job.output += "\n" + String(e.message);
+    job.exit_code = -1;
+    job.running = false;
+  });
+  child.on("close", (code) => {
+    job.exit_code = code === null ? -1 : code;
+    job.running = false;
+    clearCache(); // every panel refetches against the new truth
+  });
+  return { job: jobView() };
+}
+
+// ── the endpoint table ──────────────────────────────────────────────────────
+// READS map a route to CLI argv. WRITES are separate and POST-only — a GET can
+// never mutate, so a prefetch, a bookmark or a browser retry is always safe.
+
+const READS = {
+  "/api/version": () => ["version"],
+  "/api/changelog": () => ["changelog"],
+  "/api/where": () => ["where"],
+  "/api/doctor": () => ["doctor"],
+  "/api/config": () => ["config", "list"],
+  "/api/config/profiles": () => ["config", "profile"],
+  "/api/config/recommend": () => ["config", "recommend"],
+  // v1.0.0 W16 — the `orc lane` noun, rendered. All three are READS and all
+  // three are answers the CLI already computes in full: which lanes exist and
+  // how many keys each reads, which SHARED phases a lane runs and in what
+  // order, and the whole call catalogue. The panel draws them and decides
+  // nothing about them — the Flow-stepper rule, applied to the lane model.
+  // `lane phases` and `lane config` both exit 2 on an unknown lane, which is
+  // DATA here exactly like `pattern status` and `wiki impact` above.
+  "/api/lanes": () => ["lane", "list"],
+  "/api/lane/phases": (q) => ["lane", "phases", String(q.lane || "")],
+  "/api/lane/calls": (q) => (q.lane ? ["lane", "calls", String(q.lane)] : ["lane", "calls", "--all"]),
+  "/api/runs": (q) => ["run", "list", "--limit", String(Math.min(200, Number(q.limit) || 40))],
+  "/api/run": (q) => ["run", "show", String(q.slug || "")],
+  "/api/wiki": () => ["wiki", "status"],
+  "/api/wiki/impact": () => ["wiki", "impact"],
+  // v0.46.0. Every one is a READ with an exit-code contract, so the exit code is
+  // DATA here exactly like `pattern status` and `wiki impact` above: pact 0/1/2/3,
+  // boundary 0/1/2/3, handoff 0/1, budget 0/1/2/3, aftermath 0/1/2/3,
+  // wiki plan 0/1/2/3, wiki debt 0/1/3, export --check 0/1.
+  "/api/wiki/plan": () => ["wiki", "plan"],
+  "/api/wiki/debt": () => ["wiki", "debt"],
+  "/api/wiki/usage": () => ["wiki", "usage"],
+  // v0.49.1 — the wiki's CONTENTS, not only its temperature. All three are
+  // READS whose exit code is DATA (docs 0/1/3, show 0/2/3, coverage 0/1), and
+  // `coverage` deliberately has no threshold: nothing branches on it, here or
+  // anywhere else. `--body` is opt-in and one artifact at a time — the
+  // /api/doc/section precedent.
+  "/api/wiki/docs": () => ["wiki", "docs"],
+  "/api/wiki/show": (q) => ["wiki", "show", String(q.doc || ""), ...(q.body ? ["--body"] : [])],
+  "/api/wiki/coverage": () => ["wiki", "coverage"],
+  // The pattern file is injected LITERALLY into every executor slice, and until
+  // now nothing would show you a line of it. Same 0/1/2 contract `pattern
+  // status` has had since v0.34.8.
+  "/api/pattern/show": (q) => ["pattern", "show", String(q.lang || ""), ...(q.body ? ["--body"] : [])],
+  "/api/gotcha/show": (q) => ["gotcha", "show", String(q.id || "")],
+  "/api/gotchas/archived": () => ["gotcha", "list", "--archived"],
+  // Preview-then-apply: A COUNT IS NOT CONSENT. The Apply button stays disabled
+  // until this has been fetched, and it names every entry eviction would touch.
+  "/api/gotcha/prune/preview": () => ["gotcha", "prune", "--dry-run"],
+  // v1.1.0 — the wait. Three READS, and every one of them is a state the panel
+  // renders and never derives: `usage check` 0/1/2 (and `unknown` is a state,
+  // not a failure), the lane table, and the run's block. The panel CANNOT start
+  // a wait — a wait lives in a Claude Code session, and `orc ui` never runs a
+  // lane. It configures the defaults, shows a wait, and cancels one.
+  "/api/usage": () => ["usage", "check"],
+  "/api/wait/lanes": () => ["wait", "lanes"],
+  "/api/wait/status": (q) => (q.slug ? ["wait", "status", String(q.slug)] : ["wait", "status"]),
+  "/api/pact": () => ["pact", "status"],
+  "/api/boundary": (q) => (q.path ? ["boundary", "status", String(q.path)] : ["boundary", "status"]),
+  "/api/handoff": () => ["handoff", "surfaces"],
+  "/api/budget/rates": () => ["budget", "rates"],
+  // A forecast takes a PLAN PATH. The browser sends a path the folder picker
+  // produced; the server passes it straight to the CLI and never opens the file
+  // itself — /api/fs/list stays a directory LISTER, and widening it to read a
+  // plan would be the one change that turns this panel into a file reader.
+  "/api/budget/forecast": (q) => ["budget", "forecast", String(q.plan || "")],
+  "/api/budget/actual": (q) => ["budget", "actual", String(q.slug || "")],
+  "/api/aftermath": (q) => (q.since ? ["aftermath", "status", "--since", String(q.since)] : ["aftermath", "status"]),
+  "/api/export": () => ["export", "--check"],
+  // v0.47.0 — /orc-challenge. Same shape: every one is a READ whose exit code is
+  // DATA (list 0/1/3, status 0/1/2/3, diff 0/1/2/3, lint 0/1/2), and the panel
+  // derives nothing from them — not the state word, not the iteration order, not
+  // the pass decision, not the expected revision path.
+  "/api/challenge": () => ["challenge", "list"],
+  "/api/challenge/one": (q) => ["challenge", "status", String(q.slug || "")],
+  "/api/challenge/show": (q) => [
+    "challenge",
+    "show",
+    String(q.slug || ""),
+    ...(q.iteration ? ["--iteration", String(q.iteration)] : []),
+  ],
+  "/api/challenge/diff": (q) => ["challenge", "diff", String(q.slug || "")],
+  // v0.49.1 — the council. `roles` is STATIC (it works with no cycle at all),
+  // and it is the ONE catalogue: the panel names no lens, no class and no
+  // disposition itself, exactly as it names no flow step. `council` is 0 set /
+  // 1 unset / 3 unknown, and UNSET is an ANSWER, not an error.
+  "/api/challenge/roles": (q) => ["challenge", "roles", ...(q.kind ? ["--kind", String(q.kind)] : [])],
+  "/api/challenge/council": (q) => ["challenge", "council", String(q.slug || "")],
+  "/api/challenge/lint": (q) => [
+    "challenge",
+    "lint",
+    String(q.path || ""),
+    ...(q.template ? ["--template", String(q.template)] : []),
+  ],
+  // v0.48.0 — /orc-doc. Same shape again: every one is a READ whose exit code is
+  // DATA (list 0, status 0/1/2, map 0/2, plan 0/1, lint 0/1/2), and the panel
+  // derives nothing from them — not the section order, not a line range, not a
+  // state word, not the batching, not a lint rule name. It draws what the CLI
+  // computed.
+  //
+  // `/api/doc/section` is the ONE route that returns any of the document's
+  // prose, it returns exactly ONE section, and only on an explicit Reveal click.
+  // The rule this lane lives by is that nothing HOLDS the document — not that
+  // the text is secret — and the panel renders it as DOM through `renderMd`,
+  // never as HTML.
+  "/api/doc": () => ["doc", "list"],
+  "/api/doc/one": (q) => ["doc", "status", String(q.slug || "")],
+  "/api/doc/show": (q) => ["doc", "show", String(q.slug || "")],
+  "/api/doc/section": (q) => ["doc", "show", String(q.slug || ""), "--section", String(q.section || "")],
+  "/api/doc/map": (q) => ["doc", "map", String(q.slug || "")],
+  "/api/doc/lint": (q) => [
+    "doc",
+    "lint",
+    String(q.slug || ""),
+    ...(q.target ? ["--target", String(q.target)] : []),
+  ],
+  "/api/doc/plan": (q) => ["doc", "plan", String(q.slug || ""), "--role", String(q.role || "write")],
+  "/api/doc/templates": () => ["doc", "templates"],
+  "/api/doc/targets": () => ["doc", "targets"],
+  // v0.48.1 — the score, the drift report and the memory surface. Every one is
+  // a subprocess of the real command: the panel decides nothing about the
+  // pipeline order, nothing about which drift classes exist, and nothing about
+  // which journal rows are the user's own words.
+  //
+  // There is deliberately NO route for `orc doc log`: the SKILL records a
+  // request, because the skill is what took one. A panel that could write a
+  // journal entry could write one nobody said.
+  // v0.49.0 — the SECTION FILES. This is the one read that works before a
+  // single compile has ever run, because the files ARE the progress.
+  "/api/doc/parts": (q) => ["doc", "parts", String(q.slug || "")],
+  "/api/doc/next": (q) => ["doc", "next", String(q.slug || "")],
+  "/api/doc/audit": (q) => ["doc", "audit", String(q.slug || "")],
+  "/api/doc/journal": (q) => ["doc", "journal", String(q.slug || "")],
+  "/api/doc/context": (q) => ["doc", "context", String(q.slug || "")],
+  "/api/doc/extra": (q) => ["doc", "extra", String(q.slug || "")],
+  // v0.49.2 — the project's own house rules, the frozen set of one document,
+  // the run map and the cost report. All four are READS; the panel decides
+  // nothing about a priority, an order, a wave shape or a number.
+  "/api/doc/rules": () => ["doc", "rules"],
+  "/api/doc/rules/one": (q) => ["doc", "rules", String(q.slug || "")],
+  "/api/doc/forecast": (q) => ["doc", "forecast", String(q.slug || "")],
+  "/api/doc/cost": (q) => ["doc", "cost", String(q.slug || "")],
+  // v0.50.0 — `orc extra`. Every one is a READ, and every one is a subprocess of
+  // the real command: the panel decides nothing about a provider, a model id, a
+  // verification state, a band or a price. It renders what the CLI computed.
+  //
+  // There is deliberately NO read that returns a credential. `orc extra list`
+  // and `orc extra show` go through `redactProfile`, which is an ALLOW-LIST, so
+  // a field added later that carries a secret has to be let through on purpose.
+  "/api/extra": () => ["extra", "list"],
+  "/api/extra/providers": () => ["extra", "providers"],
+  "/api/extra/show": (q) => ["extra", "show", String(q.profile || "")],
+  "/api/extra/models": (q) => ["extra", "models", String(q.profile || "")],
+  // v0.51.0 — the LOCAL TOOLS read, and the credential-route read. Both are the
+  // real commands, so the panel decides nothing about an install command, a
+  // platform, a version floor or which of three credential routes applies.
+  // `tools` exits 1 when no tool is ready, which is exit-code-as-DATA like
+  // `pattern status` — never an error.
+  "/api/extra/tools": () => ["extra", "tools"],
+  "/api/extra/keyhelp": (q) => ["extra", "keyhelp", String(q.profile || "")],
+  "/api/extra/route": () => ["extra", "route"],
+  // v0.55.0 — THE POSITIONS, the non-scored half of routing. It exits 1 when
+  // nothing routes, which is exit-code-as-DATA like `pattern status` — an empty
+  // result is an ANSWER and it still returns its whole object.
+  "/api/extra/role": () => ["extra", "role", "list"],
+  // v0.52.0 (D6) — WHICH LANE a band governs, computed through the same
+  // resolver every dispatch uses. The panel renders it and derives nothing:
+  // a band with no lane attached is not a routing decision.
+  "/api/extra/lanes": () => ["extra", "lanes"],
+  // `stats` exits 1 with a real object when no foreign dispatch has been traced
+  // yet, and `rates` exits 1 when a pair has no price — both are exit-code-as-
+  // DATA, like `pattern status` and `wiki impact`, never an error.
+  "/api/extra/stats": (q) => (q.since ? ["extra", "stats", "--since", String(q.since)] : ["extra", "stats"]),
+  "/api/extra/rates": () => ["extra", "rates"],
+  "/api/extra/doctor": () => ["extra", "doctor"],
+  // v0.54.0 — RECOVERY. Both are FREE reads (zero model tokens), which is why
+  // both are real buttons; `resume-slice` and the dispatch that follows it cost
+  // money and are copy-able commands instead. `reconcile` exits 0-4 as an
+  // exit-code-as-DATA contract like `pattern status`, so no state here is an
+  // error — including `in-flight`, which is a REFUSAL the panel must render as
+  // one rather than as a dead control.
+  "/api/extra/journal": () => ["extra", "journal", "list"],
+  // v1.0.0 W16 — the RUN DEMOTION, read. Exit 0 armed · 1 demoted · 2 unknown
+  // run, which is exit-code-as-DATA like every other gate command here. The
+  // run is optional: with none given the CLI reads the trace pointer, which is
+  // exactly what a panel wants — "the run that is open right now".
+  "/api/extra/demotion": (q) => ["extra", "demotion", ...(q.run ? [String(q.run)] : [])],
+  "/api/extra/reconcile": (q) => ["extra", "reconcile", String(q.task || "")],
+  "/api/extra/journal/prune/preview": () => ["extra", "journal", "prune", "--dry-run"],
+  "/api/patterns": () => ["pattern", "status"],
+  "/api/gotchas": () => ["gotcha", "list"],
+  "/api/stats": (q) => (q.since ? ["stats", "--since", String(q.since)] : ["stats"]),
+  "/api/diy": () => ["diy", "show"],
+  "/api/crosslink": () => ["crosslink", "list"],
+  "/api/crosslink/kinds": () => ["crosslink", "kinds"],
+  "/api/mocks": () => ["mock", "list"],
+  "/api/mock": (q) => ["mock", "show", String(q.slug || "")],
+  "/api/stack": (q) => (q.slug ? ["pr", "stack", "status", String(q.slug)] : ["pr", "stack", "status"]),
+};
+
+// v0.46.0 writes. THE LINE THIS PANEL DOES NOT CROSS: a button exists only for an
+// action that costs NO model tokens. `orc pact check` runs the ledger's own cheap
+// proofs (a test, a command, a grep the user wrote); `orc handoff set` edits one
+// graded surface; `orc export` compiles files already on disk. Every one is
+// deterministic and every one is a real CLI command.
+//
+// The conversational half of each lane — reconciling a promise, deciding a
+// verdict, walking somebody through a change — costs model tokens, so the panel
+// COPIES those commands and never runs them. A test greps this object to make
+// sure no lane name ever appears inside it.
+const WRITES = {
+  "/api/config/set": (b) => ["config", "set", String(b.key), String(b.value)],
+  "/api/config/reset": (b) => (b.key ? ["config", "reset", String(b.key)] : ["config", "reset"]),
+  "/api/config/profile": (b) => ["config", "profile", String(b.name)],
+  "/api/diy/set": (b) => ["diy", "set", String(b.key), String(b.value)],
+  "/api/diy/compile": () => ["diy", "compile"],
+  // The bootstrap the TTY composer offers as its first question, and the one
+  // piece of DIY the panel had no way to reach (v0.44.0). `--force` is what
+  // makes it an ANSWER rather than an error on an already-configured project:
+  // `orc diy init` refuses to overwrite without it. That is destructive, so the
+  // UI confirms with the preset's own diff and the exact command on screen.
+  // An empty name is the wizard's "full-lane defaults" — a real invocation,
+  // not a synthesised one.
+  "/api/diy/preset": (b) => {
+    const argv = ["diy", "init", "--force"];
+    if (b.name) argv.push("--preset", String(b.name));
+    return argv;
+  },
+  // v1.1.0 — the only two wait mutations this panel may make, and neither
+  // starts one. `unblock` restores a gate the user vetoed; `cancel` ends a wait
+  // already running. A BLOCK cannot be created here on purpose: it needs a
+  // reason typed in the moment, and a reason typed into a settings page days
+  // later is not the record that makes the risk demonstrably the user's.
+  "/api/wait/unblock": (b) => (b.slug ? ["wait", "unblock", String(b.slug)] : ["wait", "unblock"]),
+  "/api/wait/cancel": (b) => (b.slug ? ["wait", "cancel", String(b.slug)] : ["wait", "cancel"]),
+  "/api/wiki/sync": () => ["wiki", "sync"],
+  "/api/wiki/usage/rebuild": () => ["wiki", "usage", "--rebuild"],
+  "/api/gotcha/prune": () => ["gotcha", "prune"],
+  "/api/pact/check": (b) => (b.id ? ["pact", "check", String(b.id)] : ["pact", "check"]),
+  "/api/pact/sync": () => ["pact", "sync"],
+  // The surface id, the key and the value all come from the browser — and all
+  // three are validated by the CLI, which refuses a RED surface, an unknown id,
+  // a key that does not already exist, and a write at all when handoff_write is
+  // false. There is no second idea of a safe edit anywhere in this panel.
+  "/api/handoff/set": (b) => ["handoff", "set", String(b.id), String(b.key), String(b.value)],
+  "/api/budget/calibrate": () => ["budget", "calibrate"],
+  // v0.47.0. All three are FREE and deterministic, so all three get a button.
+  // Running an ITERATION costs model tokens, so it is a copy-able command and
+  // there is deliberately no route for it here. `accept` and `rebut` both refuse
+  // without a reason — the CLI decides that, not the form.
+  "/api/challenge/accept": (b) => ["challenge", "accept", String(b.slug), String(b.id), String(b.reason || "")],
+  "/api/challenge/rebut": (b) => ["challenge", "rebut", String(b.slug), String(b.id), String(b.reason || "")],
+  "/api/challenge/report": (b) => ["challenge", "report", String(b.slug)],
+  // v0.49.1. Both are FREE and both REFUSE without a reason, so both are
+  // buttons. There is deliberately NO route for `council --set`: changing the
+  // roster mid-cycle is a decision with a recorded reason that the LANE takes in
+  // the conversation — the same reasoning that keeps `orc doc log` and
+  // `orc doc mode` off the panel. Adopting a premise needs a goals FILE, which
+  // the panel must not invent, so that one stays a copy-able command too.
+  "/api/challenge/premise": (b) => [
+    "challenge", "premise", String(b.slug), String(b.id), "--dismiss", "--reason", String(b.reason || ""),
+  ],
+  "/api/challenge/opportunity": (b) => [
+    "challenge", "opportunity", String(b.slug), String(b.id), b.take ? "--take" : "--drop", "--reason", String(b.reason || ""),
+  ],
+  // v0.48.0. `assemble` — now `compile` — is the ONE /orc-doc write that costs
+  // nothing: it concatenates section files that are already on disk, in an order
+  // the outline already fixed. Writing a section, checking one and editing one
+  // all cost model tokens, so they are copy-able commands and there is
+  // deliberately no route for any of them.
+  "/api/doc/assemble": (b) => ["doc", "assemble", String(b.slug)],
+  // v0.49.0. Both free, both non-destructive: `compile` rebuilds the artifact
+  // from disk, and `migrate` never deletes document.md and refuses what it
+  // cannot parse. `orc doc mode` deliberately has NO route — it is a USER
+  // decision the skill asks (the `orc doc log` precedent).
+  "/api/doc/compile": (b) => {
+    const argv = ["doc", "compile", String(b.slug)];
+    if (b.partial) argv.push("--partial");
+    return argv;
+  },
+  "/api/doc/migrate": (b) => ["doc", "migrate", String(b.slug)],
+  // v0.48.1. Shipping is a DECISION, so it is a write — and `--where` has no
+  // default here either, because the CLI refuses without it and the panel must
+  // never invent an argument the human path demands.
+  "/api/doc/ship": (b) => {
+    const argv = ["doc", "ship", String(b.slug), "--where", String(b.where || "")];
+    if (b.note) argv.push("--note", String(b.note));
+    if (b.force) argv.push("--force", "--reason", String(b.reason || ""));
+    return argv;
+  },
+  "/api/doc/unship": (b) => ["doc", "unship", String(b.slug), "--reason", String(b.reason || "")],
+  // v0.49.5 — the house-rule ledger is a PLAIN TEXT config, so the panel writes
+  // it the way a text config is written: the whole file, once, from one
+  // textarea. `set-all` is the only write route it needs — the per-priority
+  // `set`/`add`/`clear` commands stay a CLI convenience, and `--reset` still has
+  // no route because throwing away a project's standing rules is a CLI act.
+  //
+  // Every validator is still the CLI's. The panel has no second idea of what a
+  // house rule looks like, and the argv is a plain array, so a multi-line value
+  // needs no escaping and no temp file.
+  "/api/doc/rules/setAll": (b) => ["doc", "rules", "set-all", "--text", String(b.text || "")],
+  "/api/doc/rules/sync": (b) => ["doc", "rules", String(b.slug), "--sync"],
+  // v0.52.0 (D9) — per document, because a document's voice is the deliverable.
+  // The CLI owns the resolution order and the shadowing announcement; the panel
+  // renders both and decides neither.
+  "/api/doc/extra/set": (b) => ["doc", "extra", String(b.slug), "--set", String(b.mode)],
+  // v0.49.2. Closing a run is FREE, deterministic, reversible, and it DELETES
+  // NOTHING — `RESUME.md` is moved aside, not removed. The CLI refuses without a
+  // reason, so the form does not have to: there is one idea of a valid close and
+  // it lives in `bin/cli.js`.
+  "/api/run/close": (b) => ["run", "close", String(b.slug), "--reason", String(b.reason || "")],
+  "/api/run/reopen": (b) => ["run", "reopen", String(b.slug)],
+  // v0.50.0 — `orc extra`. Adding a connection writes a PROFILE and nothing
+  // else: no key, no route, no change to how anything builds. Removing one
+  // REFUSES without a reason — the same rule the promise ledger retires an
+  // invariant under — and names the route rows it drops, so the form does not
+  // have to: there is one idea of a valid removal and it lives in bin/cli.js.
+  //
+  // The routing table (W12). Both are STAGED in the panel and applied one at a
+  // time in staged order, so a refused row never aborts the rest — and the CLI
+  // is still what refuses an overlap, an unverified profile or a bad band spec,
+  // BY NAME. There is deliberately no `--key <value>` anywhere, because the CLI
+  // refuses it BY NAME — argv is world-readable. A pasted key travels on the
+  // connection test's STDIN and nowhere else.
+  "/api/extra/add": (b) => {
+    const argv = ["extra", "add", String(b.name), "--provider", String(b.provider), "--engine", String(b.engine)];
+    if (b.region && b.region !== "default") argv.push("--region", String(b.region));
+    if (b.base_url) argv.push("--base-url", String(b.base_url));
+    if (b.anthropic_base_url) argv.push("--anthropic-base-url", String(b.anthropic_base_url));
+    if (b.cli_bin) argv.push("--cli", String(b.cli_bin));
+    if (b.cli_agent) argv.push("--cli-agent", String(b.cli_agent));
+    // v0.52.0 — the THIRD credential source, checked FIRST. A local tool that
+    // already holds its own credential needs no key from ORC at all, and the
+    // panel forcing such a profile into the vault is what locked a run that had
+    // no business having a passphrase. ORC never writes another tool's
+    // credential store; `--tool-auth` is how that is said out loud.
+    if (b.tool_auth) argv.push("--tool-auth");
+    else if (b.vault) argv.push("--key-stdin");
+    else if (b.env_key) argv.push("--env-key", String(b.env_key));
+    return argv;
+  },
+  "/api/extra/remove": (b) => ["extra", "remove", String(b.name), "--reason", String(b.reason || "")],
+  // v0.52.0 — forgetting a saved passphrase carries no secret, so it is an
+  // ordinary argv write. SAVING one does, and has its own handler below: the
+  // passphrase travels on STDIN and `--passphrase <value>` is refused BY NAME in
+  // the CLI, so there is no argv path on either side.
+  "/api/extra/session/forget": (b) => ["extra", "session", String(b.profile), "--forget"],
+  "/api/extra/route/set": (b) => {
+    const argv = ["extra", "route", "set", String(b.band), String(b.target)];
+    if (b.small_model) argv.push("--small-model", String(b.small_model));
+    if (b.max_turns) argv.push("--max-turns", String(b.max_turns));
+    return argv;
+  },
+  "/api/extra/route/rm": (b) => ["extra", "route", "rm", String(b.band)],
+  // A slot is a POINT, not an interval, so there is no overlap to refuse and
+  // `set` on an occupied one REPLACES — which is why the panel confirms it and
+  // names what it replaces. A count is not consent.
+  "/api/extra/role/set": (b) => {
+    const argv = ["extra", "role", "set", String(b.slot), String(b.target)];
+    if (b.small_model) argv.push("--small-model", String(b.small_model));
+    if (b.max_turns) argv.push("--max-turns", String(b.max_turns));
+    return argv;
+  },
+  "/api/extra/role/rm": (b) => ["extra", "role", "rm", String(b.slot)],
+  // v0.51.0 — running the install in the USER'S OWN TERMINAL. It is a POST
+  // because it launches something; it writes no config, stores no state and
+  // never elevates. A launch that could not happen comes back exit 0 carrying
+  // the command to paste (the `openBrowser` rule), so there is no failure path
+  // that leaves the card without an answer.
+  "/api/extra/install": (b) => {
+    const argv = ["extra", "install", String(b.provider)];
+    if (b.manager) argv.push("--manager", String(b.manager));
+    return argv;
+  },
+  // A live model list is a FREE re-read of the provider's own catalogue, and a
+  // per-model test is the PAID rung scoped to one id — the only thing that tells
+  // a LISTED model from a WORKING one.
+  "/api/extra/models/refresh": (b) => ["extra", "models", String(b.profile), "--refresh"],
+  // Preview-then-apply, and the preview NAMES EVERY DIRECTORY — a count is not
+  // consent. Only a journal whose every attempt closed `done` 30+ days ago is
+  // ever a candidate, so this can never delete the record of a dispatch that
+  // never reported back.
+  "/api/extra/journal/prune": () => ["extra", "journal", "prune"],
+  // A PROMOTE IS A HUMAN ACTION AND A REASON IS REQUIRED (v1.0.0 W5). The CLI
+  // refuses without one — exit 2, `reason-required` — so the panel does not
+  // validate it a second time; it collects it and lets the CLI decide, which is
+  // the same contract every other write on this server keeps. There is
+  // deliberately NO demote route: demoting by hand is a diagnostic somebody
+  // reaches for at a terminal, and a button for it would invite muting a
+  // provider instead of fixing it.
+  "/api/extra/promote": (b) => ["extra", "promote", String(b.run || ""), "--reason", String(b.reason || "")],
+  "/api/crosslink/remove": (b) => ["crosslink", "remove", String(b.name)],
+  // The UI assembles no YAML. It hands the CLI the same arguments the
+  // interactive prompt collects, and every rejection the user sees is the
+  // CLI's own validator speaking — there is no second idea of a valid slug,
+  // a valid kind or a valid edge target anywhere in this panel.
+  "/api/crosslink/add": (b) => {
+    const argv = ["crosslink", "add", String(b.name), String(b.repo_path), "--kinds", String(b.kinds)];
+    if (b.direction) argv.push("--direction", String(b.direction));
+    if (b.via) argv.push("--via", String(b.via));
+    if (b.target) argv.push("--target", String(b.target));
+    return argv;
+  },
+};
+
+// Maintenance: the safety-critical panel. Each action is a PAIR — a read-only
+// preview and the apply that the preview is consent for. The apply route can
+// never be reached without the UI having fetched the preview first, and the
+// exact command is part of the preview payload so it is always visible in the
+// confirmation, and always typeable by hand instead.
+// `restarts_ui` — DOES THIS ACTION REPLACE WHAT THE PANEL IS SERVING?
+//
+// `orc upgrade` installs a new package over the one this process is running
+// from, and `orc update` / `--prune` / `doctor --fix` rewrite the payload every
+// panel reads. Node loaded bin/webui at require time and `STATIC` is a one-time
+// walk at boot, so neither is visible until the server is replaced — which used
+// to mean stop the server, re-run `orc ui`, open the new URL. The flag is
+// DECLARED per action rather than inferred, because "this command changed the
+// code under me" is not something a command's output can be read for.
+//
+// `update-global` is deliberately FALSE: it re-copies the payload into
+// ~/.claude, which is not what this server is running and not what any panel
+// here reads.
+const MAINTENANCE = {
+  update: {
+    apply: ["update"],
+    restarts_ui: true,
+    label: "Re-copy this package's payload over the installed one",
+    // `orc doctor --json` already itemises exactly what an update would change
+    // (version skew, missing files, orphans) — a preview with no second engine.
+    preview: ["doctor"],
+  },
+  prune: {
+    apply: ["update", "--prune"],
+    restarts_ui: true,
+    label: "Update AND delete ORC-named orphans from a pre-manifest install",
+    preview: ["doctor"],
+    // A count is not consent for a deletion: the UI must name every file, and
+    // doctor's findings carry `paths` for exactly the two orphan findings.
+    names_files: true,
+  },
+  fix: {
+    apply: ["doctor", "--fix"],
+    restarts_ui: true,
+    label: "Apply every fix orc doctor found (= update + prune + settings re-merge)",
+    preview: ["doctor"],
+  },
+  upgrade: {
+    apply: ["upgrade"],
+    restarts_ui: true,
+    label: "Fetch the LATEST package from the network, then apply it",
+    preview: ["version"],
+    network: true,
+  },
+  // v0.46.0 — the portable export. It belongs on Maintenance by the v0.43.6 rule
+  // (a caution routes to the panel that can CLEAR it): `export-stale` is cleared
+  // by `orc export`, which is a CLI write this panel can run. Its preview is the
+  // `--check` report, which names WHICH source drifted — a count of stale sources
+  // would not be consent to overwrite a committed file.
+  export: {
+    apply: ["export"],
+    label: "Recompile AGENTS.md from the wiki, patterns, PACT.md and boundary cards",
+    preview: ["export", "--check"],
+  },
+  // ADVANCED (v0.44.0) — the one action on this panel that does not target the
+  // project. Every other route pins `--dir <projectRoot>`; `--global` outranks
+  // `--dir` in `resolveClaudeDir`, so this pair reaches ~/.claude and its
+  // preview reports on the same place it would write.
+  //
+  // It is here because a stale GLOBAL install is a real failure this panel
+  // already REPORTS (the persistent banner, and doctor's global-skew finding)
+  // and previously could not act on — the fix was "go type it in a terminal".
+  // It stays boxed off as advanced, and it is still the only global reach the
+  // panel has: config is never written globally, because config does not merge
+  // and a global write would silently outrank the file every panel here edits.
+  "update-global": {
+    apply: ["update", "--global"],
+    label: "Re-copy this package's payload over the GLOBAL install in ~/.claude",
+    preview: ["doctor", "--global"],
+    advanced: true,
+  },
+};
+
+// ── the Experiment panel ────────────────────────────────────────────────────
+//
+// THE BOUNDARY MOVES EXACTLY ONE STEP, AND NO FURTHER. `orc ui` still renders
+// no model output, proxies no session and holds no API key — it does not become
+// an AI client. What it gains is a HANDOFF: it can open a terminal, in this
+// project, with `claude` running in it, and then forget about it. The spawned
+// process is not a child this server manages, reads or reports on; it is the
+// same detached-launch mechanism `openBrowser()` has always used.
+//
+// The lanes are a SERVER-SIDE catalog and the browser sends only an id. No
+// string typed in a browser ever reaches a shell — the cwd is always the
+// server's own projectRoot, and an unknown id is a 400. That constraint is the
+// only reason a launch button is safe on a write surface at all.
+const LANES = [
+  { id: "orc", cmd: "/orc", what: "Full pipeline: intake → plan → scored parallel waves → review → verify → ship." },
+  { id: "orc-quick", cmd: "/orc-quick", what: "Ask for anything. Look → ask once → do, and it always asks which agent." },
+  { id: "orc-mini", cmd: "/orc-mini", what: "One executor, smoke gate, ship. No full review or verify phase." },
+  { id: "orc-fast", cmd: "/orc-fast", what: "Fastest lane. Needs a fresh wiki AND a cached pattern, or it falls back." },
+  { id: "orc-ultra", cmd: "/orc-ultra", what: "Maximum rigor: an advisor plus three judgment gates. Cost accepted." },
+  { id: "orc-plan", cmd: "/orc-plan", what: "Turn a request or analyst spec into a grounded task plan. Plan only." },
+  { id: "orc-analyze", cmd: "/orc-analyze", what: "Turn a document or a vague requirement into code-grounded requirements." },
+  { id: "orc-wiki", cmd: "/orc-wiki", what: "Build or refresh the project wiki. Expensive; always asks first." },
+  { id: "orc-pattern", cmd: "/orc-pattern", what: "Learn this project's real code conventions and cache them per language." },
+  { id: "orc-verify", cmd: "/orc-verify", what: "Verify the git-modified changes in the working tree. Read-only." },
+  { id: "orc-learn", cmd: "/orc-learn", what: "Generate per-feature onboarding docs. Local and git-ignored." },
+  { id: "orc-retro", cmd: "/orc-retro", what: "Mine the behavior traces for calibration. Read-only, report-only." },
+];
+
+// ── the folder picker ───────────────────────────────────────────────────────
+//
+// The THIRD endpoint with no CLI behind it (after /api/learn's shipped content
+// and /api/experiment's lane catalog), and for the same reason: there is no
+// `orc` command that lists directories, so there is nothing to shell. It exists
+// because a crosslink repo path typed by hand is the one field in this panel
+// where a typo is invisible until the edge silently resolves to nothing — the
+// CLI then saves it as a PENDING edge and you find out much later.
+//
+// It is a DIRECTORY LISTER and nothing more, and the limits are the design:
+//   · directory names only — never a file list, never file contents, never a
+//     stat beyond "does .git / .claude/wiki exist here";
+//   · dotfolders are hidden (`.git`, `node_modules` and friends are noise here);
+//   · it reads, it never writes, and no path it is handed can reach a shell;
+//   · a path that cannot be read is an ANSWER (`error`), never a 500.
+// Nothing is copied out of the folders it lists, so a wrong click costs a
+// re-click. The browser is already loopback + token gated; this adds no reach
+// beyond what the person at the keyboard already has.
+const FS_LIST_MAX = 400;
+
+function fsList(dir, ctx) {
+  const target = path.resolve(dir || ctx.projectRoot || os.homedir());
+  let entries;
+  try {
+    entries = fs.readdirSync(target, { withFileTypes: true });
+  } catch (e) {
+    return { path: target, error: String(e.code || e.message), dirs: [] };
+  }
+  const dirs = [];
+  for (const e of entries) {
+    if (dirs.length >= FS_LIST_MAX) break;
+    if (!e.isDirectory() || e.name.startsWith(".") || e.name === "node_modules") continue;
+    const full = path.join(target, e.name);
+    dirs.push({
+      name: e.name,
+      path: full,
+      // The two facts that decide whether a folder is worth linking at all.
+      // Both are a single existsSync — nothing inside either one is read.
+      is_repo: fs.existsSync(path.join(full, ".git")),
+      has_wiki: fs.existsSync(path.join(full, ".claude", "wiki")),
+    });
+  }
+  dirs.sort((a, b) => a.name.localeCompare(b.name));
+  const parent = path.dirname(target);
+  return {
+    path: target,
+    parent: parent === target ? null : parent, // null AT a filesystem root
+    sep: path.sep,
+    home: os.homedir(),
+    project_root: ctx.projectRoot || null,
+    is_project_root: !!ctx.projectRoot && path.resolve(ctx.projectRoot) === target,
+    // What the crosslink config actually stores. Computed here rather than in
+    // the browser because only the server knows the real path separator, and a
+    // Windows path assembled with "/" is the kind of thing that works until it
+    // does not.
+    relative: ctx.projectRoot ? path.relative(ctx.projectRoot, target).split(path.sep).join("/") || "." : null,
+    truncated: dirs.length >= FS_LIST_MAX,
+    dirs,
+  };
+}
+
+// Open a terminal running `claude` in the project root. Best-effort and never
+// fatal — a failed launch is reported so the user can copy the command instead,
+// which is why the command is always on screen anyway.
+function launchClaude(ctx) {
+  const cwd = ctx.projectRoot;
+  let cmd, args;
+  if (process.platform === "win32") {
+    // `start` needs an empty title argument first, or a quoted path becomes it.
+    cmd = "cmd";
+    args = ["/c", "start", "", "cmd", "/k", "claude"];
+  } else if (process.platform === "darwin") {
+    cmd = "osascript";
+    args = ["-e", `tell application "Terminal" to do script "cd ${JSON.stringify(cwd).slice(1, -1)} && claude"`, "-e", 'tell application "Terminal" to activate'];
+  } else {
+    cmd = "x-terminal-emulator";
+    args = ["-e", "claude"];
+  }
+  try {
+    const child = spawn(cmd, args, { cwd, detached: true, stdio: "ignore", windowsHide: false });
+    child.unref();
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: String(e && e.message) };
+  }
+}
+
+// ── request handling ────────────────────────────────────────────────────────
+
+function json(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    // Belt and braces on top of the loopback + token checks in serve.js.
+    "x-content-type-options": "nosniff",
+  });
+  res.end(body);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    req.on("data", (c) => {
+      raw += c;
+      if (raw.length > 64_000) reject(new Error("body too large"));
+    });
+    req.on("end", () => {
+      if (!raw) return resolve({});
+      try {
+        resolve(JSON.parse(raw));
+      } catch (_) {
+        reject(new Error("body is not JSON"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+// The Overview panel needs four commands at once. Doing that in one request
+// keeps the first paint to a single round trip.
+function overview(ctx) {
+  const doctor = readCli(["doctor"], ctx);
+  const runs = readCli(["run", "list", "--limit", "200"], ctx);
+  const waiting = runs.data ? runs.data.runs.filter((r) => r.status === "waiting") : [];
+  return {
+    where: readCli(["where"], ctx).data,
+    doctor: doctor.data,
+    wiki: readCli(["wiki", "status"], ctx).data,
+    patterns: readCli(["pattern", "status"], ctx).data,
+    runs_total: runs.data ? runs.data.total : 0,
+    // Rows, not bare slugs (v0.49.2). The Overview card has an age column and
+    // rendered it empty because the payload never carried the number — and the
+    // "mark as done" button needs the slug beside a real timestamp to be worth
+    // showing at all.
+    waiting: waiting.map((r) => ({ slug: r.slug, updated_ms: r.updated_ms, lane: r.lane || null })),
+    diy: readCli(["diy", "show"], ctx).data,
+    // v0.46.0 chips. Each is the CLI's OWN answer — the panel repeats the state
+    // words and never derives them. A chip with nothing to say still renders its
+    // good state, so "healthy" and "not measured" never look the same.
+    pact: readCli(["pact", "status"], ctx).data,
+    boundary: readCli(["boundary", "status"], ctx).data,
+    wiki_debt: readCli(["wiki", "debt"], ctx).data,
+    // v0.54.0 — foreign dispatches that never reported back. Money spent and
+    // work half-done that nothing will look at again unless somebody is told.
+    // It is a FINDING, never a stop, and the Overview never resumes one.
+    extra_journal: readCli(["extra", "journal", "list"], ctx).data,
+  };
+}
+
+async function handleApi(req, res, url, ctx) {
+  const route = url.pathname;
+  const q = Object.fromEntries(url.searchParams);
+
+  // Liveness. The page pings this every 15s; no ping from any client for the
+  // grace window and the server exits, so a closed tab does not leave a write
+  // surface holding a valid token.
+  if (route === "/api/ping") {
+    ctx.onHeartbeat();
+    return json(res, 200, { ok: true, job: jobView() });
+  }
+
+  // sendBeacon on beforeunload — a best-effort fast path to the same shutdown
+  // the heartbeat timeout would reach a minute later.
+  if (route === "/api/bye") {
+    ctx.onBye();
+    return json(res, 200, { ok: true });
+  }
+
+  if (route === "/api/meta") {
+    return json(res, 200, {
+      project_root: ctx.projectRoot,
+      fixtures: ctx.fixtures,
+      version: ctx.version,
+      port: ctx.port,
+      idle_minutes: ctx.idleMinutes,
+      started_ms: ctx.startedMs,
+    });
+  }
+
+  if (route === "/api/job") return json(res, 200, jobView());
+
+  // Fixture mode short-circuits every data route: canned JSON, no project, no
+  // spawn. This is what makes the STALE chip and the unhealthy doctor panel
+  // designable on a machine where everything is green (see the plan, §9).
+  if (ctx.fixtures) {
+    if (req.method !== "GET") {
+      // Almost every mutation answers "nothing ran", which is the honest reply
+      // in a mode that runs nothing. The ONE exception is the connection test:
+      // its two outcomes are states the Extra panel is largely about, and a
+      // state with no fixture is a state nobody has ever looked at. A canned
+      // answer carries `data` and NOT the `fixture` flag, so the panel renders
+      // the real result shape — the command string is what says it was canned.
+      let body = {};
+      try {
+        body = await readBody(req);
+      } catch (_) {}
+      const canned = fixtures.post(route, body);
+      if (canned)
+        return json(res, 200, {
+          ok: true,
+          exit_code: canned.exit_code,
+          data: canned.data,
+          command: "(fixtures — nothing ran)",
+        });
+      return json(res, 200, { ok: true, fixture: true, command: "(fixtures — nothing ran)" });
+    }
+    const canned = fixtures.get(route, q);
+    if (canned === undefined) return json(res, 404, { error: "no fixture for " + route });
+    return json(res, 200, { ok: true, exit_code: 0, data: canned, fixture: true });
+  }
+
+  if (req.method === "GET") {
+    if (route === "/api/overview") return json(res, 200, { ok: true, exit_code: 0, data: overview(ctx) });
+    if (route === "/api/learn") {
+      // The only endpoint with no CLI behind it: the onboarding topics are
+      // static content already shipped as a module, so spawning to read them
+      // would be ceremony with a cost.
+      const { SECTIONS } = require("../onboarding-content.js");
+      return json(res, 200, { ok: true, exit_code: 0, data: { sections: SECTIONS } });
+    }
+    // The mocked runs (v0.46.x). Same shape as /api/learn above and for the
+    // same reason: this is static content that ships inside this package, so
+    // spawning a subprocess to read files sitting next to this one would be
+    // ceremony with a cost. `orc mock-run` reads the identical module, so the
+    // terminal and the panel cannot disagree.
+    if (route === "/api/mockruns") {
+      return json(res, 200, { ok: true, exit_code: 0, data: require("../mockrun-catalog.js").catalogue() });
+    }
+    if (route === "/api/mockrun") {
+      const doc = require("../mockrun-catalog.js").get(String(q.slug || ""));
+      if (!doc) return json(res, 200, { ok: true, exit_code: 1, data: { slug: String(q.slug || ""), found: false } });
+      return json(res, 200, { ok: true, exit_code: 0, data: { ...doc, found: true } });
+    }
+    if (route === "/api/fs/list") {
+      return json(res, 200, { ok: true, exit_code: 0, data: fsList(q.path, ctx) });
+    }
+    if (route === "/api/experiment") {
+      return json(res, 200, {
+        ok: true,
+        exit_code: 0,
+        data: {
+          lanes: LANES,
+          project_root: ctx.projectRoot,
+          platform: process.platform,
+          // Fixture mode must never spawn a real terminal on a machine that has
+          // no project — the button says so instead of lying about it.
+          can_launch: !ctx.fixtures,
+        },
+      });
+    }
+    if (route === "/api/maintenance") {
+      const actions = Object.entries(MAINTENANCE).map(([id, m]) => ({
+        id,
+        label: m.label,
+        command: "orc " + m.apply.join(" "),
+        network: !!m.network,
+        names_files: !!m.names_files,
+        advanced: !!m.advanced,
+        restarts_ui: !!m.restarts_ui,
+      }));
+      return json(res, 200, { ok: true, exit_code: 0, data: { actions } });
+    }
+    if (route === "/api/maintenance/preview") {
+      const m = MAINTENANCE[String(q.action)];
+      if (!m) return json(res, 400, { error: "unknown action" });
+      const probe = readCli(m.preview, ctx);
+      return json(res, 200, {
+        ok: true,
+        exit_code: 0,
+        data: {
+          action: String(q.action),
+          label: m.label,
+          command: "orc " + m.apply.join(" "),
+          network: !!m.network,
+          names_files: !!m.names_files,
+          advanced: !!m.advanced,
+          // Said in the confirmation, not discovered afterwards. A panel that
+          // reloads itself without warning reads as a crash.
+          restarts_ui: !!m.restarts_ui,
+          preview_command: "orc " + m.preview.join(" "),
+          preview: probe.data,
+          // Only the UI can know a run is mid-flight; updating changes the
+          // skills that run would resume into.
+          waiting_runs: (readCli(["run", "list", "--limit", "200"], ctx).data || { runs: [] }).runs
+            .filter((r) => r.status === "waiting")
+            .map((r) => r.slug),
+          dirty_tree: m.network ? isDirtyTree(ctx) : false,
+        },
+      });
+    }
+    const build = READS[route];
+    if (!build) return json(res, 404, { error: "unknown endpoint " + route });
+    const out = readCli(build(q), ctx);
+    // v0.49.2 — a read that produced no parseable object still has to SAY why.
+    // The body already carried `stderr` and `stdout`; nothing named `error`, so
+    // the client fell through to "request failed (500)" and one corrupt ledger
+    // looked like a broken panel. The reason the CLI printed is what is shown.
+    return json(res, out.ok ? 200 : 500, out.ok ? out : { ...out, error: readFailReason(out) });
+  }
+
+  if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
+
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (e) {
+    return json(res, 400, { error: e.message });
+  }
+
+  // The handoff. It takes NO command from the browser: the lane id is looked up
+  // in the server's own catalog and is used only to echo back what to type. The
+  // process spawned is always a bare `claude` in the server's own projectRoot,
+  // so there is no path by which browser input reaches a shell.
+  if (route === "/api/experiment/launch") {
+    if (ctx.fixtures) return json(res, 400, { error: "fixture mode never launches anything real" });
+    const lane = body.lane ? LANES.find((l) => l.id === String(body.lane)) : null;
+    if (body.lane && !lane) return json(res, 400, { error: "unknown lane" });
+    const r = launchClaude(ctx);
+    if (!r.ok) return json(res, 500, { error: "could not open a terminal: " + r.error });
+    return json(res, 200, {
+      ok: true,
+      // What to type once it is open. The UI shows this; the server never runs it.
+      type_this: lane ? lane.cmd : null,
+      cwd: ctx.projectRoot,
+    });
+  }
+
+  // v0.50.0 — THE CONNECTION TEST, and the one place this panel does something
+  // model-shaped. It is a DIAGNOSTIC in the same family as `orc doctor`: rung 1
+  // lists models and costs nothing, rung 2 sends a one-token completion and
+  // costs a fraction of a cent, and the CLI decides which — never this file.
+  //
+  // It is POST because it MUTATES: a green test writes `verified_at` onto the
+  // profile, and a red one on a never-verified profile REMOVES that profile
+  // (the CLI's own test-first-then-store lifecycle). A GET that did that would
+  // be reachable by a prefetch.
+  //
+  // A pasted key arrives in the BODY and leaves on the child's STDIN — line 1
+  // the key, an optional line 2 the passphrase that encrypts it. It is never in
+  // argv, never written here, and never echoed back: the response is the CLI's
+  // own `--json` object, which carries no credential by construction.
+  if (route === "/api/extra/ping") {
+    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
+    const profile = String(body.profile || "");
+    if (!profile) return json(res, 400, { error: "missing argument" });
+    const argv = ["extra", "ping", profile];
+    // v0.51.0 — the PAID rung, opt-in and never a default. The panel quotes what
+    // it costs before the button; the CLI is what decides the rung and what it
+    // reports back.
+    if (body.live) argv.push("--live");
+    if (body.model) argv.push("--model", String(body.model));
+    let input;
+    if (body.key) {
+      // A NEW key: line 1 the key, an optional line 2 the passphrase that stores
+      // it after a green test.
+      argv.push("--key-stdin");
+      input = String(body.key) + chr10 + String(body.passphrase || "") + chr10;
+    } else if (body.passphrase) {
+      // A STORED key: the passphrase decrypts it into the CLI's memory for the
+      // probe. The two flags are mutually exclusive and the CLI refuses them
+      // together BY NAME, so this branch is an `else if` rather than a guess.
+      argv.push("--passphrase-stdin");
+      input = String(body.passphrase) + chr10;
+    }
+    const out = runCli(argv, ctx, { json: true, input });
+    clearCache();
+    // `ok` here is "did the CLI answer at all". Whether the CONNECTION worked is
+    // `data.ok` and the exit code, which are the CLI's answer and are passed
+    // through untouched — a failed probe is DATA, not a server error.
+    return json(res, out.ok ? 200 : 500, out.ok
+      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
+      : { ...out, error: readFailReason(out) });
+  }
+
+  // v0.51.0 — F5's answer, scoped to ONE model id. A model that is LISTED can
+  // still be DEAD upstream, so a dropdown is a list of what is OFFERED and never
+  // a list of what WORKS. This is POST because it spends money.
+  if (route === "/api/extra/models/test") {
+    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
+    const profile = String(body.profile || "");
+    const model = String(body.model || "");
+    if (!profile || !model) return json(res, 400, { error: "missing argument" });
+    const argv = ["extra", "models", profile, "--test", model];
+    let input;
+    if (body.passphrase) {
+      argv.push("--passphrase-stdin");
+      input = String(body.passphrase) + chr10;
+    }
+    const out = runCli(argv, ctx, { json: true, input });
+    clearCache();
+    return json(res, out.ok ? 200 : 500, out.ok
+      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
+      : { ...out, error: readFailReason(out) });
+  }
+
+  // v0.52.0 — SAVING THE PASSPHRASE WITH A DEADLINE. The CLI tests it against
+  // the vault before it stores anything (test first, then store), validates the
+  // TTL against the same closed set the config key publishes, and answers with
+  // the DATE. This route composes nothing: it hands over a profile, a number of
+  // days, and a passphrase on stdin.
+  if (route === "/api/extra/session/save") {
+    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
+    const profile = String(body.profile || "");
+    const ttl = String(body.ttl_days || "");
+    if (!profile || !ttl) return json(res, 400, { error: "missing argument" });
+    const out = runCli(["extra", "session", profile, "--save", "--ttl", ttl], ctx, {
+      json: true,
+      input: String(body.passphrase || "") + chr10,
+    });
+    clearCache();
+    return json(res, out.ok ? 200 : 500, out.ok
+      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
+      : { ...out, error: readFailReason(out) });
+  }
+
+  // v0.50.0 — proving a passphrase, which is the ONE action that clears the
+  // vault's countdown. It NEVER yields the key: `orc extra unlock` answers one
+  // question with a yes or a no, and its `attempt N of 10` message is the whole
+  // point of the feature, so it is passed back verbatim.
+  if (route === "/api/extra/unlock") {
+    if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
+    const profile = String(body.profile || "");
+    if (!profile) return json(res, 400, { error: "missing argument" });
+    const out = runCli(["extra", "unlock", profile], ctx, {
+      json: true,
+      input: String(body.passphrase || "") + chr10,
+    });
+    clearCache();
+    return json(res, out.ok ? 200 : 500, out.ok
+      ? { ok: true, exit_code: out.exit_code, data: out.data, command: out.command }
+      : { ...out, error: readFailReason(out) });
+  }
+
+  // Hand the panel over to a fresh process on the SAME port and token, so the
+  // open tab only has to reload. POST-only like every other mutation, and it is
+  // a mutation: the process answering the next request is not this one.
+  //
+  // The CLIENT asks for this — never the job's own close handler. The job's
+  // output lives in this process's memory, so restarting the instant a command
+  // finished would destroy the record of what it did before anyone read it.
+  if (route === "/api/ui/restart") {
+    if (ctx.fixtures)
+      return json(res, 400, { ok: false, reason: "fixtures", error: "fixture mode serves canned data; there is nothing to restart into." });
+    if (job && job.running) return json(res, 409, { ok: false, reason: "busy", error: "a command is still running.", job: jobView() });
+    const out = typeof ctx.restart === "function" ? ctx.restart() : { ok: false, reason: "unsupported" };
+    // A failed handover is NOT fatal and never takes the running panel down:
+    // the old server keeps serving, and the client is told to do it by hand.
+    return json(res, out.ok ? 200 : 500, out);
+  }
+
+  if (route === "/api/maintenance/apply") {
+    const m = MAINTENANCE[String(body.action)];
+    if (!m) return json(res, 400, { error: "unknown action" });
+    const started = startJob(m.apply, ctx, { restartUi: !!m.restarts_ui });
+    if (started.error) return json(res, 409, started);
+    return json(res, 200, { ok: true, ...started });
+  }
+
+  const build = WRITES[route];
+  if (!build) return json(res, 404, { error: "unknown endpoint " + route });
+  if (job && job.running) return json(res, 409, { error: "busy", job: jobView() });
+  let argv;
+  try {
+    argv = build(body);
+  } catch (_) {
+    return json(res, 400, { error: "bad request body" });
+  }
+  if (argv.some((a) => a === "undefined" || a === "null" || a === ""))
+    return json(res, 400, { error: "missing argument" });
+  const out = runCli(argv, ctx);
+  clearCache();
+  // A write's exit code is a REAL failure signal (validators exit 1), unlike a
+  // read's — so it is reported as such, with the CLI's own message.
+  return json(res, 200, {
+    ok: out.exit_code === 0,
+    exit_code: out.exit_code,
+    command: out.command,
+    // Writes print human text, not JSON — that IS the confirmation to show.
+    output: (out.stdout + (out.stderr ? "\n" + out.stderr : "")).trim(),
+  });
+}
+
+// `orc upgrade` replaces the package while your working tree may hold changes.
+// Worth a warning before, not a surprise after.
+function isDirtyTree(ctx) {
+  try {
+    const r = spawnSync("git", ["status", "--porcelain"], {
+      cwd: ctx.projectRoot,
+      encoding: "utf8",
+      windowsHide: true,
+      timeout: 5000,
+    });
+    return r.status === 0 && !!(r.stdout || "").trim();
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { handleApi, clearCache, READS, WRITES, MAINTENANCE };