@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md

@@ -22,24 +22,24 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
   default: `agent({ model, instructions, workspace?, thinkingLevel?, description? })`.
 
 - **The Frame is `prompt` and `cwd`: what this Turn is about and where it works.** Neither identity nor a Dial. A
-  worktree path is per run by nature — `/work/<slot>/<branch>` exists only once a run has a branch — so no definition
-  can name it, and a directory is not a property of a persona any more than a prompt is. `cwd` leaves `AgentDefinition`.
-  The Harness roots the Working tools at the Frame's `cwd`, which rides the admit body beside the prompt and the Dials.
+  worktree path is per run by nature — `/work/<slot>/<name>` exists only once a run cuts it — so no definition can name
+  it, and a directory is not a property of a persona any more than a prompt is. `cwd` leaves `AgentDefinition`. The
+  Harness roots the Working tools at the Frame's `cwd`, which rides the admit body beside the prompt and the Dials.
 
 - **The Briefing is not the Frame.** jr2's Turn part
   ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)) follows the prompt — the resolved working
   directory, the Allowed picks and any notices — in a block of its own. The prompt stays the Machine state's words
   alone; jr2 never writes into it.
 
-- **Under a Workspace, an absent `cwd` resolves to the only Repo Slot's Worktree, and is refused when there is more than
-  one.** With one slot there is no choice, so no convention is being smuggled in (ADR-0051: the kit gives no slot a
-  meaning). With two or more, the state must say which — `cwd: context.workspace.repos.target` — and the actor refuses
-  the Turn before admission, naming the slots and the line to add. The trap is accepted with open eyes: a composer who
-  adds a second slot on the `customize` line can make a Machine that ran yesterday refuse today, in a file the Machine's
-  author never sees. The refusal is explicit, at the first Turn, before any pod is spent; `jr2 up` cannot see it because
-  the invoke's input is a function. A `workspace: "none"` Agent has no Working tools and no `cwd` (ADR-0028); a
-  stub-Harness run with no Workspace keeps `/work`. `task` always passes its `cwd`, because "the first slot is the one
-  the coder edits" is its convention and a convention is stated, not defaulted.
+- **Under Repo Slots, `cwd` is required.** A Workspace that only clones has no Worktree for a default to name
+  ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), and `/work` is the wrong default: an
+  Agent's search hits `default/`, and a relative write lands outside each Worktree, which is the incident above. So the
+  state says where — `cwd: "/work/target/fix"` — and the actor refuses the Turn before admission, naming the slots and
+  the line to add; `jr2 up` cannot see it because the invoke's input is a function. A Turn that wants `/work` states it.
+  A Workspace with no Repo Slot needs no `cwd`: its Turns work in `/work` (ADR-0051). A `workspace: "none"` Agent has no
+  Working tools and no `cwd` (ADR-0028); a stub-Harness run with no Workspace keeps `/work`. `task` passes its `cwd` as
+  any Machine does: "the first slot is the one the coder edits" is its convention, and a convention is stated, not
+  defaulted.
 
 - **`continue: true` is the whole continuation surface.** Absent, every invocation is a fresh conversation — jr's lossy
   handoff, ADR-0016's default, unchanged. Present, the Turn lands on **this Agent's one conversation in this Machine
@@ -52,6 +52,13 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
   - **Fan-out is safe by construction.** A Pool spawns each worker with the item id as its actor id (pool.ts), so three
     `task` children each mint their own `…/backlog.worker.<item>/coder`. The packaged Machine never learns it is under a
     Pool.
