@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/reference/decisions/0002-duplex-streaming-actor.md

@@ -16,21 +16,28 @@ action observably occurred only post-approval.
 
 The split-channel model:
 
-| Direction | Kind                                                      | Mechanism                                |
-| --------- | --------------------------------------------------------- | ---------------------------------------- |
-| up        | control / decision (the workflow's events, ADR-0011)      | Menu tool call → Custodian → delivery    |
-| up        | progress / telemetry (tokens, attempts, "still working")  | Harness stream (lossy, observation-only) |
-| down      | the next turn's prompt (feedback, steering at a boundary) | a new submission on the same iid         |
-| down      | the Turn part, restated (the Allowed picks changed)       | the Harness's read at each step boundary |
-| down      | interrupts (deliberate terminal cancel)                   | `abort` on the wire                      |
+| Direction | Kind                                                           | Mechanism                                     |
+| --------- | -------------------------------------------------------------- | --------------------------------------------- |
+| up        | control / decision (the workflow's events, ADR-0011)           | Menu tool call → Custodian → delivery         |
+| up        | progress / telemetry (tokens, attempts, "still working")       | Harness stream (lossy, observation-only)      |
+| down      | the next turn's prompt (feedback, steering at a boundary)      | a new submission on the same iid              |
+| down      | the Turn part, restated (the Allowed picks changed)            | the Harness's read at each step boundary      |
+| down      | a jr2 notice (a memory kill, ADR-0062), typed, to its audience | the same step-boundary read, per conversation |
+| down      | interrupts (deliberate terminal cancel)                        | `abort` on the wire                           |
 
 Tool calls are Agent-initiated, so the Machine speaks inside a Turn only as an answer. The one exception is the
 **restated Turn part**: when something other than the Agent's own pick changes its Allowed picks — a Gate's answer, an
 outside event — the Harness learns it by reading the surface at each step boundary and appends the new list
 ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). It is a pull, not a push:
-nothing new reaches the Harness, and what is restated is fixed text plus Menu names. The residual hard case is
-**unsolicited mid-turn steering** — free text from the Machine to an Agent that has not asked. That remains unsolved,
-and it is the only behavior in that bucket, not a dependency of the whole control plane.
+the Harness asks at a step boundary, and nothing reaches it that it did not ask for. What is restated is fixed text plus
+Menu names. jr2's own **typed notices** ride that same step-boundary read: the read of an open Turn returns its
+conversation's pending notices, the Harness appends them, and its acknowledgment of the append delivers them. So a
+running Agent hears a fact the mechanism knows — a memory kill above all — without an interrupt. A notice is typed data,
+and the Harness words it ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). The residual case is
+**free-text human steering** — arbitrary text from a human Caller to an Agent that has not asked. jr2 reserves it for v1
+on this same channel, authenticated as a Caller ([ADR-0011](0011-workflow-defined-events.md)) rather than by a
+Sandbox-scoped credential; its sender and authorization are designed with the Caller. It is one behavior, not a
+dependency of the whole control plane.
 
 ## Durability: the admission is the handle
 

package/docs/reference/decisions/0004-worktree-provisioning-model.md

@@ -91,34 +91,40 @@ fast setup.
 
 ## Where setup runs
 
