@jr2/orchestrator 0.1.0

package/src/http.ts

@@ -0,0 +1,753 @@
+// The orchestrator HTTP surface (ADR-0009/0013): a thin REST + SSE facade over a `RunHost`. It
+// carries NO domain logic of its own: every handler delegates to a single `RunHost` method, so the
+// wire shape and the in-process API stay one behavior.
+//
+// TWO dialects, one primitive (ADR-0013). The Orchestrator does not speak MCP — that moved into the
+// Sandbox, where the Adapter serves it to the Agent over localhost. What is left here are two thin
+// adapters over the same registration table:
+//
+//   # human / webhook / CI — the Gate resource of ADR-0011
+//   GET  /runs/:id                     open gates: accepts + schemas + meta      [Instance token]
+//   POST /runs/:id/gates/:gate/events  validate + deliver                        [Instance token]
+//
+//   # the Agent's Adapter, and nothing else
+//   GET  /agents/:iid/surface          accepts + schemas + semantics             [Sandbox token]
+//   POST /agents/:iid/events           validate + deliver → the turn receipt      [Sandbox token]
+//   POST /sandboxes/:name/fetch        ask the node cache to fetch one Repo      [Sandbox token]
+//
+// The token is not decoration: an Agent has code execution in its Harness container and shares the
+// pod's network namespace, so it can reach these routes. A Sandbox token may deliver ONLY to an
+// agent surface recorded against its own Sandbox — never to a Gate. That is what stops an Agent
+// from approving its own review.
+//
+// THREE bands of access, not two (ADR-0014) — the middleware is what says which:
+//
+//   open          structure + observation. `/workflows`, a template's Machine, the Console shell,
+//                 and the run PROJECTIONS below (`GET /workflows/:name/runs*`). No context, no
+//                 control.
+//   authenticated any principal we minted a token for. The Agent's surface lives here, scoped
+//                 further per-registration by `mayDeliverToAgent`.
+//   instanceOnly  the Instance token ALONE. Run control and full run state (`/runs*`): a Sandbox
+//                 token authenticates but is refused, because reading another feature's context or
+//                 cancelling a run is not on the Agent's surface any more than a Gate is.
+
+import { readFile, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import tsBlankSpace from "ts-blank-space";
+import { Hono } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
+import { accepts } from "hono/accepts";
+import { streamSSE } from "hono/streaming";
+import { EventValidationError, UnknownAddressError } from "./registration.ts";
+import type { RepoStatus } from "./repos.ts";
+import { UnmountedRepoError, type FetchAnswer } from "./repo-fetch.ts";
+import { mayAskForSandbox, mayDeliverToAgent, type Authenticator, type Principal } from "./tokens.ts";
+import { observe, type RunHost } from "./run-host.ts";
+import { KIT_VERSION } from "./config.ts";
+
+/** A `POST /runs/:id/events` body: the down-channel event. CANCEL is all that is left of it
+ * (ADR-0013): APPROVE and STEER rode the deferred/poll machinery, which is reserved, not built. */
+type RunEventBody = { type?: string };
+
+/** `GET /runs/resolve` floor — a 1-char prefix is a table scan, not a question. The CLI enforces
+ * the same floor on the argument; this one guards the scan regardless of who is calling. */
+const MIN_RUN_ID_PREFIX = 4;
+
+/** How many ambiguous candidates are worth showing. Proving ambiguity takes 2; letting the caller
+ * PICK is the point, so the listing goes deeper before it truncates. */
+const RESOLVE_LIMIT = 10;
+
+/** Read a request body as JSON, tolerating an empty body (→ {}) and malformed JSON (→ {}). */
+async function readJson(text: Promise<string>): Promise<Record<string, unknown>> {
+  try {
+    const raw = await text;
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The message of a thrown error, for the `{ error }` 404 body. */
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** The app's context: `authenticated` resolves the bearer to a `principal` the routes read back. */
+type JR2Env = { Variables: { principal: Principal } };
+
+/** The bearer token on a request, if it carries one. */
+function bearerOf(c: Context<JR2Env>): string | undefined {
+  const header = c.req.header("authorization") ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() || undefined;
+}
+
+// ---- Console assets (`/assets/*`) -----------------------------------------------------------
+// The Console: the browser page that renders a workflow's Machine and its runs. Shipped inside
+// this package and read from disk — no CDN, no build step (ADR-0032: the page serves only its own
+// assets). `serveStatic` is deliberately avoided: its root is cwd-relative, and this package is a
+// library that must serve its own files wherever the process starts. Assets are root-owned
+// (`/assets/*`, not under a page path) so no workflow name can ever shadow them. Three kinds:
+//
+//   .html/.css       the shipped bytes, verbatim.
+//   *.ts             Console source (ADR-0034) — the flat files plus the one `components/` level
+//                    the view modules live in. Browsers don't type-strip, so the server does what
+//                    Node does for itself: types replaced by whitespace (`ts-blank-space`), erased
+//                    once per (file, mtime) and cached. Erasure, not compilation — positions are
+//                    preserved, so stack traces point at the real line with no sourcemaps.
+//   /assets/vendor/* Preact's browser ESM, resolved through THIS package's dep edge like the elkjs
+//                    bundle. The page's import map binds the bare specifiers to these URLs.
+
+const CONSOLE_DIR = new URL("../console/", import.meta.url);
+
+/** The vendored elkjs bundle, resolved through THIS package's dep edge (pnpm-safe), read once. */
+let elkBundle: Promise<Buffer> | undefined;
+function readElkBundle(): Promise<Buffer> {
+  // elkjs ships no `exports` map today, so the subpath resolves; if a future version adds one,
+  // switch to resolving "elkjs/package.json" and joining "lib/elk.bundled.js".
+  elkBundle ??= readFile(createRequire(import.meta.url).resolve("elkjs/lib/elk.bundled.js"));
+  return elkBundle;
+}
+
+/**
+ * Preact's browser ESM at `/assets/vendor/*` (ADR-0034): the served name → the file under the
+ * `preact` package. Resolved via "preact/package.json" — preact HAS an `exports` map (unlike
+ * elkjs), so its dist subpaths don't resolve directly. `hooks.module.js` imports the bare
+ * specifier `"preact"`; the page's import map covers vendored modules too, so that import lands
+ * back on `/assets/vendor/preact.module.js` and the files can sit flat.
+ */
+const VENDOR_FILES: Record<string, string> = {
+  "preact.module.js": "dist/preact.module.js",
+  "hooks.module.js": "hooks/dist/hooks.module.js",
+};
+
+/** Vendor files, read once each — package contents only change with the package. */
+const vendorCache = new Map<string, Promise<Buffer>>();
+function readVendor(name: string): Promise<Buffer> | undefined {
+  const rel = VENDOR_FILES[name];
+  if (!rel) return undefined;
+  let body = vendorCache.get(name);
+  if (!body) {
+    const pkg = createRequire(import.meta.url).resolve("preact/package.json");
+    body = readFile(new URL(rel, pathToFileURL(pkg)));
+    vendorCache.set(name, body);
+  }
+  return body;
+}
+
+/** Serve one file of the Console with its content type. */
+async function consoleAsset(rel: string, contentType: string): Promise<Response> {
+  const body = await readFile(new URL(rel, CONSOLE_DIR));
+  return new Response(new Uint8Array(body), { headers: { "content-type": contentType } });
+}
+
+/** Erased Console source, cached per file: an edit moves the mtime, which drops the entry. */
+const erasedCache = new Map<string, { mtimeMs: number; js: string }>();
+
+/**
+ * Serve one Console `.ts` file with its types erased (ADR-0034). The failure class is gated where
+ * it belongs — what `ts-blank-space` cannot erase (an enum, a namespace), `tsc --noEmit` already
+ * rejected in CI — so the 500 here is a should-never bar, not a compiler diagnostic surface.
+ */
+async function consoleTsAsset(file: string): Promise<Response> {
+  const url = new URL(file, CONSOLE_DIR);
+  let mtimeMs: number;
+  try {
+    mtimeMs = (await stat(url)).mtimeMs;
+  } catch {
+    return Response.json({ error: `no console asset "${file}"` }, { status: 404 });
+  }
+  let hit = erasedCache.get(file);
+  if (!hit || hit.mtimeMs !== mtimeMs) {
+    const source = await readFile(url, "utf8");
+    const unerasable: string[] = [];
+    // The node's own text, sliced by position — `getText()` needs a parent chain the parse here
+    // does not build.
+    const js = tsBlankSpace(source, (node) => unerasable.push(source.slice(node.pos, node.end).trim()));
+    if (unerasable.length) {
+      return new Response(`cannot erase types from ${file}: ${unerasable.join(", ")}`, { status: 500 });
+    }
+    hit = { mtimeMs, js };
+    erasedCache.set(file, hit);
+  }
+  return new Response(hit.js, { headers: { "content-type": "text/javascript; charset=utf-8" } });
+}
+
+// Content negotiation for the two page addresses (ADR-0032). JSON is the DEFAULT dialect: only a
+// request whose `Accept` prefers `text/html` — a browser's navigation — gets the Console shell.
+// No header, a bare wildcard, `application/json`, `text/event-stream` all fall through to JSON,
+// so the CLI, the Adapter and EventSource never see HTML they did not ask for.
+function prefersHtml(c: Context): boolean {
+  return (
+    accepts(c, { header: "Accept", supports: ["application/json", "text/html"], default: "application/json" }) ===
+    "text/html"
+  );
+}
+
+/**
+ * One SSE handler's single exit. Every feed can end four ways — terminal frame, race guard, client
+ * abort, host shutdown — and each must unsubscribe, clear the ping timer, and resolve EXACTLY once.
+ * Spelling that out per exit is how a timer gets leaked, so each handler builds one of these and
+ * every exit becomes `exit.done`.
+ *
+ * `onExit` is called AFTER subscribing, because `host.subscribe` replays synchronously and can
+ * therefore finish the feed before it returns — hence the already-finished check inside it.
+ */
+function closer(resolve: () => void) {
+  let cleanups: Array<() => void> = [];
+  let finished = false;
+  const release = () => {
+    for (const fn of cleanups) fn();
+    cleanups = [];
+  };
+  return {
+    done: () => {
+      if (finished) return;
+      finished = true;
+      release();
+      resolve();
+    },
+    /** Register cleanup (an unsubscribe, a timer clear) to run on whichever exit happens first. */
+    onExit: (fn: () => void) => (finished ? fn() : cleanups.push(fn)),
+    /** Run the cleanups WITHOUT ending the feed — the read-through race guard, which detaches from
+     *  a run that is already gone and then still has a final frame to write. */
+    release,
+  };
+}
+
+/** How often an otherwise-silent feed writes a ping. */
+const PING_MS = 15_000;
+
+/**
+ * Keep a quiet feed alive.
+ *
+ * A run parked on a gate transitions for hours, so its feed writes zero bytes and any idle
+ * intermediary drops the connection — the client sees a dead socket that still looks healthy (this
+ * is the `error: terminated` an attached `jr2 run` hit). The frame is an SSE COMMENT (`:\n\n`):
+ * every client ignores it, so it needs no place in the wire vocabulary.
+ *
+ * It is deliberately a **ping**, not a heartbeat or keepalive — CONTEXT.md puts both on the Lease's
+ * Avoid list, and this asserts nothing and expects no answer.
+ *
+ * It is NOT a liveness probe, and must not be mistaken for one: `stream.write` swallows its own
+ * errors (hono's `StreamingApi`), so a failed write is indistinguishable from a good one. A peer
+ * that goes away is detected by `stream.onAbort`, which is what every handler here wires to its
+ * exit. The tick checks `aborted`/`closed` only so a ping that fires between the abort and the
+ * teardown does not write into a dead stream. Returns its own clear fn.
+ */
+function pinger(stream: SseStream, done: () => void, everyMs = PING_MS): () => void {
+  const timer = setInterval(() => {
+    if (stream.aborted || stream.closed) return done();
+    void stream.write(":\n\n");
+  }, everyMs);
+  return () => clearInterval(timer);
+}
+
+/** The slice of hono's `StreamingApi` the ping needs: the raw write (`writeSSE` cannot express a
+ *  comment frame) plus the two flags that say the peer is gone. */
+type SseStream = { write: (s: string) => Promise<unknown>; aborted: boolean; closed: boolean };
+
+export type CreateAppOptions = {
+  /** Ping interval for the SSE feeds. Tests shorten it; nothing in production sets it. */
+  pingMs?: number;
+  /**
+   * Whether this instance has a data plane at all (ADR-0051): a registered Machine composes a
+   * Sandbox AND the process is deployed in a cluster. `false` is an answer — "this instance runs
+   * no Workspace" — and `jr2 status` says so rather than listing nothing.
+   */
+  dataPlane?: boolean;
+  /**
+   * The Repo resources as the cluster currently reports them (ADR-0051), read per request off the
+   * port — a cache the agent cloned minutes after boot reads as present the next time anyone asks.
+   * Absent for an instance without a data plane and for the in-process tests that build an app
+   * straight over a host: both answer no Repos.
+   */
+  repos?: () => Promise<RepoStatus[]>;
+  /**
+   * The ask a pod makes when something inside it fetches (ADR-0053), off the port the caller
+   * built: mark the Sandbox CR for one Repo key, wait for the landing on its status, answer.
+   * Absent for an instance without a data plane and for the in-process tests: no Sandbox, so no
+   * ask, and the route says so rather than waiting on a cluster that is not there.
+   */
+  fetchRepo?: (sandbox: string, identity: string) => Promise<FetchAnswer>;
+};
+
+/**
+ * Build the orchestrator HTTP app over a `RunHost` (ADR-0009/0013 route table).
+ *
+ * `auth` is how a bearer token becomes a principal. Omitting it leaves the surface OPEN, which is
+ * only ever right for an in-process test that reaches `app.request` directly — `startInstance`
+ * (every real boot, deployed or fixture) always supplies one.
+ */
+export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOptions = {}): Hono<JR2Env> {
+  const pingMs = opts.pingMs ?? PING_MS;
+  const app = new Hono<JR2Env>();
+
+  /** Authenticate, or refuse. There is no anonymous principal (ADR-0013) — an open surface would
+   * hand every Agent in the cluster a delivery API, which is the hole this ADR exists to close. */
+  const authenticated: MiddlewareHandler<JR2Env> = async (c, next) => {
+    if (!auth) return next(); // no authenticator configured: tests only (see the doc comment)
+    const principal = auth(bearerOf(c));
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    c.set("principal", principal);
+    return next();
+  };
+  /** The principal `authenticated` resolved. An unconfigured `auth` means full trust. */
+  const principalOf = (c: Context<JR2Env>): Principal => c.get("principal") ?? { kind: "instance" };
+
+  /**
+   * Authenticate, AND require the INSTANCE token (ADR-0014). A Sandbox token is a token we minted,
+   * so `authenticated` alone lets it through — which on the run surface is too much: it would let an
+   * Adapter's credential read every run's context (other features' branches, tickets, verdicts) and
+   * CANCEL any run. Neither is on the Agent's surface. Its scope is delivering to agent
+   * registrations recorded against its OWN Sandbox (ADR-0013), and the gate route already says so in
+   * the other direction.
+   */
+  const instanceOnly: MiddlewareHandler<JR2Env> = async (c, next) => {
+    if (!auth) return next(); // no authenticator configured: tests only (see the doc comment)
+    const principal = auth(bearerOf(c));
+    if (!principal) return c.json({ error: "unauthorized" }, 401);
+    if (principal.kind !== "instance") {
+      return c.json({ error: "run state and control need the Instance token — a Sandbox token has neither" }, 403);
+    }
+    c.set("principal", principal);
+    return next();
+  };
+
+  // Liveness, and the one place an instance says WHAT IT IS. Unauthenticated because it is the
+  // readiness probe's target and because identity is not run state — it is the same class of thing
+  // as the route table, which is public by being served. The CLI probes it to explain a failure it
+  // could otherwise only report as a bare status code (version skew reads as a nonsense 404).
+  // `hash` is the image's content address (ADR-0019), absent for a host-booted fixture process,
+  // which has no image to be addressed.
+  app.get("/healthz", (c) => c.json({ ok: true, version: KIT_VERSION, hash: process.env.JR2_CONTENT_HASH }));
+  app.get("/readyz", (c) => c.json({ ready: true }));
+
+  // Structure, not state: the workflow listing, a template's Machine, and the Console shell are
+  // unauthenticated. They expose no run, drive nothing, and the Console is a BROWSER page — it
+  // loads before any token is entered (ADR-0032). Everything that reads or moves a run is guarded
+  // below.
+  app.get("/workflows", (c) => c.json(host.workflows()));
+
+  // The two PAGE addresses (ADR-0032): `/` and `/workflows/:name` negotiate. A browser navigation
+  // (`Accept` prefers text/html) gets the one Console shell — the path carries the selection, the
+  // shell is the same bytes for any of them. Every other caller gets JSON, the default dialect.
+  //
+  // JSON `/` is a 404: nothing lived there before the Console, and inventing an index now would be
+  // surface no client asked for. JSON `/workflows/:name` is the workflow DETAIL: identity plus the
+  // machine's declared input as JSON Schema (`null` when it declares none — ADR-0033). Open band:
+  // a schema is structure, exactly like the Machine document below.
+  app.get("/", (c) => {
+    if (prefersHtml(c)) return consoleAsset("page.html", "text/html; charset=utf-8");
+    return c.json({ error: "no JSON resource at / — the Console is the HTML dialect" }, 404);
+  });
+  app.get("/workflows/:name", (c) => {
+    // The shell for ANY name — an unknown workflow surfaces in-page via its 404'd /machine fetch.
+    if (prefersHtml(c)) return consoleAsset("page.html", "text/html; charset=utf-8");
+    const name = c.req.param("name");
+    const doc = host.machine(name);
+    if (!doc) return c.json({ error: `no workflow "${name}"` }, 404);
+    return c.json({ name, machineId: doc.id, input: host.inputSchema(name) ?? null });
+  });
+
+  // Push work: start a run of a registered workflow. Unknown workflow → host.start throws → 404.
+  // A body failing the machine's declared input schema (ADR-0033) → 400 naming the accepted
+  // shape — the same error class, and the same wire mapping, as a gate delivery failing its
+  // schema (`POST /runs/:id/gates/:gate/events` below).
+  app.post("/workflows/:name/runs", authenticated, async (c) => {
+    const name = c.req.param("name");
+    const input = await readJson(c.req.text());
+    try {
+      const { runId, instanceId } = await host.start(name, input);
+      return c.json({ runId, instanceId }, 201);
+    } catch (err) {
+      if (err instanceof EventValidationError) return c.json({ error: errMessage(err) }, 400);
+      return c.json({ error: errMessage(err) }, 404);
+    }
+  });
+
+  // The registered template Machine's structure — what the Console's diagram renders (structure
+  // is provider-independent, so the un-`provide()`d template is exactly right).
+  app.get("/workflows/:name/machine", (c) => {
+    const name = c.req.param("name");
+    const doc = host.machine(name);
+    return doc ? c.json(doc) : c.json({ error: `no workflow "${name}"` }, 404);
+  });
+
+  // ---- Observation (`GET /workflows/:name/runs*`) ---------------------------------------------
+  // What the tokenless Console needs, and the most it may have. The page is a BROWSER: it holds no
+  // token until one is ENTERED (ADR-0032), and baking one in would mean giving the INSTANCE token
+  // — gates, run control, every run's context — to whatever can load a URL (and the orchestrator
+  // binds 0.0.0.0 — pods must reach it — so that URL is not only yours). So the page gets a
+  // projection instead of a credential: `observe()` keeps identity + the state VALUE and drops
+  // context, and the guarded `/runs*` routes above stay exactly as guarded as they were. A
+  // projection, not a bypass.
+  //
+  // Scoped to one workflow because that is what an observer already knows (it is in the page's
+  // path): no listing of everything this orchestrator is running.
+
+  app.get("/workflows/:name/runs", (c) => c.json(host.observations(c.req.param("name"))));
+
+  /**
+   * SSE: a whole WORKFLOW's activity (ADR-0022) — every run of it appearing, moving, emitting and
+   * leaving, on one connection that outlives all of them.
+   *
+   * The feed is LEVEL-TRIGGERED: `status` always carries a whole observation, never a patch, and the
+   * opening `runs` frame carries the entire current set. A reconnecting client therefore converges
+   * with no replay buffer, no Last-Event-ID and no per-client state on this side — re-delivery is
+   * idempotent by construction. Same reconciliation idiom as the Lease (ADR-0021) and ADR-0019.
+   *
+   * Unknown workflow is NOT a 404: it attaches and reports an empty set, matching
+   * `/workflows/:name/runs`. The page is opened by path, and a later registration may supply the
+   * name a moment later — the already-open feed then just starts working.
+   *
+   * Same open band as the routes above (ADR-0014): `observe()` projects away context, instanceId and
+   * fault at every depth, and an emit contributes its TYPE alone.
+   */
+  app.get("/workflows/:name/events", async (c) => {
+    const name = c.req.param("name");
+    return streamSSE(c, async (stream) => {
+      await new Promise<void>((resolve) => {
+        const exit = closer(resolve);
+        // Subscribe and snapshot in one call, then write the snapshot in the same tick: nothing can
+        // start, move or finish in between, so the client's first frame is a complete picture.
+        const { runs, unsubscribe } = host.observeWorkflow(name, (ev) => {
+          if (ev.kind === "closed") return exit.done();
+          if (ev.kind === "gone") {
+            void stream.writeSSE({ event: "gone", data: JSON.stringify({ runId: ev.runId }) });
+            return;
+          }
+          if (ev.kind === "emit") {
+            // The TYPE alone: an emit's payload is author data, the same class of thing as context.
+            void stream.writeSSE({ event: "emit", data: JSON.stringify({ runId: ev.runId, type: ev.event.type }) });
+            return;
+          }
+          if (ev.kind === "retry") {
+            // `{ child, attempt }` only — `reason` is mechanism/error text, which stays behind the
+            // Instance token like `fault` (ADR-0014/0016).
+            void stream.writeSSE({
+              event: "retry",
+              data: JSON.stringify({ runId: ev.runId, child: ev.child, attempt: ev.attempt }),
+            });
+            return;
+          }
+          void stream.writeSSE({ event: "status", data: JSON.stringify(observe(ev.status)) });
+        });
+        exit.onExit(unsubscribe);
+        // `retry` steers the browser's own EventSource backoff. This feed never ends on its own, so
+        // every close is a fault worth reconnecting from — the client does not decide that.
+        void stream.writeSSE({ event: "runs", data: JSON.stringify(runs.map(observe)), retry: 2000 });
+        exit.onExit(pinger(stream, exit.done, pingMs));
+        stream.onAbort(exit.done);
+      });
+    });
+  });
+
+  app.get("/workflows/:name/runs/:runId/events", async (c) => {
+    const name = c.req.param("name");
+    const runId = c.req.param("runId");
+    const live = host.status(runId);
+    // LIVE runs only, and only through the workflow that owns them. A settled run's terminal status
+    // is a read-through into the store (`host.read`) — that is the Instance's feed, not this one.
+    if (!live || live.workflow !== name) return c.json({ error: `no live run "${runId}" of "${name}"` }, 404);
+    return streamSSE(c, async (stream) => {
+      await new Promise<void>((resolve) => {
+        const exit = closer(resolve);
+        exit.onExit(
+          host.subscribe(runId, (ev) => {
+            // The host is shutting down under a feed that has no end of its own.
+            if (ev.kind === "closed") return exit.done();
+            if (ev.kind === "emit") {
+              // The TYPE alone: an emit's payload is author data, the same class of thing as context.
+              void stream.writeSSE({ event: "emit", data: JSON.stringify({ type: ev.event.type }) });
+              return;
+            }
+            if (ev.kind === "retry") {
+              // `{ child, attempt }` only — `reason` is mechanism/error text, which stays behind
+              // the Instance token like `fault` (ADR-0014/0016).
+              void stream.writeSSE({ event: "retry", data: JSON.stringify({ child: ev.child, attempt: ev.attempt }) });
+              return;
+            }
+            // Turn markers (ADR-0023) carry an Agent's framing and pick payload — Instance-token
+            // class, so the OPEN band never sees them (not even their types).
+            if (ev.kind === "admission" || ev.kind === "pick") return;
+            // Terminal frame must flush before the handler returns and closes the stream (see the
+            // guarded feed below for why the exit is chained off the write).
+            const terminal = ev.status.status !== "active";
+            void stream.writeSSE({ event: "status", data: JSON.stringify(observe(ev.status)) }).then(() => {
+              if (terminal) exit.done();
+            });
+          }),
+        );
+        // Race guard: settled between the liveness check and the subscribe, which then attached to
+        // nothing. No read-through on this route, so there is nothing to fall back to — just close.
+        if (host.status(runId) === undefined) return exit.done();
+        exit.onExit(pinger(stream, exit.done, pingMs));
+        stream.onAbort(exit.done);
+      });
+    });
+  });
+
+  // The Console's assets, root-owned (`/assets/*`): they share no prefix with a page address, so
+  // no workflow name can capture them — the guard the old `/viz/assets` ordering provided, now by
+  // construction. The shell itself is served by the negotiated page addresses above.
+  app.get("/assets/style.css", () => consoleAsset("style.css", "text/css; charset=utf-8"));
+  app.get("/assets/elk.js", async () => {
+    const body = await readElkBundle();
+    return new Response(new Uint8Array(body), {
+      headers: { "content-type": "text/javascript; charset=utf-8" },
+    });
+  });
+
+  // Console SOURCE (ADR-0034): any `.ts` under console/ is served with its types erased — the
+  // flat files (main.ts, store.ts, canvas.ts) and the `components/` level the view modules live
+  // in. Each param pattern admits one flat path segment of name characters — no separators, so no
+  // traversal, and nothing outside console/ is reachable by construction.
+  app.get("/assets/:file{[\\w.-]+\\.ts}", (c) => consoleTsAsset(c.req.param("file")));
+  app.get("/assets/components/:file{[\\w.-]+\\.ts}", (c) => consoleTsAsset(`components/${c.req.param("file")}`));
+
+  // Preact's browser ESM (ADR-0034), off this package's own dep edge — the elkjs precedent.
+  app.get("/assets/vendor/:file", async (c) => {
+    const file = c.req.param("file");
+    const body = await readVendor(file);
+    if (!body) return c.json({ error: `no vendor asset "${file}"` }, 404);
+    return new Response(new Uint8Array(await body), {
+      headers: { "content-type": "text/javascript; charset=utf-8" },
+    });
+  });
+
+  app.get("/runs", instanceOnly, (c) => c.json(host.list()));
+
+  // The Repos as the cluster currently reports them (ADR-0048/0051) — what `jr2 status` renders,
+  // and the place ADR-0047's "register the key, the cache agent retries" points at. Instance band,
+  // like every other state route: a row names a Repo and carries git's own error text, which is
+  // exactly the class of thing the open observation projections strip (ADR-0014). An instance
+  // without a data plane answers `{ dataPlane: false, repos: [] }` rather than 404 — "this
+  // instance runs no Workspace" is an answer, and it is the same answer next boot.
+  app.get("/repos", instanceOnly, async (c) =>
+    c.json({ dataPlane: opts.dataPlane ?? false, repos: (await opts.repos?.()) ?? [] }),
+  );
+
+  // Abbreviated run ids (ADR-0009). Registered before `/runs/:runId` so "resolve" is never captured
+  // as a run id. The prefix rides in the query string
+  // because this is a search, not an address: `/runs/resolve/abc` would read like a run named
+  // "resolve". Resolution lives HERE and not on the addressed routes below, which stay full-id —
+  // a prefix that resolves today goes ambiguous tomorrow, and a write must never be prefix-sensitive.
+  //
+  // Ids ONLY, never RunStatus: it keeps the scan index-only, it matches what git prints for an
+  // ambiguous hash, and it holds down what this newly reveals — settled run ids are now visible to
+  // an Instance-token holder, which `GET /runs`'s deferred `?all` had withheld. Deliberately not on
+  // the open observation routes: prefix probing there would be a run-id enumeration oracle.
+  app.get("/runs/resolve", instanceOnly, async (c) => {
+    const prefix = c.req.query("prefix") ?? "";
+    if (prefix.length < MIN_RUN_ID_PREFIX) {
+      return c.json({ error: `prefix must be at least ${MIN_RUN_ID_PREFIX} characters` }, 400);
+    }
+    // Scan one past the cap so `truncated` is knowable without a second COUNT.
+    const found = await host.candidates(prefix, RESOLVE_LIMIT + 1);
+    return c.json({
+      prefix,
+      runIds: found.slice(0, RESOLVE_LIMIT),
+      truncated: found.length > RESOLVE_LIMIT,
+    });
+  });
+
+  // Read-through (ADR-0009): a completed run's final status lives in the store after the registry
+  // drops it, so this serves terminal runs too — only a genuinely unknown run is a 404. The status
+  // carries the run's OPEN GATES (ADR-0011) — the discovery listing external callers act on
+  // (`jr2 send` menus, UI inbox cards, webhook translators matching on meta). Settled run → [].
+  app.get("/runs/:runId", instanceOnly, async (c) => {
+    const runId = c.req.param("runId");
+    const status = await host.read(runId);
+    return status ? c.json({ ...status, gates: host.gates(runId) }) : c.json({ error: `no run "${runId}"` }, 404);
+  });
+
+  // Gates delivery (ADR-0011): validate the body against the gate's named schema and deliver into
+  // the gated state. Unknown gate (never opened, state exited, run settled) → 404; a name the gate
+  // doesn't accept, or a payload failing its schema → 400 naming what IS accepted.
+  //
+  // A Gate is a HUMAN's decision (or a webhook's, or CI's). An Agent holding a Sandbox token is
+  // refused here unconditionally — this is the exact line between "the Agent reports an outcome"
+  // and "the Agent approves its own PR" (ADR-0013).
+  app.post("/runs/:runId/gates/:gate/events", authenticated, async (c) => {
+    if (principalOf(c).kind === "sandbox") {
+      return c.json({ error: "a Sandbox token cannot deliver to a gate — gates are not on the Agent's surface" }, 403);
+    }
+    const body = await readJson(c.req.text());
+    try {
+      host.sendToGate(c.req.param("runId"), c.req.param("gate"), body);
+      return c.json({ ok: true });
+    } catch (err) {
+      if (err instanceof UnknownAddressError) return c.json({ error: errMessage(err) }, 404);
+      if (err instanceof EventValidationError) return c.json({ error: errMessage(err) }, 400);
+      throw err;
+    }
+  });
+
+  // SSE: a live run streams its status deltas + author `emit`s (current status replayed on attach,
+  // then live until the terminal transition or client abort). A run that has already settled streams
+  // its final status once and closes (so `jr2 logs -f` works on a finished run). Unknown run → 404.
+  app.get("/runs/:runId/events", instanceOnly, async (c) => {
+    const runId = c.req.param("runId");
+    if (host.status(runId) === undefined) {
+      const finalStatus = await host.read(runId);
+      if (!finalStatus) return c.json({ error: `no run "${runId}"` }, 404);
+      return streamSSE(c, async (stream) => {
+        await stream.writeSSE({ event: "status", data: JSON.stringify(finalStatus) });
+      });
+    }
+    return streamSSE(c, async (stream) => {
+      await new Promise<void>((resolve) => {
+        const exit = closer(resolve);
+        exit.onExit(
+          host.subscribe(runId, (ev) => {
+            if (ev.kind === "closed") return exit.done();
+            if (ev.kind === "emit") {
+              void stream.writeSSE({ event: "emit", data: JSON.stringify(ev.event) });
+              return;
+            }
+            if (ev.kind === "retry") {
+              // The Instance's own feed: the full telemetry, reason included (same trust class as
+              // `fault`).
+              void stream.writeSSE({ event: "retry", data: JSON.stringify(ev) });
+              return;
+            }
+            if (ev.kind === "admission" || ev.kind === "pick") {
+              // Turn markers (ADR-0023) — Instance-token band, so the framing/payload ride whole.
+              // These stay OFF the open workflow feed entirely (run-host.ts feeds them per-run).
+              void stream.writeSSE({ event: ev.kind, data: JSON.stringify(ev) });
+              return;
+            }
+            // Exiting lets the handler return, which CLOSES the stream — so on the terminal frame we
+            // must wait for the write to flush first, or a fire-and-forget write races the close and the
+            // final status is dropped (the very frame `jr2 run` blocks on). Chain the exit off the write.
+            const terminal = ev.status.status !== "active";
+            void stream.writeSSE({ event: "status", data: JSON.stringify(ev.status) }).then(() => {
+              if (terminal) exit.done();
+            });
+          }),
+        );
+        // Race guard: the run may have settled between the liveness check above and this subscribe,
+        // which then attaches to nothing and never fires. Fall back to the terminal read-through.
+        if (host.status(runId) === undefined) {
+          exit.release();
+          void host.read(runId).then((s) => {
+            if (s) void stream.writeSSE({ event: "status", data: JSON.stringify(s) });
+            exit.done();
+          });
+          return;
+        }
+        exit.onExit(pinger(stream, exit.done, pingMs));
+        stream.onAbort(exit.done);
+      });
+    });
+  });
+
+  // Run control (ADR-0002). CANCEL is the only event left on this seam: APPROVE and STEER answered
+  // held `deferred` calls and drained `poll` inboxes, and ADR-0013 reserves both semantics without
+  // building them. Workflow-defined events reach a run through its GATES, not through here.
+  //
+  // It ENDS the run (ADR-0025): the Agents' turns end with it and the run does not come back on
+  // the next restore. `RunHost.stop()` — park it, keep it restorable — is a different verb, and
+  // deliberately not on the wire.
+  app.post("/runs/:runId/events", instanceOnly, async (c) => {
+    const runId = c.req.param("runId");
+    const body = (await readJson(c.req.text())) as RunEventBody;
+    if (body.type !== "CANCEL") {
+      return c.json({ error: `unknown event type "${body.type ?? ""}" (accepts: CANCEL)` }, 400);
+    }
+    try {
+      await host.cancel(runId);
+      return c.json({ ok: true });
+    } catch (err) {
+      return c.json({ error: errMessage(err) }, 404);
+    }
+  });
+
+  // ---- The Agent's surface (`/agents/:iid/*` — ADR-0013) --------------------------------------
+  // Served to ONE caller: the Adapter in the Agent's Sandbox. It renders `surface` as `tools/list`
+  // and turns a `tools/call` into an `events` POST. The Orchestrator therefore keeps no MCP
+  // dependency, no transport, no session handling — and the Agent keeps no route to this API
+  // except through a process whose credential it cannot read.
+  //
+  // Both routes are adapters over the SAME registration table the gates ride: lookup, validation
+  // and delivery are implemented once, in `registration.ts`.
+
+  /** Guard: the surface must exist, and this principal must be allowed to speak for it. */
+  const agentRegistration = (c: Context<JR2Env, "/agents/:instanceId/surface" | "/agents/:instanceId/events">) => {
+    const instanceId = c.req.param("instanceId");
+    const surface = host.agentSurface(instanceId);
+    // The one catch point (ADR-0011): no live registration (settled run, exited state, unknown
+    // iid) → there is no surface to serve. 404 BEFORE the scope check — a caller with a valid
+    // token learns nothing from it that it did not already know.
+    if (!surface) return { error: c.json({ error: `no live agent surface for instance "${instanceId}"` }, 404) };
+    if (!mayDeliverToAgent(principalOf(c), surface.sandbox)) {
+      // A Sandbox token for a DIFFERENT Sandbox (or for a workspace-less run, which no Sandbox
+      // owns). This is the check that keeps one feature's coder out of another's reviewer.
+      return { error: c.json({ error: `this token cannot speak for instance "${instanceId}"` }, 403) };
+    }
+    return { surface };
+  };
+
+  // This turn's menu: the events the invoking state accepts, their input schemas, their semantics.
+  // A transition swaps the registration, which swaps this — so the Adapter gets a state-scoped
+  // toolset for free, and needs no `list_changed` to know it (flue re-lists on every submission).
+  app.get("/agents/:instanceId/surface", authenticated, (c) => {
+    const { surface, error } = agentRegistration(c);
+    return error ?? c.json(surface);
+  });
+
+  // The Agent's pick, delivered into the state that invoked it. The receipt describes itself
+  // (ADR-0024): what was delivered, and whether that ended the turn — which the Adapter renders as
+  // prose. Its `deliveryId` still makes an outcome addressable after the fact, the room a deferred
+  // result will need when it lands.
+  app.post("/agents/:instanceId/events", authenticated, async (c) => {
+    const { error } = agentRegistration(c);
+    if (error) return error;
+    const body = await readJson(c.req.text());
+    try {
+      return c.json(host.sendToAgent(c.req.param("instanceId"), body));
+    } catch (err) {
+      if (err instanceof UnknownAddressError) return c.json({ error: errMessage(err) }, 404);
+      if (err instanceof EventValidationError) return c.json({ error: errMessage(err) }, 400);
+      throw err;
+    }
+  });
+
+  // The pod's one route out (ADR-0053). A `git fetch` inside a Sandbox runs a program on the
+  // runtime volume, which asks the Adapter on localhost, which forwards to this. What lands here
+  // is one identity; what goes back is the landing, or the cache as it stands with git's own words
+  // — freshness degrades, absence does not, so this answers 200 either way and the program prints
+  // the warning. The caller waits on the ask the way an attach waits on Ready: same status, same
+  // per-key entry, one wait.
+  //
+  // Scoped by the token to ITS OWN pod, and then by the CR to the Repos that pod mounts. Neither
+  // is decoration: without the first, one feature's Sandbox could spend the cluster's credential
+  // on another's; without the second, on any Repo in the namespace.
+  app.post("/sandboxes/:name/fetch", authenticated, async (c) => {
+    const name = c.req.param("name");
+    if (!mayAskForSandbox(principalOf(c), name)) {
+      return c.json({ error: `this token cannot ask for Sandbox "${name}"` }, 403);
+    }
+    if (!opts.fetchRepo) {
+      return c.json({ error: "this instance runs no Workspace, so it holds no Repo cache to ask" }, 404);
+    }
+    const body = await readJson(c.req.text());
+    const identity = body.identity;
+    if (typeof identity !== "string" || identity === "") {
+      return c.json({ error: "a fetch names the Repo's identity: { identity }" }, 400);
+    }
+    try {
+      return c.json(await opts.fetchRepo(name, identity));
+    } catch (err) {
+      // The scope refusal, and the only one: a Repo this Sandbox does not mount.
+      if (err instanceof UnmountedRepoError) return c.json({ error: errMessage(err) }, 404);
+      throw err;
+    }
+  });
+
+  return app;
+}