@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/reference/decisions/0019-one-converging-command-against-the-current-context.md

@@ -45,11 +45,13 @@ loudly narrated, safe to re-run:
   ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). Referenced-but-unmanaged Secrets
   (`envFrom` refs, git credentials) are **preflighted**: `up` fails naming the missing Secret with the exact creation
   hint — converting the `CreateContainerConfigError` hang into an immediate error. Sealed Secrets/External Secrets ride
-  this seam untouched: jr2's contract is "a Secret named X exists", however it got there. A credential the Harness uses
-  is a held secret ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): `up` writes a
-  literal value into `jr2-held-secrets-<pod>` for each pod that names it, which only that pod's Custodian mounts, and
-  checks that a referenced Secret and key exist. Like the signing key, the held-secret CA (`jr2-held-ca`) is kept across
-  converges — minted on first need, never rotated by `up` — because a live pod trusts it.
+  this seam untouched: jr2's contract is "a Secret named X exists", however it got there. `up` also refuses a held
+  secret's name that is a key of an `envFrom` Secret, and names the Secret, the key and the held secret (ADR-0059, R14).
+  A credential the Harness uses is a held secret
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): `up` writes a literal value into
+  `jr2-held-secrets-<pod>` for each pod that names it, which only that pod's Custodian mounts, and checks that a
+  referenced Secret and key exist. Like the signing key, the held-secret CA (`jr2-held-ca`) is kept across converges —
+  minted on first need, never rotated by `up` — because a live pod trusts it.
 - **Repos**: `up`'s walk of the registered Machines collects every bound Repo Slot (ADR-0049, ADR-0051) — to refuse an
   open slot nobody bound, and to see which urls need a key. The Orchestrator creates one `Repo` resource per url at
   boot, and the operator's cache agent clones each onto the nodes that need it (ADR-0004). There is no `repos` config
@@ -59,6 +61,11 @@ loudly narrated, safe to re-run:
   in-cluster deploy keypair (the recommended default, public key printed to register), a local key, or one pasted on
   stdin ([ADR-0047](0047-the-git-ssh-key-source-is-the-users-choice.md)) — declining bails. A personal key never enters
   a cluster silently: only by that explicit, warned choice.
+- **Landlock**: `up` refuses to converge while a Sandbox node lacks Landlock. It reads the pods of the Repo cache
+  agent's DaemonSet, which probe Landlock on each Sandbox node, within the rollout wait it already makes for the cache.
+  It is an ordinary converge failure: it names each node whose agent reports none, the probe's reason, and the fix (keep
+  the node out with `sandbox.nodeSelector` or a taint, ADR-0052, or enable Landlock); a run after the fix converges
+  ([ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)).
 - **Provider preflight**: `up` checks each provider that a carried model names. It checks from inside the cluster, with
   one trivial tool-call completion. An endpoint that the pods cannot reach, a wrong or missing key, or a vLLM without
   `--enable-auto-tool-choice` then fails at converge time, not as `agent.fault` in a run. Reachability is the user's
@@ -75,14 +82,17 @@ loudly narrated, safe to re-run:
     the config, each model's result says why, in words.
   - **The check pod.** It is a Harness pod with no Harness in it. It has a Custodian and the stock Harness image's
     `provider-preflight.ts`. The function that composes the Custodian of every Harness pod composes this Custodian too.
-    Its token is a value that the Orchestrator never signed. `provider-preflight.ts` gets the env of the Harness
-    container: the harness config, `harness.env`, `harness.envFrom`, the Stand-ins, the proxy and the trust. pi resolves
+    Its token is a value that the Orchestrator never signed. Its Stand-ins are secret and its own: `jr2 up` mints them
+    with the signing key, as it does for the Instance Harness
+    ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). The check pod runs no Workspace
+    code, so it may hold them in env. `provider-preflight.ts` gets the env of the Harness container, with the Stand-ins
+    in it: the harness config, `harness.env`, `harness.envFrom`, the Stand-ins, the proxy and the trust. pi resolves
     each model and uses its api, as in a Turn. The `harness.catalog` gateway applies. The key never enters the check
     container, its argv or its log.
   - **Its own objects.** The check pod reads no object of the Instance. `up` writes copies from the values on the host:
     - a ConfigMap with the Custodian's files, the program and the harness config;
     - a ConfigMap with the trust bundles;
-    - a Secret with the token and the literal values of the held secrets;
+    - a Secret with the token, the check pod's Stand-ins and the literal values of the held secrets;
     - a Secret with the leaves;
     - a Secret with the literal `harness.env` values.
 
@@ -194,7 +204,9 @@ loudly narrated, safe to re-run:
   - **A limit.** The check pod has labels of its own. It does not get the labels of a Harness pod: the Instance Harness
     Service selects its pods by label, and would send Turns to the check pod. So a NetworkPolicy that selects Harness
     pods by label does not select the check pod. When such a policy closes the egress of the Harness pods, the check can
