@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0025-cancel-ends-a-run-stop-parks-it.md

@@ -33,16 +33,21 @@ carved out for "the Orchestrator ending a run for its own reasons" was being spe
 - **`stop()` stays public with no production caller, and is deliberately not on the wire.** It is correct, it is what
   the durability suite drives, and it is what a future graceful shutdown should call. What nobody asked for is a
   user-facing "park this run" verb.
+- **A cancel of a standing run is also a pause.** The run ends `cancelled` as any run does, and jr2 does not start its
+  Workflow again until `jr2 run <workflow>` resumes it, with the items it held
+  ([ADR-0017](0017-pool-over-a-source-port.md)). Without the pause, jr2 would start the standing run again at the next
+  boot or publish, and a person could not stop it. The runs that it dispatched go on, as for any dispatch.
 - **A cancelled run's Workspaces are destroyed, unless the cancel says `keep`.** The run is over, so nothing can use
   them, and each holds its whole Size (ADR-0060) — a placed pod left to the idle GC is capacity for nobody. The
   wrapper's `teardown` is a STATE, entered when the body reaches final, and an actor stop skips it; so the host destroys
   every Sandbox the run owns after the stop, the same idempotent delete `teardown` runs.
   `POST /runs/:id/events { type: "CANCEL", keep: true }` — `jr2 send <run> --event CANCEL --keep` — leaves them for
-  inspection instead: with no Lease they age out at the operator's idle timeout, and `jr2 ssh` reaches them until then.
-  Whether to keep is a fact of the moment of the cancel, never a config key. A **faulted** run keeps its Workspaces as
-  before ([ADR-0012](0012-workspace-wrapper-machine.md)'s destroy-less terminal, ADR-0021): a fault is the case nobody
-  chose, and the pod is the evidence. A **failed** run deletes them, as a `done` run does: a Failure is an end that the
-  Machine chose ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).
+  inspection instead: with no Lease they age out at the operator's idle timeout, and `jr2 workspace shell` reaches them
+  until then; `jr2 workspace rm` removes one sooner. Whether to keep is a fact of the moment of the cancel, never a
+  config key. A **faulted** run keeps its Workspaces as before ([ADR-0012](0012-workspace-wrapper-machine.md)'s
+  destroy-less terminal, ADR-0021): a fault is the case nobody chose, and the pod is the evidence. A **failed** run
+  deletes them, as a `done` run does: a Failure is an end that the Machine chose
+  ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).
 
 ## Considered options
 

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

@@ -57,8 +57,8 @@ does not exist for a caller that owns tool assembly. jr2 owns the rest: the engi
   ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)). The model sent
   `bash` with `git add … && git commit …` and the pick `publish` in one model answer. In 3 of 10 trials, `publish`
   pushed before the commit existed. A `write` and a `bash` test run in one model answer had the same race. The rule is
-  for all tools, the Working tools and the Menu. The cost is that independent reads of one model answer do not run at
-  the same time. Four facts follow:
+  for all tools: the Working tools, the MCP tools and the Menu. The cost is that independent reads of one model answer
+  do not run at the same time. Four facts follow:
   - Only the first pick of a model answer runs
     ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)). The model wrote a later one before it
     read the first one's answer. The seam states two more facts, so that the Turn can find the first pick by itself. The
@@ -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
@@ -170,10 +177,11 @@ does not exist for a caller that owns tool assembly. jr2 owns the rest: the engi
     long as its run** (ADR-0031). The Harness persists each conversation to a directory as it goes and rebuilds it on
     boot, so a Harness restart inside a living pod keeps it; a Submission in flight at the restart settles `failed`.
     What is durable across a lost pod is Orchestrator-side — the admission ledger and snapshot
-    ([ADR-0007](0007-durable-machine-state.md)), and `wait`'s reconnect-from-offset. A conversation that is gone
-    surfaces as 404 → fault → workflow policy, the same family as `workspace.lost`. Provider-stream retry moves inside
-    the turn: the Harness states 2 retries, and pi-ai runs them (`maxRetries`) — the seat ADR-0016 delegated to flue's
-    `durability{}`.
+    ([ADR-0007](0007-durable-machine-state.md)), `wait`'s reconnect-from-offset, and the kept conversation, which a
+    person reads and no Turn continues from ([ADR-0023](0023-the-harness-prints-the-conversation.md)). A conversation
+    that is gone surfaces as 404 → fault → workflow policy, the same family as `workspace.lost`. Provider-stream retry
+    moves inside the turn: the Harness states 2 retries, and pi-ai runs them (`maxRetries`) — the seat ADR-0016
+    delegated to flue's `durability{}`.
   - **[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)'s enabling fact is reproduced
     as explicit code.** Each Submission reads `$JR2_CUSTODIAN_URL/agents/<iid>/surface` afresh and presents it to pi as
     the Menu, so the menu is per-turn with no push channel, no turn index, no second port. Menu tools keep the
