@jr2/orchestrator 0.4.1 → 0.6.0

package/src/http.ts

@@ -5,17 +5,14 @@
 // TWO dialects, one primitive (ADR-0013). The Orchestrator does not speak MCP — nothing does: the
 // Harness presents the Menu to its model itself, and reaches these routes through the Custodian in
 // its pod, which holds the Sandbox token. What is left here are two thin adapters over the same
-// registration table:
+// registration table: the Gate resource of ADR-0011, for a human, a webhook or CI
+// (`GET /runs/:id`, `POST /runs/:id/gates/:gate/events`), and the Agent's surface, for the Agent's
+// Harness through its Custodian and nothing else (`/agents/:iid/*`). `/sandboxes/:name/fetch` also
+// serves the Harness's pod, but it is not an adapter over the 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 Harness, through its Custodian, and nothing else
-//   GET  /agents/:iid/surface          accepts + schemas + semantics             [Sandbox token]
-//   POST /agents/:iid/events           validate + deliver → the turn receipt      [Sandbox token]
-//   GET  /agents/:iid/deliveries/:id   long-poll an outstanding pick's answer    [Sandbox token]
-//   POST /sandboxes/:name/fetch        ask the node cache to fetch one Repo      [Sandbox token]
+// Every route, with its band, is a row of `HTTP_ROUTES` below. That table is data: the HTTP API
+// Reference is generated from it (ADR-0072), and http-routes.test.ts holds it to the routes
+// `createApp` registers, both ways.
 //
 //   # named Charts (ADR-0070): a Chart under a name is a Workflow `<wrapper>/<name>`
 //   GET    /workflows/:wrapper/chart-schema           the grammar, narrowed to the Open body    [open]
@@ -53,16 +50,397 @@ import { Hono } from "hono";
 import type { Context, MiddlewareHandler } from "hono";
 import { accepts } from "hono/accepts";
 import { streamSSE } from "hono/streaming";
-import { EventValidationError, NotTakenError, OutstandingError, UnknownAddressError } from "./registration.ts";
+import { z } from "zod";
+import {
+  DISPATCHED_BY_HEADER,
+  EventValidationError,
+  NotTakenError,
+  OutstandingError,
+  UnknownAddressError,
+  type DispatchedBy,
+} 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 RunFeedEvent, type RunHost, type RunStatus, type WorkflowFeedEvent } from "./run-host.ts";
+import {
+  isAgentPrincipal,
+  mayAskForSandbox,
+  mayDeliverToAgent,
+  SLOT_HEADER,
+  type Authenticator,
+  type Principal,
+} from "./tokens.ts";
+import {
+  DispatchKeyConflictError,
+  keyAnswer,
+  keyConflict,
+  observe,
+  UnknownWorkflowError,
+  type RunFeedEvent,
+  type RunHost,
+  type RunStatus,
+  type WorkflowFeedEvent,
+} from "./run-host.ts";
 import { KIT_VERSION } from "./config.ts";
 import type { AssemblyDoor } from "./assembly.ts";
 import { ChartRefusal } from "./chart.ts";
 import { chartName, NamedChartError, splitChartName, type NamedCharts } from "./charts.ts";
 