-    pass while a Turn fails.
+    pass while a Turn fails. jr2's own egress policy, which closes the cloud metadata addresses
+    ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)), gives the check pod one
+    of its own, so it does not have this limit.
 
 **`jr2 down`** removes the instance from the cluster. It asks for confirmation unless `--yes` is given (for CI). `--all`
 takes the operator too.

package/docs/reference/decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md

@@ -31,7 +31,8 @@ end. And a restarted Harness answered a `continue` with no memory of the convers
   Sandbox goes to the terminal phase **`Lost`**, with the pod's own reason and message (for a deleted pod, the last it
   saw). It never returns to `Pending` and is never given a second pod: `work` is an `emptyDir`, so a new pod could
   continue nothing, and it would hold a whole Size for nobody while hiding the loss. The CR stays, so `jr2 status` can
-  say why, until teardown or the idle GC.
+  say why, until teardown or the idle GC. A Sandbox delete waits for its pod, because a retry can take the name of a pod
+  that is still going away.
 - **The operator judges identity, because it knows which pod it created.** It still publishes `status.podUID`; the
   Orchestrator reads `Lost`, not a UID comparison.
 - **The watch answers; the lease asserts.** The Orchestrator watches its Sandboxes

package/docs/reference/decisions/0023-the-harness-prints-the-conversation.md

@@ -122,10 +122,10 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
 
 - **Per-`agentRun` containers, or a pod per Agent.** Rejected on lifetime before merit: the container list is fixed when
   the CR is created, before the body has run, while `agentRun` is a per-turn invocation. Pre-declaring per _Agent_ is
-  possible but pays N resident copies of a Harness image that deliberately carries the agent toolchain (ADR-0005) to run
-  one at a time. It buys no isolation — containers in a pod share the network namespace, so it does not even fix the
-  port contention that motivates it (ADR-0005:31) — and the git contention it would address is prohibited anyway
-  (ADR-0004:95). What it actually buys is `kubectl logs -c <agent>`: a container, to avoid a prefix.
+  possible but pays N resident copies of a Harness image that deliberately carries the agent toolchain (ADR-0005). It
+  buys no isolation — containers in a pod share the network namespace, so it does not even fix the port contention that
+  motivates it (ADR-0005:31) — and it does not remove the git contention, because the containers share one `/work` and
+  one clone (ADR-0004). What it actually buys is `kubectl logs -c <agent>`: a container, to avoid a prefix.
 - **A trace from the Custodian.** Tempting, and wrong on the facts. The Custodian carries the Menu's reads and the
   Agent's picks — a handful of deliveries per turn — and the model calls, and it logs names only, never a body
   ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). The Agent's working tools execute in
@@ -159,11 +159,10 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
   what it happened to read; what jr2 told it includes an Effect's output, so a `command` Effect's output and a Held
   value echoed into it reach the log as they reach the model, and so does an Effect secret in a form an Effector's scrub
   does not catch (a transformed secret, a partial echo; ADR-0068). Fine on kind; a real decision on a shared cluster.
-- **It depends on an invariant that is documented but not enforced.** One Agent at a time per Workspace (ADR-0004:95,
-  "structural since ADR-0012") is what makes two conversations never interleave on one container's stdout. Nothing
-  refuses a body that invokes concurrent `agentRun`s; such a body corrupts a shared `default/.git` before it garbles a
-  log, so enforcement is owed on its own merits — the ambient registrar (ADR-0012:32, ADR-0016) is the one thing that
-  sees every Agent in a Workspace, and the place to refuse a second concurrent admission.
+- **The conversations of concurrent Agents interleave in one log.** The author chooses how many Agents work in a
+  Workspace ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), so two conversations can
+  print at one time on one container's stdout. The prefix keeps them apart: every line carries its label and its iid, so
+  a reader keeps one conversation's lines by its iid.
 - **Truncation is load-bearing, not cosmetic.** Kubelet rotates container logs at 10Mi by default and drops the
   remainder. jr's filter capped `Bash` at 100 chars and unknown tools at 150 and reduced `Write`/`Edit` to a path; that
   was readability, and it is now also what keeps a long turn inside the window.

package/docs/reference/decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md

@@ -34,8 +34,7 @@ state. A prompt fix cannot be relied on and cannot even be shown to have worked.
 Workspace; the Machine's states are sequential, but the Agents are not. Throughout `reviewing`, the orphaned coder was
 still live in the worktree the reviewer was reviewing — and still live at `humanReview`, the park that deliberately
 retains the Sandbox so a human can exec in and inspect the diff. In the runs we watched, the orphan only read. Nothing
-prevented it writing. An un-ended turn is an unaccounted-for concurrent writer in a Workspace the Machine believes is
-single-threaded.
+prevented it writing. An un-ended turn is a concurrent writer in a Workspace that the Machine did not put there.
 
 ## Decision
 
@@ -190,69 +189,67 @@ single-threaded.
   is local to its Machine: two Machines of one tree, and the workers of a pool, which run one body, may each have a
   child of one id, and one never reads or changes the other's entry. A child started on an event that names no Agent
   anywhere else is no Agent's. The other Agent's pick keeps its default answer, and when the Agent the event names has