@@ -219,7 +227,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)
@@ -31,9 +31,12 @@ definition can state.
   Workspace (it is this ADR's title). A string field, JSON-serializable, riding the existing ConfigMap channel unchanged
   (ADR-0018's constraint holds).
 - **`"none"` is the Menu-only Agent — and the value also names the Harness that hosts the Agent.** `"none"` withholds
-  the entire Working toolset: the Agent converses and picks from its Menu, nothing else — the decisioning persona (read
-  inputs, pick the next event). Because such an Agent touches no Workspace, it does not run in one: `"write"`/`"read"`
-  place a Turn on the enclosing Workspace's Harness; `"none"` places it on the
+  the entire Working toolset: the Agent converses, picks from its Menu and calls the MCP tools of the remote servers it
+  names
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)), and
+  runs no code — the decisioning persona (read inputs, pick the next event). "Menu-only" means "no Working tools": such
+  an Agent can also hold MCP tools. Because such an Agent touches no Workspace, it does not run in one:
+  `"write"`/`"read"` place a Turn on the enclosing Workspace's Harness; `"none"` places it on the
   [Instance Harness](0031-menu-only-agents-run-on-the-instance-harness.md), always — even when a `workspace()` encloses
   the invocation. Placement is definitional, which is this ADR's thesis extended one step: what an Agent may do to the
   Workspace decides where it runs. (`cwd` is moot for `"none"` — only Working tools consume it.)
@@ -41,19 +44,32 @@ 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.
+- **An MCP allowlist is a guarantee about the credential, and jr2 offers it only where it can keep it.** An Agent's MCP
+  tools ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md))
+  spend the server's token, so the allowlist guards that token, not the Workspace. A remote server needs a list (tool
+  names, or `"*"`): the Harness offers and runs only those tools. Where Workspace code of the Sandbox in which the
+  Agent's Turns run can spend that secret, Workspace code can call every tool, so `jr2 up` refuses a list and takes only
+  `"*"`. That is the case when the Sandbox's `workspace()` grants the secret, when a credentialed `command` of that
+  Workspace names it, or when an `http` Effect of that Workspace whose body is a Worktree file names it: the Agent
+  writes that body ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). A `"none"` Agent's
+  Turns run on the Instance Harness, where no Workspace code runs, so it keeps its list. A stdio server runs as
+  Workspace code and gets no list. The token's own scopes are the outer limit. This is not the shape of
+  `workspace: "read"` above: there the tool list is the hint, because `bash` can write; here the list is the guarantee,
+  because no Workspace code can spend the secret.
+- **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
 
@@ -78,10 +94,11 @@ definition can state.
 - **The reviewer definition becomes `workspace: "read"`**, and the prose ban stays in its instructions as intent — the
   half of the contract a model reads — no longer as the mechanism. A decisioner becomes `workspace: "none"`.
 - **The definition stays plain data.** No code enters the ConfigMap channel; composition by re-export/spread (ADR-0018)
-  is preserved. Custom tool _implementations_ remain out of the contract — this decision adds a restriction vocabulary,
-  not an extension one. Growing extension tools is a separate, later decision.
-- **GLOSSARY.md arbitrates the three senses of "tools"**: the Menu (control plane — what an Agent may say) and Working
-  tools (data plane — what it may do) become glossary entries; unqualified "tools" joins the Avoid lists.
+  is preserved. Tool _implementations_ stay out of the contract — this decision adds a restriction vocabulary, not an
+  extension one. The extension is MCP: an Agent names servers, and a server holds the code (ADR-0079).
+- **GLOSSARY.md arbitrates the senses of "tools"**: the Menu (control plane — what an Agent may say), Working tools
+  (data plane — what it may do) and MCP tools (what it may do through a service, ADR-0079) are glossary entries;
+  unqualified "tools" joins the Avoid lists.
 - **The `@kind` tier gains the containment scenario**: from the review worktree, a write probe followed by a commit must
   leave the branch ref and the coder's worktree untouched.
 - **The zero-support guard stays available to workflows**: a workflow can still have both Agents report the sha and gate