+// ---- The route table (ADR-0072) -------------------------------------------------------------
+// The routes `createApp` registers, as data. It is the source of the HTTP API Reference page, so a
+// row says what a CALLER needs: the address, the credential, the body, the answer. Why a route is
+// in its band stays in the comment above its handler. http-routes.test.ts compares the rows with
+// the app's own registrations both ways and checks each row's band on the wire, so the table
+// cannot drift from the code by forgetting.
+
+/** The access bands of ADR-0014, named for the credential each requires, and the publish door's
+ * band (ADR-0069): the publish token alone. */
+export type HttpBand = "open" | "authenticated" | "instanceOnly" | "publishOnly";
+
+/** One route of the Orchestrator's HTTP API (ADR-0072). */
+export type HttpRoute = {
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  /** In Hono syntax, exactly as registered: `:param`, and `:param{regex}` for a constrained one. */
+  path: string;
+  band: HttpBand;
+  /** One line: what the route does. */
+  summary: string;
+  /** The request body, as a type name or in short; absent when the route reads none. */
+  body?: string;
+  /** The success answer, in short. Errors are `{ error }` with the status the handler says. */
+  response: string;
+  /** `true` when the answer is a Server-Sent Events stream. */
+  stream: boolean;
+  /** The decisions that shape the route, as bare ADR numbers: `"0014"`. */
+  adrs: readonly string[];
+};
+
+/** Every route of the Orchestrator's HTTP API, in the order `createApp` registers them. */
+export const HTTP_ROUTES: readonly HttpRoute[] = [
+  {
+    method: "GET",
+    path: "/healthz",
+    band: "open",
+    summary: "Liveness, and what this instance is: its Kit version and image content hash.",
+    response: "{ ok: true, version, hash? }",
+    stream: false,
+    adrs: ["0009", "0019"],
+  },
+  {
+    method: "GET",
+    path: "/readyz",
+    band: "open",
+    summary: "Readiness.",
+    response: "{ ready: true }",
+    stream: false,
+    adrs: ["0009"],
+  },
+  {
+    method: "GET",
+    path: "/workflows",
+    band: "open",
+    summary:
+      "The Workflows a run can start, each with its origin, and each Chart wrapper's named Charts in its entry. A named Chart that cannot run now says why.",
+    response: "WorkflowListing[]",
+    stream: false,
+    adrs: ["0014", "0070"],
+  },
+  {
+    method: "GET",
+    path: "/assembly",
+    band: "open",
+    summary: "The current Assembly and the Assemblies that live runs hold.",
+    response: "AssemblyView",
+    stream: false,
+    adrs: ["0069"],
+  },
+  {
+    method: "PUT",
+    path: "/assembly",
+    band: "publishOnly",
+    summary:
+      "Publish the next Assembly. `jr2 up` calls it, and nothing else. A refused Assembly leaves the current one current.",
+    body: "the Assembly as a tar stream, with the headers `jr2-kit-version` and `jr2-assembly-hash`",
+    response:
+      "200 with the Assembly, its Workflows, the held Assemblies and the ones collected; 400, 409 or 422 with the reason",
+    stream: false,
+    adrs: ["0069"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:wrapper/chart-schema",
+    band: "open",
+    summary: "The Chart grammar, narrowed to the Open body of one Chart wrapper.",
+    response: "JSON Schema",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "PUT",
+    path: "/workflows/:wrapper/charts/:name",
+    band: "instanceOnly",
+    summary: "Admit and keep a runtime Chart under a name. Its Workflow is `<wrapper>/<name>`.",
+    body: "the Chart text alone",
+    response: "201 { name, origin, hash } when new, 200 when it replaced one; 422 { error, report } when refused",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "DELETE",
+    path: "/workflows/:wrapper/charts/:name",
+    band: "instanceOnly",
+    summary: "Remove a runtime Chart. A live run of it keeps its own text.",
+    response: "204",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "POST",
+    path: "/workflows/:wrapper/charts/:name/runs",
+    band: "instanceOnly",
+    summary: "Start a run of a named Chart, as `POST /workflows/<wrapper>%2F<name>/runs` does.",
+    body: "the Chart wrapper's input, without the Chart",
+    response: "201 { runId, instanceId }; 409 when the named Chart cannot run now",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/runs/:runId/machine",
+    band: "open",
+    summary: "The Machine that a run binds, with each bound Chart compiled in, which the Console draws.",
+    response: "MachineDoc",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "GET",
+    path: "/",
+    band: "open",
+    summary: "The Console page to a browser; a 404 to a JSON caller.",
+    response: "text/html (the Console shell)",
+    stream: false,
+    adrs: ["0032"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name",
+    band: "open",
+    summary: "The Console page to a browser; to a JSON caller, the workflow and its declared input schema.",
+    response: "{ name, machineId, input: JSON Schema | null }, or text/html",
+    stream: false,
+    adrs: ["0032", "0033"],
+  },
+  {
+    method: "POST",
+    path: "/workflows/:name/runs",
+    band: "instanceOnly",
+    summary:
+      "Start a run of a registered workflow. A `dispatch` from another Orchestrator sends the header `jr2-dispatched-by`, and a repeated start with its key answers the run that it started.",
+    body: "the workflow's input, checked against its declared input schema",
+    response:
+      "201 { runId, instanceId }; 200 { runId, instanceId, existing: true } for a repeated dispatch; 422 { error, report } when the door refuses a Chart in the input",
+    stream: false,
+    adrs: ["0033", "0058", "0070", "0071"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/machine",
+    band: "open",
+    summary: "The registered template Machine's structure, which the Console draws.",
+    response: "MachineDoc",
+    stream: false,
+    adrs: ["0014"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/runs",
+    band: "open",
+    summary: "The live runs of one workflow, as observations: identity and state value, no context.",
+    response: "RunObservation[]",
+    stream: false,
+    adrs: ["0014"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/events",
+    band: "open",
+    summary: "The activity of every run of one workflow, as observations, on one connection.",
+    response: "SSE: runs, status, emit (type only), retry, gone",
+    stream: true,
+    adrs: ["0014", "0022"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/runs/:runId/events",
+    band: "open",
+    summary: "One live run's activity, as observations, until it settles.",
+    response: "SSE: status, emit (type only), retry",
+    stream: true,
+    adrs: ["0014", "0022"],
+  },
+  {
+    method: "GET",
+    path: "/assets/style.css",
+    band: "open",
+    summary: "The Console's stylesheet.",
+    response: "text/css",
+    stream: false,
+    adrs: ["0032"],
+  },
+  {
+    method: "GET",
+    path: "/assets/elk.js",
+    band: "open",
+    summary: "The Console's graph layout library (the elkjs bundle).",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0032"],
+  },
+  {
+    method: "GET",
+    path: "/assets/:file{[\\w.-]+\\.ts}",
+    band: "open",
+    summary: "A Console source module, with its types erased.",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0034"],
+  },
+  {
+    method: "GET",
+    path: "/assets/components/:file{[\\w.-]+\\.ts}",
+    band: "open",
+    summary: "A Console view module, with its types erased.",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0034"],
+  },
+  {
+    method: "GET",
+    path: "/assets/vendor/:file",
+    band: "open",
+    summary: "Preact's browser ESM, which the Console's import map names.",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0034"],
+  },
+  {
+    method: "GET",
+    path: "/runs",
+    band: "instanceOnly",
+    summary: "The live runs, with their full status.",
+    response: "RunStatus[]",
+    stream: false,
+    adrs: ["0009", "0014"],
+  },
+  {
+    method: "GET",
+    path: "/repos",
+    band: "instanceOnly",
+    summary: "The Repos as the cluster reports them.",
+    response: "{ dataPlane, repos: RepoStatus[] }",
+    stream: false,
+    adrs: ["0048", "0051"],
+  },
+  {
+    method: "GET",
+    path: "/runs/resolve",
+    band: "instanceOnly",
+    summary: "The run ids that start with a prefix (`?prefix=`, at least 4 characters).",
+    response: "{ prefix, runIds: string[], truncated }",
+    stream: false,
+    adrs: ["0009"],
+  },
+  {
+    method: "GET",
+    path: "/runs/:runId",
+    band: "instanceOnly",
+    summary: "One run's status, live or settled, with its open Gates.",
+    response: "RunStatus & { gates: GateView[] }",
+    stream: false,
+    adrs: ["0009", "0011"],
+  },
+  {
+    // `authenticated` in the code, and the handler refuses a Sandbox token itself (ADR-0013): the
+    // credential the route requires is the Instance token's, so this is its band.
+    method: "POST",
+    path: "/runs/:runId/gates/:gate/events",
+    band: "instanceOnly",
+    summary: "Deliver an event to an open Gate of a run.",
+    body: "{ type, ...payload }, checked against the Gate's schema for that event",
+    response: "{ ok: true }; 409 { error, acceptsNow } when the run does not take it now",
+    stream: false,
+    adrs: ["0011", "0013"],
+  },
+  {
+    method: "GET",
+    path: "/runs/:runId/events",
+    band: "instanceOnly",
+    summary: "One run's full activity until it settles; a settled run's final status, once.",
+    response: "SSE: status, emit, retry, admission, pick, placing, placed, child-error, effect, gone",
+    stream: true,
+    adrs: ["0022", "0023", "0064", "0067"],
+  },
+  {
+    method: "POST",
+    path: "/runs/:runId/events",
+    band: "instanceOnly",
+    summary: "Cancel a run: it ends, and its Workspaces go unless `keep` is true.",
+    body: '{ type: "CANCEL", keep?: boolean }',
+    response: "{ ok: true }",
+    stream: false,
+    adrs: ["0002", "0025"],
+  },
+  {
+    method: "GET",
+    path: "/agents/:instanceId/surface",
+    band: "authenticated",
+    summary:
+      "An Agent's Menu, this Turn's Allowed picks and the conversation's pending notices. A control token reads only its own pod's, for the slot it states.",
+    response: "AgentSurfaceView & { notices: Array<{ id, notice }> }",
+    stream: false,
+    adrs: ["0013", "0029"],
+  },
+  {
+    method: "POST",
+    path: "/agents/:instanceId/events",
+    band: "authenticated",
+    summary: "Deliver an Agent's pick into the state that invoked it.",
+    body: "{ type, ...payload }, checked against the pick's input schema",
+    response: 'AgentDeliveryReceipt; 409 { refused: "outstanding", outstanding?, allowed }',
+    stream: false,
+    adrs: ["0013", "0024", "0029"],
+  },
+  {
+    method: "GET",
+    path: "/agents/:instanceId/deliveries/:deliveryId",
+    band: "authenticated",
+    summary: "Long-poll the answer to an outstanding pick; 503 means ask again.",
+    response: "AgentDeliveryReceipt",
+    stream: false,
+    adrs: ["0013", "0024"],
+  },
+  {
+    method: "POST",
+    path: "/agents/:instanceId/notices",
+    band: "authenticated",
+    summary: "Acknowledge the notices a step boundary appended to the Turn: they are heard in its conversation.",
+    body: "{ heard: string[] }",
+    response: "{ heard: number }",
+    stream: false,
+    adrs: ["0062", "0076"],
+  },
+  {
+    method: "POST",
+    path: "/sandboxes/:name/fetch",
+    band: "authenticated",
+    summary: "Ask the node cache to fetch one Repo that this Sandbox mounts. A fetch token asks only for its own.",
+    body: "{ identity }",
+    response: "FetchAnswer: { fetched } | { stale, asOf }",
+    stream: false,
+    adrs: ["0053"],
+  },
+];
+
 /** 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: `deferred`
  * is retired (ADR-0006), `poll` reserved but not built.
@@ -89,6 +467,40 @@ async function readJson(text: Promise<string>): Promise<Record<string, unknown>>
   }
 }
 
+/**
+ * The `jr2-dispatched-by` header a foreign `dispatch` sends (ADR-0071). `instance` is required: a
+ * start that comes over the door with a key comes from another Orchestrator by construction (an
+ * in-process dispatch never reaches the door). Unknown fields are dropped, as a door drops them: a
+ * caller at a later Kit version may send more.
+ */
+const DispatchedByHeader = z.object({
+  run: z.string().min(1),
+  slot: z.string().min(1),
+  effect: z.string().min(1),
+  depth: z.number().int().positive(),
+  instance: z.string().min(1),
+});
+
+/** The header's {@link DispatchedBy}, absent when no header was sent, or why it is refused. */
+function dispatchedByOf(raw: string | undefined): { by?: DispatchedBy } | { error: string } {
+  if (raw === undefined) return {};
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return { error: `the ${DISPATCHED_BY_HEADER} header is not JSON: ${errMessage(err)} (ADR-0071)` };
+  }
+  const parsed = DispatchedByHeader.safeParse(json);
+  if (!parsed.success) {
+    return {
+      error:
+        `the ${DISPATCHED_BY_HEADER} header must be { run, slot, effect, depth, instance }: ` +
+        `${parsed.error.issues.map((i) => `${i.path.join(".") || "(header)"}: ${i.message}`).join("; ")} (ADR-0071)`,
+    };
+  }
+  return { by: parsed.data };
+}
+
 /** The message of a thrown error, for the `{ error }` 404 body. */
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
@@ -434,7 +846,8 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
    * 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));
+    // The slot a control request states (ADR-0076): a control token without one resolves to nothing.
+    const principal = auth(bearerOf(c), c.req.header(SLOT_HEADER));
     if (!principal) return c.json({ error: "unauthorized" }, 401);
     if (principal.kind === "publisher") return c.json({ error: PUBLISHER_ONLY }, 403);
     c.set("principal", principal);
@@ -453,7 +866,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
    */
   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));
+    const principal = auth(bearerOf(c), c.req.header(SLOT_HEADER));
     if (!principal) return c.json({ error: "unauthorized" }, 401);
     if (principal.kind === "publisher") return c.json({ error: PUBLISHER_ONLY }, 403);
     if (principal.kind !== "instance") {
@@ -581,18 +994,35 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
    * Start a run of a Workflow (ADR-0009). A named Chart that cannot run now is 409 with why
    * (ADR-0070); a Chart in the input that the door refuses is 422 with the report; input failing
    * the door schema is 400 (ADR-0033); an unknown Workflow is 404.
+   *
+   * A foreign `dispatch` sends `jr2-dispatched-by` (ADR-0071): its key makes a repeated start one
+   * run, answered `200 { runId, instanceId, existing: true }` where a new one is `201`. The key is
+   * asked first, so a re-send answers its run even when the name would be refused now; a key a
+   * run of another Workflow carries is 409. A header that does not parse is 400. `jr2 run` and the
+   * Console send none. Any throw that is not a refusal is a defect, 500: a foreign caller reads a
+   * 404 as "nothing was started", and a defect may come after a start.
    */
   const startRun = async (c: Context<JR2Env>, name: string): Promise<Response> => {
+    const header = dispatchedByOf(c.req.header(DISPATCHED_BY_HEADER));
+    if ("error" in header) return c.json({ error: header.error }, 400);
+    const { by } = header;
+    if (by) {
+      const found = await host.dispatched(by.effect);
+      if (found && found.workflow !== name) return c.json({ error: keyConflict(found, name, by.effect) }, 409);
+      if (found) return c.json({ ...keyAnswer(found, name, by.effect), existing: true }, 200);
+    }
     const unrunnable = opts.charts?.get(name)?.unrunnable;
     if (unrunnable !== undefined) return c.json({ error: `named Chart "${name}" cannot run: ${unrunnable}` }, 409);
     const input = await readJson(c.req.text());
     try {
-      const { runId, instanceId } = await host.start(name, input);
-      return c.json({ runId, instanceId }, 201);
+      const { runId, instanceId, existing } = await host.start(name, input, by ? { dispatchedBy: by } : {});
+      return existing ? c.json({ runId, instanceId, existing }, 200) : c.json({ runId, instanceId }, 201);
     } catch (err) {
       if (err instanceof ChartRefusal) return c.json({ error: "refused", report: err.report }, 422);
       if (err instanceof EventValidationError) return c.json({ error: errMessage(err) }, 400);
-      return c.json({ error: errMessage(err) }, 404);
+      if (err instanceof DispatchKeyConflictError) return c.json({ error: errMessage(err) }, 409);
+      if (err instanceof UnknownWorkflowError) return c.json({ error: errMessage(err) }, 404);
+      return c.json({ error: errMessage(err) }, 500);
     }
   };
 
@@ -660,7 +1090,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
     });
   });
 