-  no pick being answered, it sets nothing. When one Agent slot is invoked in two regions, it shapes the pick at the same
-  invoke as the pick that sent the event or started the child, and nothing otherwise: with both regions' picks being
-  answered, the done event of a child shapes the pick whose invoke started it; a pick in its own send is shaped while
-  the slot's other pick is outstanding; and the done event of a child that one region's pick started after that pick's
-  Turn ended (its child runs on) shapes no pick, while the other region's pick keeps its default answer. When the event
-  names no Agent (a timer, a Gate's answer, an outside send, the done event of a child no Agent's pick started), it
-  shapes the pick in its own send; outside one, it shapes the one such pick outstanding only while one Agent's state is
-  active. Outside a pick's own send, while two Agents' states are active, it sets nothing, whatever is outstanding: the
-  event cannot say whose pick it is. On an entry or an exit below no Agent's state it sets nothing, whatever is
-  outstanding, and the load walk warns, naming the Agent states it could be moved under: an entry or exit there is no
-  transition an Agent's event takes. One action object written in two places runs from each by that place's rule alone,
-  never by their sum: written below two Agents' states, from A's state it shapes only A's pick and from B's only B's;
-  written below A's state and on a transition below none, from A's state it shapes only A's pick and from the transition
-  the pick of the Agent the event names; written on an entry or exit below no Agent's state as well, it sets nothing as
-  that entry or exit. An `answer` that an `enqueueActions` enqueues, at any depth, runs from the place the enqueuing
-  action is written, by that place's rule: enqueued on an entry or exit below no Agent's state it sets nothing, and
-  enqueued below an Agent's state it shapes only that Agent's pick. The load walk cannot see inside an `enqueueActions`,
-  so it does not warn on one enqueued on an entry or exit below no Agent's state. An `answer` that runs while no pick of
-  that Agent is being answered (a state's first entry, a later Turn's re-entry, another Agent's region of a parallel
-  state) sets nothing. A reply comes from a child invoked on an active state below the Agent's state, or from a party
-  whose Gate invoke id or Agent slot is invoked there (its sender, ADR-0015). The events the Machine sent itself (a
-  `raise`, a `sendTo(self)`, a timer) are no reply, and neither is an event from outside that set (a Gate in a sibling
-  region, a root Gate, an outside send), nor a child's error: every outcome of work is its output, and an error is a jr2
-  or config defect, so by default its message never reaches the model. The operator reads it: while a pick is
-  outstanding, an error from a child below the Agent's state goes on the run's feed (`child-error`: the Agent, its pick,
-  the child and the message; Instance-token band, as `fault` is), and `jr2 run` and `jr2 logs` print it. An author who
-  wants the Agent told passes it explicitly: `answer(...)` on the `onError` route (ADR-0067), or an `onError` route to a
-  state whose prompt carries it. With none, the answer carries no reply, and its words say only that ("No reply came
-  back for it"): never that nothing ran, because a timer or an outside event may have stopped work that did run. The
-  pick's `POST` answers at once with `outstanding` and a delivery id, and the Harness long-polls the answer inside the
-  one tool call (ADR-0002, ADR-0013). A child that settles inside the pick's own send — a decision Machine that is final
-  as it starts — replies before the `POST` answers: when that reply leaves the workflow at Rest, or out of the Agent's
-  state, the `POST` itself is the answer, with `answered` and nothing to poll. So is a guard straight back: a pick that
-  enters a state and leaves it again inside its own send (an `always` back), with no reply, leaves the state value as it
-  was, and is answered with `straightBack` — the one answer that says "it moved the workflow, and nothing ran". An
-  outstanding pick's answer never carries it. A pick that changes the state value moved to a mode, and gets the plain
-  receipt with its Allowed picks; a pick with no target went nowhere, and gets the same, as does a pick whose target is
-  the state it was taken in (it enters nothing it leaves). Every receipt that leaves the Turn open (the plain receipt, a
-  guard straight back, and an answered pick back at Rest) ends its state part with the same words, "Your turn is not
-  over.": the plain receipt once said "the workflow is still in the state that asked for this turn, so it is not over
-  yet", and real Haiku 5.5 runs stopped after it, because "it" can be the workflow or the Turn. The refusals and the
-  notices of a cut or unsent pick keep their own words. A route that leaves the Agent's state ends the Turn like any
-  other: the poll reads `turnComplete`, the next state's prompt is the author's, and the answer is a `pick-answer`
-  notice to the Agent that picked: the next Turn of the conversation the picking Turn continued (`continue: true`,
-  ADR-0062). A FRESH picking Turn's conversation is never heard again, and a later continued Turn of the same slot never
-  made the pick, so its answer goes nowhere: the ledger keeps no notice for it. The route of a reply includes the events
-  the Machine sends itself AT ONCE while it runs (a `raise`, or a `sendTo(self)` with no delay, in `onDone` or in the
-  next state's entry): a reply whose route leaves the Agent's state that way is the answer, never stopped. Something
-  other than the route can leave the Agent's state while the pick's work still runs below it — a timer the Machine set
-  (a Turn timeout `after`, a named delay, a delayed `raise` or `sendTo(self)`), an event from outside the states below,
-  a Gate's event, the Agent's own end. The exit stops that work (an invoke is stopped when its state exits), and the
-  answer says so (`stopped`): the poll reads "The workflow left the state that asked for this turn while it ran your
-  pick, and that stopped the pick's work before it finished: your turn is over.", and the next continued Turn's notice
-  reads "Your pick `X` did not finish: the workflow left the state that asked for your last turn while it ran, and that
-  stopped it." Both keep the last reply an earlier link gave, if any, and state it: an earlier link's reply is never
-  dropped because a later link was stopped. The run host tells a fired timer from an event sent at once by the
-  scheduler's own table: it watches what the actor system arms, cancels and fires (`timers.ts`, the same xstate
-  internals as the timer table, ADR-0007). Back at Rest INSIDE the Agent's state — a per-step timeout `after` on the
-  child state that exits the work — the answer is the last reply since the pick, with the Allowed picks; with no reply
-  since the pick, the answer carries none. A restored hold is the Turn of the first registration of its address in the
-  restored tree: a restore that ends that Turn and starts another at the same address before anything settles answers
-  the pick with `turnComplete`. There is no default time bound on a held Turn; the Console shows each outstanding pick
-  "held since".
+  no pick being answered, it sets nothing. One Agent slot can be invoked by two states that are not active together (two
+  states one after the other). Then it shapes the pick at the same invoke as the pick that sent the event or started the
+  child, and nothing otherwise: the done event of a child that the earlier state's pick started, after that pick's Turn
+  ended (its child runs on), shapes no pick, and the later Turn's pick keeps its default answer. When the event names no
+  Agent (a timer, a Gate's answer, an outside send, the done event of a child no Agent's pick started), it shapes the
+  pick in its own send; outside one, it shapes the one such pick outstanding only while one Agent's state is active.
+  Outside a pick's own send, while two Agents' states are active, it sets nothing, whatever is outstanding: the event
+  cannot say whose pick it is. On an entry or an exit below no Agent's state it sets nothing, whatever is outstanding,
+  and the load walk warns, naming the Agent states it could be moved under: an entry or exit there is no transition an
+  Agent's event takes. One action object written in two places runs from each by that place's rule alone, never by their
+  sum: written below two Agents' states, from A's state it shapes only A's pick and from B's only B's; written below A's
+  state and on a transition below none, from A's state it shapes only A's pick and from the transition the pick of the
+  Agent the event names; written on an entry or exit below no Agent's state as well, it sets nothing as that entry or
+  exit. An `answer` that an `enqueueActions` enqueues, at any depth, runs from the place the enqueuing action is
+  written, by that place's rule: enqueued on an entry or exit below no Agent's state it sets nothing, and enqueued below
+  an Agent's state it shapes only that Agent's pick. The load walk cannot see inside an `enqueueActions`, so it does not
+  warn on one enqueued on an entry or exit below no Agent's state. An `answer` that runs while no pick of that Agent is
+  being answered (a state's first entry, a later Turn's re-entry, another Agent's region of a parallel state) sets
+  nothing. A reply comes from a child invoked on an active state below the Agent's state, or from a party whose Gate
+  invoke id or Agent slot is invoked there (its sender, ADR-0015). The events the Machine sent itself (a `raise`, a
+  `sendTo(self)`, a timer) are no reply, and neither is an event from outside that set (a Gate in a sibling region, a
+  root Gate, an outside send), nor a child's error: every outcome of work is its output, and an error is a jr2 or config
+  defect, so by default its message never reaches the model. The operator reads it: while a pick is outstanding, an
+  error from a child below the Agent's state goes on the run's feed (`child-error`: the Agent, its pick, the child and
+  the message; Instance-token band, as `fault` is), and `jr2 run` and `jr2 logs` print it. An author who wants the Agent
+  told passes it explicitly: `answer(...)` on the `onError` route (ADR-0067), or an `onError` route to a state whose
+  prompt carries it. With none, the answer carries no reply, and its words say only that ("No reply came back for it"):
+  never that nothing ran, because a timer or an outside event may have stopped work that did run. The pick's `POST`
+  answers at once with `outstanding` and a delivery id, and the Harness long-polls the answer inside the one tool call
+  (ADR-0002, ADR-0013). A child that settles inside the pick's own send — a decision Machine that is final as it starts
+  — replies before the `POST` answers: when that reply leaves the workflow at Rest, or out of the Agent's state, the
+  `POST` itself is the answer, with `answered` and nothing to poll. So is a guard straight back: a pick that enters a
+  state and leaves it again inside its own send (an `always` back), with no reply, leaves the state value as it was, and
+  is answered with `straightBack` — the one answer that says "it moved the workflow, and nothing ran". An outstanding
+  pick's answer never carries it. A pick that changes the state value moved to a mode, and gets the plain receipt with
+  its Allowed picks; a pick with no target went nowhere, and gets the same, as does a pick whose target is the state it
+  was taken in (it enters nothing it leaves). Every receipt that leaves the Turn open (the plain receipt, a guard
+  straight back, and an answered pick back at Rest) ends its state part with the same words, "Your turn is not over.":
+  the plain receipt once said "the workflow is still in the state that asked for this turn, so it is not over yet", and
+  real Haiku 5.5 runs stopped after it, because "it" can be the workflow or the Turn. The refusals and the notices of a
+  cut or unsent pick keep their own words. A route that leaves the Agent's state ends the Turn like any other: the poll
+  reads `turnComplete`, the next state's prompt is the author's, and the answer is a `pick-answer` notice to the Agent
+  that picked: the next Turn of the conversation the picking Turn continued (`continue: true`, ADR-0062). A FRESH
+  picking Turn's conversation is never heard again, and a later continued Turn of the same slot never made the pick, so
+  its answer goes nowhere: the ledger keeps no notice for it. The route of a reply includes the events the Machine sends
+  itself AT ONCE while it runs (a `raise`, or a `sendTo(self)` with no delay, in `onDone` or in the next state's entry):
+  a reply whose route leaves the Agent's state that way is the answer, never stopped. Something other than the route can
+  leave the Agent's state while the pick's work still runs below it — a timer the Machine set (a Turn timeout `after`, a
+  named delay, a delayed `raise` or `sendTo(self)`), an event from outside the states below, a Gate's event, the Agent's
+  own end. The exit stops that work (an invoke is stopped when its state exits), and the answer says so (`stopped`): the
+  poll reads "The workflow left the state that asked for this turn while it ran your pick, and that stopped the pick's
+  work before it finished: your turn is over.", and the next continued Turn's notice reads "Your pick `X` did not
+  finish: the workflow left the state that asked for your last turn while it ran, and that stopped it." Both keep the
+  last reply an earlier link gave, if any, and state it: an earlier link's reply is never dropped because a later link
+  was stopped. The run host tells a fired timer from an event sent at once by the scheduler's own table: it watches what
+  the actor system arms, cancels and fires (`timers.ts`, the same xstate internals as the timer table, ADR-0007). Back
+  at Rest INSIDE the Agent's state — a per-step timeout `after` on the child state that exits the work — the answer is
+  the last reply since the pick, with the Allowed picks; with no reply since the pick, the answer carries none. A
+  restored hold is the Turn of the first registration of its address in the restored tree: a restore that ends that Turn
+  and starts another at the same address before anything settles answers the pick with `turnComplete`. There is no
+  default time bound on a held Turn; the Console shows each outstanding pick "held since".
 - **The one exception is the Orchestrator ending it for its own reasons**, which is ADR-0007's requirement and exactly
   one place: `RunHost.stop()`. Process shutdown never stops actors at all (`instance.ts` calls `host.close()`, which
   ends observation feeds and nothing else), and restore is a fresh process. So "the host did this" is a flag it sets,

package/docs/reference/decisions/0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md

@@ -106,6 +106,13 @@ does not exist for a caller that owns tool assembly. jr2 owns the rest: the engi
   no adapter: a test rig can pass another (`TurnDeps.engineAdapter`). So a second engine changes `engine-choice.ts`, not
   the Turn. The Working tools, the printer, the transcript and Compaction do not change.
 
+- **The Working tools run as confined children beside the engine.** The engine runs in the Harness process, which runs
+  jr2's code only and holds the control credential
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). Each process that a
+  Working tool starts — each `bash` call and what it runs, and the search tools' `rg` or `grep` — runs confined by the
+  Effector's Landlock confiner ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), with an
+  explicit env. The file tools (read, write, edit) run in the Harness process, and resolve each path beneath `/work`,
+  with no escape by `..` or by a symbolic link. A second engine keeps this rule: it is the Harness's, not pi's.
 - **Assembly is runtime construction, not codegen.** `main.ts` constructs the server and listens; each admission carries
   its Agent's definition (ADR-0049), validated loudly and re-read per Submission. `boot.mjs`, the generated shims, the
   boot-time `flue build`, and the readiness lag it caused are deleted, and so — later — was the `JR2_AGENTS_JSON` roster
@@ -219,7 +226,8 @@ does not exist for a caller that owns tool assembly. jr2 owns the rest: the engi
 - **Kept verbatim**: the wire, the stub as the mechanics fixture, `AgentRunPort` and the admission ledger, ADR-0024's
   rule, receipt, and ordering, and the container split — restated in jr2 terms: the pod's credentials live in a separate
   container (the Custodian, ADR-0059) _because working tools execute in the Harness container_, so the
-  credential-isolation premise survives while `local()` leaves the vocabulary.
+  credential-isolation premise survives while `local()` leaves the vocabulary. The one credential that the Harness
+  process holds, the control Stand-in, is out of reach of the Working tools' children, which run confined (ADR-0076).
 - **The `flue-contract` tier dissolves into the conformance suite.** Its rig — scripted OpenAI-compatible provider, the
   Menu over a real socket to a killable fake Orchestrator, real server — moves into `packages/harness/test/` and runs in
   the default `test` gate: the opt-in-ness existed only because the tier owned a foreign pin and build. Its claims

package/docs/reference/decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md

@@ -13,8 +13,8 @@ instructions that say "Do not modify the code yourself".
 [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) already established what that means: the same
 prompt, model, and state produce compliance on one run and not the next, "which is what rules out fixing this with
 words." The prose ban is a persona, not a boundary. ADR-0024 also named the stakes — an Agent with write access is a
-concurrent writer in a Workspace the Machine believes is single-threaded — and
-[ADR-0012](0012-workspace-wrapper-machine.md) puts coder and reviewer in that one Workspace on purpose.
+writer that the Machine did not plan for — and [ADR-0012](0012-workspace-wrapper-machine.md) puts coder and reviewer in
+one Workspace on purpose.
 
 Under the retired flue runtime this had no seat — its tool list was take-it-or-replace-it, and the only recorded out was
 ejecting to a foreign harness project. [ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)
@@ -41,19 +41,20 @@ definition can state.
   tools (the tool set that the Harness gives the loop for each Submission). `bash` stays — the reviewer's own
   instructions require running the tests — and the ADR says plainly what that means: a shell can write, so the tool
   layer states intent and stops the honest path. It is known leaky, and it is not the guarantee.
-- **The worktree layer contains the blast radius: a reviewer works in a detached review worktree.** The attach step —
-  already jr2-owned (`sandbox-kubectl.ts`'s `attachScript`) — adds a worktree at the sha under review with a detached
-  HEAD, sibling to the branch worktree per the Project layout. A write there cannot move the branch or dirty the coder's
-  worktree; a rogue commit lands on a detached HEAD and evaporates with the checkout. This is not a permission boundary
-  — it is containment, the property ADR-0024 bought for turns, bought for the filesystem.
+- **The worktree layer contains the blast radius: a reviewer works in a detached review Worktree.** The Machine cuts it
+  with `worktree()`, `{ path, detach: sha }`, at the sha under review, with a detached HEAD, sibling to the coder's
+  Worktree per the Project layout ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)). A write
+  there cannot move the branch or dirty the coder's Worktree; a rogue commit lands on a detached HEAD and goes when the
+  next cut forces the folder. This is not a permission boundary — it is containment, the property ADR-0024 bought for
+  turns, bought for the filesystem.
 - **Two layers, one structure: the tool list is the hint, the worktree is the guarantee** — the same shape as ADR-0024's
   receipt (hint) and abort (guarantee). Neither layer alone: tools without the worktree leak through bash; the worktree
   without tools invites the model to fight its checkout instead of declining politely.
-- **The reviewing state requests the review worktree per round.** The sha under review moves between rounds, so the
-  detached worktree is attached (idempotently, by sha) on entry to the reviewing state, and its path frames the
-  reviewer's turn — cwd and prompt — instead of the branch worktree. The exact Workspace-port verb is settled at
-  implementation; what is decided here is the seat: worktree mechanics stay in the attach step and the Workspace
-  wrapper, never in Agent instructions.
+- **A state before the reviewing state cuts the review Worktree on each round.** The sha under review moves between
+  rounds, so each round cuts the one folder again at the new sha. The cut forces the folder to the commit and cleans it
+  with `-ffd`. Ignored files stay, because the reviewer runs the tests. The folder's path frames the reviewer's turn —
+  cwd and prompt — instead of the coder's Worktree. What is decided here is the seat: worktree mechanics stay in
+  `worktree()` and the Machine's states, never in Agent instructions.
 
 ## Considered options
 

package/docs/reference/decisions/0031-menu-only-agents-run-on-the-instance-harness.md

@@ -42,7 +42,10 @@ built.
   carries the Instance Harness's model calls the same way. It holds only the model keys of the `"none"` Agents it hosts
   — the keys their providers read — and none of the held secrets a `workspace()` lists: a `"none"` Agent cannot execute
   code, so it had no way to use the rest. Its held objects are its own (`held-instance.json`,
-  `jr2-held-secrets-instance`). Defense-in-depth is the bonus, not the reason.
+  `jr2-held-secrets-instance`). Its held secrets get secret Stand-ins, as in every Harness pod: `jr2 up` mints them with
+  the signing key when it writes that pod's Secrets, as it does for the Instance Effector's key
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). It starts no confined child, so this
+  is for consistency, not a boundary. Defense-in-depth is the bonus, not the reason.
 - **The Instance Effector is the second Instance-level pod, beside it**
   ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), on the same convention: `jr2 up`
   converges it when a registered Machine places an Effect there — an `http` Effect — and deletes it otherwise. It runs