+  - **Each segment of the actor path is encoded, then the segments are joined with `.`.** An actor id can be any text
+    (an item id is the source's), and with plain `.` joints the paths `a.b`, `c` and `a`, `b.c` were one conversation. A
+    letter, a digit, `-` and `_` stay as they are; each other character becomes `~` and two upper-case hex digits for
+    each of its UTF-8 bytes (`F.12` is `F~2E12`). So a segment has no `.` and no `/`, the iid's two joints, and nothing
+    that a URL path or a header must escape. The root Machine's path is `root`. Two segments are escaped although each
+    of their characters may stay: `root` is `~72oot`, and the empty id is `~`. So no other path is `root` or empty, and
+    two paths never have one spelling.
   - **States of one Machine share by saying `continue`.** States differ by Menu — a coder in `implement` offers
     `finish`, the same coder in `fix` offers `finish` and `dispute` — and the same conversation is wanted across them. A
     state that wants a clean context leaves `continue` off. A Turn joins only a conversation that an earlier Turn
@@ -112,11 +119,11 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
   that is wrong under every `workspace()` is not a default.
 - **`cwd` as a third Dial.** Rejected on the word: Dials say how hard to run. A directory says where, which is the same
   kind of fact as the prompt — hence Frame.
-- **Default `cwd` to the first Repo Slot.** Rejected: reverses ADR-0051 ("there is no `workdir`"). The single-slot
-  default is not the same thing — with one slot there is nothing to privilege.
-- **Refuse an absent `cwd` under every Workspace.** The safer twin of the single-slot default: one line per invoke, no
-  composition trap. Not taken: the trap's failure is explicit and early, and the line is noise for the common
-  single-repo Machine.
+- **Default `cwd` to the first Repo Slot.** Rejected: reverses ADR-0051 ("there is no `workdir`").
+- **Default `cwd` to the only Repo Slot's Worktree.** Rejected: a Workspace that only clones has no such Worktree. And a
+  refusal under every Workspace with Repo Slots has no composition trap: with a default, a composer who adds a second
+  slot on the `customize` line makes a Machine that ran yesterday refuse today, in a file the Machine's author never
+  sees. The cost is one line per invoke.
 - **A caller-chosen conversation key (`conversation: "coder"`).** Rejected: it either restates the structure or
   contradicts it. Path-scoping the key was proposed and made the key redundant — once the id is
   `<run>/<machine path>/<agent>`, the author has nothing left to name.
@@ -133,19 +140,19 @@ ADR-0018 and GLOSSARY.md said `cwd` is identity, never per Turn. The decided thi
 - `AgentTurnInput` is `{ prompt, cwd?, continue?, model?, thinkingLevel? }`; `AgentDefinition` loses `cwd`. The Harness
   admit body gains the Frame's `cwd`; `ResolvedDefinition.cwd` resolves from it, not the definition; the Harness stops
   validating `description`, which the Orchestrator strips before admission (it is Console material).
-- **A Frame's `cwd` is absolute or the admission is refused**, naming the Frame. Absent is the one silent case, and it
-  says `/work` — a stated default. A relative path has no such answer: it would resolve against whatever directory the
-  Harness process sits in, which is the silent wrong directory this ADR was written for, one level further from the
-  author. The refusal is a 400 at admission, before a pod is spent.
-- `task` passes `cwd: worktreeOf(context).path` and `continue: true`, and drops `generation` (and its `scope`). It keeps
-  `turns`, reset on `agent.fault`, because re-briefing is prompt policy.
+- **A Frame's `cwd` is absolute or the admission is refused**, naming the Frame. Absent is the one silent case, it
+  reaches a Harness only where no Repo Slot is, and it says `/work` — a stated default. A relative path has no such
+  answer: it would resolve against whatever directory the Harness process sits in, which is the silent wrong directory
+  this ADR was written for, one level further from the author. The refusal is a 400 at admission, before a pod is spent.
+- `task` passes the path of the Worktree it cuts as `cwd`, and `continue: true`, and drops `generation` (and its
+  `scope`). It keeps `turns`, reset on `agent.fault`, because re-briefing is prompt policy.
 - The ledger record for a continued conversation carries its epoch; the input mapper reads it at mint time, so the
   minted id persists with the input and restore re-attaches the same conversation (ADR-0016's mapper rule holds — the
   fresh suffix is still the random component).
 - The `@kind` fixtures drop `tools:` and `instanceId:`; the steps compute the continued id from the actor path, as they
   already computed today's pin.
 - A regression scenario for the silent success: a `task` whose model uses relative paths must produce its file inside
-  the worktree, and a multi-slot Machine with no `cwd` must be refused with the slots named.
+  the worktree, and a Machine under Repo Slots with no `cwd` must be refused with the slots named.
 - GLOSSARY.md: **Frame** enters; **Dials** loses `cwd`; **Instance ID** states the `continue` scope and that a faulted
   conversation is not continued. ADR-0016 (continuation), ADR-0018 (identity line), ADR-0031 (placement scenario),
   ADR-0035 (reroll gate wording), ADR-0049 (persona hazard), and ADR-0054 (`task`'s continuation) are edited to state

package/docs/reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md

@@ -42,7 +42,7 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   bearer. A 401 comes before a 404, so a refused caller does not learn which conversations exist. A refused admission
   creates no conversation. The Harness requires `JR2_HARNESS_TOKEN_SHA256` at boot and fails loudly without it.
 - **The echo uses the same bearer.** `JR2_ECHO_TOKEN_SHA256` is removed. The Instance token no longer enters any pod,
-  which is what [ADR-0032](0032-the-console-unlocks-with-the-instance-token.md) and
+  which is what [ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md) and
   [Secrets and trust](../../concepts/secrets-and-trust.md) say.
 - **A refused stream is a fault, not a reconnect.** The bearer is derived, so a Harness that refuses it once refuses it
   on every retry. `wait` settles a 401 or 403 as a `SettlementFault` and does not park the Turn forever.
@@ -52,9 +52,11 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   Orchestrator pods (`app: jr2-orchestrator`, `jr2.dev/instance: <name>`). They are converged unconditionally, so a
   Harness pod is never created before its policy exists. The Instance Effector gets a third of the same form,
   `jr2-instance-effector`, applied with it in one List (ADR-0068).
-- **Starting a run needs the Instance token.** `POST /workflows/:name/runs` moves from `authenticated` to
-  `instanceOnly`. The scope of a Sandbox token is its own agent surface. The Custodian's route allowlist does not
-  forward this route, but that is not a control.
+- **Starting a run needs a Caller with `start`.** `POST /workflows/:name/runs` moves from `authenticated` to the guarded
+  band, where a Caller's `start` scope opens it
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A Sandbox token is no
+  Caller: its scope is its own agent surface. The Custodian's route allowlist does not forward this route, but that is
+  not a control.
 
 ## Considered options
 
@@ -84,18 +86,24 @@ and we add an ingress NetworkPolicy that admits only the Orchestrator to a Harne
   transport failure, not a status, because a 401 would mean the bearer stopped it and the policy did not.
 - **Port-forward and probes are not affected.** `kubectl port-forward` enters the pod's network namespace through the
   kubelet, and the kubelet's probes come from the node. On kind, neither is filtered by an ingress policy. So the CLI,
-  the Console, and a human's shell into the User Container ([ADR-0005](0005-sandbox-pod-composition.md)) keep working.
-  If routable access to the User Container is added later (ADR-0005 leaves it open), it must add its own ingress rule.
+  the Console, `jr2 workspace forward` and `jr2 workspace shell --user` into the User Container
+  ([ADR-0005](0005-sandbox-pod-composition.md), [ADR-0009](0009-cli-and-instance-interface.md)) keep working: they reach
+  the pod by port-forward and exec through the kube API, and no Service routes to the User Container. If routable access
+  to the User Container is added later (ADR-0005 leaves it open), it must add its own ingress rule.
 - **The `@kind` history reads present the bearer.** The steps derive it from the instance Secret's signing key, as the
-  CLI reads the Instance token: over the kube API, with RBAC as the gate. A human reading a conversation does the same.
+  CLI reads the Instance token: over the kube API, with RBAC as the gate. A human reads a conversation from the
+  Orchestrator's record with `jr2 logs`, behind `read` ([ADR-0023](0023-the-harness-prints-the-conversation.md)), and
+  needs no bearer of a Harness.
 - **Model keys are not in the Harness container.** `JR2_PROVIDER_API_KEY` and every other held secret live in the
   Custodian, and the Harness container's env holds their Stand-ins (ADR-0059). `jr2 up` refuses a known model key in
   `harness.env` or in an `envFrom` Secret.
 - **Open gaps, recorded here and not fixed:**
   - **Sandbox egress.** An Agent with bash can reach the internet and send out anything it can read — which no longer
-    includes a held key: a client that goes around the Custodian carries only Stand-ins. A default-deny egress policy
-    needs an allowlist: DNS, the Orchestrator, the model provider, and whatever the work needs (package registries, for
-    example). That needs a config surface and cluster CIDRs, so it is a separate decision.
+    includes a held key: a client that goes around the Custodian carries only Stand-ins. One exception: no Harness pod
+    reaches a cloud metadata address
+    ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). A default-deny egress
+    policy needs an allowlist: DNS, the Orchestrator, the model provider, and whatever the work needs (package
+    registries, for example). That needs a config surface and cluster CIDRs, so it is a separate decision.
   - **A held key can be spent.** The Agent can use a key through the Custodian while its pod lives, and a SigV4 or ADC
     credential cannot be held at all ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)).
   - **The Orchestrator's Secret writes are namespace-wide.** Its Role may create and patch every Secret, and may not get

