@jr2/orchestrator 0.5.1 → 0.6.0

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 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.** 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
+  `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,42 @@ 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 five 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 /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 four 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 — and an acknowledgment of notices, which marks them heard however often it
+  lands, 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 +107,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
@@ -143,10 +175,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
@@ -192,21 +225,26 @@ decision generalizes that container. It holds every credential the Harness in it
   `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; 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-*`, 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
@@ -309,16 +347,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,7 +378,7 @@ 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
@@ -346,16 +386,19 @@ decision generalizes that container. It holds every credential the Harness in it
 - **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

package/docs/reference/decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md

@@ -34,16 +34,22 @@ whose processes are gone, with no way to know why.
   than the Agent's own pick changes them inside the Turn, the Harness appends the Allowed picks again at the next step
   boundary, in a `<jr2-turn>` block of their own: "The workflow's state changed since you last read the Allowed picks.
   Allowed now: …" ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). It is
-  appended, never a rewrite of the first, so the cache argument above holds for it too. It carries no notice: notices
-  are for the next Turn in their scope. It carries a pick's briefing when the restatement opens that pick.
+  appended, never a rewrite of the first, so the cache argument above holds for it too. It carries a pick's briefing
+  when the restatement opens that pick. The same read at a step boundary returns the conversation's pending notices, and
+  the Harness appends them in the same way (below).
 - **The Turn part comes last, because a model obeys what it read last.** Measured on the home-lab vLLM model: with a
   prompt that argued for a pick the Turn did not allow, the Allowed picks placed ahead of the prompt were obeyed 0/10
   (thinking off) and 5/10 (thinking on); placed after it, 10/10 both. Wording made no difference. The author's task
   still reads first, as it would with no jr2.
 - **Always on.** No author can turn it off: every fact in it passes the rule above, so removing one can only make the
   Agent act worse. An `instructions` that repeats a fact is harmless.
-- **A notice is delivered once**, on the next admission in its scope that takes it, then cleared. That is the next Turn,
-  or, for a guard kill that the Agent of an open Turn was not told, that Turn's nudge or wake (below).
+- **A notice is heard once by each member of its audience.** A member takes it at its next admission, or at a step
+  boundary of an open Turn: the surface read of the open Turn returns the conversation's pending notices, and the
+  Harness appends them, as it appends a changed Allowed-picks list
+  ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md), ADR-0002). For a guard
+  kill that the Agent of an open Turn was not told, a member also takes it at that Turn's nudge or wake (below). A
+  conversation is an Instance ID ([ADR-0057](0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md)): a fresh
+  Turn, a runaway reroll and a burned conversation's successor each start a new one.
   - **Conversation scope** ("this conversation is new; earlier context is gone") goes to that Agent's next Turn. So does
     a pick's answer that never reached its call
     ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)): the route left the Agent's state, and
@@ -53,18 +59,31 @@ whose processes are gone, with no way to know why.
     and that stopped it" (`stopped`), with an earlier link's reply when one came. No pick-answer notice says the work
     ran to its end. A fresh picking Turn has no such conversation, and its answer is no notice.
   - **Workspace scope** ("the Sandbox's processes were killed at its memory limit during `coder`'s Turn; `/dev/shm` was
-    cleared. Anything that was running in the Sandbox at that time is gone.") goes to the next admission of any Agent in
-    that Workspace that takes it. One kill is one notice, however many Turns saw it. Only a kill read on a stream while
-    its wait is live names the Turn whose Submission ran. Both forms end with the whole Sandbox, because every process
-    in it died, a shared Workspace's too, and in the past tense, because the Agent may hear it after processes started
-    again. A kill read from the pod's list names no Turn and says nothing of when or whose: "the Sandbox's processes
-    were killed at its memory limit (peak X of Y); /dev/shm was cleared. Anything that was running in the Sandbox at
-    that time is gone." The list cannot say whose Turn a kill ended: the kill may land after a state exits, or end an
-    attach, a sync or a command. A kernel kill read from the Sandbox's last end (below) says the same, with the limit
-    and no peak: "the Sandbox's processes were killed at its memory limit of Y; …". A Menu-only Agent outside a
-    Workspace receives conversation notices only.
+    cleared. Anything that was running in the Sandbox at that time is gone.") goes to an **audience** that the ledger
+    fixes when it raises the notice. The rule is: an Agent hears a kill if it was there for it.
+    1. Each conversation admitted in that Workspace before the kill that can still take a Turn: the conversation of an
+       open Turn, which hears it at its next step boundary, or a continued conversation, which hears it at its next
+       Turn. A fresh Turn that already ended is not in the audience.
+    2. When the kill cut a specific Turn — a kill read on that Turn's stream names it — that Agent's next Turn, fresh or
+       continued: the retry of the broken work.
+    3. Minus each conversation whose own `bash` answer returned the kill's verdict (`told`, below). That answer told it
+       already.
+
+    Each member hears the notice once. The notice retires when every member has heard it. A conversation that starts
+    after the kill does not hear it, except the retry of (2). So a Pool of coders in one Workspace
+    ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)) all hear a kill that cut their work.
+    Only a kill read on a stream while its wait is live names the Turn whose Submission ran. Both forms end with the
+    whole Sandbox, because every process in it died, a shared Workspace's too, and in the past tense, because the Agent
+    may hear it after processes started again. A kill read from the pod's list names no Turn and says nothing of when or
+    whose: "the Sandbox's processes were killed at its memory limit (peak X of Y); /dev/shm was cleared. Anything that
+    was running in the Sandbox at that time is gone." The list cannot say whose Turn a kill ended: the kill may land
+    after a state exits, or end an attach, a sync or a command. A kernel kill read from the Sandbox's last end (below)
+    says the same, with the limit and no peak: "the Sandbox's processes were killed at its memory limit of Y; …". A
+    Menu-only Agent outside a Workspace receives conversation notices only.
+
   - A notice never replaces a fault. The Machine still receives `agent.fault` and decides (ADR-0016); the notice makes
     sure the next Agent is not working blind.
+
 - **The Orchestrator is the only keeper of notices**: pending notices are plain data in the run's persisted state
   (ADR-0007). It sees kernel kills and fresh conversations itself. A kernel kill (ADR-0061, layer 5) has two paths,
   under one source, the Workspace and the time the Harness container ended. A Turn that the kill ended faults on it, and
@@ -89,13 +108,15 @@ whose processes are gone, with no way to know why.
     the only limit. A read that never left the Orchestrator, or a draining Harness's 503, is sent again in that time. A
     read that fails or times out is none, and the next admission reads again: the list keeps the kill. The Orchestrator
     logs one line when the reads from a Harness start to fail. It logs no line when a read works again, and it logs the
-    failure again only when a read fails after a read that worked. The Agent's uid can write the file, as it can the
-    conversation records: it can change only what its own Workspace is told. So a `peak` or a `limit` that is not a size
-    in the guard's form, or is long, is left out and logged, on the Harness's read of the file and on the Orchestrator's
-    read of the list and of a stream. The kill is kept, so a real kill is never lost, and its notice says no sizes: "the
-    Sandbox's processes were killed at its memory limit; /dev/shm was cleared. …". Only a kill with no id or no time, or
-    one outside the bounds below, is dropped. A stream event from an older Harness has no id; its source is then its
-    place on the stream, exactly as the Orchestrator raised it before.
+    failure again only when a read fails after a read that worked. The file is beside the Harness's conversations, which
+    no confined child can reach
+    ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). The bounds stay as a
+    second layer: a `peak` or a `limit` that is not a size in the guard's form, or is long, is left out and logged, on
+    the Harness's read of the file and on the Orchestrator's read of the list and of a stream. The kill is kept, so a
+    real kill is never lost, and its notice says no sizes: "the Sandbox's processes were killed at its memory limit;
+    /dev/shm was cleared. …". Only a kill with no id or no time, or one outside the bounds below, is dropped. A stream
+    event from an older Harness has no id; its source is then its place on the stream, exactly as the Orchestrator
+    raised it before.
 
   Both paths raise the notice with the same source, the Workspace and the kill's id. The ledger keeps every source it
   raised (`seen`) in the run's persisted state. So a kill read on both paths, or on two streams, is one notice. Each
@@ -107,62 +128,64 @@ whose processes are gone, with no way to know why.
   restart of the Orchestrator raises no kill twice. A restart of the Harness container keeps the file, which is on the
   pod's emptyDir with its conversations (ADR-0031). A lost pod takes the file with it, but then the Workspace is lost
   (ADR-0021). The list keeps the newest 16 kills, each with at most 32 conversations in `told`, and the Orchestrator
-  reads at most 256 KiB of it. The Agent's uid can write the file, so the two sides hold the same bounds: an `id` and an
-  `at` of at most 64, an `agent` and an `instanceId` of at most 128, and an `at` that parses as a time. A kill outside
-  them is dropped, and a `told` entry outside them is left out. The Harness counts the bytes of the JSON text, and the
-  Orchestrator counts characters, which are never more, so the Harness keeps no kill that the Orchestrator drops. The
-  Harness reads at most the last 256 KiB of the file. With these bounds the largest list is 149,259 bytes. When more
-  come between two admissions, the oldest is lost, and a newer kill tells the same thing. When more than 16 come in one
-  Turn, the Turn's mark leaves the list too, and every kill in the list then counts as after the mark; a nudge or a wake
-  of that Turn may then carry a kill from before it. The Instance Harness keeps no kill, because it holds no Workspace.
+  reads at most 256 KiB of it. The two sides hold the same bounds: an `id` and an `at` of at most 64, an `agent` and an
+  `instanceId` of at most 128, and an `at` that parses as a time. A kill outside them is dropped, and a `told` entry
+  outside them is left out. The Harness counts the bytes of the JSON text, and the Orchestrator counts characters, which
+  are never more, so the Harness keeps no kill that the Orchestrator drops. The Harness reads at most the last 256 KiB
+  of the file. With these bounds the largest list is 149,259 bytes. When more come between two admissions, the oldest is
+  lost, and a newer kill tells the same thing. When more than 16 come in one Turn, the Turn's mark leaves the list too,
+  and every kill in the list then counts as after the mark; a nudge or a wake of that Turn may then carry a kill from
+  before it. The Instance Harness keeps no kill, because it holds no Workspace.
 
   A notice counts as delivered when its admission is ledgered, so a restart before that point delivers it again and a
-  restart after it does not. Delivered is not yet heard: if the Orchestrator ends the Turn before the Harness reads its
-  surface, the Harness never prompts it (ADR-0026), so the Orchestrator raises that admission's notices again. This
-  holds for a nudge and a wake too: each one must have its surface read again before its notices count as heard. An
-  admission that fails leaves the earlier admission's notices heard. A nudge and a wake re-prompt the Turn within
-  itself, so they take no notice of the kind a Turn takes. They take only the guard kills of the list that come after
-  the newest kill whose `told` names their conversation. That `bash` answer told the Agent that all its processes died,
-  so it covers every kill up to it. They also take no kill from before the Turn started. Such a kill would tell the
-  Agent that processes it started in this Turn died. The Turn's first read of the list sets its mark: the id of the
-  newest kill it saw, or "none". The mark is ledgered with every admission of the Turn, and a restore reads it back, so
-  a nudge or a wake takes only kills after it. Only when the first read failed is the Turn's start the mark, ledgered
-  the same way, with one second allowed for a pod clock that runs behind. A read that failed is "could not tell", never
-  an empty list, so it sets no mark. The kills they do not take stay pending for the next Turn. The re-admission after a
-  Harness restart cut the Turn continues the same Turn, so it takes every notice in scope except the guard kills that
-  this rule leaves out. When its read could not tell, it takes no guard kill at all, as a nudge then takes none: it
-  cannot know which kills its own `bash` reported. The notices that the Turn's admissions carried since the Harness last
-  read the Turn's surface are pending again first, each with the source it was raised with, and this re-admission
-  carries them whatever else its scope leaves out. A notice with no source merges only into a pending one with no
-  source, so an equal notice of another kill never takes its place. When such an unread admission carried the Turn's
-  task, the task follows the re-admit text. When the rebuilt Harness lost the conversation, nothing of the Turn is left:
-  every notice that the Turn's admissions carried is pending again whatever the surface reads said, the re-admission
-  takes every notice in scope, as a Turn's admission does, and the Turn's task follows the re-admit text. It says once
-  that the conversation is new. A restore drops the prompt from a Turn's input, so the task rides the ledgered admission
-  too; a lost conversation with no task to send faults the Turn instead. Whether the Harness still holds the
-  conversation is asked again for up to 30 seconds while the new container does not listen yet or drains, and only then
-  is the answer taken as "held". The continue path asks the same way, so a continued Turn after a restart can wait up to
-  30 seconds before its admission. A Harness in CrashLoopBackOff can take longer than that: the answer is then "held",
-  and it can be wrong. So every admission to a conversation that the Harness was taken to keep says so with
-  `kept: true`: the re-admission after a cut, a continued Turn, and a nudge or a wake. A Harness that keeps no such
-  conversation refuses it with 404 and `kept: false` in the body, and seats none. The Orchestrator takes only that 404
-  as the refusal; another 404 is a failed admission. Without the refusal the Harness would seat a new conversation, and
-  a model on an empty context would read "continue your task" with no task. On the refusal the Turn takes the path of a
-  lost conversation. The re-admission is admitted as a Turn, with the task after the re-admit text and the notice that
-  the conversation is new, or faults when it has no task to send. A continued Turn is told that its conversation is new,
-  and is admitted again. A nudge or a wake is admitted again as a Turn: its prompt is the task alone, because nothing
-  was cut, with the notice that the conversation is new and every notice in scope. Every notice that the Turn's
-  admissions carried is pending again first, as for a lost conversation after a cut. With no task to send, the Turn
-  faults. The Instance Harness's restart is on no watch, so this refusal is the only way a nudge or a wake learns of it.
-  What the Turn's admissions carried, and whether the Harness read their surface, is kept in the Orchestrator's memory
-  alone: after a restore of the Orchestrator before a surface read, nothing is raised again. A fresh Turn's "this
-  conversation is new", which rides an admission alone, is carried again by the next re-admission when the Harness has
-  not read the one before.
+  restart after it does not. A notice at a step boundary has no admission. The surface read of the open Turn reserves it
+  for that member, and it counts as delivered, and heard, when the Harness acknowledges the append. When the Turn ends
+  with no acknowledgment, the reservation is released, and the notice is pending again for that member. A reservation
+  lives in the Orchestrator's memory only, so a restart forgets it: the notice is pending again, and the next read or
+  admission carries it. So a conversation can hear a notice twice after a crash, as for an admission. Delivered is not
+  yet heard: if the Orchestrator ends the Turn before the Harness reads its surface, the Harness never prompts it
+  (ADR-0026), so the Orchestrator raises that admission's notices again. This holds for a nudge and a wake too: each one
+  must have its surface read again before its notices count as heard. An admission that fails leaves the earlier
+  admission's notices heard. A nudge and a wake re-prompt the Turn within itself. Of the notices, they take only the
+  guard kills of the list that come after the newest kill whose `told` names their conversation. That `bash` answer told
+  the Agent that all its processes died, so it covers every kill up to it. They also take no kill from before the Turn
+  started. Such a kill would tell the Agent that processes it started in this Turn died. The Turn's first read of the
+  list sets its mark: the id of the newest kill it saw, or "none". The mark is ledgered with every admission of the
+  Turn, and a restore reads it back, so a nudge or a wake takes only kills after it. Only when the first read failed is
+  the Turn's start the mark, ledgered the same way, with one second allowed for a pod clock that runs behind. A read
+  that failed is "could not tell", never an empty list, so it sets no mark. The kills they do not take stay pending for
+  the next Turn. The re-admission after a Harness restart cut the Turn continues the same Turn, so it takes every notice
+  in scope except the guard kills that this rule leaves out. When its read could not tell, it takes no guard kill at
+  all, as a nudge then takes none: it cannot know which kills its own `bash` reported. The notices that the Turn's
+  admissions carried since the Harness last read the Turn's surface are pending again first, each with the source it was
+  raised with, and this re-admission carries them whatever else its scope leaves out. A notice with no source merges
+  only into a pending one with no source, so an equal notice of another kill never takes its place. When such an unread
+  admission carried the Turn's task, the task follows the re-admit text. When the rebuilt Harness lost the conversation,
+  nothing of the Turn is left: every notice that the Turn's admissions carried is pending again whatever the surface
+  reads said, the re-admission takes every notice in scope, as a Turn's admission does, and the Turn's task follows the
+  re-admit text. It says once that the conversation is new. A restore drops the prompt from a Turn's input, so the task
+  rides the ledgered admission too; a lost conversation with no task to send faults the Turn instead. Whether the
+  Harness still holds the conversation is asked again for up to 30 seconds while the new container does not listen yet
+  or drains, and only then is the answer taken as "held". The continue path asks the same way, so a continued Turn after
+  a restart can wait up to 30 seconds before its admission. A Harness in CrashLoopBackOff can take longer than that: the
+  answer is then "held", and it can be wrong. So every admission to a conversation that the Harness was taken to keep
+  says so with `kept: true`: the re-admission after a cut, a continued Turn, and a nudge or a wake. A Harness that keeps
+  no such conversation refuses it with 404 and `kept: false` in the body, and seats none. The Orchestrator takes only
+  that 404 as the refusal; another 404 is a failed admission. Without the refusal the Harness would seat a new
+  conversation, and a model on an empty context would read "continue your task" with no task. On the refusal the Turn
+  takes the path of a lost conversation. The re-admission is admitted as a Turn, with the task after the re-admit text
+  and the notice that the conversation is new, or faults when it has no task to send. A continued Turn is told that its
+  conversation is new, and is admitted again. A nudge or a wake is admitted again as a Turn: its prompt is the task
+  alone, because nothing was cut, with the notice that the conversation is new and every notice in scope. Every notice
+  that the Turn's admissions carried is pending again first, as for a lost conversation after a cut. With no task to
+  send, the Turn faults. The Instance Harness's restart is on no watch, so this refusal is the only way a nudge or a
+  wake learns of it. What the Turn's admissions carried, and whether the Harness read their surface, is kept in the
+  Orchestrator's memory alone: after a restore of the Orchestrator before a surface read, nothing is raised again. A
+  fresh Turn's "this conversation is new", which rides an admission alone, is carried again by the next re-admission
+  when the Harness has not read the one before.
 
-  A continued Turn of the same conversation is told, as a notice, a kill that its own `bash` call answered in an earlier
-  Turn. The Agent reads that kill twice, which is true and costs little. The `told` rule could later extend to the first
-  admission of a continued Turn too; it does not now, because a fresh Turn's conversation holds no earlier answer, and
-  the rule would then need the conversation in the ledger's scope.
+  A conversation whose own `bash` call answered a kill is not in that kill's audience, so it does not hear the kill
+  again as a notice, at its next Turn or at a step boundary.
 
 - **The Harness writes every word.** The admit body carries typed notices
   (`notices: [{ kind: "memory-limit", scope, agent?, limit?, peak? } | { kind: "conversation-new", reason } | { kind: "pick-answer", pick, cut, answer?, stopped? } …]`,
@@ -209,4 +232,8 @@ whose processes are gone, with no way to know why.
 - The Briefing is how a Turn learns its Allowed picks: the tools block is the whole Menu, fixed for a conversation so it
   does not break the cache
   ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)).
+- A Workspace notice reaches each conversation that was there for the kill, and the retry of the Turn that it cut; an
+  open Turn hears it at its next step boundary, not only at its next admission (ADR-0002,
+  [ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). So a memory kill reaches
+  every coder of a Pool that shares one Workspace (ADR-0075).
 - GLOSSARY.md gains **Briefing**.