package/docs/reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md

@@ -24,9 +24,9 @@ machine is the one piece of its vocabulary that pattern missed.
   Thus a `workspace()` or `pool()` wrapper with its own door passes. A `.provide()` clone keeps the config of its
   original, so the walk gets the same result for the clone. A Machine with no `input`, or with an `input` that is not
   zod, can use `setup()`. The `ping` Workflow that `jr2 init` writes uses it. The walk checks the registered roots only,
-  because the `input` of a nested Machine is never the door (see below). `workspace()` refuses a body with a zod `input`
-  when you call it. It reads the config and the attached door, so it also refuses a body that `setup()` made. Considered
-  and rejected:
+  because a run starts at a root, and a door under a parent is parsed at invoke (see below). `workspace()` refuses a
+  body with a zod `input` when you call it. It reads the config and the attached door, so it also refuses a body that
+  `setup()` made. Considered and rejected:
   - Refuse all `setup()` Machines. This adds work to the first Workflow and gives nothing.
   - Refuse at boot. Then an Assembly that is already published stops the Orchestrator. The walk refuses only the next
     publish.
@@ -34,7 +34,7 @@ machine is the one piece of its vocabulary that pattern missed.
     two ways to declare one door. Also, the zod schema stays in `machine.config`, and a schema must not go into the
     fingerprint and serialization paths that read the config. And that Machine does not get the Vocabulary checks of
     `jr2Setup`.
