@jr2/orchestrator 0.2.1 → 0.3.0

package/src/http.ts

@@ -2,15 +2,16 @@
 // 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:
+// 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:
 //
 //   # 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
+//   # 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]
 //   POST /sandboxes/:name/fetch        ask the node cache to fetch one Repo      [Sandbox token]
@@ -180,7 +181,7 @@ async function consoleTsAsset(file: string): Promise<Response> {
 // 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.
+// so the CLI, the Harness 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" }) ===
@@ -301,8 +302,8 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
 
   /**
    * 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
+   * so `authenticated` alone lets it through — which on the run surface is too much: it would let a
+   * Custodian'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.
@@ -358,8 +359,8 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // 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
-  // run control, and a Sandbox token's scope is its own agent surface — no Adapter forwarding this
-  // route is what keeps an Agent from starting runs today, and that is not a control.
+  // run control, and a Sandbox token's scope is its own agent surface — the Custodian's route
+  // allowlist not forwarding this route is a second layer, not the control (ADR-0059).
   app.post("/workflows/:name/runs", instanceOnly, async (c) => {
     const name = c.req.param("name");
     const input = await readJson(c.req.text());
@@ -671,10 +672,12 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   });
 
   // ---- 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.
+  // Served to ONE caller: the Agent's Harness, through the Custodian in its pod. The Harness renders
+  // `surface` as the Menu and turns a pick 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 container whose credential it cannot read. Everything a pick is judged by
+  // is judged HERE: the token's scope, the live registration, the event's name and payload — the
+  // Custodian forwards and never decides (ADR-0059).
   //
   // Both routes are adapters over the SAME registration table the gates ride: lookup, validation
   // and delivery are implemented once, in `registration.ts`.
@@ -696,7 +699,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   };
 
   // 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
+  // A transition swaps the registration, which swaps this — so the Harness 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);
@@ -704,7 +707,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   });
 
   // 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
+  // (ADR-0024): what was delivered, and whether that ended the turn — which the Harness 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) => {
@@ -721,7 +724,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   });
 
   // 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
+  // runtime volume, which asks the Custodian 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

package/src/images.ts

@@ -4,7 +4,7 @@
 // not folded into sandbox-kubectl.ts, because the CLI needs the type without dragging in the
 // kubectl port.
 //
-// The map is NESTED, never flat. The kit's own `harness`/`adapter` refs sit beside a `sandbox`
+// The map is NESTED, never flat. The kit's own `harness` and the `custodian` sit beside a `sandbox`
 // sub-map, so a user image can never shadow them — and `default` is the one reserved key in that
 // sub-map, because ADR-0037's fallback chain is built on it.
 //
@@ -26,8 +26,9 @@ import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
- * Every image ref one converge resolved. `harness`/`adapter` are the kit's own (built from a kit
- * checkout, or the published `<kitversion>` tags); `sandbox` is the instance's own docker-context
+ * Every image ref one converge resolved. `harness` is the kit's own (built from a kit checkout, or
+ * the published `<kitversion>` tag); `custodian` is the pinned Envoy the kit deploys and never
+ * builds (ADR-0038, ADR-0059); `sandbox` is the instance's own docker-context
  * builds — one `docker build` straight to a content tag, carrying no jr2 layers at all, because the
  * Harness arrives at POD time on the `/opt/jr2` volume (ADR-0037).
  *
@@ -38,9 +39,10 @@ import { fileURLToPath } from "node:url";
 export type ImageRefs = {
   /** The stock Harness image — also the last leg of the Sandbox Image fallback chain. */
   harness: string;
-  /** The Adapter image (ADR-0013). An Agent with no Adapter cannot drive its Machine at all, so
+  /** The Custodian's image (ADR-0059) — upstream Envoy, pinned by digest, re-homed onto a
+   * `kitRegistry` when one is set. Every Harness pod runs one (it carries the Menu, ADR-0013), so
    * this is required: a map without it fails the provision rather than shipping a mute pod. */
-  adapter: string;
+  custodian: string;
   /** Built Sandbox Images by their build context's CONTENT DIGEST (ADR-0049), plus the reserved
    * key `default` — the Instance's `images/default`, ADR-0037's middle leg. Empty when the
    * instance ships no context and scaffolded no default. */
@@ -99,10 +101,9 @@ export async function readImageRefs(path: string): Promise<ImageRefs> {
     return value as string;
   };
   const harness = ref("harness");
-  // Required, not optional: with the ref living in the map there is no "no adapter configured"
-  // branch left to gate on, and an Agent whose pod has no Adapter parks forever on a tool call it
-  // cannot make (ADR-0013). Failing the provision is the only honest outcome.
-  const adapter = ref("adapter");
+  // Required, not optional: an Agent whose pod has no Custodian parks forever on a Menu it cannot
+  // read (ADR-0013). Failing the provision is the only honest outcome.
+  const custodian = ref("custodian");
   const sandboxRaw = map["sandbox"];
   if (sandboxRaw !== undefined && (typeof sandboxRaw !== "object" || sandboxRaw === null || Array.isArray(sandboxRaw)))
     bad("`sandbox` must be an object of name → ref");
@@ -121,7 +122,7 @@ export async function readImageRefs(path: string): Promise<ImageRefs> {
     if (typeof value !== "string") bad(`\`sandboxUser.${name}\` is not a USER (got ${JSON.stringify(value)})`);
     sandboxUser[name] = value as string;
   }
-  return { harness, adapter, sandbox, sandboxUser };
+  return { harness, custodian, sandbox, sandboxUser };
 }
 
 /**

package/src/index.ts

@@ -2,8 +2,9 @@
 // delivery surfaces, the duplex Actor over the Harness wire, and durable snapshot persistence
 // (ADR-0002/0006/0007). Builds on the `@jr2/agent-protocol` wire contract.
 //
-// It does NOT speak MCP (ADR-0013): the Agent's MCP surface is hosted by the Adapter, in the
-// Sandbox. What lives here is the registration table and two thin HTTP adapters over it.
+// It does NOT speak MCP (ADR-0013): the Harness presents the Menu to its model itself, and reaches
+// the surface here through the Custodian in its pod. What lives here is the registration table and
+// two thin HTTP adapters over it — plus what composes a Custodian (ADR-0059).
 
 // The wire contract, re-exported: a workflow authors against ONE package (`defineEvent`,
 // `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" — ADR-0015).
@@ -24,6 +25,9 @@ export * from "./actor.ts";
 export * from "./gate.ts";
 export * from "./workspace.ts";
 export * from "./images.ts";
+export * from "./model-keys.ts";
+export * from "./held-secrets.ts";
+export * from "./custodian.ts";
 export * from "./sandbox-kubectl.ts";
 export * from "./repos.ts";
 export * from "./repo-fetch.ts";

package/src/instance.ts

@@ -116,7 +116,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // Resolved BEFORE the host, and the signing key with it: the host derives every Harness bearer
   // from the key (ADR-0058) — admission, stream, abort, echo. The key is loaded from (or minted
   // into) the instance folder, NOT generated per process: live Sandboxes outlive a restart, their
-  // Adapters still bear tokens this key signed, and their Harnesses still check bearers it derived.
+  // Custodians still hold tokens this key signed, and their Harnesses still check bearers it derived.
   // The Instance token is per-boot; the key is not. Both are served under in step 4 below.
   const instanceToken = opts.instanceToken ?? mintInstanceToken();
   const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));

package/src/model-keys.ts

@@ -0,0 +1,92 @@
+// The known model keys (ADR-0059): every env var pi's catalog reads a provider's credential from,
+// the catalog provider(s) that read it, and the one host those providers' calls go to by default.
+//
+// A COPY of pi's data at the exact pin `@jr2/harness` holds, because this package has no pi
+// dependency and must not grow one: `jr2 up` reads this table host-side (R1, and the default
+// `hosts` of a held secret), and the in-cluster Orchestrator never touches pi. The copy cannot
+// drift silently — `@jr2/harness`'s `model-keys.test.ts` checks it against pi itself, env names per
+// provider and every provider's default host, in the default gate. A pi bump that adds or moves a
+// provider fails there first, the same canary role Harness conformance plays (ADR-0027).
+//
+// `host` is present only when every model of every provider that reads the name goes to ONE static
+// host. It is absent when there is none: the base URL is a template (`{location}`, an account id),
+// the providers disagree (MOONSHOT_API_KEY serves two regions), or the host is regional (Bedrock).
+// A held secret with such a name must then say its `hosts` itself (§3.4 of the spec, R5).
+
+/** One known model-key env name. */
+export type ModelKey = {
+  /** The catalog provider ids that read this name. */
+  providers: readonly string[];
+  /** The host (port 443) those providers' calls go to by default, when there is exactly one. */
+  host?: string;
+};
+
+export const MODEL_KEYS: Readonly<Record<string, ModelKey>> = {
+  // anthropic reads three names. AUTH_TOKEN goes as `Authorization: Bearer`, the other two as
+  // `x-api-key` (an `sk-ant-oat` value is an OAuth token, which a Stand-in never is).
+  ANTHROPIC_API_KEY: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_AUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_OAUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  OPENAI_API_KEY: { providers: ["openai"], host: "api.openai.com" },
+  GEMINI_API_KEY: { providers: ["google"], host: "generativelanguage.googleapis.com" },
+  // `https://{location}-aiplatform.googleapis.com` — regional, so no default.
+  GOOGLE_CLOUD_API_KEY: { providers: ["google-vertex"] },
+  COPILOT_GITHUB_TOKEN: { providers: ["github-copilot"], host: "api.individual.githubcopilot.com" },
+  // The bearer form of Bedrock auth. Regional, so no default. (SigV4 credentials cannot be held at
+  // all — a signature is not a header a Stand-in can be swapped into — and `jr2 up` warns on them.)
+  AWS_BEARER_TOKEN_BEDROCK: { providers: ["amazon-bedrock"] },
+  ANT_LING_API_KEY: { providers: ["ant-ling"], host: "api.ant-ling.com" },
+  QWEN_TOKEN_PLAN_API_KEY: {
+    providers: ["qwen-token-plan"],
+    host: "token-plan.ap-southeast-1.maas.aliyuncs.com",
+  },
+  QWEN_TOKEN_PLAN_CN_API_KEY: { providers: ["qwen-token-plan-cn"], host: "token-plan.cn-beijing.maas.aliyuncs.com" },
+  // The catalog names no base URL: an Azure deployment is the user's own resource.
+  AZURE_OPENAI_API_KEY: { providers: ["azure-openai-responses"] },
+  NVIDIA_API_KEY: { providers: ["nvidia"], host: "integrate.api.nvidia.com" },
+  DEEPSEEK_API_KEY: { providers: ["deepseek"], host: "api.deepseek.com" },
+  GROQ_API_KEY: { providers: ["groq"], host: "api.groq.com" },
+  CEREBRAS_API_KEY: { providers: ["cerebras"], host: "api.cerebras.ai" },
+  XAI_API_KEY: { providers: ["xai"], host: "api.x.ai" },
+  // pi reads the name, and its catalog lists no model for the provider at this pin.
+  RADIUS_API_KEY: { providers: ["radius"] },
+  OPENROUTER_API_KEY: { providers: ["openrouter"], host: "openrouter.ai" },
+  AI_GATEWAY_API_KEY: { providers: ["vercel-ai-gateway"], host: "ai-gateway.vercel.sh" },
+  ZAI_API_KEY: { providers: ["zai"], host: "api.z.ai" },
+  ZAI_CODING_CN_API_KEY: { providers: ["zai-coding-cn"], host: "open.bigmodel.cn" },
+  MISTRAL_API_KEY: { providers: ["mistral"], host: "api.mistral.ai" },
+  MINIMAX_API_KEY: { providers: ["minimax"], host: "api.minimax.io" },
+  MINIMAX_CN_API_KEY: { providers: ["minimax-cn"], host: "api.minimaxi.com" },
+  // Two providers, two hosts (`.ai` and `.cn`): no single default.
+  MOONSHOT_API_KEY: { providers: ["moonshotai", "moonshotai-cn"] },
+  HF_TOKEN: { providers: ["huggingface"], host: "router.huggingface.co" },
+  FIREWORKS_API_KEY: { providers: ["fireworks"], host: "api.fireworks.ai" },
+  TOGETHER_API_KEY: { providers: ["together"], host: "api.together.ai" },
+  // Two providers, one host.
+  OPENCODE_API_KEY: { providers: ["opencode", "opencode-go"], host: "opencode.ai" },
+  KIMI_API_KEY: { providers: ["kimi-coding"], host: "api.kimi.com" },
+  // Account-templated base URLs.
+  CLOUDFLARE_API_KEY: { providers: ["cloudflare-workers-ai", "cloudflare-ai-gateway"] },
+  XIAOMI_API_KEY: { providers: ["xiaomi"], host: "api.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_CN_API_KEY: { providers: ["xiaomi-token-plan-cn"], host: "token-plan-cn.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_AMS_API_KEY: { providers: ["xiaomi-token-plan-ams"], host: "token-plan-ams.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_SGP_API_KEY: { providers: ["xiaomi-token-plan-sgp"], host: "token-plan-sgp.xiaomimimo.com" },
+};
+
+/** Every catalog provider id some known model key belongs to — the set `harness.catalog` may name. */
+export const MODEL_KEY_PROVIDERS: ReadonlySet<string> = new Set(
+  Object.values(MODEL_KEYS).flatMap((key) => key.providers),
+);
+
+/**
+ * Credentials that sign a request instead of riding it in a header (ADR-0059). A Stand-in cannot be
+ * swapped into a signature, so these cannot be held — `jr2 up` warns when `harness.env` sets one,
+ * because the Agent can read it, and names a gateway as the way out.
+ */
+export const SIGNING_CREDENTIALS: readonly string[] = [
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+  "AWS_PROFILE",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+];

package/src/names.ts

@@ -12,13 +12,13 @@ export const INSTANCE_SECRET = "jr2-instance";
 /** The Instance Harness's Deployment + Service name (ADR-0031): converged by `jr2 up` whenever any
  * Agent definition declares `workspace: "none"`, and the deterministic Service DNS the Agent actor
  * resolves such a Turn to. Doubles as the delivery scope a Menu-only registration records — the
- * name the placement's Adapter token is signed for (tokens.ts, ADR-0013). The port is the
+ * name the placement's Sandbox token is signed for (tokens.ts, ADR-0013), which its Custodian holds. The port is the
  * Harness's own listen port (`PORT` default). */
 export const INSTANCE_HARNESS_SERVICE = "jr2-instance-harness";
 export const INSTANCE_HARNESS_PORT = 8080;
 
 /** The harness config ConfigMap the stock Harness boots from (ADR-0018): what this instance can
- * REACH — the custom model provider, minus its key. No Agents ride it: a Machine carries its own
+ * REACH — the custom model provider minus its key, and the catalog providers' gateways (ADR-0059). No Agents ride it: a Machine carries its own
  * (ADR-0049), and the definition rides each admission, so this holds deployment facts alone
  * (ADR-0050). */
 export const HARNESS_CONFIGMAP = "jr2-harness";
@@ -26,7 +26,7 @@ export const HARNESS_CONFIGMAP = "jr2-harness";
 export const HARNESS_CONFIG_KEY = "harness.json";
 
 /** The resolved image map `jr2 up` writes and every provision reads (ADR-0037/0038): key → ref for
- * the Harness, the Adapter, and every Sandbox Image context the registered Machines carry — keyed
+ * the Harness, the Custodian, and every Sandbox Image context the registered Machines carry — keyed
  * by content digest, plus the reserved `default` (ADR-0049).
  *
  * MOUNTED, never projected into env — the load-bearing part. A mount updates in place through
@@ -38,13 +38,37 @@ export const IMAGES_MOUNT = "/etc/jr2/images";
 /** The ConfigMap key, hence the filename under the mount — the two-sided contract's other half. */
 export const IMAGES_KEY = "images.json";
 
-/** The HARNESS containers' env Secret — Agent creds only, never the Instance token (ADR-0013). */
+/** The HARNESS containers' env Secret — the literal `harness.env` values, never the Instance token
+ * (ADR-0013) and never a model key (ADR-0059: those are held). */
 export const HARNESS_ENV_SECRET = "jr2-harness-env";
 
-/** The instance's private-CA bundle ConfigMap (`harness.caBundle`, ADR-0020) — mounted into the
- * Harness container (and only it) so Agent egress trusts an internal CA. Public data by nature. */
+/** The instance's trust ConfigMap (ADR-0020, ADR-0059): the user's `harness.caBundle` as `ca.crt`
+ * and, while a held secret exists, the three bundles the held-secret path needs — `extra.crt` and
+ * `bundle.crt` for the Harness, `upstream.crt` for the Custodian. Public data by nature. */
 export const CA_CONFIGMAP = "jr2-ca";
 
+/** Held secrets (ADR-0059). The per-Instance CA — its key included — that `jr2 up` alone reads over
+ * the kube API, and that NO pod mounts: every leaf is issued before a pod starts. */
+export const HELD_CA_SECRET = "jr2-held-ca";
+/** The literal held values, one key per name — mounted into the Custodian and nothing else. */
+export const HELD_SECRETS_SECRET = "jr2-held-secrets";
+/** One leaf per bound `host:port` (`<stem>.crt`, `<stem>.key`) — the Custodian's alone. */
+export const HELD_TLS_SECRET = "jr2-held-tls";
+/** `held.json` (what `jr2 up` resolved) plus the Custodian's bootstrap and script. Always applied,
+ * possibly holding no secret: every Harness pod runs a Custodian. */
+export const HELD_CONFIGMAP = "jr2-held";
+/** Where the Orchestrator reads `held.json`, per provision — a mount, so a held-secret edit reaches
+ * future Sandboxes without rolling the Orchestrator (the `jr2-images` pattern, ADR-0038). */
+export const HELD_MOUNT = "/etc/jr2/held";
+export const HELD_KEY = "held.json";
+
+/** The Custodian's listeners (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
+ * HTTPS proxy on loopback, the kubelet's probe, and the control listener the Menu and the ask ride
+ * to the Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). */
+export const CUSTODIAN_PORT = 15001;
+export const CUSTODIAN_HEALTH_PORT = 15021;
+export const CUSTODIAN_CONTROL_PORT = 8081;
+
 /** The scaffold's default deploy-key Secret name (ADR-0047/0051): what `jr2 init`'s wildcard
  * `git.credentials` entry names as its `sshKey`, and what `jr2 up`'s ssh offer generates into when
  * an entry names it. Only a default — an entry may name any Secret. */

package/src/registration.ts

@@ -1,6 +1,6 @@
 // The internal registration table (ADR-0011): one structure behind both delivery dialects.
 // An Agent slot and `gate` register `address → { accepted event defs, deliver closure, meta }`;
-// the two HTTP surfaces (`/agents/:iid/*` for the Adapter, `/runs/:id/gates/*` for humans and
+// the two HTTP surfaces (`/agents/:iid/*` for the Agent's Harness, `/runs/:id/gates/*` for humans and
 // webhooks) are adapters over it — lookup, schema validation, delivery, discovery, and lifecycle
 // are implemented ONCE. The table is implementation structure, not vocabulary: workflows speak
 // only `defineEvent` / `agent` / `gate`.

package/src/repo-fetch.ts

@@ -2,7 +2,7 @@
 //
 // Nothing in the pod holds a git credential, and nothing in it may talk to a remote — the node's
 // cache agent is the only thing that fetches (ADR-0051). So a `git fetch` in a pod is a program on
-// the runtime volume (`jr2-upload-pack`, operator/cmd) asking the Adapter on localhost, the Adapter
+// the runtime volume (`jr2-upload-pack`, operator/cmd) asking the Custodian on localhost, the Custodian
 // asking the Orchestrator with the Sandbox token it already holds, and this port marking the
 // Sandbox CR: one annotation per Repo key, timestamp value. The operator copies the mark onto the
 // pod, the agent reads its demand off pods alone, and the landing comes back on the Sandbox's

package/src/run-host.ts

@@ -7,7 +7,7 @@
 //     closures over their own `sendBack` — so delivery lands on the invoking state at any
 //     nesting depth and the host routes nothing.
 //   - Two thin surfaces sit on that table, and NEITHER is MCP (ADR-0013 — the Orchestrator does
-//     not speak it): `agentSurface` / `sendToAgent` serve the Agent's Adapter (`/agents/:iid/*`),
+//     not speak it): `agentSurface` / `sendToAgent` serve the Agent's Harness (`/agents/:iid/*`),
 //     `gates` / `sendToGate` serve humans, webhooks and CI (`/runs/:id/gates/*`). Lookup,
 //     validation, delivery and lifecycle stay implemented once, in the table.
 //   - The run's Agent children report their durable admissions through the run binding into
@@ -169,13 +169,14 @@ export type GateView = {
 };
 
 /**
- * One live agent surface, as its Adapter reads it (`GET /agents/:iid/surface` — ADR-0013). The
- * Adapter renders this as `tools/list`: each accepted event becomes a tool, its `input` schema the
- * tool's input schema. `semantics` rides along so the Adapter can tell an awaiting tool from a
- * fire-and-forget one — the room ADR-0006's deferred results will land in, unbuilt today.
+ * One live agent surface, as the Harness reads it through its Custodian (`GET /agents/:iid/surface`
+ * — ADR-0013). The Harness presents it to its model as the Menu: each accepted event becomes a
+ * tool, its `input` schema the tool's parameters. `semantics` rides along so the Harness can tell
+ * an awaiting tool from a fire-and-forget one — the room ADR-0006's deferred results will land in,
+ * unbuilt today.
  *
- * `sandbox` is the Sandbox that may deliver here. It is not a secret from the Adapter (that pod IS
- * the sandbox), and serving it lets the Adapter fail loudly on a surface that is not its own.
+ * `sandbox` is the Sandbox that may deliver here. It is not a secret from that pod (the pod IS the
+ * sandbox), and serving it lets a caller fail loudly on a surface that is not its own.
  */
 export type AgentSurfaceView = {
   instanceId: string;
@@ -186,7 +187,7 @@ export type AgentSurfaceView = {
 
 /**
  * The answer to one Agent delivery (`POST /agents/:iid/events`) — a receipt that DESCRIBES ITSELF
- * (ADR-0024). The Adapter renders it as prose, because a bare `deliveryId` told the Agent nothing
+ * (ADR-0024). The Harness renders it as prose, because a bare `deliveryId` told the Agent nothing
  * about whether it was finished, and the model answered that silence by calling again.
  *
  * `turnComplete` is the HINT, never the guarantee (the abort on invocation end is): it is read off
@@ -579,15 +580,14 @@ export class RunHost {
   /**
    * An agent instance's LIVE surface (`GET /agents/:iid/surface` — ADR-0013): what the state that
    * invoked this Agent accepts, right now. Undefined once nothing is registered (the state exited,
-   * the run settled, the iid is unknown) — the one catch point, and the reason the Adapter never
+   * the run settled, the iid is unknown) — the one catch point, and the reason the Harness never
    * has to learn which turn is live: it asks, per turn, and the answer IS the turn.
    *
    * "Right now" is load-bearing (ADR-0029): the registered defs are the state's VOCABULARY, derived
    * statically from its transitions, and the guards on those transitions are asked here — so an
    * event the Machine cannot currently accept is not offered. The pick has not happened yet, so the
    * question is `mayMove`, not `wouldMove`: a guard that would have judged the Agent's arguments is
-   * left on the menu and settled at delivery. The Adapter rebuilds this per MCP connection and the
-   * Harness re-lists per Submission, so the filter lands at turn boundaries and never moves under
+   * left on the menu and settled at delivery. The Harness reads this afresh per Submission, so the filter lands at turn boundaries and never moves under
    * an Agent mid-turn.
    */
   agentSurface(instanceId: string): AgentSurfaceView | undefined {
@@ -609,8 +609,10 @@ export class RunHost {
   }
 
   /**
-   * Deliver one event from an Agent's Adapter (`POST /agents/:iid/events` — ADR-0013). Validation
-   * and delivery are the table's; this only agent-scopes the address and mints the receipt.
+   * Deliver one event from an Agent's Harness (`POST /agents/:iid/events` — ADR-0013). Validation
+   * and delivery are the table's; this only agent-scopes the address and mints the receipt. (A
+   * `deferred` event never reaches here: `jr2Setup` refuses to build a Machine that declares one —
+   * ADR-0013.)
    */
   sendToAgent(instanceId: string, event: { type?: unknown } & Record<string, unknown>): AgentDeliveryReceipt {
     const { type, ...payload } = event;