package/docs/reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md

@@ -13,11 +13,24 @@ decision generalizes that container. It holds every credential the Harness in it
 
 ## Decision
 
-- **A held secret is a credential the Harness uses and never holds.** The Harness container's env holds its
-  **Stand-in**, `jr2-held-<NAME>`. The Stand-in is deterministic and public. It means something only to the Custodian,
-  and only toward a host the secret is bound to. It is unique per name, it is a valid header and env value, and it never
-  contains `sk-ant-oat` (pi reads such a key as an Anthropic OAuth token). The word is not "placeholder", because that
-  is the word of an Open part.
+- **A held secret is a credential the Harness uses and never holds.** The Harness process holds its **Stand-in**. It
+  means something only to the Custodian, and only toward a host the secret is bound to. It is unique per name, it is a
+  valid header and env value, and it never contains `sk-ant-oat` (pi reads such a key as an Anthropic OAuth token). The
+  word is not "placeholder", because that is the word of an Open part.
+- **Every Stand-in is secret, except the fetch Stand-in.** The pod's maker mints each Stand-in for its pod with the
+  signing key, and no process can guess it: the Orchestrator for a Sandbox, and `jr2 up` for the Instance Harness, as it
+  writes that pod's other Secrets (the Instance Effector's key too), and for a check pod
+  ([ADR-0019](0019-one-converging-command-against-the-current-context.md)). Only the Harness process holds the
+  Stand-ins. It holds each one, the control Stand-in included, as a file under `/run/jr2/` that no process it confines
+  can read, and never in the Harness container's env. It gives a model key's Stand-in to the engine in-process. A
+  process that the Harness confines gets in its env only the Stand-ins of the secrets that its `workspace()`'s `secrets`
+  list grants ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). So the
+  Stand-in of a model key is in reach of the Harness process alone, unless the author grants that key. Secrecy matters
+  because confinement makes it hold: a Stand-in that Workspace code can guess lets that code spend the secret. A call
+  that code in `/work` makes to the model directly is outside the Turn's Settlement, so it escapes the usage that jr2
+  records ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)) and each
+  ceiling on spend. A project whose own code needs a model gets a key that the author grants on purpose. The fetch
+  Stand-in stays public (below): it can only ask for a fetch, for its own Sandbox.
 - **The Custodian holds them.** It is a container in every Harness pod — every Sandbox and the Instance Harness — beside
   the Harness, and it holds the held secrets its own pod names (below). The Agent executes no code in it, and
   `shareProcessNamespace` stays off ([ADR-0005](0005-sandbox-pod-composition.md)). So the Agent cannot read its env, its
@@ -25,16 +38,25 @@ decision generalizes that container. It holds every credential the Harness in it
   `@jr2/orchestrator`). The pod's maker writes Envoy's whole configuration — the Orchestrator a Sandbox's at provision,
   `jr2 up` the Instance Harness's — from the manifest `jr2 up` declares (see "Objects, per pod"). There is no admin
   listener and no xDS, so nothing in the pod can change the configuration or read it back.