-- **A wrapper declares its own door; it never borrows its child's.** `workspace(body, { input, spec })` and
+- **A wrapper declares its own door; it never borrows its child's.** `workspace(body, { input })` and
   `pool(worker, { input, … })` each take an `input` of their own, and neither propagates one upward. The reason is the
   same in both, at different strengths: a wrapper does not feed its child what a caller sent. `pool` is the sharp case —
   a worker is fed per-item, never the run body, so propagating its schema would demand fields the pool never passes and
@@ -55,10 +55,10 @@ machine is the one piece of its vocabulary that pattern missed.
   it was rejected because the author then chooses between two names for one statement, and finds the second only after
   the opaque error. A body that _still_ declares a schema is refused by `workspace()` with a message naming the fix:
   nothing would ever serve or validate it, and a contract nobody enforces is worse than none.
-- **The door types the mapping, and constrains the body.** `WorkspaceOptions.spec` reads its `input` from the declared
-  schema (`z.infer`), so a workflow states its shape once and the workspace mapping is checked against it — the drift
-  this ADR exists to close, closed in the one place that used to re-declare the shape by hand. The same schema checks
-  the _body_, in **one direction only**: the body may not demand more than the wrapper will hand it, which is
+- **The door types the mapping, and constrains the body.** A per-run Repo Slot's mapper reads its `input` from the
+  declared schema (`z.infer`), so a workflow states its shape once and the workspace mapping is checked against it — the
+  drift this ADR exists to close, closed in the one place that used to re-declare the shape by hand. The same schema
+  checks the _body_, in **one direction only**: the body may not demand more than the wrapper will hand it, which is
   `Workspaced<door, slots>`; demanding _less_ is safe, because it is fed a superset. So a body reading a field the door
   never carries is a build error at the `workspace()` call instead of an `undefined` mid-run. The guard counts the raw
   door as provided beside `Workspaced<door, slots>`: for the door `z.object({})` the two differ, and a body that writes