package/docs/reference/decisions/0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md

@@ -21,12 +21,19 @@ whole history again. It also left the history calling tools the request no longe
 
 ## Decision
 
-- **The Menu is the whole of what an Agent can ever be offered in its Machine, and it is the tools block.** It is the
-  union of the derived sets of every state that invokes an Agent of that name — the same scope as its continued
-  conversation's id (ADR-0057). `jr2Setup.createMachine` derives it in ADR-0015's walk, in a fixed order, so it is
-  byte-stable for every Turn of the conversation and for every fresh conversation of that Agent. The descriptions are
-  the event defs' own and do not vary by state, so a def's description must hold at every writing of it the Agent can
-  reach; the load warns where its writings on one path differ (ADR-0015).
+- **The Menu is the whole of what an Agent can ever be offered in its Machine, and it is the Menu's part of the tools
+  block.** It is the union of the derived sets of every state that invokes an Agent of that name — the same scope as its
+  continued conversation's id (ADR-0057). `jr2Setup.createMachine` derives it in ADR-0015's walk, in a fixed order, so
+  it is byte-stable for every Turn of the conversation and for every fresh conversation of that Agent. The descriptions
+  are the event defs' own and do not vary by state, so a def's description must hold at every writing of it the Agent
+  can reach; the load warns where its writings on one path differ (ADR-0015).
+- **An Agent's MCP tools are fixed for the conversation too.** The Harness reads a server's tools at the conversation's
+  first Turn, keeps the allowed ones sorted by name, records them with the conversation, and never reads them again for
+  it, across a park and a restart
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). The
+  tools block is the Working tools, then the MCP tools, then the Menu, and it is the same bytes for every Turn of the
+  conversation. Any fixed order keeps the cache. A tool that the server took away stays in the block, and its call fails
+  with jr2's text.
 - **What one Turn may pick is its Allowed picks**: the invoking state's derived set (its own, its ancestors' and its
   modes' picks — ADR-0015), narrowed to what the live Machine would currently accept **from this Agent**: xstate's
   selection for an event that carries the Agent's sender, a guard that reads the payload counted as passing, must move
@@ -117,7 +124,8 @@ block was not perfect either: once the model invented a tool it had never been g
   cross-state `continue`.
 - **The Machine's whole agent-audience vocabulary as the Menu.** Rejected: it offers picks only another Agent's states
   handle.
-- **Put the Menu tools last.** Rejected: measured, a reordered tools block misses as completely as a changed one.
+- **Narrow the Menu per Turn, with the Menu tools last so that only the tail of the block changes.** Rejected: measured,
+  a change at the tail of the tools block misses as completely as one at its head.
 - **Mask at decode time** (OpenAI `allowed_tools`, logit masking). Deferred: it is provider-specific — Anthropic has no
   subset form, and changing `tool_choice` there drops the messages cache; vLLM's Chat Completions refuses it. The design
   must hold without it; where it is cache-safe, it can be added in the presenter.
@@ -141,9 +149,9 @@ block was not perfect either: once the model invented a tool it had never been g
 
 ## Consequences
 
-- **One state can allow different picks as its context changes or its active mode changes; the Menu does not change.**
-  The conformance tier asserts it: two Submissions with different Allowed picks send a byte-identical tools block
-  (ADR-0027).
+- **One state can allow different picks as its context changes or its active mode changes; the Menu and the MCP tools do
+  not change.** The conformance tier asserts it: two Submissions with different Allowed picks send a byte-identical
+  tools block (ADR-0027).
 - **A restatement is appended, never rewritten.** Conformance asserts that each request of a Submission is a byte prefix
   of the next, with the tools and the system prompt unchanged, and that the restatement sits right after the model
   answer's last tool result.

package/docs/reference/decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md

@@ -89,8 +89,9 @@ to ask about.
   ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)) is the run's data, not its Machine's shape: the Chart's
   text and its hash ride the body's own snapshot, restore admits the text again and compares the hash, and a mismatch or
   a refusal is drift naming the body slot and the reason, after the stamp check and in the same words.