-  // Push work: start a run of a registered workflow. Unknown workflow → host.start throws → 404.
+  // Push work: start a run of a registered workflow. Unknown workflow → UnknownWorkflowError → 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). Instance-band (ADR-0058): starting work is
@@ -877,11 +1307,11 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // 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).
+  // A Gate is a HUMAN's decision (or a webhook's, or CI's). Every Agent principal — a control
+  // token or a fetch 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, ADR-0076).
   app.post("/runs/:runId/gates/:gate/events", authenticated, async (c) => {
-    if (principalOf(c).kind === "sandbox") {
+    if (isAgentPrincipal(principalOf(c))) {
       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());
@@ -1008,7 +1438,9 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // 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 agentRegistration = (
+    c: Context<JR2Env, "/agents/:instanceId/surface" | "/agents/:instanceId/events" | "/agents/:instanceId/notices">,
+  ) => {
     const instanceId = c.req.param("instanceId");
     // Only a Turn that is over answers 404 (ADR-0026). While the host is stopping its runs are
     // parked for restore, not over, so every `/agents/*` call answers 503: the Harness re-asks a
@@ -1031,9 +1463,10 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
     // 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.
+    if (!mayDeliverToAgent(principalOf(c), surface)) {
+      // A control token for a DIFFERENT pod (or for a workspace-less run, which no pod owns), a
+      // stated slot that is not this registration's (ADR-0076), or a fetch token. The first 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 };
@@ -1043,11 +1476,28 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // semantics, fixed for the conversation — and this Turn's Allowed picks (ADR-0029). A transition
   // swaps the registration, which swaps the Allowed picks, never the Menu; the Harness reads both
   // per Submission and needs no `list_changed`.
-  app.get("/agents/:instanceId/surface", authenticated, (c) => {
+  // The same read at a step boundary carries the conversation's pending notices in its audience
+  // (ADR-0062), reserved for this read: the Harness appends them and acknowledges them below.
+  app.get("/agents/:instanceId/surface", authenticated, async (c) => {
     const { surface, error } = agentRegistration(c);
     if (error) return error;
     host.agentSurfaceServed(c.req.param("instanceId"));
-    return c.json(surface);
+    const notices = await host.boundaryNotices(c.req.param("instanceId"));
+    return c.json({ ...surface, notices });
+  });
+
+  // The Harness appended a step boundary's notices to the Turn (ADR-0062, ADR-0076): they are heard
+  // in that conversation, ledgered in one save. An id this conversation did not reserve is ignored,
+  // so the call says nothing a caller did not already know.
+  app.post("/agents/:instanceId/notices", authenticated, async (c) => {
+    const { error } = agentRegistration(c);
+    if (error) return error;
+    const body = await readJson(c.req.text());
+    const heard = (body as { heard?: unknown }).heard;
+    if (!Array.isArray(heard) || heard.some((id) => typeof id !== "string")) {
+      return c.json({ error: "an acknowledgment names the notices heard: { heard: string[] }" }, 400);
+    }
+    return c.json({ heard: host.noticesHeard(c.req.param("instanceId"), heard as string[]) });
   });
 
   // The Agent's pick, delivered into the state that invoked it. The receipt describes itself
@@ -1103,7 +1553,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
       return c.json({ error: restorePendingMessage(`delivery "${deliveryId}"`) }, 503);
     }
     if (!scope) return c.json({ error: `no delivery "${deliveryId}" for instance "${instanceId}"` }, 404);
-    if (!mayDeliverToAgent(principalOf(c), scope.sandbox)) {
+    if (!mayDeliverToAgent(principalOf(c), scope)) {
       return c.json({ error: `this token cannot speak for instance "${instanceId}"` }, 403);
     }
     const receipt = await host.awaitDelivery(instanceId, deliveryId, opts.deliveryWaitMs, c.req.raw.signal);