@@ -75,22 +75,21 @@ machine is the one piece of its vocabulary that pattern missed.
   a parent invoking a nested `workspace()` has its input mapper checked against that wrapper's door, and gets the body's
   output typed back. With no schema declared the door is permissive, so there is nothing to infer and the mapper's
   argument is `unknown` — an honest "jr2 does not know", not `any`; a wrapper fed by something other than a caller (a
-  pool worker) states what it is fed by annotating the parameter, as `PoolSpec.cap`/`itemInput` do. `spec` takes the
-  same permissive answer as the guard: its `input` is the door plus `HostInjectedInput`, so a `spec` gives each run a
-  branch from `instanceId` with no cast, and a nested wrapper whose `spec` reads it needs a parent that gives it.
-  `Partial<HostInjectedInput>` was the alternative; it was rejected because each root `spec` would then write a fallback
-  for a value that is always there. The input of the wrapper stays the door alone, so no parent must send `instanceId`.
-  For the door `z.object({})` that input is `{}`, the door without its `Record<string, never>`, so a parent can give
-  `instanceId` to a nested `spec` that reads it; with the raw `z.infer` it could not, and the nested Workspace then
-  pushed each run to `fix/undefined`. `z.infer<…> & Partial<HostInjectedInput>` was the alternative; it was rejected
-  because the index signature makes `instanceId` `never` there too. A per-run Repo Slot's mapper keeps the door alone,
-  because a url does not come from a run's id.
+  pool worker) states what it is fed by annotating the parameter, as `PoolSpec.cap`/`itemInput` do. The input of the
+  wrapper stays the door alone, so no parent must send `instanceId`, and a nested body that reads it needs a parent that
+  gives it. For the door `z.object({})` that input is `{}`, the door without its `Record<string, never>`, so a parent
+  can give `instanceId` to such a body; with the raw `z.infer` it could not. A per-run Repo Slot's mapper keeps the door
+  alone, because a url does not come from a run's id.
 - **The schema is structure, so it is open.** Workflow-detail JSON (`GET /workflows/:name`, the address ADR-0032's
   negotiation kept) serves it as JSON Schema — same band as the Machine doc, and what drives the Console's start form
   before any token is entered. The _submit_ stays `authenticated`; schema open, trigger guarded.
 - **A declared schema is enforced at the door.** `POST /workflows/:name/runs` validates the body and 400s naming the
   accepted shape — parity with what Gates already do for deliveries. No schema declared → accept anything (today's
-  behavior), and the Console falls back from a generated form to a raw-JSON textarea.
+  behavior), and the Console falls back from a generated form to a raw-JSON textarea. A wrapper's door is parsed under a
+  parent too, so a parent that passes less than a `workspace()` or a `pool()` requires fails at invoke, before any pod.
+  That is a defect of the parent's Machine, so it goes to the parent's `onError`, and a Pool's `itemInput` is held to
+  the door of a `workspace()` worker in the same way. A plain child Machine's door is a type: no wrapper reads it at run
+  time.
 - **The door takes an idempotency key, out of band.** A start may carry one in a header, never in the body (a body field
   would be one every door had to reserve); a repeat with the same key answers with the run the first one made. A
   `dispatch` Effect sends its ledger row's id ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), so a