-Worktree provisioning is a post-`Ready` step owned by the Orchestrator: the Sandbox CRD names repositories by identity
-so the operator can place and mount them, but it knows nothing about clones or worktrees (ADR-0001, ADR-0051).
-`workspace()`'s attach is one idempotent in-pod script the Harness runs on `POST /attach` (ADR-0012,
-[ADR-0063](0063-the-orchestrator-watches-the-cluster.md)), once `Ready` says every cache is present and fetched.
+The clone is a post-`Ready` step owned by the Orchestrator: the Sandbox CRD names repositories by identity so the
+operator can place and mount them, but it knows nothing about clones or worktrees (ADR-0001, ADR-0051). `workspace()`'s
+attach is one idempotent in-pod script the Harness runs on `POST /attach` (ADR-0012,
+[ADR-0063](0063-the-orchestrator-watches-the-cluster.md)), once `Ready` says every cache is present and fetched. The
+attach only clones. A Machine cuts each Worktree with the kit Effect `worktree()`
+([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
 
 ## In-Sandbox layout: worktrees off the per-Sandbox clone (gwtmux convention)
 
 "Not a shared worktree" above means _not a worktree off a fleet-shared `.git`_. **Inside** a Sandbox, worktrees are the
-intended ergonomic — taken off the Sandbox's **own** clone. The per-Sandbox clone _is_ the `default/`, and branch
-working trees are its siblings, matching the layout [gwtmux](https://github.com/snapwich/gwtmux) already expects, under
-the slot the Machine gave the repository (ADR-0051):
+intended ergonomic — taken off the Sandbox's **own** clone. The per-Sandbox clone _is_ the `default/`, and the Worktrees
+are its siblings, matching the layout [gwtmux](https://github.com/snapwich/gwtmux) already expects, under the slot the
+Machine gave the repository (ADR-0051):
 
 ```
-/work/<slot>/default/        the per-Sandbox `git clone --shared` (holds the pod-local .git; the default branch checked out)
-/work/<slot>/<branch>/        `git worktree add` siblings, one per branch worked
+/work/<slot>/default/        the per-Sandbox `git clone --shared` (holds the pod-local .git; stays on the Binding's base)
+/work/<slot>/<name>/         `git worktree add` siblings: folders a Machine cuts, each with one branch or one commit
 ```
 
 Because the layout is identical to the one used outside the cluster, existing worktree tooling works **unchanged** when
-you exec into a Sandbox. Object resolution falls through: a branch worktree shares the per-Sandbox `default/.git`, whose
+you exec into a Sandbox. Object resolution falls through: a Worktree shares the per-Sandbox `default/.git`, whose
 alternates point at the read-only cache — existing objects are read from the cache, new commits land in the pod-local
-`.git`. `default/` is a checkout of the Repo's default branch, as gwtmux's `default/` is outside the cluster: work
-happens in the branch worktrees, and `default/` is the reference tree a human or a tool finds where it expects one. Not
-`--no-checkout`: an empty working tree reads as every tracked file deleted to `git status`, which misleads an Agent that
-looks. The branch name `default` is refused by the spec guard: the branch Worktree is a sibling of that directory, never
-it. `origin`'s push url is the binding's own spelling, so a Machine that bound over ssh pushes over ssh even when the
-cache was cloned over https.
-
-This does **not** reintroduce jr's contention: the shared `.git` here is _per-Sandbox_, and it is accessed serially
-under the standing invariant that **one Agent runs at a time per Workspace** — structural since ADR-0012 (one sequential
-body per workspace). A Machine that runs concurrent Agents in one Sandbox, or an Agent that spawns parallel git-touching
-subagents, reintroduces contention (pod-scoped, not fleet-wide) and must opt into separate Sandboxes instead.
+`.git`. `default/` stays on the Binding's base: a branch is attached, a tag or a commit is detached, and with no base it
+is the Repo's default branch, as gwtmux's `default/` is outside the cluster. No work happens in it: work happens in the
+Worktrees, and `default/` is the reference tree that a human, a tool or an Agent that only reads finds where it expects
+one. Not `--no-checkout`: an empty working tree reads as every tracked file deleted to `git status`, which misleads an
+Agent that looks. A Worktree's folder cannot be named `default`, and a cut of the branch that `default/` holds is
+`refused`, with a reason that names `/work/<slot>/default`. `origin`'s push url is the binding's own spelling, so a
+Machine that bound over ssh pushes over ssh even when the cache was cloned over https.
+
+This does **not** reintroduce jr's contention: the shared `.git` here is _per-Sandbox_, so what contends stays in one
+pod and never crosses the fleet. Inside the pod it is the author's choice. A Machine that runs concurrent Agents in
+Worktrees of one clone, or an Agent that spawns parallel git-touching subagents, takes that contention, and a Machine
+that does not want it uses separate Sandboxes. Two things keep one clone safe to share. The attach sets `gc.auto=0` and
+`maintenance.auto=false` in the clone, because a `gc` beside a cut or a commit can prune what another Worktree needs.
+And all Worktrees of a clone share `refs/remotes/origin/*`, so `jr2-upload-pack` holds a per-clone lock for each fetch
+(ADR-0053, ADR-0075).

package/docs/reference/decisions/0005-sandbox-pod-composition.md

@@ -6,14 +6,20 @@ A Sandbox pod composes up to four containers around one shared worktree volume (
   [ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)) with jr2's runtime mounted at
   `/opt/jr2` and the command overridden to start the Harness. The Agent's toolchain lives here because the Working tools
   (read/write/edit/bash) execute here — the tools the Agent can reach are this image's. It is also where a human
-  `kubectl exec`s to inspect a run with the agent's exact tools, worktrees, and filesystem.
+  `kubectl exec`s to inspect a run with the agent's exact tools, worktrees, and filesystem. One Harness container serves
+  every workspace-ful Agent of the Sandbox. Each process that the Harness starts in `/work` — a Working tool's shell, a
+  test, git, a `command` Effect — runs as a confined child of the Harness process, so no code from `/work` reaches the
+  control credential that the Harness process holds
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
 - **Custodian container** — jr2-composed sidecar, upstream Envoy configured at provision by the Orchestrator
   ([ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md),
   [ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): the pod's credential holder. It holds
   the Sandbox token and the held secrets its pod names — model API keys above all — as files, and carries the Harness's
   traffic out: its Menu and the ask to the Orchestrator, and its outbound HTTPS. It exists as a separate container
   precisely _because_ the Working tools give the Agent code execution in the Harness container — the credentials live
-  where the Agent cannot read them, and the Harness container's env holds only their Stand-ins.
+  where the Agent cannot read them, and the Harness container holds only their Stand-ins, which are secret: only the
+  Harness process holds them, as files, and a process it confines gets only those that its `workspace()` grants
+  (ADR-0059, ADR-0076).
 - **User Container** — opt-in third seat, composed only when the `workspace()` names its image (a `file:` docker context
   the Machine ships or a registry ref, the same resolution as the Sandbox Image, no default —
   [ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)). The authoring surface is that string —
@@ -63,8 +69,8 @@ What each container mounts of the credentials, stated once:
 
 | Container   | Mounts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `harness`   | `jr2-ca` at `/etc/jr2/ca` (the trust bundles). None of the Custodian's volumes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `custodian` | its values (the Sandbox token, its pod's `jr2-held-secrets-<pod>`, each user `secretKeyRef` its pod names) at `/etc/jr2/custodian/values`; its leaves (`jr2-held-tls`); its pod's config (its own `<sandbox>-custodian`, and `program.lua` from `jr2-held`); `upstream.crt`.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `harness`   | `jr2-ca` at `/etc/jr2/ca` (the trust bundles); the Stand-ins — the control one and each held secret's — as files under `/run/jr2/` that only the Harness process reads and no process it confines can (ADR-0059, ADR-0076); no Stand-in is in its env. None of the Custodian's volumes.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `custodian` | its values (the Sandbox's control token and fetch token, its pod's `jr2-held-secrets-<pod>`, each user `secretKeyRef` its pod names) at `/etc/jr2/custodian/values`; its leaves (`jr2-held-tls`); its pod's config (its own `<sandbox>-custodian`, and `program.lua` from `jr2-held`); `upstream.crt`.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `user`      | the checkouts' three volumes, and nothing else.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `effector`  | `/work`, `/repos/<key>` and `/opt/jr2` read-only; at `/run/jr2/secrets` (0400) the secrets its Effects name — its pod's `jr2-effector-<pod>` literals, each user `secretKeyRef` by reference — and at `@git/<name>/` each `git.credentials` entry's push Secret the Sandbox CR names (`gitCredentials`), which the operator projects from that entry's Secret by reference into this container alone (`@` is no character of a secret's name, so no secret's file takes that directory); at `/run/jr2/effector` its key (its own `<sandbox>-effector`) and `effector.json`; an emptyDir at `/run/jr2/scratch` as `$HOME`; at `/etc/jr2/effector-ca`, read-only, the instance's caBundle ConfigMap when the instance ships one (ADR-0020). |
 
@@ -98,12 +104,13 @@ jr2 sets `runAsUser` nowhere — each image's own `USER` decides its seat's uid
 and plain POSIX modes would then make the other seat's files read-only. jr2 closes that with two mechanisms it happens
 to own, unconditionally (both are inert when the uids already match):
 
-- **The pod carries `fsGroup` — the work group, default `2000`.** The default is convention; the one override lives on
-  the `WorkspaceSpec` (`workGroup?: number`, beside `image` and `user` — pod composition is the spec's business,
-  ADR-0037), for the image whose session users already hold a gid of their own. Never a config key. Any value is safe
-  for the jr2 seats: Kubernetes grants the fsGroup as a supplemental group to every container process, so the Harness
-  writes `/work` whatever the number, and no image's `/etc/group` needs to know it. fsGroup puts a setgid group on
-  `/work`'s root, and setgid propagates down, so everything either seat creates is group-_owned_ by the work group.
+- **The pod carries `fsGroup` — the work group, default `2000`.** The default is convention; the one override is an
+  option of `workspace()` (`workspace(body, { workGroup: 2000 })`, beside `image` and `user` — pod composition is the
+  wrapper's business, ADR-0037), for the image whose session users already hold a gid of their own. Never a config key.
+  Any value is safe for the jr2 seats: Kubernetes grants the fsGroup as a supplemental group to every container process,
+  so the Harness writes `/work` whatever the number, and no image's `/etc/group` needs to know it. fsGroup puts a setgid
+  group on `/work`'s root, and setgid propagates down, so everything either seat creates is group-_owned_ by the work
+  group.
 - **The attach stamps a default ACL on every repo root it creates** — `u::rwx,g::rwx,o::r-x`, set by `work-acl`, a
   static helper on the runtime volume (part of ADR-0037's published `/opt/jr2` surface, static for the same reason `rg`
   is: it executes on a libc jr2 does not control). A default ACL is inherited by everything created beneath it, and
@@ -116,16 +123,16 @@ to own, unconditionally (both are inert when the uids already match):
 Group _membership_ is the one thing an image can still owe. `kubectl exec` sessions and a non-root sshd's logins hold
 the work group automatically — both inherit the container's supplemental groups, where Kubernetes put the fsGroup. A
 **root** sshd is the exception: the logins it setuids rebuild their groups from `/etc/group`, so that image puts its
-session user in the work group itself (`groupadd -g 2000 work && usermod -aG work <user>`) — or the spec points
+session user in the work group itself (`groupadd -g 2000 work && usermod -aG work <user>`) — or the `workspace()` points
 `workGroup` at a gid its users already hold.
 
 **The promise is scoped to repo trees.** An ad-hoc path at `/work`'s top level — either seat's `mkdir /work/scratch` —
 carries no default ACL, so files there fall back to the writer's umask. The Harness runs at `umask 002` (itself and
 every tool child) and the attach script opens with the same line, so jr2's own writes are group-writable even there;
 what a User Container session writes outside a repo tree is its own business. A Workspace with no Repo Slot (ADR-0051)
-has no repo tree: its steps share `/work` itself, every Agent and `command` of it in the one Harness container as one
-uid, so they need no ACL; a User Container's writes there have this paragraph's limit, until a user of that seat needs
-more.
+has no repo tree: its steps share `/work` itself, every Agent and `command` of it at the one uid in the one Harness
+container, so they need no ACL; a User Container's writes there have this paragraph's limit, until a user of that seat
+needs more.
 
 ## Constraints on the seat
 
@@ -134,8 +141,8 @@ The seat is zero-_contract_, not zero-_physics_. What an image brought here must
 - **The entrypoint must block.** The pod's restart policy restarts an exited container, so a `CMD` that finishes
   crash-loops. Run a long-lived process — an sshd, an IDE server, `sleep infinity` at minimum.
 - **The ports of jr2's seats are taken** — one network namespace: `:8080` (the Harness), the Custodian's
-  `127.0.0.1:8081` (control), `127.0.0.1:15001` (egress) and `:15021` (health), and `:8082` (the Sandbox Effector, in a
-  pod that has one). Everything else is the image's. A process that binds `:8082` while the Sandbox Effector is down
+  `127.0.0.1:8081` (the fetch), `127.0.0.1:15001` (egress) and `:15021` (health), and `:8082` (the Sandbox Effector, in
+  a pod that has one). Everything else is the image's. A process that binds `:8082` while the Sandbox Effector is down
   gets signed requests it can neither forge nor answer (ADR-0068): the Effect fails closed.
 - **Root is allowed.** The hardened security context (non-root, all capabilities dropped, no escalation) applies to the
   seats jr2 owns — Harness, Custodian and Sandbox Effector, per container — and deliberately not here: the seat's
@@ -162,7 +169,10 @@ namespace, node, and the worktree volume, and are one trust domain in every isol
 container edge does provide is **credential visibility** — the asymmetry ADR-0013 builds on: the Agent executes code in
 the Harness container and none in the others, so a secret that exists only in another container's mount namespace is out
 of its reach. That is why the Custodian holds the Orchestrator credential and the model keys, and it is what the User
-Container offers a human session — with its edges stated plainly:
+Container offers a human session. Inside the Harness container, a second edge holds the one credential the Harness keeps
+itself, the control Stand-in: the Harness process is jr2's code, and each process it starts in `/work` is confined from
+that Stand-in by Landlock (ADR-0076, [ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)). The edges, stated
+plainly:
 
 - It holds only for what stays in the private filesystem or session. Anything on `/work` or listening on `localhost` is
   shared with the Agent — the pod has one network namespace. The Custodian's listeners are on `localhost` too; what they
@@ -206,8 +216,8 @@ Container offers a human session — with its edges stated plainly:
 
 - The generic `Sandbox` CRD composes all of this as plain container specs
   ([ADR-0001](0001-operator-owned-generic-sandbox.md) holds — the operator stays agent-agnostic); the Orchestrator's
-  `kubectlSandbox` supplies the images. The pod runs two containers, plus `user` when the spec names one and `effector`
-  when an Effect is placed there.
+  `kubectlSandbox` supplies the images. The pod runs two containers, plus `user` when the `workspace()` names one and
+  `effector` when an Effect is placed there.
 - Every container but the Sandbox Effector carries a limit from the Workspace's Size (ADR-0060): the Custodian a fixed
   kit slice, the User Container its split if stated, the Harness the rest. The Sandbox Effector carries no limit of its
   own: like a User Container with no split, it shares the pod's Size ceiling — the whole Size, as pod-level resources —

package/docs/reference/decisions/0006-agent-control-surface.md

@@ -42,6 +42,9 @@ is the only structured channel. Consequences:
 
 ## Residual
 
-Unsolicited mid-turn steering remains the hard case (ADR-0002): the menu only opens when the Agent reaches a checkpoint
-or a turn boundary. Evidence for the findings above: `poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md`
-(`poc/` is gitignored; conclusions live here).
+jr2's own typed notices now reach a running Agent through the step-boundary read (ADR-0002,
+[ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)); the Menu still opens only when the Agent
+reaches a checkpoint or a turn boundary. Free-text human steering is the remaining case, reserved for v1 as a
+Caller-authenticated message on the same channel (ADR-0002, [ADR-0011](0011-workflow-defined-events.md)). Evidence for
+the findings above: `poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md` (`poc/` is gitignored; conclusions
+live here).

package/docs/reference/decisions/0012-workspace-wrapper-machine.md

@@ -1,15 +1,15 @@
 # `workspace()` wraps a body Machine and owns only Sandbox lifecycle
 
 jr2 provides Workspaces as a helper so workflows never provision Sandboxes themselves:
-`workspace(body, { input, repos, spec })` is a statically-imported factory (per
-[ADR-0011](0011-workflow-defined-events.md)'s import doctrine) returning a Machine that provisions a Sandbox and its
-worktrees, runs the author's **body** Machine inside it, and tears the Sandbox down when the body finishes. This makes
-GLOSSARY.md's "Workspace = child Machine bound to a unit of work" concrete.
+`workspace(body, { input, repos })` is a statically-imported factory (per [ADR-0011](0011-workflow-defined-events.md)'s
+import doctrine) returning a Machine that provisions a Sandbox and clones its Repos, runs the author's **body** Machine
+inside it, and tears the Sandbox down when the body finishes. This makes GLOSSARY.md's "Workspace = child Machine bound
+to a unit of work" concrete.
 
 ```
 placing:       create Sandbox CR → await the pod scheduled, no deadline (ADR-0064)
-provisioning:  await phase: Ready (watched, ADR-0063) → Harness /attach repos/worktrees (ADR-0004)
-running:       invoke body; input = parent input + { workspace: { repos, branch } }
+provisioning:  await phase: Ready (watched, ADR-0063) → Harness /attach repos (ADR-0004)
+running:       invoke body; input = parent input + { workspace: { repos } }
 teardown:      destroy the CR
 done:          final; workspace output = body output
 ```
@@ -25,29 +25,29 @@ already is. When the guarantee still fails (`kill -9`, hard cancel), the operato
 (ADR-0001) — the reason ADR-0001 made the CR the durable desired state. Author-assembled provisioning/cleanup states
 (the obvious alternative) put the guarantee in every workflow's hands to forget, on every error path.
 
-## Boundary: the spec speaks workspace vocabulary only
+## Boundary: the options speak workspace vocabulary only
 
-The spec — `{ branch, workGroup?, reviewSha? }` — is mapped from the parent's context by the author, but its _shape_ is
-workspace-domain: the branch to cut, and what the attach needs to cut it. The branch itself is the author's: its name
-and its granularity (per feature, per task, from a ticket, from run input) are the Machine's policy, not jr2's; the
-workspace only cuts it. Which Repos to attach is not per-run at all: they are slots on the wrapper's options
+The wrapper's options are workspace-domain. Which Repos to attach is not per-run at all: they are slots on the options
 (`repos: { target: open, docs: { url, ref } }`, ADR-0051), static so `jr2 up` can see them, each bound by the Machine,
-by a composer's `customize`, or by a mapper over the door. Workflow configuration (review rounds, budgets, ticket data)
-passes through to the body untouched; the workspace never sees it. In return the body gets what it needs to operate
-inside the Sandbox: `{ repos: Record<slot, path>, branch }`, the handles keyed by the slots the wrapper declared, in
-declaration order. No handle names a primary checkout: which tree an Agent works in is a fact about that Agent's Turn,
-which the body states (ADR-0051). The Harness `endpoint` and the Sandbox name are mechanism-facing, not body-facing —
-`agentRun` resolves them **ambiently** from the enclosing wrapper (a registrar actor co-invoked in `running`, ADR-0016),
-so the body cannot mis-thread them. Keeping this boundary is what lets one helper serve any workflow rather than
-coupling to coding-shaped ones.
+by a composer's `customize`, or by a mapper over the door. The Workspace only clones. A branch and a Worktree are the
+body's: their names and their granularity (per feature, per task, from a ticket, from run input) are the Machine's
+policy, not jr2's, and the body cuts each Worktree with `worktree()`
+([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)). Workflow configuration (review rounds,
+budgets, ticket data) passes through to the body untouched; the workspace never sees it. In return the body gets what it
+needs to operate inside the Sandbox: `{ repos: Record<slot, path> }`, the handles keyed by the slots the wrapper
+declared, in declaration order. A handle is the slot's folder, `/work/<slot>`, and not a Worktree. No handle names a
+primary checkout: which tree an Agent works in is a fact about that Agent's Turn, which the body states (ADR-0051). The
+Harness `endpoint` and the Sandbox name are mechanism-facing, not body-facing — `agentRun` resolves them **ambiently**
+from the enclosing wrapper (a registrar actor co-invoked in `running`, ADR-0016), so the body cannot mis-thread them.
+Keeping this boundary is what lets one helper serve any workflow rather than coupling to coding-shaped ones.
 
-The wrapper's `input` beside it is the door the spec maps FROM — the wrapper's own declared run-input schema, which also
-types the mapping ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)). It sits on the wrapper and not on
-the body precisely because of the injection above: the body's input is the door plus `workspace`, which no caller sends.
-That same composition is what the door checks the body against, one way only — the body may not demand more than the
-wrapper hands it; demanding less is safe — so the injection is a compile-time contract, not just a comment. The host's
-own injection into a root machine's input (`instanceId`) counts as handed over for that check, because whether it
-actually reaches this body depends on where the wrapper sits and no type can see that
+The wrapper's `input` is its door — the wrapper's own declared run-input schema, which also types a per-run slot's
+mapper ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)). It sits on the wrapper and not on the body
+precisely because of the injection above: the body's input is the door plus `workspace`, which no caller sends. That
+same composition is what the door checks the body against, one way only — the body may not demand more than the wrapper
+hands it; demanding less is safe — so the injection is a compile-time contract, not just a comment. The host's own
+injection into a root machine's input (`instanceId`) counts as handed over for that check, because whether it actually
+reaches this body depends on where the wrapper sits and no type can see that
 ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)).
 
 ## An Effect runs in its Workspace: the Harness container or the Sandbox Effector