-- **A drifted run is not in `jr2 runs`**, which lists only the live registry. It is reachable through the announce line
-  and `jr2 status <id>`. If stranded runs become common enough to browse, the listing is where that belongs.
+- **A drifted run is in `jr2 runs --status drifted`** and in the Console's list of ended runs, with its reason
+  ([ADR-0009](0009-cli-and-instance-interface.md)), and `jr2 status <id>` reads it whole. It is not in the default
+  listing, which is the live runs.
 - **The digest is only as complete as the walk.** A state running `enqueueActions` can spawn children no static analysis
   recovers (`machine-doc.ts`'s `opaqueStates`); the opacity is folded into the hash, but what it hides is not. Drift
   inside such a subtree can go unnoticed.

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

@@ -39,16 +39,23 @@ built.
   the Harness has exactly one route to its Menu — the Custodian on `localhost` — and forking that path for one pod buys
   a divergence in the component this ADR keeps deliberately uniform. The pod is composed by the same function a
   Sandbox's is ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)), so its Custodian
-  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.
+  carries the Instance Harness's model calls the same way. It holds what the `"none"` Agents it hosts name — the keys
+  their providers read, and the secrets of the remote MCP servers they name
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)) — and
+  none of the held secrets a `workspace()` lists: a `"none"` Agent cannot execute code, so it had no way to use the
+  rest. A `"none"` Agent names no stdio MCP server, because the Instance Harness has no Landlock domain to start one in.
+  Its held objects are its own (`held-instance.json`, `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
-  the same `jr2-harness` image with `/opt/jr2/bin/effector` as its command, holds no conversation and runs no Agent, and
-  is a Deployment, not a StatefulSet: it keeps nothing, and a rollout must run the new pod beside the old one. No config
-  key names, sizes, addresses, or enables it.
+  converges it when a registered Machine places an Effect there — an `http`, an `mcp` or a targeted `dispatch` Effect —
+  or a Hook needs it (a `mac` verifier, or a kind that declares `posts`), and deletes it otherwise. It runs the same
+  `jr2-harness` image with `/opt/jr2/bin/effector` as its command, holds no conversation and runs no Agent, and is a
+  Deployment, not a StatefulSet: it keeps nothing, and a rollout must run the new pod beside the old one. No config key
+  names, sizes, addresses, or enables it.
 - **No image config at all.** The Harness image was once configured as `sandbox.image` because the Sandbox pod was the
   only place a Harness ran — a misnomer once the Instance Harness exists, and config is the wrong seat regardless:
   `jr2 up` builds and resolves every image it deploys ([ADR-0038](0038-jr2-up-builds-every-image-it-deploys.md)), and
@@ -68,13 +75,14 @@ pointers only; memory snapshots are tied to one template version, so the state w
 change is a volume the actor reloads on a cold boot. These decisions take that shape.
 
 - **A conversation is persisted to a directory, and rebuilt from it on boot.** The Harness writes each conversation as
-  it goes: jr2's own record — the stream log, the Settlements, the history messages, in the wire's shapes — plus the
-  engine part, in a folder the engine names (`engine/<name>`), which the record does not read. Today it is jr2's
-  transcript (ADR-0027): `engine/pi/transcript.jsonl`, the pi-ai messages the model read and each Compaction. Rebuilding
-  reads jr2's record first; an engine that cannot read the engine part (another engine, another version) continues from
-  the history messages. The record is the contract; the engine part is not. A Submission in flight at the restart
-  settles `failed` (the typed error `harness_restarted`, which the Agent's Actor reads as "Turn lost") on the rebuilt
-  stream, so the Orchestrator reads a Settlement, not a 404, and the conversation's next Turn continues it.
+  it goes: jr2's own record — the stream log, the Settlements, the history messages, the conversation's MCP tools, in
+  the wire's shapes — plus the engine part, in a folder the engine names (`engine/<name>`), which the record does not
+  read. Today it is jr2's transcript (ADR-0027): `engine/pi/transcript.jsonl`, the pi-ai messages the model read and
+  each Compaction. Rebuilding reads jr2's record first; an engine that cannot read the engine part (another engine,
+  another version) continues from the history messages. The record is the contract; the engine part is not. A Submission
+  in flight at the restart settles `failed` (the typed error `harness_restarted`, which the Agent's Actor reads as "Turn
+  lost") on the rebuilt stream, so the Orchestrator reads a Settlement, not a 404, and the conversation's next Turn
+  continues it.
 - **A restart while the Agent's state is busy cuts the Turn and is no fault.** When the Agent's state is not at Rest —
   its pick is outstanding, or work it started in runs below it — or its pick's answer was read and never reached the
   model, the Agent's Actor raises no `agent.fault` for a restart: the Machine would route it and stop the work the Turn

package/docs/reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md

@@ -0,0 +1,101 @@
+# The Console unlocks with a Caller's credential, and shows what its scopes allow
+
+[ADR-0014](0014-observation-is-open-run-state-is-not.md) built the HTTP surface on one premise: the visualizer page is a
+browser, and a browser holds no token — so it got a projection instead of a credential, and "give the page a token" was
+explicitly rejected. That page is now the **Console**: it starts runs, answers Gates and cancels runs, which are writes
+on the guarded surface. This ADR records how a browser earns those writes without moving the open band. The person
+presents a credential; the page never ships with one.
+
+## Decision
+
+- **The person presents a Caller's credential; the page never ships with one.** The Console's nav carries a password
+  field, and a login button for each JWT issuer that the Instance declares with `login: true`
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Empty, the page is
+  precisely ADR-0014's observer: open structure and observation, no control rendered. With a credential, the page sends
+  `Authorization: Bearer` on the guarded surface. The credential is any Caller's: the Instance token, a named Caller
+  token, or a JWT. The login gets a JWT from the issuer with OIDC (the authorization code flow with PKCE, as a public
+  client), and the page then uses it as it uses a typed token. The page as _served_ stays open and inert; ADR-0014's
+  rejection stands, because what it rejected was baking the credential into the page.
+- **The login's facts come from an open route, and its client id is the issuer's `audience`.** Before a login, the page
+  reads `GET /console/config`: `{ login: [{ issuer, clientId }] }`, from the issuers of the current Assembly that have
+  `login: true`. The route is in the open band (ADR-0014), because the page reads it before it holds a credential, and
+  both values are public: a public client has no secret, and the issuer's URL is in every JWT that it signs. The client
+  id is the issuer entry's `audience`, because the JWT that the login gives names its client as its audience, and that
+  is what the JWT authenticator checks. A login is opt-in for each issuer, because an issuer for machines (a CI
+  provider's tokens) has no login page. The page reads the issuer's discovery document, asks for `openid`, `profile`,
+  `email` and `groups` where the issuer lists each, and sends the ID token as the bearer: an access token's audience and
+  form differ between providers. The return address is always the Console's root (`/`), so the client registers one
+  redirect URI; the page then puts the address back to where the login began. The verifier, the state and that address
+  wait in `sessionStorage` until the return, and a return whose state does not match is refused. PKCE needs
+  `crypto.subtle`, so a login needs the Console on https or on localhost, and the issuer must let the Console's origin
+  call its discovery document and its token endpoint (CORS).
+- **The page shows only what the Caller's scopes allow.** On entry the page asks `GET /whoami` for the Caller record:
+  its name, the name that jr2 shows, and its scopes for each Workflow. It renders a control only where a scope opens its
+  route: the start form with `start` for that Workflow, Gate cards with `answer`, cancel with `cancel`, a run's full
+  state with `read`, and the Steering box with `steer`. The page re-fetches a run on a frame only for a Caller with
+  `answer` or `read` on its Workflow. The nav shows who the page acts as: the name that jr2 shows, else `<via>/<name>`,
+  with the scopes in its title, and a sign-out button in place of the field. The server still checks each request
+  (ADR-0014); the page hides a control so that a person does not meet a 403, not as a guard.
+- **The credential lives in `sessionStorage`** — survives a reload, dies with the tab, never a cookie (no ambient
+  credential, no CSRF surface). A typed token and a login's JWT live there alike. A later 401 (an expired JWT, a rotated
+  token) drops the UI back to observer mode rather than failing per widget.
+- **Gate discovery is a frame-triggered guarded read, not an open-band extension.** A Gate exists exactly while its
+  invoking state is entered ([ADR-0011](0011-workflow-defined-events.md)), and every entry/exit lands a status frame on
+  the open workflow feed (ADR-0022) — so a Console whose Caller has `answer` reads `GET /gates` on entry and again on
+  each frame, and folds the Gates into its store. `GET /gates` lists only the Gates that the Caller may answer, across
+  every Workflow (ADR-0078), so the Gate cards are the person's inbox and never show a Gate the person cannot answer.
+  Synchronized, no polling loop, and the observation projection is untouched. A delivery's success is likewise confirmed
+  by the next frame emptying the card, never by local bookkeeping.
+- **The rail lists ended runs too.** It lists the live runs and, under them, the ended runs of the selected Workflow
+  from `GET /runs?status=ended&workflow=<name>` (ADR-0009), each with its status, and a `drifted` run with its reason
+  (ADR-0030). An ended run opens as a live one does: its graph, its last status and its conversations, for as long as
+  jr2 keeps the run (ADR-0065). A run on an older Assembly carries the mark "older Assembly · <hash>" and is drawn on
+  its own Machine, live or ended: an ended run's row names the Machine it ran on
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). A `drifted` run has no
+  Machine to draw, so it shows its drift reason in place of the graph. The Console shows each outstanding pick as
+  "outstanding since".
+- **A conversation opens in a bottom drawer.** A full-width drawer across the bottom of the page shows the run's
+  conversations ([ADR-0023](0023-the-harness-prints-the-conversation.md)). A person can change its height, and the page
+  keeps the height for that viewer. Closed, it is a bar of tabs, one for each Agent slot, with a dot on a slot whose
+  Turn is live. Open, it shows the selected slot's conversation and follows a live Turn, with the Steering box beside it
+  for a Caller with `steer`. It reads the conversation routes, so it needs `read`. The right drawer keeps Attention and
+  Activity.
+- **Page addresses content-negotiate; JSON is the default dialect.** `/` and `/workflows/:name` serve the Console shell
+  to `Accept: text/html` and JSON to everything else — so the workflow-detail resource keeps its natural address (the
+  run-input schema's home, [ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)) and no future page has to
+  squat on a mangled sibling path. Nothing existing moves: EventSource asks `text/event-stream`, and the Harness's Menu
+  and the CLI never ask for HTML. `/viz/*` is deleted (greenfield, no redirects); assets move to `/assets/*`, which also
+  retires the "a workflow named `assets` is shadowed" hazard.
+
+## Considered options
+
+- **`jr2 ui` — the CLI opens the browser through an authenticated local proxy.** A convenience layer worth building _on
+  top of_ the token field later, not a substitute: it has no answer for the deployed jr2 Application behind an ingress,
+  where the browser talks to the Service directly and the CLI is not in the path.
+- **The Instance token alone.** Rejected (ADR-0078): a person who must answer Gates and holds no cluster RBAC would then
+  hold every act on every run. A scoped Caller's credential is what that person holds.
+- **The conversation in the right drawer.** Rejected: a conversation needs the page's width, and the right drawer keeps
+  Attention and Activity.
+- **Announce gates on the open observation feed** (even just `{runId, gate}`). Rejected: it widens the projection for a
+  convenience the credential already solves, and the open band has an unresolved exposure question as it stands (spawn
+  ids — the ADR-0014 open call). The projection stays the one place the line is drawn.
+- **A `/ui` path prefix, or moving the API under `/api`.** Rejected for negotiation: the first is ceremony on the
+  address a human types, the second churns the Harness's Menu, the Custodian's route allowlist, the CLI, and the
+  ADR-0009/0013 route tables for cosmetics.
+
+## Consequences
+
+- **No new band.** The server-side diff of the Console itself is: negotiate two addresses, serve the shell, retire
+  `/viz/*`, and serve `GET /console/config` in the open band. The scopes, `GET /whoami` and the login's issuers are
+  ADR-0078's.
+- **Possession follows the credential.** The Instance token stays one `kubectl get secret` away for whoever holds
+  cluster RBAC; a named token is what its holder was given; a login is what the identity provider's groups grant.
+- **The XSS caveat is the real one and is bounded by what the page is:** a credential in `sessionStorage` is readable by
+  scripts on the page, so the Console must keep serving only its own assets — no CDN, no third-party script, exactly the
+  constraint the viz page already lives under.
+- **GLOSSARY.md**: **Console** is a glossary term (visualizer, dashboard, UI, viz on its Avoid list).
+- **The Console's UX gets a browser tier** — `@console`-tagged Cucumber scenarios holding a Playwright page, in
+  `@jr2/e2e`, excluded from the default profile ([ADR-0010](0010-bdd-acceptance-tests.md) as amended). What the page
+  _believes_ stays unit-tested in `console-store.test.ts`, and the login's pure half in `console-login.test.ts`; the
+  browser tier asserts what a user does and sees, and the login against Dex in a container (ADR-0078). The login
+  scenario is also tagged `@dex`, because it needs docker, which the rest of the tier does not.

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

@@ -3,7 +3,7 @@
 `POST /workflows/:name/runs` takes a JSON body and hands it to the machine as xstate `input` — unvalidated, and
 undescribed: the module contract is `export const machine` alone (ADR-0011/0015), so nothing at runtime says what a run
 of a given workflow should be started _with_. The Console's start form
-([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)) forced the question, but the gap predates it —
+([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)) forced the question, but the gap predates it —
 `jr2 run` has the same blindness, and a typo'd input surfaces as a confusing mid-run failure instead of a refusal at the
 door. Meanwhile every event a machine _accepts_ already carries a zod schema, attached to the machine itself
 ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)'s vocabulary-on-the-machine). The input that starts a
@@ -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,27 +75,27 @@ 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
-  start whose answer was lost is sent once where it may have arrived (ADR-0067) and makes one run. `jr2 run` and the
-  Console send none.
+  start whose answer was lost is sent once where it may have arrived (ADR-0067) and makes one run. With a second header,
+  a start is a key-only ask: the door answers the run under the key, or that no run has it, and starts nothing.
+  `jr2 run` and the Console send none.
 
 ## Considered options
 

package/docs/reference/decisions/0034-the-console-renders-with-preact-and-the-server-erases-the-types.md

@@ -1,11 +1,11 @@
 # The Console renders with Preact, and the server erases the types
 
-The Console ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)) outgrew its framework-free form: `main.js`
-reached ~1,500 lines, much of it hand-rolled DOM reconciliation (`memo()`, `paint()`, manual list diffing) — work a view
-library exists to own. Three standing constraints shaped the replacement: the repo is zero-build (Node 24 strips types;
-nothing compiles), the Console serves only its own assets (ADR-0032), and `@jr2/orchestrator` is a library that serves
-its files from disk wherever the process starts. A fourth arrived with this decision: Console source is TypeScript like
-everything else.
+The Console ([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)) outgrew its framework-free form:
+`main.js` reached ~1,500 lines, much of it hand-rolled DOM reconciliation (`memo()`, `paint()`, manual list diffing) —
+work a view library exists to own. Three standing constraints shaped the replacement: the repo is zero-build (Node 24
+strips types; nothing compiles), the Console serves only its own assets (ADR-0032), and `@jr2/orchestrator` is a library
+that serves its files from disk wherever the process starts. A fourth arrived with this decision: Console source is
+TypeScript like everything else.
 
 ## Decision
 

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

@@ -81,10 +81,11 @@ every build) and promotes incidental image properties into contract items.
   because jr2's file supplies one; such an image sets `GIT_CONFIG_SYSTEM=/etc/gitconfig` itself, and jr2 then adds
   nothing. With the variable set, `git config --system <key> <value>` writes jr2's file on the read-only volume and
   fails (exit 4); without it, an Agent that runs as root wrote `/etc/gitconfig`. A `--global` or repo-local write works
-  as before. A human's `kubectl exec` shell does not get the variable, as it does not get the PATH append. jr2's other
-  git is out of scope: the sync runs under `GIT_CONFIG_NOSYSTEM` (ADR-0067); the Sandbox Effector is another container
-  with its own committer rules (ADR-0068), and a credentialed `command` Effect runs there with `PATH`, `HOME` and
-  `TMPDIR` alone, so it gets no default identity.
+  as before. A raw `kubectl exec` shell does not get the variable, as it does not get the PATH append;
+  `jr2 workspace shell` starts through the spawner, as an Agent's `bash` does (ADR-0009). jr2's other git is out of
+  scope: the sync runs under `GIT_CONFIG_NOSYSTEM` (ADR-0067); the Sandbox Effector is another container with its own
+  committer rules (ADR-0068), and a credentialed `command` Effect runs there with `PATH`, `HOME` and `TMPDIR` alone, so
+  it gets no default identity.
 
 - **The contract is the floor, and the preflight proves it.** What is inherent to "jr2's runtime in your filesystem" and
   nothing more: a **glibc** base no older than the one jr2's node was built against (musl is out entirely), **`git`** on
@@ -101,14 +102,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.