package/docs/reference/decisions/0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md

@@ -101,14 +101,14 @@ every build) and promotes incidental image properties into contract items.
   its first provision, in the `preflight` init container's log, with an error that names the fix (because "node did not
   execute" is not actionable) — never as a mid-turn tool failure, and never as a converge refusal for a contract the
   image was not under.
-- **`workspace()` names the image as a STATIC OPTION, never in the per-run spec** — what the Sandbox is _made of_ is the
-  wrapper's business in the same way its worktrees are, but it is a fact about the MACHINE, not about a run: `jr2 up`
-  finds it by walking the registered Machines ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)),
-  and a spec is a function of run input that no walk can evaluate. The User Container rides the same rule and the same
-  resolution as one more option beside `image` (`user?: string`, [ADR-0005](0005-sandbox-pod-composition.md)). Neither
-  is ever persisted: the option rides the Machine (a parts map keyed on `machine.config`, as the vocabulary is) and the
-  provisioning state re-reads it at invoke time, so a restore provisions what the Machine carries now — and a resolved
-  content-addressed tag, which would outlive the image it names, never leaves the port's side of the seam at all.
+- **`workspace()` names the image as a STATIC OPTION, never from run input** — what the Sandbox is _made of_ is the
+  wrapper's business in the same way its clones are, and it is a fact about the MACHINE, not about a run: `jr2 up` finds
+  it by walking the registered Machines ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), and no
+  walk can evaluate a function of run input. The User Container rides the same rule and the same resolution as one more
+  option beside `image` (`user?: string`, [ADR-0005](0005-sandbox-pod-composition.md)). Neither is ever persisted: the
+  option rides the Machine (a parts map keyed on `machine.config`, as the vocabulary is) and the provisioning state
+  re-reads it at invoke time, so a restore provisions what the Machine carries now — and a resolved content-addressed
+  tag, which would outlive the image it names, never leaves the port's side of the seam at all.
 - **A Menu-only Agent never gets a Sandbox Image.** `workspace: "none"` withholds the entire Working toolset (ADR-0028),
   so there is no tooling to carry; the Instance Harness (ADR-0031) runs the stock image permanently. The feature has
   exactly one seat, and it is the Workspace.