@@ -58,8 +58,8 @@ Worktree file and a `command` that names a secret run in that Workspace's Sandbo
 container ([ADR-0005](0005-sandbox-pod-composition.md),
 [ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), which the provision adds only when an
 Effect below the `workspace()` is placed there; its image is the Sandbox Image unless the `workspace()` names
-`effector: { image }`. Each one's Worktree follows the Turn's rule (ADR-0057): the one Repo Slot's, or the slot it names
-with `slot`; a Workspace with several and none named refuses it. A push goes to that slot's Binding, and after every
+`effector: { image }`. Each one's Worktree follows the Turn's rule (ADR-0057): its input names it, and under Repo Slots
+it must. A push goes to the Binding of its Repo Slot, the one slot or the one its static `slot` names, and after every
 push whose published commit is not the Agent's own — signed copies, or one squashed commit, signed or not — the
 Workspace's Harness moves the Agent's branch to the published commits (the sync, ADR-0067). An Effect of these kinds
 outside any `workspace()` is refused at invoke, as an error, never as output. A `command` that names a secret runs
@@ -86,8 +86,8 @@ the same contract as a temp directory.
 
 ## Consequences
 
-- ADR-0004's single-active-Agent-per-Workspace invariant becomes structural: one sequential body per workspace, no lock
-  machinery.
+- The body chooses how many Agents work in its Workspace (ADR-0004, ADR-0075). The wrapper has no lock machinery for
+  them.
 - The workspace labels the CR with its run (`jr2.dev/run`, `jr2.dev/workflow`), which is what `jr2 ls` groups by
   (ADR-0009).
 - **Lost workspace: the wrapper emits, the body decides.** While the body runs, a lease actor beside it renews the

package/docs/reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md

@@ -25,16 +25,21 @@ is needed either (ADR-0006).
 ## Decision
 
 - **The Custodian carries the Agent's Menu, and holds the credential that makes it work.** It is a jr2-composed
-  container in every Harness pod ([ADR-0005](0005-sandbox-pod-composition.md)). The Sandbox token is mounted into it as
-  a file, and into no other container. The Harness container holds the token's Stand-in,
-  `JR2_SANDBOX_TOKEN=jr2-held-JR2_SANDBOX_TOKEN`, and reaches the Orchestrator only through the Custodian's control
-  listener on `127.0.0.1:8081`. The Custodian forwards four routes, with the token put in place of the Stand-in, and
-  answers every other route itself:
+  container in every Harness pod ([ADR-0005](0005-sandbox-pod-composition.md)). A Sandbox has two tokens, its **Sandbox
+  tokens**: the **control token** and the **fetch token**, mounted into the Custodian as files, and into no other
+  container. The Harness process holds the control token's Stand-in, which is secret: a file that no process it confines
+  can read, in no child's env
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). The fetch token's Stand-in
+  is public, `jr2-held-JR2_SANDBOX_TOKEN`, and `jr2-upload-pack` holds it as a constant. The Harness reaches the
+  Orchestrator only through the Custodian: the agent routes on its control socket, `/run/jr2/custodian/control.sock`,
+  which no confined program can replace (ADR-0076), and the fetch on `127.0.0.1:8081`. The Custodian forwards five
+  routes, with each route's own token put in place of its Stand-in, and answers every other route itself:
 
   ```
   GET  /agents/<iid>/surface          the Menu                            → the Orchestrator
   POST /agents/<iid>/events           a pick                              → the Orchestrator
   GET  /agents/<iid>/deliveries/<id>  an outstanding pick's answer        → the Orchestrator
+  POST /agents/<iid>/notices          a step boundary's notices heard     → the Orchestrator
   POST /fetch                         the ask (ADR-0053), for THIS pod's Sandbox → POST /sandboxes/<name>/fetch
   anything else                       404
   ```