-- **The Custodian replaces the Adapter.** The `@jr2/adapter` package and the `jr2-adapter` image are deleted. The
-  Sandbox token is a held secret of the kit's own: the Harness container holds
-  `JR2_SANDBOX_TOKEN=jr2-held-JR2_SANDBOX_TOKEN`, and the Custodian holds the token as a file from the `<sandbox>-token`
-  Secret (the Instance Harness: the `JR2_INSTANCE_HARNESS_TOKEN` key of `jr2-instance`). No other container mounts it.
-- **The Harness reads its Menu itself.** There is no MCP. For each Submission, `menu.ts` reads
-  `GET /agents/<iid>/surface` and delivers a pick with `POST /agents/<iid>/events`, both to the Custodian on
-  `127.0.0.1:8081`, with the Stand-in as the bearer. `menu-tools.ts` gives pi each accepted event as a tool. The tool
-  names stay `mcp__jr2__<event>`, because shipped instructions and the printer depend on them; the name is no longer a
-  transport. `menu-tools.ts` adds the prefix, and `menu.ts` keeps the bare name, because an MCP client adds
-  `mcp__<server>__` itself. The Harness keeps what the Adapter did: a turn that is over is never prompted
+- **The Custodian replaces the Adapter.** The `@jr2/adapter` package and the `jr2-adapter` image are deleted. A
+  Sandbox's two tokens are held secrets of the kit's own (ADR-0013): the Custodian holds the control token and the fetch
+  token as files from the `<sandbox>-token` Secret (the Instance Harness: its control token, from
+  `jr2-instance-harness-token`, which `jr2 up` mints as that pod's maker; it serves no fetch). No other container mounts
+  the tokens, and the real tokens never leave the Custodian. The same Secret holds the pod's Stand-ins, which the
+  Harness container mounts as files; so it is never `jr2-instance`, which holds the Instance token and the signing key.
+  - The **control Stand-in** is secret, as every Stand-in but one. The Harness process alone holds it, as a file under
+    `/run/jr2/` that no process it confines can read, and no `secrets` list can grant it: it is in no child's env
+    (ADR-0076). The Custodian puts the control token in its place on the agent routes. There is one control Stand-in for
+    each Sandbox, whatever the count of its Agents.
+  - The **fetch Stand-in** is public, `jr2-held-JR2_SANDBOX_TOKEN`. `jr2-upload-pack` holds it as a constant. The
+    Custodian puts the fetch token in its place on the fetch route alone, and refuses it on every agent route.
+- **The Harness reads its Menu itself.** No MCP carries the Menu. For each Submission, `menu.ts` reads
+  `GET /agents/<iid>/surface` and delivers a pick with `POST /agents/<iid>/events`, both to the Custodian's control
+  socket, `/run/jr2/custodian/control.sock`, with the control Stand-in as the bearer and the slot it states for the
+  conversation (ADR-0076). `menu-tools.ts` gives pi each accepted event as a tool. The tool names stay
+  `mcp__jr2__<event>`, because shipped instructions and the printer depend on them; the name is no longer a transport.
+  `menu-tools.ts` adds the prefix, and `menu.ts` keeps the bare name, because an MCP client adds `mcp__<server>__`
+  itself. The Harness keeps what the Adapter did: a turn that is over is never prompted
   ([ADR-0026](0026-a-turn-that-is-over-is-never-prompted.md)), a receipt is prose
   ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md),
   [ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)), the surface read retries
@@ -42,32 +64,44 @@ decision generalizes that container. It holds every credential the Harness in it
   ([ADR-0042](0042-ready-is-not-routable-an-admission-retries-its-connection.md)), and a `poll` event refuses the turn
   (`deferred` is retired, ADR-0006). The event's own JSON Schema is the tool's parameters, so the model sees the
   contract the Orchestrator validates against.