package/docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md

@@ -31,11 +31,11 @@ because they are one problem: **what a Machine depends on that is not inside it.
     names of the secrets it names — or the `open` sentinel where a package left the url, the argv or a secret's name for
     its composer ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). `jr2 up` reads them
     without running anything, and a secret named there is what places it.
-  - **The Sandbox Image is a `workspace()` option**, static: `workspace(body, { input, image, repos, spec })` (`repos`
-    is ADR-0051's, and follows the same rule). `image` is a string in one of two shapes — a `file:` URL
+  - **The Sandbox Image is a `workspace()` option**, static: `workspace(body, { input, image, repos, workGroup })`
+    (`repos` is ADR-0051's, and follows the same rule). `image` is a string in one of two shapes — a `file:` URL
     (`import.meta.resolve("./image")`, a docker context the module ships) or a registry ref — or absent, which keeps
-    ADR-0037's fallback. It moved out of the per-run spec because `jr2 up` must find it statically. It is never
-    persisted: the provisioning state re-reads it off the Machine on restore.
+    ADR-0037's fallback. It is static because `jr2 up` must find it with no run. It is never persisted: the provisioning
+    state re-reads it off the Machine on restore.
 - **The definition rides the Turn.** The admission body carries the slot's definition; the Harness runs what it was
   handed and re-reads it per Submission as before. The Instance roster (`agents/`, then `config.agents`), its ConfigMap,
   and `JR2_AGENTS_JSON` retire — a flat roster cannot hold two `researcher`s, and a Machine edit already needs `jr2 up`