@jr2/orchestrator 0.2.0 → 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]
@@ -27,9 +28,10 @@
 //                 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.
+//   instanceOnly  the Instance token ALONE. Run control — starting a run included (ADR-0058) — and
+//                 full run state (`/runs*`): a Sandbox token authenticates but is refused, because
+//                 starting work, 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";
@@ -179,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" }) ===
@@ -300,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.
@@ -356,8 +358,10 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // 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) => {
+  // 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 — 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());
     try {
@@ -668,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`.
@@ -693,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);
@@ -701,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) => {
@@ -718,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

@@ -29,7 +29,7 @@ import { RunHost } from "./run-host.ts";
 import type { RunRecord } from "./run-host.ts";
 import { SqliteSnapshotStore } from "./snapshot-store.ts";
 import type { SnapshotStore } from "./snapshot-store.ts";
-import { createAuthenticator, loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import { createAuthenticator, harnessToken, loadSigningKey, mintInstanceToken } from "./tokens.ts";
 import type { SandboxPort } from "./workspace.ts";
 
 export type InstanceOptions = {
@@ -113,19 +113,25 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   }
   await store.init();
 
-  // Resolved BEFORE the host: the Instance token is also the echo bearer (ADR-0023), so the
-  // host's echo pusher closes over it. Served under in step 4 below, unchanged.
+  // 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
+  // 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));
 
   const host = new RunHost({
     store,
     reconcile: opts.reconcile,
     sandbox: opts.sandbox,
     instanceHarness: opts.instanceHarness,
+    harnessBearer: (placement) => harnessToken(signingKey, placement),
     // The run-narrative echo (ADR-0023): tee a run's feed to its enclosing Workspace's Harness,
-    // authenticated as the instance. The wire push is here and the fire-and-forget is the
-    // host's, so a Harness that refuses (or is gone) costs a log line at most.
-    echo: (endpoint) => createEchoPush({ baseUrl: endpoint, token: instanceToken }),
+    // bearing that Workspace's Harness bearer (ADR-0058) — never the Instance token, which would
+    // otherwise pass through a process the Agent executes code beside. The wire push is here and
+    // the fire-and-forget is the host's, so a Harness that refuses (or is gone) costs a log line.
+    echo: (endpoint, bearer) => createEchoPush({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
     // A run left `live` to be retried is otherwise unexplained — the announce line names it, this
     // says why (ADR-0030). stderr, because it is a fault, not the boot's structured result.
     onRestoreError: (runId, err) =>
@@ -153,10 +159,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // discoverable by asking after a specific run id nobody knows to ask about.
   const restored = await host.restore();
 
-  // 4. Serve, authenticated (ADR-0013). The signing key is loaded from (or minted into) the
-  // instance folder, NOT generated per process: live Sandboxes outlive a restart, and their
-  // Adapters still bear tokens this key signed. The Instance token is per-boot; the key is not.
-  const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));
+  // 4. Serve, authenticated (ADR-0013) — the token and key resolved above.
   const auth = createAuthenticator({ instanceToken, signingKey });
   // The Repos are read PER REQUEST, never snapshotted here: a cache the agent cloned minutes
   // after boot must show as present the next time anyone asks (ADR-0048/0051).

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`.
@@ -246,6 +246,13 @@ export type RunBinding = {
    * absent, a `"none"` Agent without an explicit `endpoint` fails loudly.
    */
   instanceHarness?: string;
+  /**
+   * The Harness bearer for a placement (ADR-0058): `harnessToken(signingKey, placement)`, closed
+   * over the key by the host. The Agent actor asks it for the pod its Turn resolved to; the echo
+   * attach asks it for the Workspace's. Absent (bare unit-test bindings, the stub path), no bearer
+   * is sent — which only a Harness that checks nothing accepts.
+   */
+  harnessBearer?: (placement: string) => string;
   /**
    * Record an Agent invocation's durable admission in the host ledger (ADR-0016): persisted
    * beside the snapshot in the same RunBlob save, keyed by iid (globally unique, so the map is
@@ -283,12 +290,13 @@ export type RunBinding = {
   marker?: (event: TurnMarker) => void;
   /**
    * Attach the run-narrative echo to a Workspace's Harness (ADR-0023): the host replays the
-   * run's feed-so-far to `endpoint`, then tees live; returns the detach. Called by `workspace()`'s
+   * run's feed-so-far to `endpoint` — the Harness in `placement`'s pod, pushed with that
+   * placement's bearer (ADR-0058) — then tees live; returns the detach. Called by `workspace()`'s
    * registrar — the same restore-safe seat the ambient handles ride — and scoped to the OWNING
    * run by construction: the binding is per-run, so a sibling run's feed is unreachable.
    * Host-supplied; absent = no echo.
    */
-  echo?: (endpoint: string) => () => void;
+  echo?: (endpoint: string, placement: string) => () => void;
   /**
    * The HOST is ending this run for its own reasons (ADR-0024). An Agent invocation ending
    * normally ends the Agent's turn — the state stopped waiting — but `RunHost.stop()` is the one

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
@@ -312,13 +313,18 @@ export type RunHostOptions = {
   sandbox?: SandboxPort;
   /** The Instance Harness base URL (ADR-0031) — where `workspace: "none"` Turns are admitted. */
   instanceHarness?: string;
+  /** The Harness bearer for a placement (ADR-0058) — `startInstance` closes `harnessToken` over the
+   * signing key. Handed to every run's binding, and to the echo pusher below. Absent, no Harness
+   * call bears one: only the stub Harness answers such a host. */
+  harnessBearer?: (placement: string) => string;
   /**
    * Build the run-narrative echo pusher for one Workspace's Harness (ADR-0023) — the seam a fake
-   * echo server rides in tests; `startInstance` binds the real wire push (harness-client.ts),
-   * closed over the Instance token. Absent = no echo: a host without it runs identically, because
-   * the echo is a courtesy view of the feed, never a dependency of the run.
+   * echo server rides in tests; `startInstance` binds the real wire push (harness-client.ts).
+   * `bearer` is that Workspace's Harness bearer (ADR-0058), when the host derives one. Absent = no
+   * echo: a host without it runs identically, because the echo is a courtesy view of the feed,
+   * never a dependency of the run.
    */
-  echo?: (endpoint: string) => (events: EchoEvent[]) => Promise<void>;
+  echo?: (endpoint: string, bearer: string | undefined) => (events: EchoEvent[]) => Promise<void>;
 };
 
 /** What we persist per run: the machine snapshot wrapped with the run metadata restore needs.
@@ -383,7 +389,11 @@ export class RunHost {
   private readonly onRestoreError?: (runId: string, err: unknown) => void;
   private readonly sandbox?: SandboxPort;
   private readonly instanceHarness?: string;
-  private readonly echoFactory?: (endpoint: string) => (events: EchoEvent[]) => Promise<void>;
+  private readonly harnessBearer?: (placement: string) => string;
+  private readonly echoFactory?: (
+    endpoint: string,
+    bearer: string | undefined,
+  ) => (events: EchoEvent[]) => Promise<void>;
   private readonly workflowDefs = new Map<string, WorkflowDef>();
   private readonly runs = new Map<string, LiveRun>();
   /**
@@ -401,6 +411,7 @@ export class RunHost {
     this.onRestoreError = opts.onRestoreError;
     this.sandbox = opts.sandbox;
     this.instanceHarness = opts.instanceHarness;
+    this.harnessBearer = opts.harnessBearer;
     this.echoFactory = opts.echo;
   }
 
@@ -569,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 {
@@ -599,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;
@@ -883,11 +895,11 @@ export class RunHost {
    * Scoped to the OWNING run's lineage by construction: it reads one run's buffer and listeners
    * and nothing else — a sibling run's events cannot reach this endpoint through here.
    */
-  private attachEcho(runId: string, endpoint: string): () => void {
+  private attachEcho(runId: string, endpoint: string, placement: string): () => void {
     const run = this.runs.get(runId);
     const factory = this.echoFactory;
     if (!run || !factory) return () => {};
-    const push = factory(endpoint);
+    const push = factory(endpoint, this.harnessBearer?.(placement));
     let chain = Promise.resolve();
     let reported = false;
     const enqueue = (events: EchoEvent[]): void => {
@@ -965,6 +977,7 @@ export class RunHost {
       table: this.table,
       sandbox: this.sandbox,
       instanceHarness: this.instanceHarness,
+      ...(this.harnessBearer ? { harnessBearer: this.harnessBearer } : {}),
       // The admission ledger's write half (ADR-0016): the Agent actor reports the durable handle the
       // moment the Harness admits it, and the ledger hits the store in the same RunBlob save. An
       // admission arriving around stop/untrack still lands in `agents` but skips the save,
@@ -999,7 +1012,7 @@ export class RunHost {
         if (run && run.binding === binding) this.feed(run, event);
       },
       // The run-narrative echo attach (ADR-0023), called from `workspace()`'s registrar.
-      echo: (endpoint) => this.attachEcho(record.runId, endpoint),
+      echo: (endpoint, placement) => this.attachEcho(record.runId, endpoint, placement),
     };
     let bound = false;
     const actor = createActor(machine, {