@@ -60,9 +65,10 @@ is needed either (ADR-0006).
   POST /runs/:id/gates/:gate/events    → validate + deliver, or 409                   [Instance token]
 
   # the Agent's, through its pod's Custodian
-  GET  /agents/:iid/surface            → Menu + Allowed picks + schemas + semantics [Sandbox token]
-  POST /agents/:iid/events             → validate + deliver → the receipt, or 409  [Sandbox token]
-  GET  /agents/:iid/deliveries/:id     → an outstanding pick's answer, long-polled [Sandbox token]
+  GET  /agents/:iid/surface            → Menu + Allowed picks + schemas + semantics [control token]
+  POST /agents/:iid/events             → validate + deliver → the receipt, or 409  [control token]
+  GET  /agents/:iid/deliveries/:id     → an outstanding pick's answer, long-polled [control token]
+  POST /agents/:iid/notices            → the notices a step boundary appended, heard (ADR-0062) [control token]
   ```
 
   The receipt is `{ delivered, event, moved, turnComplete, allowed, deliveryId }`. A pick the workflow is still running
@@ -86,11 +92,13 @@ is needed either (ADR-0006).
 - **Bearer tokens, because the boundary is otherwise theater.** The Harness container shares the pod's network
   namespace, so an Agent can `curl` the Orchestrator directly; a per-pod NetworkPolicy cannot distinguish it from the
   Custodian. Only authentication closes this.
-  - **Sandbox token** — minted per Sandbox at provision (a signed Sandbox name, so re-provision after a restart yields
-    the same token), delivered as a Secret mounted into the **Custodian container only**. User `harness.env`/`envFrom`
-    land on the Harness container, never the Custodian. Authorizes exactly: deliver to agent registrations **whose
-    Sandbox is this one**, and ask for this Sandbox's fetch. Never a Gate (they are not on that surface at all), never
-    another Sandbox. The Stand-in the Harness holds is refused on every route.
+  - **Control token and fetch token** — minted per Sandbox at provision (signed names, so re-provision after a restart
+    yields the same tokens), delivered as a Secret mounted into the **Custodian container only**. User
+    `harness.env`/`envFrom` land on the Harness container, never the Custodian. The control token authorizes exactly:
+    read and deliver to agent registrations **whose Sandbox is this one** and whose slot is the slot the Harness states
+    for the conversation (ADR-0076). The fetch token authorizes exactly: ask for this Sandbox's fetch. The Orchestrator
+    accepts each token only on its own routes. Neither reaches a Gate: a Gate refuses every principal of an Agent.
+    Neither reaches another Sandbox. A Stand-in is refused on every route.
   - **Instance token** — the human/CLI credential for Gates and run control. Minted into an in-cluster Secret at
     `jr2 up`; the CLI reads it over the kube API (RBAC is the gate) while port-forwarding the Service (ADR-0019).
   - **The Instance-token door.** The Instance token may also read any Agent's surface and deliver to it —
@@ -98,13 +106,17 @@ is needed either (ADR-0006).
     AS the Agent: it reads the Agent's Menu and Allowed picks and its picks are judged as the Agent's — they carry the
     Agent's sender (ADR-0011) — and no audience filter applies, so it can send a pick no Gate's caller may send
     ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)). It is deliberate — it is how the e2e tier stands in
-    for an Agent — and it adds no party: neither `jr2 send` nor the Console offers it, and a Sandbox token never opens
+    for an Agent — and it adds no party: neither `jr2 send` nor the Console offers it, and a control token never opens
     it for a registration that is not its own.
   - An agent registration records its Sandbox **ambiently**: `agentRun` resolves the enclosing `workspace()` and records
     the same deterministic name the token was minted for (ADR-0016), so forgetting to pass it is unrepresentable (the
     pre-ambient version shipped exactly that footgun: `sandbox` omitted, every tool call 403'd — fail-closed but
     silent). A run-scoped token instead of a Sandbox-scoped one would be genuinely exploitable: derivable iids plus
-    readable ticket ids would let one feature's coder inject a `review_verdict` into another feature's reviewer.
+    readable ticket ids would let one feature's coder inject a `review_verdict` into another feature's reviewer. That
+    holds across Sandboxes, where another feature's Agents are in another pod. Within one Sandbox several Agents can
+    share it ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)); there the Sandbox scope is
+    not enough, and ADR-0076 keeps the control credential where no Workspace code runs, so a coder's code cannot act as
+    the reviewer beside it.
 - **Reachability, narrowed to one caller.** The Orchestrator is always in-cluster (ADR-0019), so the route home is
   simply **Service DNS**, which the pod's maker writes into the Custodian's configuration — the Orchestrator at a
   Sandbox's provision, `jr2 up` for the Instance Harness. The Harness is told the Custodian's loopback address
@@ -140,12 +152,18 @@ is needed either (ADR-0006).
   understanding; the Custodian is exactly that. `kubeSandbox` composes it (plus the token Secret, written right after
   the CR with the CR as its owner from birth, so Kubernetes reaps it with the Sandbox and no path leaks it — ADR-0001).
 - **Nothing in jr2 speaks MCP.** The Orchestrator, the Harness and the CLI carry no MCP dependency.
-- **One container holds the Sandbox token and every model key.** A fault in the Custodian's engine is a fault in the one
-  container that holds both. ADR-0059 records the trade.
+- **One container holds the Sandbox's tokens and every model key.** A fault in the Custodian's engine is a fault in the
+  one container that holds both. ADR-0059 records the trade.
 - **The `@kind` e2e tier owns the pod → Orchestrator leg** — the pod's Harness actually calls its tool through the
   Custodian, so a broken leg is a red test, and a Harness container that posts a pick straight to the Orchestrator with
   the Stand-in it holds is refused. The mechanics tier plays `/agents/:iid/*` from the host, which is honestly
   simulating the Harness's Menu, not an Agent.
+- **Per-agent identity within one Sandbox is ADR-0076.** A Sandbox-scoped credential that an Agent's code could read
+  would let one Agent in a shared Sandbox deliver a pick as another, and ADR-0075 makes a shared Sandbox normal. Only
+  the Harness process holds the control credential, and each process it starts in `/work` runs confined; the Harness
+  states each conversation's slot, and the Orchestrator checks it on the whole `/agents/:iid/*` set. The `@kind` tier
+  gains the sibling cases: a coder's `bash` finds no control credential, and code it plants that the reviewer's own
+  `bash` runs cannot deliver a pick as the reviewer.
 - **NetworkPolicy is a second layer, not the control.** It bounds where a pod may talk; only the token bounds what it
   may _do_. `jr2 up` converges ingress policies that admit only the Orchestrator to a Harness pod
   ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)); the Orchestrator itself is left reachable, because a

package/docs/reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md

@@ -143,8 +143,14 @@ sends there, and every case with the Agent's state at Rest.
 **Load checks on modes and audience.** `createMachine` refuses a registered event that no state handles: it is in no
 derived set, so it is on no Menu and no Gate. It refuses a parallel region below a state that invokes an Agent — the
 Agent's state itself being parallel included, since its regions are below it: the shape is reserved for picks the Agent
-does not wait for, which jr2 does not build, and background work goes above the Agent's state. It warns — the Machine
-stays legal; the doc carries the warning, `jr2 up` prints it and the Console shows it with the seats — about a mode that
+does not wait for, which jr2 does not build, and background work goes above the Agent's state. It refuses one Agent slot
+invoked by two states that can be active together — two parallel regions, one state inside the other, or one state
+twice: a slot is one Agent of the Machine, so its two Turns would have one sender, which `sentBy` cannot tell apart, and
+one conversation, which `continue` cannot give to both. Two Agents at once are two slots (one definition can fill both),
+a child Machine in each region, or a Pool ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
+jr2 refuses this shape and does not support it as a special case, because jr2 can remove a refusal later without
+breaking a Machine, but a refusal that it adds later breaks each Machine that loads now. It warns — the Machine stays
+legal; the doc carries the warning, `jr2 up` prints it and the Console shows it with the seats — about a mode that
 nothing enters (not initial, and no state the Machine can enter has a transition into it or a state inside it — so
 neither the mode's own `initial` nor its transition into itself counts: its picks are on the Menu and never allowed; a
 transition into a history state enters that history state's default target, shallow or deep, or its parent's initial

package/docs/reference/decisions/0016-agent-turn-mechanics-are-internal.md

@@ -21,7 +21,7 @@ restore re-attaches to a Submission whose model is already fixed server-side and
 `agentRun` walks `self._parent` to the nearest registered ancestor. Invoked-actor registration (not an entry action) is
 what makes this restore-safe: invoked actors restart on snapshot restore, entry actions do not. Not under a workspace →
 fail loudly, unless input carries an explicit `endpoint` (the dev-stub, workspace-less path). Body-facing workspace
-handles are `{ repos, branch }` ([ADR-0012](0012-workspace-wrapper-machine.md)).
+handles are `{ repos }`: each is a Repo Slot's folder ([ADR-0012](0012-workspace-wrapper-machine.md)).
 
 **[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)'s token scoping survives and
 strengthens**: the registration records the Sandbox resolved from the enclosing wrapper — the same deterministic
@@ -108,12 +108,14 @@ modes — `continue` governs only what a _new invocation_ means. The author name
 conversation's identity is already on the page. (This corrects the jr-parity exercise's "same iid = jr's resume
 machinery, free" — an inversion of jr's actual semantics.)
 
-Two live invocations of one continued iid — parallel states — are refused at the registration table: one live surface
-per address. A Submission that arrives behind a live one on the Harness queues: prompts for one instance enter one
-per-instance queue in admission order, and a Submission is promoted only when it is the first unsettled one for its
-conversation (ADR-0027 states this as jr2's own semantics). A queued prompt waits behind work that may never finish,
-which is why [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) both ends the turn and orders the
-abort ahead of the next `send`.
+Two live invocations of one continued iid are refused: one live surface per address. The load walk refuses the shape
+that makes them, one Agent slot in two states that can be active together
+([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)), and the registration table refuses a second registration
+of one address as a second guard. A Submission that arrives behind a live one on the Harness queues: prompts for one
+instance enter one per-instance queue in admission order, and a Submission is promoted only when it is the first
+unsettled one for its conversation (ADR-0027 states this as jr2's own semantics). A queued prompt waits behind work that
+may never finish, which is why [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) both ends the
+turn and orders the abort ahead of the next `send`.
 
 The minting doctrine — addresses are computed by jr2, never by the workflow — covers gate ids too: a gate with no
 authored id derives one from its actor path below the run root, through the same walk `mintIid` uses (`actorPath` in

package/docs/reference/decisions/0017-pool-over-a-source-port.md

@@ -22,10 +22,12 @@ outgrowing the pool means hand-rolling without penalty, not fighting a framework
 
 ## The source port is generalized; Work Source is one adapter
 
-The pool draws from a **Source** port — `next(active) → item | null`, plus an optional `wake` event def (webhook /
-`jr2 send` push seam) and `pollEvery` (the set mutates underneath us) — a queue, a generator, or a re-queried set. tk's
-claim actor is one adapter; GLOSSARY.md's **Work Source** reframes as _the Source adapter for tickets_, and the
-Ready-set doctrine (re-query, never materialize) survives as that adapter's semantics, not the primitive's.
+The pool draws from a **Source** port — `next({ active, settled, input }) → item | null`, plus an optional `wake` event
+def (webhook / `jr2 send` push seam) and `pollEvery` (the set mutates underneath us) — a queue, a generator, or a
+re-queried set. `input` is the Pool's input and `settled` holds the ids of the finished and failed items, so a Source
+can fan out over a plan with no state of its own. tk's claim actor is one adapter; GLOSSARY.md's **Work Source**
+reframes as _the Source adapter for tickets_, and the Ready-set doctrine (re-query, never materialize) survives as that
+adapter's semantics, not the primitive's.
 
 A Work Source — `tk`, GitHub issues, Jira, a task queue — is a behavior port, not a canonical data schema: verbs like
 `claimNext`, `updateStatus` and `comment`, each gated by a capability the adapter advertises. It owns the dependency