-- **The control listener forwards four routes and no other.** `127.0.0.1:8081`, plain HTTP, to the Orchestrator's
-  Service (`jr2-orchestrator.<ns>.svc:4000`, written into the pod's bootstrap by whoever makes the pod — see "Objects,
-  per pod"):
+- **The control listener forwards six routes and no other.** Plain HTTP, to the Orchestrator's Service
+  (`jr2-orchestrator.<ns>.svc:4000`, written into the pod's bootstrap by whoever makes the pod — see "Objects, per
+  pod"):
 
   ```
   GET  /agents/<iid>/surface          → the same path     the Menu
   POST /agents/<iid>/events           → the same path     a pick
   GET  /agents/<iid>/deliveries/<id>  → the same path     an outstanding pick's answer (ADR-0024)
+  POST /agents/<iid>/notices          → the same path     a step boundary's notices heard (ADR-0062, ADR-0076)
+  POST /agents/<iid>/conversation     → the same path     a batch of the conversation's entries (ADR-0023)
   POST /fetch                         → /sandboxes/<this pod's Sandbox>/fetch     the ask (ADR-0053)
   anything else                       → 404, from the Custodian
   ```
 
-  A read — the surface, a delivery's poll — is retried on any reset; a pick and the ask only on a reset before they were
-  sent, so one the Orchestrator may have read is not sent twice. A poll holds up to about 25 s, far below the listener's
-  3600 s idle limit, so an outstanding pick never rides one long request (ADR-0002).
+  The five agent routes are on a Unix socket, `/run/jr2/custodian/control.sock`, in a folder that the Harness and the
+  Custodian share and that no confined program can write (ADR-0076). The fetch is on `127.0.0.1:8081`, because
+  `jr2-upload-pack` runs in the domain, and the fetch Stand-in is public. Each listener answers 404 to the other's
+  routes. Landlock does not limit a connect to a named socket, so a confined program can connect to the control socket.
+  It holds no control Stand-in, so the Custodian refuses each agent route that it asks for there, with the fetch
+  Stand-in or with none, and the control socket answers 404 to the fetch route.
 
-  On each forwarded request, the Custodian swaps `Authorization: Bearer <Stand-in>` for the token and removes every
-  other credential header. A request without the Stand-in gets 403. The ask's path comes from the Custodian
-  (`JR2_SANDBOX` in its env, set per pod); on the Instance Harness there is none, and the ask gets 404. The route
-  allowlist is the second layer. The control stays in the Orchestrator: the token's scope, the live registration, and
-  the event's name and payload are judged there, as before (ADR-0013).
+  A read — the surface, a delivery's poll — an acknowledgment of notices, which marks them heard however often it lands,
+  and a batch of the conversation's entries, whose `seq`s make a second send add nothing (ADR-0023), are retried on any
+  reset; a pick and the ask only on a reset before they were sent, so one the Orchestrator may have read is not sent
+  twice. A poll holds up to about 25 s, far below the listener's 3600 s idle limit, so an outstanding pick never rides
+  one long request (ADR-0002).
+
+  On each forwarded request, the Custodian swaps `Authorization: Bearer <Stand-in>` for the token of that route — the
+  control token on an agent route, the fetch token on the fetch route — and removes every other credential header. A
+  request without the Stand-in of its route gets 403. The ask's path comes from the Custodian (`JR2_SANDBOX` in its env,
+  set per pod); on the Instance Harness there is none, and the ask gets 404. The route allowlist is the second layer.
+  The control stays in the Orchestrator: the token's scope, the live registration, and the event's name and payload are
+  judged there, as before (ADR-0013). The Orchestrator also accepts each token on its own routes only, and checks the
+  slot that the Harness states against the registration's (ADR-0076).
 
 - **Model keys go the same way, over HTTPS.** When its pod holds a held secret, the Harness container also gets:
 
   ```sh
-  <NAME>=jr2-held-<NAME>                         one per held secret of the pod
   HTTPS_PROXY / https_proxy=http://127.0.0.1:15001
   NO_PROXY / no_proxy=localhost,127.0.0.1,::1
   NODE_USE_ENV_PROXY=1
@@ -75,11 +109,11 @@ decision generalizes that container. It holds every credential the Harness in it
   SSL_CERT_FILE / REQUESTS_CA_BUNDLE / GIT_SSL_CAINFO=/etc/jr2/ca/bundle.crt
   ```
 
-  These ride `env`, after `harness.env` and before the wire's digest. In Kubernetes `env` wins over `envFrom`, so a
-  Stand-in overrides a same-named key of an `envFrom` Secret, even one that changes later. There is no `HTTP_PROXY`: the
-  Custodian carries TLS only, and plain HTTP (the Custodian's control listener, an in-cluster seed repository) goes
-  direct. `NO_PROXY` is loopback only, so an in-cluster gateway that a secret is bound to still goes through the
-  Custodian.
+  These ride `env`, after `harness.env` and before the wire's digest. This is the Harness container's env, and it holds
+  no Stand-in: the Stand-ins are files (above). A process that the Harness confines gets an explicit env instead, which
+  holds only the Stand-ins that its `workspace()` grants (ADR-0076). There is no `HTTP_PROXY`: the Custodian carries TLS
+  only, and plain HTTP (the Custodian's control listener, an in-cluster seed repository) goes direct. `NO_PROXY` is
+  loopback only, so an in-cluster gateway that a secret is bound to still goes through the Custodian.
 
 - **The egress listener: CONNECT only.** `127.0.0.1:15001`. The CONNECT target decides everything (lowercased, without a
   trailing dot) — never the SNI, never the `Host` header. A target that a held secret is bound to goes to an internal
@@ -92,7 +126,10 @@ decision generalizes that container. It holds every credential the Harness in it
     `paths` gives 403. It is checked after Envoy removes dot segments and reads `\` as `/` and `..;` as `..`, and the
     upstream gets that path. So IIS and Tomcat cannot read a different path. A credential header sent twice gives 400.
   - The swap: in each header the secret names, the Stand-in alone, or one auth scheme and the Stand-in
-    (`Bearer <Stand-in>`), becomes the value. Nothing else is rewritten.
+    (`Bearer <Stand-in>`), becomes the value. Nothing else is rewritten. The Stand-in chooses the secret: when several
+    secrets are bound to one target and one header, the header gets the value of the secret whose Stand-in it carries.
+    So two MCP servers of one service, with two tokens, can be in one pod
+    ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)).
   - Every credential header that is not the product of a swap is removed. A request with no swap gets 403 and never
     leaves the pod: `jr2 custodian: <target> needs the stand-in of <NAME> in <headers>`.
   - Envoy opens its own TLS to the target, verifies the chain against `upstream.crt` and the name against the target's
@@ -143,10 +180,11 @@ decision generalizes that container. It holds every credential the Harness in it
   (`program.lua`); each pod's own `custodian.lua` is a generated `HELD` table — names, headers, paths and targets, never
   a value — that ends with `dofile` of the program, so the program runs after the table it reads. At start the program
   reads each value from `/etc/jr2/custodian/values/<NAME>`, takes off one trailing `\n` or `\r\n`, and stops the
-  start-up with a line that names the secret when a value is missing, empty, or has a byte outside `0x20`–`0x7E`.
-  Envoy's `credential_injector` is not used: it is alpha, it breaks on a secret file that ends in a newline (1.39.1),
-  and it replaces a whole header, where the swap must see the Stand-in. Values never enter a ConfigMap. Envoy runs one
-  worker, with hot restart off, and flushes its access log twice a second.
+  start-up with a line that names the secret when a value is missing, empty, or has a byte outside `0x20`–`0x7E`. Each
+  Stand-in but the fetch Stand-in is a value too: the Custodian reads it from its values, never from the table. Envoy's
+  `credential_injector` is not used: it is alpha, it breaks on a secret file that ends in a newline (1.39.1), and it
+  replaces a whole header, where the swap must see the Stand-in. Values never enter a ConfigMap. Envoy runs one worker,
+  with hot restart off, and flushes its access log twice a second.
 - **The log is a contract.** One line per decision on stdout, with the prefix `jr2.custodian` and `key=value` pairs:
   `ready secrets=… hosts=N` (at the first probe), `action=intercept target=… secret=… method=… status=…`,
   `action=tunnel target=…`, `action=refuse target=… reason=…`. Never a header value, a body, a path, a query, a value or
@@ -170,51 +208,59 @@ decision generalizes that container. It holds every credential the Harness in it
   and `harness.catalog` (a catalog provider id → `{ baseUrl }`). The list serves both sides
   ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). `harness.provider.apiKey` is an entry
   too, implicitly: `JR2_PROVIDER_API_KEY`, bound to its `baseUrl`'s host. `loadConfig` checks the shape in both worlds.
-- **Naming is placement: a pod gets the held secrets something in it names.** Placement is read, never declared
-  (`secretPlacementsOf`), and an entry's `hosts`, `headers` and `paths` are its binding — where the Custodian may put
-  the value — never its placement:
+- **Naming is placement: a pod gets the held secrets something in it names, and a Custodian holds what its pod's Agents
+  name.** Placement is read, never declared (`secretPlacementsOf`), and an entry's `hosts`, `headers` and `paths` are
+  its binding — where the Custodian may put the value — never its placement:
 
-  | Pod                   | The held secrets its Custodian holds                                                       |
-  | --------------------- | ------------------------------------------------------------------------------------------ |
-  | A Workspace's Sandbox | the names its `workspace()` lists under `secrets: [...]`, and the model keys of its Agents |
-  | The Instance Harness  | the model keys of the `"none"` Agents it hosts, and nothing else                           |
+  | Pod                   | The held secrets its Custodian holds                                                                                                 |
+  | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+  | A Workspace's Sandbox | the names its `workspace()` lists under `secrets: [...]`, the model keys of its Agents, and the secrets of the MCP servers they name |
+  | The Instance Harness  | the model keys of the `"none"` Agents it hosts, and the secrets of the MCP servers they name                                         |
 
   A model key is claimed by the PROVIDER: an Agent names its model, and jr2 knows which keys that provider reads
   (`MODEL_KEYS`; the custom provider's id for `JR2_PROVIDER_API_KEY`). An Agent's Turns run in the Workspace below which
   it is declared, down to the next `workspace()`, unless it is `"none"`, whose Turns run at the Instance Harness
-  ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)). A `"none"` Agent cannot execute code, so the
-  Instance Harness loses nothing by holding only model keys. Listing a model key under a `workspace()`'s `secrets` is
-  allowed, and `jr2 up` reports it as redundant. A name a `workspace()` lists that the list does not hold is refused,
-  with the line to add. An entry nothing names — no `workspace()`, no provider, no Effect — goes nowhere, and `jr2 up`
-  warns. `jr2 up` reports per pod:
+  ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)). An MCP server's secret is claimed by the Agent
+  that names the server in its `mcp` list (ADR-0079), and held in the pod where that Agent's Turns run. The rule is the
+  same for every pod: a `"none"` Agent cannot execute code, so the Instance Harness holds only what its Agents name, and
+  only the Harness process spends it. Listing a model key under a `workspace()`'s `secrets` is allowed, and `jr2 up`
+  reports it as redundant. A name a `workspace()` lists that the list does not hold is refused, with the line to add. An
+  entry nothing names — no `workspace()`, no provider, no Effect, no MCP server that an Agent or an Effect names — goes
+  nowhere, and `jr2 up` warns. `jr2 up` reports per pod:
   `Workspace of workflow "coding": Custodian holds ANTHROPIC_API_KEY (provider), JIRA_TOKEN`.
 
   `jr2 up` alone checks the claimed entries (`heldSecretsOf`), host-side, because `.env` values are absent in-cluster.
   An entry no pod claims is not checked as a held secret:
 
-  | #   | Refused                                                                                                                                                                                                                                                                                                             |
-  | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-  | R1  | A known model key (`MODEL_KEYS`) in `harness.env`, or as a key of a Secret or ConfigMap `harness.envFrom` names.                                                                                                                                                                                                    |
-  | R2  | A held-secret name that is `JR2_*` or a proxy or trust variable.                                                                                                                                                                                                                                                    |
-  | R3  | One name held twice, or held and set by `harness.env`.                                                                                                                                                                                                                                                              |
-  | R4  | Not exactly one of `value`/`valueFrom`; an empty value; a byte outside `0x20`–`0x7E`; leading or trailing space.                                                                                                                                                                                                    |
-  | R5  | A claimed entry with no `hosts` where no default exists; a wildcard, userinfo, a non-`https` scheme, a bare-host path, a bad port; two secrets on one host in one header.                                                                                                                                           |
-  | R6  | A `headers` entry that is not a lowercase token, or that frames or routes the request; a duplicate.                                                                                                                                                                                                                 |
-  | R7  | `provider.apiKey` with a non-`https` `baseUrl`; a non-`https` catalog `baseUrl`.                                                                                                                                                                                                                                    |
-  | R8  | A catalog key that is not a known provider, or that is the custom provider's id.                                                                                                                                                                                                                                    |
-  | R9  | Explicit `hosts` on a known model key that leave out where a carried Agent's provider sends its calls.                                                                                                                                                                                                              |
-  | R10 | A `secretKeyRef` whose Secret or key does not exist.                                                                                                                                                                                                                                                                |
-  | R11 | While a secret is held: `harness.env` sets a proxy or trust variable.                                                                                                                                                                                                                                               |
-  | R12 | A `paths` entry that does not start with `/`, or holds `..`, `;`, `\`, `%2e`, `%2f` or `%5c`.                                                                                                                                                                                                                       |
-  | R13 | A held value that also reaches the Harness: its Secret loaded by `harness.envFrom`, its key read by a `harness.env` `secretKeyRef`, or its literal set by `harness.env`. A kit Secret (`jr2-instance`, `jr2-held-*`, `jr2-instance-effector`, `jr2-effector-*`, `<sandbox>-effector`, `jr2-git-*`) named by either. |
+  | #   | Refused                                                                                                                                                                                                                                                                                                                                                                                             |
+  | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | R1  | A known model key (`MODEL_KEYS`) in `harness.env`, or as a key of a Secret or ConfigMap `harness.envFrom` names.                                                                                                                                                                                                                                                                                    |
+  | R2  | A held-secret name that is `JR2_*` or a proxy or trust variable.                                                                                                                                                                                                                                                                                                                                    |
+  | R3  | One name held twice, or held and set by `harness.env`.                                                                                                                                                                                                                                                                                                                                              |
+  | R4  | Not exactly one of `value`/`valueFrom`; an empty value; a byte outside `0x20`–`0x7E`; leading or trailing space.                                                                                                                                                                                                                                                                                    |
+  | R5  | A claimed entry with no `hosts` where no default exists; a wildcard, userinfo, a non-`https` scheme, a bare-host path, a bad port.                                                                                                                                                                                                                                                                  |
+  | R6  | A `headers` entry that is not a lowercase token, or that frames or routes the request; a duplicate; explicit `headers` on an MCP server's secret that leave out `authorization`, where the Harness sends its Stand-in.                                                                                                                                                                              |
+  | R7  | `provider.apiKey` with a non-`https` `baseUrl`; a non-`https` catalog `baseUrl`; an MCP server with a `secret` and a non-`https` `url`.                                                                                                                                                                                                                                                             |
+  | R8  | A catalog key that is not a known provider, or that is the custom provider's id.                                                                                                                                                                                                                                                                                                                    |
+  | R9  | Explicit `hosts` on a known model key that leave out where a carried Agent's provider sends its calls, or on an MCP server's secret that leave out the host of the `url` of a server that names it.                                                                                                                                                                                                 |
+  | R10 | A `secretKeyRef` whose Secret or key does not exist.                                                                                                                                                                                                                                                                                                                                                |
+  | R11 | While a secret is held: `harness.env` sets a proxy or trust variable.                                                                                                                                                                                                                                                                                                                               |
+  | R12 | A `paths` entry that does not start with `/`, or holds `..`, `;`, `\`, `%2e`, `%2f` or `%5c`; explicit `paths` on an MCP server's secret that do not cover the path of the server's `url`.                                                                                                                                                                                                          |
+  | R13 | A held value that also reaches the Harness: its Secret loaded by `harness.envFrom`, its key read by a `harness.env` `secretKeyRef`, or its literal set by `harness.env`. A kit Secret (`jr2-instance`, `jr2-held-*`, `jr2-instance-effector`, `jr2-effector-*`, `<sandbox>-effector`, `jr2-git-*`, and each pod's credentials, `jr2-instance-harness-token` and `<sandbox>-token`) named by either. |
+  | R14 | A held secret's name that is also a key of a Secret that `harness.envFrom` names. The message names the Secret, the key and the held secret.                                                                                                                                                                                                                                                        |
+
+  R14 exists because the Stand-ins are files, not env: no Stand-in hides such a key, so its real value would reach the
+  Harness's env, and the Harness uses a held secret but never holds it. `up` already reads each `envFrom` Secret to
+  check that it exists (ADR-0019).
 
   Each message names the config path, never a value, and says what to write instead. A SigV4 or ADC credential in
   `harness.env` is warned about, not refused. A known model key with no `hosts` is bound to the host its provider's
   calls go to: the host of `harness.catalog.<id>.baseUrl` when set, else pi's catalog host. The key and the calls then
-  read one config and cannot drift. `MODEL_KEYS` is pi's data at the pin, written as plain data by `just model-keys` (a
-  script in `@jr2/harness`) at each pi bump, so the Orchestrator has no pi dependency. A test in `@jr2/harness` checks
-  the table against pi, and checks that the file is the script's exact text. So a pi bump that moves a provider, or a
-  hand edit of the file, fails the default gate until the recipe runs.
+  read one config and cannot drift. An MCP server's secret with no `hosts` is bound to the host of the `url` of each
+  server that names it, in the header `authorization`, in the same way. `MODEL_KEYS` is pi's data at the pin, written as
+  plain data by `just model-keys` (a script in `@jr2/harness`) at each pi bump, so the Orchestrator has no pi
+  dependency. A test in `@jr2/harness` checks the table against pi, and checks that the file is the script's exact text.
+  So a pi bump that moves a provider, or a hand edit of the file, fails the default gate until the recipe runs.
 
 - **A catalog provider can move to a gateway.** pi has no env var for a catalog provider's base URL. It hands the
   provider the model it is given. So `resolveModel` returns a copy of the catalog model with `baseUrl` replaced, for
@@ -309,16 +355,18 @@ decision generalizes that container. It holds every credential the Harness in it
 
 ## Consequences
 
-- **What this closes, and what it does not.** The Agent cannot take a model key or the Sandbox token out of the pod. It
-  can still **spend** a key through the Custodian while its pod lives, on any path `paths` allows. A key with admin
-  rights can mint a new key, and a minted key is one the Agent can take away: use a key with no admin rights, and narrow
-  `paths`. The User Container shares the pod's loopback, so a human in it can spend a key the same way. That human
-  cannot read one either.
+- **What this closes, and what it does not.** The Agent cannot take a model key or a Sandbox's token out of the pod. The
+  Harness spends the model keys for the Turns. Workspace code can still **spend** a key through the Custodian while its
+  pod lives, on any path `paths` allows, when the `workspace()` grants that key. A key with admin rights can mint a new
+  key, and a minted key is one the Agent can take away: use a key with no admin rights, and narrow `paths`. The User
+  Container shares the pod's loopback, so a human in it can spend a key the same way. That human cannot read one either.
 - **Response echo.** Responses pass unchanged. An upstream that echoes the full credential in a response hands it to the
   Agent. Providers mask keys in errors; jr2 does not scrub responses.
 - **Bypass.** A client that ignores `HTTPS_PROXY` goes direct and sends the Stand-in, which is worth nothing. It is not
-  blocked: egress control stays the cluster's decision (ADR-0058's open egress gap). The same holds for the control
-  plane: a caller that skips the Custodian and sends the Stand-in to the Orchestrator gets 401 on every route
+  blocked: egress control stays the cluster's decision (ADR-0058's open egress gap), except for the cloud metadata
+  addresses, which no Harness pod reaches
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). The same holds for the
+  control plane: a caller that skips the Custodian and sends the Stand-in to the Orchestrator gets 401 on every route
   (`auth.test.ts`).
 - **Clients that do not trust the jr2 CA** (Java, a pinned client) fail TLS to a bound host. They fail closed and send
   nothing. Unbound hosts still work for them.
@@ -338,24 +386,27 @@ decision generalizes that container. It holds every credential the Harness in it
 - **Rotation of a value** reaches a live Sandbox only when its pod is replaced.
 - **The walk reads definitions, not Turns.** A pod's model keys come from the models its Agents' definitions name. A
   Turn whose invocation overrides the model with another provider's (`AgentTurnInput.model`) finds no key for that
-  provider in its pod: the Harness container gets a Stand-in only for the names in its own pod's manifest, so that
+  provider in its pod: the Harness process holds a Stand-in only for the names in its own pod's manifest, so that
   provider's key variable is not set at all. The call then has no key (a catalog provider) or sends the custom
   provider's placeholder `unused`, and it fails. This holds in a Workspace and in the Instance Harness alike. The fix is
   a definition that names the provider; in a Workspace, the key under the `workspace()`'s `secrets` also works. The
-  Instance Harness has no such list: its pod holds only the model keys of the `"none"` Agents it hosts.
+  Instance Harness has no such list: its pod holds only what the `"none"` Agents it hosts name.
 - **TLS-only bindings.** A key for a plain-HTTP endpoint is refused (R7). A LAN `llama-server --api-key` needs TLS and
   its CA in `caBundle`, or no key.
 - **No proxy chaining.** The Custodian cannot forward to a corporate proxy. R11 says so rather than fail silently.
-- **Two Harness env shapes.** With no held secret in it, a pod gets the Custodian's address and the token's Stand-in and
-  no proxy, and its HTTPS goes direct. The Custodian runs in both shapes, because it carries the Menu.
-- **The dial guard adds no confinement while egress is open.** The Agent can dial those addresses itself. The guard
-  matters when a cluster closes egress to everything but the Custodian: then the Custodian is not a way around it.
+- **Two Harness env shapes.** With no held secret in it, a pod gets the Custodian's address and no proxy, and its HTTPS
+  goes direct. The Harness process holds the control Stand-in in both shapes. The Custodian runs in both shapes, because
+  it carries the Menu.
+- **The dial guard adds no confinement while egress is open.** The Agent can dial those addresses itself, except the
+  cloud metadata addresses, which jr2's egress policy closes on a CNI that enforces it (ADR-0076). The guard matters
+  when a cluster closes egress to everything but the Custodian: then the Custodian is not a way around it.
 - **One container holds two kinds of credential.** A fault in Envoy's TLS or HTTP parsing is a fault in the container
-  that holds both the Sandbox token and the model keys. The branch with a separate Adapter keeps them apart.
-- **The Harness container now speaks the Orchestrator's two agent routes.** The Agent could always make those calls (the
-  Adapter would forward any MCP call it asked for); now the Harness makes them itself. Nothing is judged in the pod.
-- **`jr2-upload-pack` carries the Stand-in as a constant.** The User Container gets no env (ADR-0005), and asks like any
-  other seat. A test pins the Go literal to `standIn("JR2_SANDBOX_TOKEN")`.
+  that holds both the Sandbox's tokens and the model keys. The branch with a separate Adapter keeps them apart.
+- **The Harness process speaks the Orchestrator's agent routes itself.** Nothing is judged in the pod. No process that
+  the Harness confines holds the control Stand-in, so none can make those calls (ADR-0076).
+- **`jr2-upload-pack` carries the fetch Stand-in as a constant.** The User Container gets no env (ADR-0005), and asks
+  like any other seat. A test pins the Go literal to `standIn("JR2_SANDBOX_TOKEN")`. The Custodian swaps it on the fetch
+  route alone, so the constant reaches no agent route.
 - **The Custodian's image is a Pinned image.** It is deployed and never built, which
   [ADR-0038](0038-jr2-up-builds-every-image-it-deploys.md) now states. `kitRegistry` re-homes it and `jr2 kit push`
   mirrors it ([ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md)). The image sweep never