@jr2/orchestrator 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -35,18 +35,17 @@
   "types": "./src/index.ts",
   "dependencies": {
     "@hono/node-server": "^2.0.6",
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "elkjs": "^0.11.1",
     "hono": "^4.12.27",
     "preact": "^10.29.8",
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.2.0"
+    "@jr2/agent-protocol": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.2.0"
+    "@jr2/harness": "0.3.0"
   },
   "files": [
     "bin",

package/src/actor.ts

@@ -4,8 +4,8 @@
 //   1. REGISTERS the invocation's event surface: `tools` names are resolved against the
 //      INVOKING MACHINE's vocabulary (per-Machine scoping — an unlisted name fails at invoke time)
 //      and registered in the host's table under the instance's agent address, with a deliver
-//      closure over THIS invocation's `sendBack`. The Agent's domain tool calls arrive from its
-//      Adapter (`/agents/<iid>/events` — ADR-0013), are validated by the table, and land on the
+//      closure over THIS invocation's `sendBack`. The Agent's domain tool calls arrive through its
+//      pod's Custodian (`/agents/<iid>/events` — ADR-0013), are validated by the table, and land on the
 //      state that invoked the agent — at any nesting depth, no routing, no `instanceId` on
 //      domain events (the closure IS the provenance). `/agents/<iid>/surface` serves exactly
 //      this registration, so menus are state-scoped by lifecycle (ADR-0006's dynamic
@@ -150,7 +150,7 @@ export type AgentTurnInput = {
 export type AgentTurnPlacement = {
   /** The Harness base URL this Turn is admitted over. */
   endpoint?: string;
-  /** The Sandbox whose Adapter token may deliver this Turn's picks (ADR-0013). */
+  /** The Sandbox whose token (held by that pod's Custodian) may deliver this Turn's picks (ADR-0013). */
   sandbox?: string;
 };
 
@@ -257,8 +257,10 @@ export interface AgentRunPort {
  * Machine edit that changed it. */
 export type AgentAdmitOptions = { definition: AgentDefinition; signal?: AbortSignal };
 
-/** Build a port for one invocation from its serializable input (ADR-0011 static-import doctrine). */
-export type AgentRunPortFactory = (endpoint: string) => AgentRunPort;
+/** Build a port for one invocation from its serializable input (ADR-0011 static-import doctrine),
+ * plus the Harness bearer for the placement that input resolved to (ADR-0058) — absent where no
+ * placement is named (the stub path) or the host derives none. */
+export type AgentRunPortFactory = (endpoint: string, bearer?: string) => AgentRunPort;
 
 /** Absorbed-turn-mechanics knobs (ADR-0016): defaulted, never Machine context. */
 export type AgentRunOptions = {
@@ -433,7 +435,7 @@ export function agentActorWith(
       }
       endpoint = binding.instanceHarness;
       // The registration records the PLACEMENT's name as its delivery scope — ADR-0013's
-      // doctrine, extended to the second placement: the Instance Harness Adapter bears a token
+      // doctrine, extended to the second placement: the Instance Harness's Custodian holds a token
       // signed for this name (deploy.ts), so it may speak for the Turns hosted there and for no
       // Workspace's. The Instance token still may (it is the operator, tokens.ts).
       sandbox = INSTANCE_HARNESS_SERVICE;
@@ -504,7 +506,10 @@ export function agentActorWith(
       );
     registerSurface(currentIid);
 
-    const client = portFactory(endpoint);
+    // The Harness bearer (ADR-0058) is derived from the SAME name the registration records as its
+    // delivery scope: the pod hosting this Turn. One name, both directions — the Custodian there may
+    // speak for these picks, and only this bearer may drive the conversation there.
+    const client = portFactory(endpoint, sandbox === undefined ? undefined : binding.harnessBearer?.(sandbox));
     const controller = new AbortController();
     // Shared per run, created on demand so the ordering guarantee holds for any binding.
     const pendingAborts = (binding.pendingAborts ??= new Map<string, Promise<void>>());

package/src/agent.ts

@@ -1,6 +1,6 @@
 // The Agent definition (ADR-0018/0027): the part of an Agent a user genuinely owns — model +
-// instructions + workspace access — as SERIALIZABLE DATA. Everything mechanical (the Adapter
-// leash, the Working-tool assembly, the wire) lives in the stock Harness image (`@jr2/harness`),
+// instructions + workspace access — as SERIALIZABLE DATA. Everything mechanical (the Menu,
+// the Working-tool assembly, the wire) lives in the stock Harness image (`@jr2/harness`),
 // which runs the definition it is handed and re-reads it per Submission.
 //
 // A definition is NOT an Instance roster entry: a Machine CARRIES it as an actor slot —

package/src/config.ts

@@ -105,6 +105,8 @@ export type HarnessEnvVar = {
 /** A whole-Secret/ConfigMap env injection (corev1.EnvFromSource) for the Harness container —
  * e.g. `{ secretRef: { name: "anthropic" } }` to hand a real Harness its model API key. */
 export type HarnessEnvFromSource = {
+  /** Put before every key's name, as corev1 does. */
+  prefix?: string;
   secretRef?: { name: string };
   configMapRef?: { name: string };
 };
@@ -136,8 +138,9 @@ export type HarnessProvider = {
   /** The endpoint — reachable FROM PODS (`localhost` never is; a LAN address works on kind).
    * Deployment-varying → resolve from env (`.env`), never hardcode (ADR-0019). */
   baseUrl: string;
-  /** API key, when the endpoint wants one. May read `process.env` — `jr2 up` materializes config
-   * env values into the instance's Secret; the literal never lands in a manifest (ADR-0019).
+  /** API key, when the endpoint wants one. May read `process.env`. It is a held secret
+   * (ADR-0059): `jr2 up` gives the value to the Custodian alone, bound to `baseUrl`'s host, and the
+   * Harness container holds only its Stand-in. So `baseUrl` must be `https://` when this is set.
    * Genuinely optional: an unauthenticated endpoint needs none (the Harness sends the wire
    * library's placeholder, which vLLM/Ollama ignore). */
   apiKey?: string;
@@ -153,6 +156,41 @@ export type HarnessProvider = {
   models?: Record<string, HarnessProviderModel>;
 };
 
+/** Where one of pi's catalog providers sends its calls (ADR-0059) — reach, not a model choice
+ * (ADR-0018). The catalog keeps every model fact (limits, cost, thinking levels); this changes only
+ * the endpoint, for a gateway that serves the provider's own API (LiteLLM, for example). */
+export type CatalogReach = {
+  /** Replaces `model.baseUrl` for every model of this provider — the WHOLE base the provider's API
+   * appends to (`https://litellm.corp.example` for `anthropic`, which appends `/v1/messages`;
+   * `https://litellm.corp.example/v1` for `openai`). HTTPS only. Deployment-varying → `.env`. */
+  baseUrl: string;
+};
+
+/** A credential the Harness uses and never holds (ADR-0059). The Harness container's env carries
+ * its Stand-in, `jr2-held-<name>`; the Custodian puts the value into requests toward `hosts` alone. */
+export type HeldSecret = {
+  /** The env var the Harness container sees — `[A-Z_][A-Z0-9_]*`. It holds the Stand-in. */
+  name: string;
+  /** The value as a literal, usually read from `process.env`/`.env`. `jr2 up` writes it into the
+   * `jr2-held-secrets` Secret, which only the Custodian mounts. Exactly one of `value`/`valueFrom`. */
+  value?: string;
+  /** Or a key of a Secret you manage (Sealed Secrets, External Secrets). `jr2 up` checks that the
+   * Secret and key exist; the Custodian mounts that one key as a file, and no other container does. */
+  valueFrom?: { secretKeyRef: { name: string; key: string } };
+  /** Where the value may go. Each entry is `host`, `host:port`, or an `https://` URL (its host and
+   * port are taken; the path is ignored). Exact DNS names or IP literals; no wildcards. Port
+   * default 443. Optional ONLY for a known model-key name (`MODEL_KEYS`), where it defaults to the
+   * one host that provider's calls go to. */
+  hosts?: readonly string[];
+  /** Request headers the Stand-in is swapped in, lowercase. Default
+   * `["authorization", "x-api-key", "x-goog-api-key", "api-key"]`. */
+  headers?: readonly string[];
+  /** Optional path prefixes the value may be sent to (`/v1/messages`). Absent → every path. A
+   * gateway key that can reach admin routes (a LiteLLM key that can mint keys) should narrow this:
+   * a key minted through the Custodian is a key the Agent can take away. */
+  paths?: readonly string[];
+};
+
 /** The agent-runtime section (ADR-0018): what the stock Harness image consumes alongside the
  * Agent definition each Turn hands it (ADR-0049). Moved out of `sandbox` deliberately — `sandbox`
  * is pod transport (it still CARRIES this env to the Harness container), but model concerns are
@@ -164,20 +202,29 @@ export type HarnessProvider = {
  * One definition value may still be carried by several Machines, so the variation that matters is
  * per-definition and per-invocation, which one global default serves not at all. */
 export type HarnessConfig = {
-  /** Custom model provider, preflighted from inside the cluster by `jr2 up` (ADR-0019). */
+  /** Custom model provider, preflighted from inside the cluster by `jr2 up` (ADR-0019). Its
+   * `apiKey` is a held secret, `JR2_PROVIDER_API_KEY`, bound to `baseUrl`'s host (ADR-0059). */
   provider?: HarnessProvider;
-  /** Env vars for the Harness container (Agent creds, e.g. ANTHROPIC_API_KEY). Values read from
-   * `process.env`/`.env` are materialized into the instance-owned Secret by `jr2 up`. */
+  /** pi catalog providers whose calls go somewhere else, keyed by the catalog provider id
+   * (`anthropic`, `openai`, ...) — a gateway that serves the provider's own API (ADR-0059). */
+  catalog?: Readonly<Record<string, CatalogReach>>;
+  /** Credentials the Harness uses and never holds (ADR-0059): the Harness container sees a
+   * Stand-in, and the Custodian puts the value into requests toward the bound hosts alone. A model
+   * API key belongs here, never in `env`. */
+  heldSecrets?: readonly HeldSecret[];
+  /** Env vars for the Harness container. Values read from `process.env`/`.env` are materialized
+   * into the instance-owned Secret by `jr2 up`. The Agent can read every one of them, so a known
+   * model key here is refused — it goes in `heldSecrets` (ADR-0059). */
   env?: readonly HarnessEnvVar[];
   /** Whole-Secret/ConfigMap env for the Harness container — `envFrom` refs to Secrets YOU manage
-   * (Sealed Secrets etc.); `jr2 up` preflights that each referenced Secret exists (ADR-0019). */
+   * (Sealed Secrets etc.); `jr2 up` preflights that each referenced Secret exists (ADR-0019), and
+   * refuses one that carries a known model key (ADR-0059). */
   envFrom?: readonly HarnessEnvFromSource[];
   /** Path to a PEM CA bundle, RELATIVE to the instance folder — commit the file (CA certs are
    * public; e.g. an internal CA in front of a LAN vLLM). Only `jr2 up` reads it (host-side): it
    * materializes the `jr2-ca` ConfigMap and runs the provider preflight with the same trust. The
-   * bundle lands on the Harness container and NOWHERE else — never the Adapter, whose Orchestrator
-   * credential has no business behind the same trust store (the `harness.env` asymmetry,
-   * ADR-0013/0020). */
+   * Harness container trusts it, and so does the Custodian when it verifies a bound host
+   * (ADR-0020, ADR-0059). */
   caBundle?: string;
 };
 
@@ -231,7 +278,7 @@ export type JR2Config = {
    *
    * Separate from `registry` on purpose: `registry` addresses images THIS converge builds,
    * `kitRegistry` addresses artifacts the kit already published. One key for both would make every
-   * private-registry user mirror three images they could have pulled from the home. */
+   * private-registry user mirror the Kit images they could have pulled from the home. */
   kitRegistry?: string;
   /** What `jr2 up` builds its images FOR — docker platform strings, e.g. `["linux/arm64"]`
    * (deployment-varying — resolve from env). Absent → derived from the cluster's schedulable nodes
@@ -260,10 +307,13 @@ export function defineConfig(c: JR2Config): JR2Config {
 /**
  * Load an instance's `jr2.config.ts` (default export). Absent file → undefined (an instance
  * can boot configless); a file that fails to IMPORT throws — a broken config must be loud,
- * never silently treated as "no config". The one shape check lives here, on the path the host
- * CLI and the in-cluster Orchestrator share: `git.credentials` is checked at runtime, because an
- * instance is zero-build and nothing typechecks this file before Node strips its types and
- * imports it.
+ * never silently treated as "no config". The shape checks live here, on the path the host CLI
+ * and the in-cluster Orchestrator share: `git.credentials`, `harness.heldSecrets` and
+ * `harness.catalog` are checked at runtime, because an instance is zero-build and nothing
+ * typechecks this file before Node strips its types and imports it. SHAPE only: a held secret's
+ * `value` reads `.env`, which the in-cluster evaluation does not have, so an absent value is not
+ * this function's to refuse — `jr2 up` checks presence and every held-secret rule host-side
+ * (`heldSecretsOf`, ADR-0059).
  */
 export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
   const file = join(dir, "jr2.config.ts");
@@ -271,6 +321,7 @@ export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
   const mod = (await import(pathToFileURL(file).href)) as { default?: JR2Config };
   if (!mod.default) throw new Error(`${file} has no default export (use \`export default defineConfig({…})\`)`);
   if (mod.default.git !== undefined) checkGit(mod.default.git, file);
+  if (mod.default.harness !== undefined) checkHeld(mod.default.harness, file);
   return mod.default;
 }
 
@@ -295,3 +346,57 @@ function checkGit(git: unknown, where: string): void {
 }
 
 const GIT_HINT = "an entry is { match, token?, sshKey? } (ADR-0051)";
+
+const OptionalText = z.string().optional();
+const HeldSecretShape = z
+  .object({
+    name: NonEmpty,
+    // `.env` values are absent in-cluster, so `undefined` must pass here — presence is `jr2 up`'s.
+    value: OptionalText,
+    valueFrom: z
+      .object({ secretKeyRef: z.object({ name: NonEmpty, key: NonEmpty }).strict() })
+      .strict()
+      .optional(),
+    hosts: z.array(z.string()).optional(),
+    headers: z.array(z.string()).optional(),
+    paths: z.array(z.string()).optional(),
+  })
+  .strict();
+const CatalogReachShape = z.object({ baseUrl: z.string() }).strict();
+
+/** `harness.heldSecrets` and `harness.catalog`, SHAPE only (ADR-0059) — by index and field, the
+ * `checkGit` style, so a bad entry names itself (`harness.heldSecrets[1].hosts`). */
+function checkHeld(harness: unknown, where: string): void {
+  if (typeof harness !== "object" || harness === null || Array.isArray(harness)) {
+    throw new Error(`${where} at harness: expected an object`);
+  }
+  const { heldSecrets, catalog } = harness as { heldSecrets?: unknown; catalog?: unknown };
+  if (heldSecrets !== undefined) {
+    if (!Array.isArray(heldSecrets)) {
+      throw new Error(`${where} at harness.heldSecrets: expected an array — ${HELD_HINT}`);
+    }
+    for (const [i, entry] of heldSecrets.entries()) {
+      const parsed = HeldSecretShape.safeParse(entry);
+      if (parsed.success) continue;
+      const issue = parsed.error.issues[0];
+      const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+      throw new Error(`${where} at harness.heldSecrets[${i}]${at}: ${issue?.message ?? "invalid"} — ${HELD_HINT}`);
+    }
+  }
+  if (catalog !== undefined) {
+    if (typeof catalog !== "object" || catalog === null || Array.isArray(catalog)) {
+      throw new Error(`${where} at harness.catalog: expected an object keyed by catalog provider id — ${CATALOG_HINT}`);
+    }
+    for (const [id, reach] of Object.entries(catalog)) {
+      const parsed = CatalogReachShape.safeParse(reach);
+      if (parsed.success) continue;
+      const issue = parsed.error.issues[0];
+      const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+      throw new Error(`${where} at harness.catalog.${id}${at}: ${issue?.message ?? "invalid"} — ${CATALOG_HINT}`);
+    }
+  }
+}
+
+const HELD_HINT =
+  "an entry is { name, value? | valueFrom?: { secretKeyRef: { name, key } }, hosts?, headers?, paths? } (ADR-0059)";
+const CATALOG_HINT = "an entry is <provider id>: { baseUrl } (ADR-0059)";

package/src/custodian.lua

@@ -0,0 +1,312 @@
+-- The Custodian's decisions (ADR-0059), run by Envoy's Lua filter on every listener it owns.
+--
+-- Envoy carries the bytes: the CONNECT listener, TLS on both sides, the upstream pools, streaming.
+-- This script makes every choice about a credential, and nothing else. `jr2 up` prepends a
+-- generated `HELD` table (names, headers, paths, bound targets — never a value) and ships the
+-- whole file in the `jr2-held` ConfigMap. Envoy loads it once per Lua state at start, so the
+-- top-level code below runs before any listener serves: a value that is missing or cannot ride a
+-- header stops the start-up with a line that names the secret, never the value.
+--
+-- Four roles, one per route family, read from the route's metadata:
+--
+--   control    the Harness's Menu and the ask, plain HTTP on loopback, toward the Orchestrator
+--   egress     the CONNECT listener: dial guard, then tunnel or hand to an intercept listener
+--   intercept  one bound host, TLS already ended: swap the Stand-in, strip the rest
+--   health     the kubelet's probe
+
+local VALUES = "/etc/jr2/custodian/values/"
+
+-- The value of one held secret, read once. One trailing line end is taken off, because
+-- `kubectl create secret --from-file` writes one; anything else a header cannot carry stops us.
+local function load(name)
+  local f = io.open(VALUES .. name, "rb")
+  if f == nil then
+    error("jr2.custodian refuse secret=" .. name .. " reason=missing-value")
+  end
+  local v = f:read("*a")
+  f:close()
+  v = v:gsub("\r?\n$", "", 1)
+  if v == "" then
+    error("jr2.custodian refuse secret=" .. name .. " reason=empty-value")
+  end
+  if v:find("[^\32-\126]") then
+    error("jr2.custodian refuse secret=" .. name .. " reason=value-not-printable-ascii")
+  end
+  return v
+end
+
+local STAND_IN = {}
+local VALUE = {}
+for _, s in ipairs(HELD.secrets) do
+  STAND_IN[s.name] = "jr2-held-" .. s.name
+  VALUE[s.name] = load(s.name)
+end
+
+-- The headers every bound target treats as a credential (`CREDENTIAL_HEADERS`, held-secrets.ts).
+local CREDENTIAL = {}
+for _, h in ipairs(HELD.credential) do CREDENTIAL[h] = true end
+
+-- Everything a target's requests may carry a credential in: the fixed set, plus every header a
+-- secret bound to it names.
+local function credentialHeaders(bound)
+  local set = {}
+  for h in pairs(CREDENTIAL) do set[h] = true end
+  for _, s in ipairs(bound) do
+    for _, h in ipairs(s.headers) do set[h] = true end
+  end
+  return set
+end
+
+local function tag(handle, key, value)
+  handle:streamInfo():dynamicMetadata():set("jr2", key, value)
+end
+
+local function refuse(handle, status, reason, body)
+  tag(handle, "action", "refuse")
+  tag(handle, "reason", reason)
+  tag(handle, "log", true)
+  handle:respond({ [":status"] = tostring(status), ["content-type"] = "text/plain" }, "jr2 custodian: " .. body .. "\n")
+end
+
+-- The swap, in the two forms a client writes a key in: the Stand-in alone (`x-api-key`), or one
+-- auth scheme then the Stand-in (`Authorization: Bearer`). Nothing else is ever rewritten.
+local function swapped(value, standIn, secret)
+  if value == standIn then return secret end
+  local scheme, rest = value:match("^([A-Za-z][A-Za-z0-9._~+/-]*) (.+)$")
+  if scheme ~= nil and rest == standIn then return scheme .. " " .. secret end
+  return nil
+end
+
+-- One request toward a target whose secrets are `bound`: every credential header is either the
+-- product of a swap or gone, and a request that swapped nothing never leaves.
+local function hold(handle, headers, bound, target, path)
+  local creds = credentialHeaders(bound)
+  for h in pairs(creds) do
+    if headers:getNumValues(h) > 1 then
+      return refuse(handle, 400, "credential", target .. " got header " .. h .. " more than once")
+    end
+  end
+  local done = {}
+  local names = {}
+  for _, s in ipairs(bound) do
+    for _, h in ipairs(s.headers) do
+      local v = headers:get(h)
+      if v ~= nil and not done[h] then
+        local out = swapped(v, STAND_IN[s.name], VALUE[s.name])
+        if out ~= nil then
+          if s.paths ~= nil then
+            local allowed = false
+            for _, p in ipairs(s.paths) do
+              if path == p or path:sub(1, #p) == p and (p:sub(-1) == "/" or path:sub(#p + 1, #p + 1) == "/") then
+                allowed = true
+              end
+            end
+            if not allowed then
+              return refuse(handle, 403, "path", s.name .. " may not be sent to this path of " .. target)
+            end
+          end
+          headers:replace(h, out)
+          done[h] = true
+          names[#names + 1] = s.name
+        end
+      end
+    end
+  end
+  for h in pairs(creds) do
+    if not done[h] then headers:remove(h) end
+  end
+  if #names == 0 then
+    local wanted, where = {}, {}
+    for _, s in ipairs(bound) do
+      wanted[#wanted + 1] = s.name
+      for _, h in ipairs(s.headers) do where[#where + 1] = h end
+    end
+    return refuse(handle, 403, "stand-in", target .. " needs the stand-in of " .. table.concat(wanted, ", ") ..
+      " in " .. table.concat(where, ", "))
+  end
+  tag(handle, "action", "intercept")
+  tag(handle, "secret", table.concat(names, ","))
+  tag(handle, "log", true)
+end
+
+-- A CONNECT target, one spelling: lowercase, no trailing dot on the name.
+local function normal(authority)
+  local a = authority:lower()
+  local host, port = a:match("^(%[[^%]]+%]):(%d+)$")
+  if host == nil then host, port = a:match("^([^:]+):(%d+)$") end
+  if host == nil then return nil end
+  host = host:gsub("%.$", "")
+  return host, port
+end
+
+local function ipv4(host)
+  local a, b, c, d = host:match("^(%d+)%.(%d+)%.(%d+)%.(%d+)$")
+  if a == nil then return nil end
+  a, b, c, d = tonumber(a), tonumber(b), tonumber(c), tonumber(d)
+  if a > 255 or b > 255 or c > 255 or d > 255 then return nil end
+  return a, b, c, d
+end
+
+-- An IPv6 literal as eight numbers, or nil.
+local function ipv6(host)
+  local s = host:match("^%[(.+)%]$")
+  if s == nil or not s:find(":") then return nil end
+  local v4 = s:match(":(%d+%.%d+%.%d+%.%d+)$")
+  if v4 ~= nil then
+    local a, b, c, d = ipv4(v4)
+    if a == nil then return nil end
+    s = s:sub(1, #s - #v4) .. string.format("%x:%x", a * 256 + b, c * 256 + d)
+  end
+  local head, rest = s:match("^(.-)::(.*)$")
+  local function groups(part)
+    local out = {}
+    if part == "" then return out end
+    for g in (part .. ":"):gmatch("([^:]*):") do
+      if not g:match("^%x%x?%x?%x?$") then return nil end
+      out[#out + 1] = tonumber(g, 16)
+    end
+    return out
+  end
+  local left, right
+  if head == nil then
+    left, right = groups(s), {}
+    if left == nil or #left ~= 8 then return nil end
+  else
+    left, right = groups(head), groups(rest)
+    if left == nil or right == nil or #left + #right > 7 then return nil end
+  end
+  local out = {}
+  for _, g in ipairs(left) do out[#out + 1] = g end
+  for _ = 1, 8 - #left - #right do out[#out + 1] = 0 end
+  for _, g in ipairs(right) do out[#out + 1] = g end
+  return out
+end
+
+-- The dial guard's first half: a tunnel never reaches loopback, link-local (the cloud metadata
+-- address among it), or an unspecified address — nor an IPv4-mapped spelling of one. By NAME it
+-- knows only `localhost`. The second half is Envoy's: an RBAC filter judges the address the
+-- dynamic forward proxy resolved a name to, and `envoy_on_response` logs its refusal (ADR-0059).
+local function guarded(host)
+  if host == "localhost" or host:sub(-10) == ".localhost" then return true end
+  local a, b = ipv4(host)
+  if a ~= nil then
+    return a == 127 or a == 0 or (a == 169 and b == 254)
+  end
+  local g = ipv6(host)
+  if g ~= nil then
+    local zero = true
+    for i = 1, 7 do if g[i] ~= 0 then zero = false end end
+    if zero and (g[8] == 0 or g[8] == 1) then return true end
+    if g[1] >= 0xfe80 and g[1] <= 0xfebf then return true end
+    if g[1] == 0xfd00 and g[2] == 0xec2 and g[3] == 0 and g[4] == 0 and g[5] == 0 and g[6] == 0 and g[7] == 0
+      and g[8] == 0x254 then return true end
+    local mapped = g[1] == 0 and g[2] == 0 and g[3] == 0 and g[4] == 0 and g[5] == 0 and g[6] == 0xffff
+    if mapped then
+      local x, y = math.floor(g[7] / 256), g[7] % 256
+      return x == 127 or x == 0 or (x == 169 and y == 254)
+    end
+  end
+  return false
+end
+
+local function egress(handle, headers)
+  if headers:get(":method") ~= "CONNECT" then
+    return refuse(handle, 405, "method", "this listener speaks CONNECT alone")
+  end
+  local authority = headers:get(":authority") or ""
+  local host, port = normal(authority)
+  if host == nil then
+    return refuse(handle, 400, "target", "a CONNECT names host:port")
+  end
+  local target = host .. ":" .. port
+  if target ~= authority then
+    headers:replace(":authority", target)
+    handle:clearRouteCache()
+  end
+  if HELD.targets[target] ~= nil then
+    -- Handed to the intercept listener, which logs each request it carries.
+    return
+  end
+  if guarded(host) then
+    return refuse(handle, 403, "guard", target .. " is loopback, link-local or unspecified")
+  end
+  tag(handle, "action", "tunnel")
+  tag(handle, "log", true)
+end
+
+-- What a bound host is sent. TRACE is not: a server that answers it echoes the request, the
+-- swapped value among it, back to the Agent. Neither is a WebDAV or other extension method.
+local METHODS = { GET = true, HEAD = true, POST = true, PUT = true, PATCH = true, DELETE = true, OPTIONS = true }
+
+local function intercept(handle, headers, target)
+  if not METHODS[headers:get(":method")] then
+    return refuse(handle, 405, "method", target .. " takes GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS here")
+  end
+  if headers:get("upgrade") ~= nil then
+    return refuse(handle, 501, "upgrade", target .. " takes no protocol upgrade here")
+  end
+  local host = (headers:get(":authority") or ""):lower()
+  local want = target
+  if target:sub(-4) == ":443" then
+    if host == target:sub(1, -5) then host = target end
+  end
+  if host ~= want then
+    return refuse(handle, 421, "host", "Host does not name " .. target)
+  end
+  local path = (headers:get(":path") or "/"):match("^[^?]*")
+  if path:lower():find("%%2[ef]") then
+    return refuse(handle, 400, "path", "an encoded / or . in the path")
+  end
+  for _, h in ipairs({ "te", "trailer", "keep-alive", "proxy-connection" }) do headers:remove(h) end
+  return hold(handle, headers, HELD.targets[target], target, path)
+end
+
+local function control(handle, headers, route)
+  if route == "fetch" then
+    local sandbox = os.getenv("JR2_SANDBOX")
+    if sandbox == nil or sandbox == "" then
+      tag(handle, "action", "refuse")
+      tag(handle, "reason", "no-sandbox")
+      tag(handle, "log", true)
+      return handle:respond({ [":status"] = "404", ["content-type"] = "application/json" },
+        '{"error":"this pod serves no Sandbox, so it mounts no Repo to fetch (ADR-0053)"}')
+    end
+    headers:replace(":path", "/sandboxes/" .. sandbox .. "/fetch")
+  end
+  return hold(handle, headers, HELD.control, "orchestrator", headers:get(":path"))
+end
+
+local READY = false
+
+-- A refusal by resolved address comes from the RBAC filter after this one: the one 403 a request
+-- this script let through as a tunnel can get. It is logged as a refusal by spelling is.
+function envoy_on_response(handle)
+  if handle:metadata():get("role") ~= "egress" then return end
+  if handle:headers():get(":status") ~= "403" then return end
+  local jr2 = handle:streamInfo():dynamicMetadata():get("jr2")
+  if jr2 == nil or jr2.action ~= "tunnel" then return end
+  tag(handle, "action", "refuse")
+  tag(handle, "reason", "guard")
+end
+
+function envoy_on_request(handle)
+  local meta = handle:metadata()
+  local role = meta:get("role")
+  local headers = handle:headers()
+  if role == "egress" then return egress(handle, headers) end
+  if role == "intercept" then return intercept(handle, headers, meta:get("target")) end
+  if role == "control" then return control(handle, headers, meta:get("route")) end
+  if role == "health" then
+    if not READY then
+      READY = true
+      local names = {}
+      for _, s in ipairs(HELD.secrets) do names[#names + 1] = s.name end
+      io.stdout:write("jr2.custodian ready secrets=" .. table.concat(names, ",") .. " hosts=" .. HELD.hosts .. "\n")
+      io.stdout:flush()
+    end
+    return handle:respond({ [":status"] = "200", ["content-type"] = "text/plain" }, "ok\n")
+  end
+  if role == "deny" then
+    return refuse(handle, 404, "route", "no such route")
+  end
+end