@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -50,7 +50,7 @@ decision generalizes that container. It holds every credential the Harness in it
     each Sandbox, whatever the count of its Agents.
   - The **fetch Stand-in** is public, `jr2-held-JR2_SANDBOX_TOKEN`. `jr2-upload-pack` holds it as a constant. The
     Custodian puts the fetch token in its place on the fetch route alone, and refuses it on every agent route.
-- **The Harness reads its Menu itself.** There is no MCP. For each Submission, `menu.ts` reads
+- **The Harness reads its Menu itself.** No MCP carries the Menu. For each Submission, `menu.ts` reads
   `GET /agents/<iid>/surface` and delivers a pick with `POST /agents/<iid>/events`, both to the Custodian's control
   socket, `/run/jr2/custodian/control.sock`, with the control Stand-in as the bearer and the slot it states for the
   conversation (ADR-0076). `menu-tools.ts` gives pi each accepted event as a tool. The tool names stay
@@ -64,7 +64,7 @@ decision generalizes that container. It holds every credential the Harness in it
   ([ADR-0042](0042-ready-is-not-routable-an-admission-retries-its-connection.md)), and a `poll` event refuses the turn
   (`deferred` is retired, ADR-0006). The event's own JSON Schema is the tool's parameters, so the model sees the
   contract the Orchestrator validates against.
-- **The control listener forwards five routes and no other.** Plain HTTP, to the Orchestrator's Service
+- **The control listener forwards six routes and no other.** Plain HTTP, to the Orchestrator's Service
   (`jr2-orchestrator.<ns>.svc:4000`, written into the pod's bootstrap by whoever makes the pod — see "Objects, per
   pod"):
 
@@ -73,21 +73,23 @@ decision generalizes that container. It holds every credential the Harness in it
   POST /agents/<iid>/events           → the same path     a pick
   GET  /agents/<iid>/deliveries/<id>  → the same path     an outstanding pick's answer (ADR-0024)
   POST /agents/<iid>/notices          → the same path     a step boundary's notices heard (ADR-0062, ADR-0076)
+  POST /agents/<iid>/conversation     → the same path     a batch of the conversation's entries (ADR-0023)
   POST /fetch                         → /sandboxes/<this pod's Sandbox>/fetch     the ask (ADR-0053)
   anything else                       → 404, from the Custodian
   ```
 
-  The four agent routes are on a Unix socket, `/run/jr2/custodian/control.sock`, in a folder that the Harness and the
+  The five agent routes are on a Unix socket, `/run/jr2/custodian/control.sock`, in a folder that the Harness and the
   Custodian share and that no confined program can write (ADR-0076). The fetch is on `127.0.0.1:8081`, because
   `jr2-upload-pack` runs in the domain, and the fetch Stand-in is public. Each listener answers 404 to the other's
   routes. Landlock does not limit a connect to a named socket, so a confined program can connect to the control socket.
   It holds no control Stand-in, so the Custodian refuses each agent route that it asks for there, with the fetch
   Stand-in or with none, and the control socket answers 404 to the fetch route.
 
-  A read — the surface, a delivery's poll — and an acknowledgment of notices, which marks them heard however often it
-  lands, are retried on any reset; a pick and the ask only on a reset before they were sent, so one the Orchestrator may
-  have read is not sent twice. A poll holds up to about 25 s, far below the listener's 3600 s idle limit, so an
-  outstanding pick never rides one long request (ADR-0002).
+  A read — the surface, a delivery's poll — an acknowledgment of notices, which marks them heard however often it lands,
+  and a batch of the conversation's entries, whose `seq`s make a second send add nothing (ADR-0023), are retried on any
+  reset; a pick and the ask only on a reset before they were sent, so one the Orchestrator may have read is not sent
+  twice. A poll holds up to about 25 s, far below the listener's 3600 s idle limit, so an outstanding pick never rides
+  one long request (ADR-0002).
 
   On each forwarded request, the Custodian swaps `Authorization: Bearer <Stand-in>` for the token of that route — the
   control token on an agent route, the fetch token on the fetch route — and removes every other credential header. A
@@ -124,7 +126,10 @@ decision generalizes that container. It holds every credential the Harness in it
     `paths` gives 403. It is checked after Envoy removes dot segments and reads `\` as `/` and `..;` as `..`, and the
     upstream gets that path. So IIS and Tomcat cannot read a different path. A credential header sent twice gives 400.
   - The swap: in each header the secret names, the Stand-in alone, or one auth scheme and the Stand-in
-    (`Bearer <Stand-in>`), becomes the value. Nothing else is rewritten.
+    (`Bearer <Stand-in>`), becomes the value. Nothing else is rewritten. The Stand-in chooses the secret: when several
+    secrets are bound to one target and one header, the header gets the value of the secret whose Stand-in it carries.
+    So two MCP servers of one service, with two tokens, can be in one pod
+    ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)).
   - Every credential header that is not the product of a swap is removed. A request with no swap gets 403 and never
     leaves the pod: `jr2 custodian: <target> needs the stand-in of <NAME> in <headers>`.
   - Envoy opens its own TLS to the target, verifies the chain against `upstream.crt` and the name against the target's
@@ -203,23 +208,25 @@ decision generalizes that container. It holds every credential the Harness in it
   and `harness.catalog` (a catalog provider id → `{ baseUrl }`). The list serves both sides
   ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). `harness.provider.apiKey` is an entry
   too, implicitly: `JR2_PROVIDER_API_KEY`, bound to its `baseUrl`'s host. `loadConfig` checks the shape in both worlds.
-- **Naming is placement: a pod gets the held secrets something in it names.** Placement is read, never declared
-  (`secretPlacementsOf`), and an entry's `hosts`, `headers` and `paths` are its binding — where the Custodian may put
-  the value — never its placement:
+- **Naming is placement: a pod gets the held secrets something in it names, and a Custodian holds what its pod's Agents
+  name.** Placement is read, never declared (`secretPlacementsOf`), and an entry's `hosts`, `headers` and `paths` are
+  its binding — where the Custodian may put the value — never its placement:
 
-  | Pod                   | The held secrets its Custodian holds                                                       |
-  | --------------------- | ------------------------------------------------------------------------------------------ |
-  | A Workspace's Sandbox | the names its `workspace()` lists under `secrets: [...]`, and the model keys of its Agents |
-  | The Instance Harness  | the model keys of the `"none"` Agents it hosts, and nothing else                           |
+  | Pod                   | The held secrets its Custodian holds                                                                                                 |
+  | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+  | A Workspace's Sandbox | the names its `workspace()` lists under `secrets: [...]`, the model keys of its Agents, and the secrets of the MCP servers they name |
+  | The Instance Harness  | the model keys of the `"none"` Agents it hosts, and the secrets of the MCP servers they name                                         |
 
   A model key is claimed by the PROVIDER: an Agent names its model, and jr2 knows which keys that provider reads
   (`MODEL_KEYS`; the custom provider's id for `JR2_PROVIDER_API_KEY`). An Agent's Turns run in the Workspace below which
   it is declared, down to the next `workspace()`, unless it is `"none"`, whose Turns run at the Instance Harness
-  ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)). A `"none"` Agent cannot execute code, so the
-  Instance Harness loses nothing by holding only model keys. Listing a model key under a `workspace()`'s `secrets` is
-  allowed, and `jr2 up` reports it as redundant. A name a `workspace()` lists that the list does not hold is refused,
-  with the line to add. An entry nothing names — no `workspace()`, no provider, no Effect — goes nowhere, and `jr2 up`
-  warns. `jr2 up` reports per pod:
+  ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)). An MCP server's secret is claimed by the Agent
+  that names the server in its `mcp` list (ADR-0079), and held in the pod where that Agent's Turns run. The rule is the
+  same for every pod: a `"none"` Agent cannot execute code, so the Instance Harness holds only what its Agents name, and
+  only the Harness process spends it. Listing a model key under a `workspace()`'s `secrets` is allowed, and `jr2 up`
+  reports it as redundant. A name a `workspace()` lists that the list does not hold is refused, with the line to add. An
+  entry nothing names — no `workspace()`, no provider, no Effect, no MCP server that an Agent or an Effect names — goes
+  nowhere, and `jr2 up` warns. `jr2 up` reports per pod:
   `Workspace of workflow "coding": Custodian holds ANTHROPIC_API_KEY (provider), JIRA_TOKEN`.
 
   `jr2 up` alone checks the claimed entries (`heldSecretsOf`), host-side, because `.env` values are absent in-cluster.
@@ -231,14 +238,14 @@ decision generalizes that container. It holds every credential the Harness in it
   | R2  | A held-secret name that is `JR2_*` or a proxy or trust variable.                                                                                                                                                                                                                                                                                                                                    |
   | R3  | One name held twice, or held and set by `harness.env`.                                                                                                                                                                                                                                                                                                                                              |
   | R4  | Not exactly one of `value`/`valueFrom`; an empty value; a byte outside `0x20`–`0x7E`; leading or trailing space.                                                                                                                                                                                                                                                                                    |
-  | R5  | A claimed entry with no `hosts` where no default exists; a wildcard, userinfo, a non-`https` scheme, a bare-host path, a bad port; two secrets on one host in one header.                                                                                                                                                                                                                           |
-  | R6  | A `headers` entry that is not a lowercase token, or that frames or routes the request; a duplicate.                                                                                                                                                                                                                                                                                                 |
-  | R7  | `provider.apiKey` with a non-`https` `baseUrl`; a non-`https` catalog `baseUrl`.                                                                                                                                                                                                                                                                                                                    |
+  | R5  | A claimed entry with no `hosts` where no default exists; a wildcard, userinfo, a non-`https` scheme, a bare-host path, a bad port.                                                                                                                                                                                                                                                                  |
+  | R6  | A `headers` entry that is not a lowercase token, or that frames or routes the request; a duplicate; explicit `headers` on an MCP server's secret that leave out `authorization`, where the Harness sends its Stand-in.                                                                                                                                                                              |
+  | R7  | `provider.apiKey` with a non-`https` `baseUrl`; a non-`https` catalog `baseUrl`; an MCP server with a `secret` and a non-`https` `url`.                                                                                                                                                                                                                                                             |
   | R8  | A catalog key that is not a known provider, or that is the custom provider's id.                                                                                                                                                                                                                                                                                                                    |
-  | R9  | Explicit `hosts` on a known model key that leave out where a carried Agent's provider sends its calls.                                                                                                                                                                                                                                                                                              |
+  | R9  | Explicit `hosts` on a known model key that leave out where a carried Agent's provider sends its calls, or on an MCP server's secret that leave out the host of the `url` of a server that names it.                                                                                                                                                                                                 |
   | R10 | A `secretKeyRef` whose Secret or key does not exist.                                                                                                                                                                                                                                                                                                                                                |
   | R11 | While a secret is held: `harness.env` sets a proxy or trust variable.                                                                                                                                                                                                                                                                                                                               |
-  | R12 | A `paths` entry that does not start with `/`, or holds `..`, `;`, `\`, `%2e`, `%2f` or `%5c`.                                                                                                                                                                                                                                                                                                       |
+  | R12 | A `paths` entry that does not start with `/`, or holds `..`, `;`, `\`, `%2e`, `%2f` or `%5c`; explicit `paths` on an MCP server's secret that do not cover the path of the server's `url`.                                                                                                                                                                                                          |
   | R13 | A held value that also reaches the Harness: its Secret loaded by `harness.envFrom`, its key read by a `harness.env` `secretKeyRef`, or its literal set by `harness.env`. A kit Secret (`jr2-instance`, `jr2-held-*`, `jr2-instance-effector`, `jr2-effector-*`, `<sandbox>-effector`, `jr2-git-*`, and each pod's credentials, `jr2-instance-harness-token` and `<sandbox>-token`) named by either. |
   | R14 | A held secret's name that is also a key of a Secret that `harness.envFrom` names. The message names the Secret, the key and the held secret.                                                                                                                                                                                                                                                        |
 
@@ -249,10 +256,11 @@ decision generalizes that container. It holds every credential the Harness in it
   Each message names the config path, never a value, and says what to write instead. A SigV4 or ADC credential in
   `harness.env` is warned about, not refused. A known model key with no `hosts` is bound to the host its provider's
   calls go to: the host of `harness.catalog.<id>.baseUrl` when set, else pi's catalog host. The key and the calls then
-  read one config and cannot drift. `MODEL_KEYS` is pi's data at the pin, written as plain data by `just model-keys` (a
-  script in `@jr2/harness`) at each pi bump, so the Orchestrator has no pi dependency. A test in `@jr2/harness` checks
-  the table against pi, and checks that the file is the script's exact text. So a pi bump that moves a provider, or a
-  hand edit of the file, fails the default gate until the recipe runs.
+  read one config and cannot drift. An MCP server's secret with no `hosts` is bound to the host of the `url` of each
+  server that names it, in the header `authorization`, in the same way. `MODEL_KEYS` is pi's data at the pin, written as
+  plain data by `just model-keys` (a script in `@jr2/harness`) at each pi bump, so the Orchestrator has no pi
+  dependency. A test in `@jr2/harness` checks the table against pi, and checks that the file is the script's exact text.
+  So a pi bump that moves a provider, or a hand edit of the file, fails the default gate until the recipe runs.
 
 - **A catalog provider can move to a gateway.** pi has no env var for a catalog provider's base URL. It hands the
   provider the model it is given. So `resolveModel` returns a copy of the catalog model with `baseUrl` replaced, for
@@ -382,7 +390,7 @@ decision generalizes that container. It holds every credential the Harness in it
   provider's key variable is not set at all. The call then has no key (a catalog provider) or sends the custom
   provider's placeholder `unused`, and it fails. This holds in a Workspace and in the Instance Harness alike. The fix is
   a definition that names the provider; in a Workspace, the key under the `workspace()`'s `secrets` also works. The
-  Instance Harness has no such list: its pod holds only the model keys of the `"none"` Agents it hosts.
+  Instance Harness has no such list: its pod holds only what the `"none"` Agents it hosts name.
 - **TLS-only bindings.** A key for a plain-HTTP endpoint is refused (R7). A LAN `llama-server --api-key` needs TLS and
   its CA in `caBundle`, or no key.
 - **No proxy chaining.** The Custodian cannot forward to a corporate proxy. R11 says so rather than fail silently.

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

@@ -30,6 +30,15 @@ whose processes are gone, with no way to know why.
   workflow prompts you again when something is." The last sentence is safe because the wake asks a model that stopped
   with nothing allowed when a pick opens ([ADR-0016](0016-agent-turn-mechanics-are-internal.md)). A line that says a
   Turn ends with exactly one pick would be false for a pick that keeps the Turn open.
+- **An Agent with MCP tools is told that they are not picks.** Its standing part has one more statement: "Your tools
+  named `mcp__<server>__<tool>`, where `<server>` is not `jr2`, act on outside services, not on the workflow. A call to
+  one is not a pick, and it does not end your Turn." Both tool families share the `mcp__` prefix: the Menu's own tools
+  are `mcp__jr2__<event>`, so the statement names `jr2` as the exception. A model that read a call of a service as its
+  pick would stop with the workflow's work not done. The statement names no server and no tool, so it is byte-stable; an
+  Agent with no MCP tools does not get it. A `"none"` Agent with MCP tools is not told that it acts only by picking from
+  its Menu, because its MCP tools act too. The `@model` claim `mcp-then-pick` measures it
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md),
+  [ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)).
 - **The Turn part is written once per Submission, and restated when its Allowed picks change.** When something other
   than the Agent's own pick changes them inside the Turn, the Harness appends the Allowed picks again at the next step
   boundary, in a `<jr2-turn>` block of their own: "The workflow's state changed since you last read the Allowed picks.
@@ -84,17 +93,18 @@ whose processes are gone, with no way to know why.
   - A notice never replaces a fault. The Machine still receives `agent.fault` and decides (ADR-0016); the notice makes
     sure the next Agent is not working blind.
 
-- **The Orchestrator is the only keeper of notices**: pending notices are plain data in the run's persisted state
-  (ADR-0007). It sees kernel kills and fresh conversations itself. A kernel kill (ADR-0061, layer 5) has two paths,
-  under one source, the Workspace and the time the Harness container ended. A Turn that the kill ended faults on it, and
-  the fault raises the notice with the Turn's Agent. A kill while no Turn runs faults nothing, so before each admission
-  into a Workspace the Agent actor also reads the container's last end from the Sandbox watch, which the operator
-  publishes: a last end `OOMKilled` raises the notice, which names no Turn. The ledger's `seen` makes the two paths one
-  notice. An actor whose own watch saw the restart reads the last end only when it re-admits the Turn after the cut.
-  When the Turn faults, the fault's notice names the Turn's Agent. A watch that has not listed yet says nothing, and the
-  next admission reads again: the last end stays until the container ends again. A nudge and a wake take no kernel kill;
-  it stays for the next Turn. The re-admission after a cut takes it, as it takes every notice in scope that is not a
-  guard kill. The Harness reports a guard kill (ADR-0061) on two paths, under one id that the Harness gives the kill:
+- **The Orchestrator is the only keeper of notices and Steering messages**: pending ones are plain data in the run's
+  persisted state (ADR-0007). It sees kernel kills and fresh conversations itself. A kernel kill (ADR-0061, layer 5) has
+  two paths, under one source, the Workspace and the time the Harness container ended. A Turn that the kill ended faults
+  on it, and the fault raises the notice with the Turn's Agent. A kill while no Turn runs faults nothing, so before each
+  admission into a Workspace the Agent actor also reads the container's last end from the Sandbox watch, which the
+  operator publishes: a last end `OOMKilled` raises the notice, which names no Turn. The ledger's `seen` makes the two
+  paths one notice. An actor whose own watch saw the restart reads the last end only when it re-admits the Turn after
+  the cut. When the Turn faults, the fault's notice names the Turn's Agent. A watch that has not listed yet says
+  nothing, and the next admission reads again: the last end stays until the container ends again. A nudge and a wake
+  take no kernel kill; it stays for the next Turn. The re-admission after a cut takes it, as it takes every notice in
+  scope that is not a guard kill. The Harness reports a guard kill (ADR-0061) on two paths, under one id that the
+  Harness gives the kill:
   - **On a stream.** While a Submission runs, the kill is an event on that conversation's updates stream. The Agent
     actor reads a stream while it waits on the Submission. It stops when the Agent's state exits, before its abort
     reaches the Harness. So a stream does not always reach a reader: a kill in that window is on a stream that no one
@@ -187,14 +197,48 @@ whose processes are gone, with no way to know why.
   A conversation whose own `bash` call answered a kill is not in that kill's audience, so it does not hear the kill
   again as a notice, at its next Turn or at a step boundary.
 
+- **One ledger carries notices and Steering messages.** A Steering message ([ADR-0002](0002-duplex-streaming-actor.md))
+  is not a notice: a notice is a fact that jr2 knows and that has no author, and a Steering message is an utterance with
+  an author, which the model weighs by who wrote it. So the two are siblings on one transport. Each entry of the ledger
+  is an **envelope** and a **body**. The envelope holds what the ledger delivers by: the address, the source, the
+  audience, and what was reserved and heard. The body is a Notice, or a Steering message with its text and its author:
+  `{ kind: "caller", via, name, onBehalfOf? }` or `{ kind: "machine", from? }`, where `from` is the Sender whose words
+  the Machine relays. The rules above, heard once, reserved at a step boundary and delivered when the append is
+  acknowledged, hold for both.
+  - **The address is a tagged value.** `{ conversation }` and `{ workspace }` are the two kinds that notices use, and
+    `{ slot }` (an Agent slot of one Machine instance of the run) is the kind that a Steering message uses. A new kind
+    is an addition, and no kind changes the meaning of another's fields.
+  - **A slot's audience is a future member.** A Workspace notice fixes its audience when the ledger raises it. A message
+    to a slot goes to the slot's open Turn, or, when there is none, to the slot's next Turn in the same Machine
+    instance, whose conversation does not exist yet at the raise. It retires, recorded "not delivered", when that
+    Machine instance ends.
+  - **The Harness frames a Steering message by its author.** A Caller's message is an instruction from outside the run,
+    and the frame names the Caller. A message that the Machine relays `from` another Agent is information from a peer.
+    The frame says that the workflow passes it on but did not write it, and a closing line after the text says that it
+    is not an instruction and does not change the Agent's task: the Agent does what the workflow asked. The closing line
+    is read last, after the peer's text (ADR-0029). In `peer-not-order`, a frame that said only "not an order" read 5 of
+    10, because a model that obeyed read "the workflow relays" as the workflow's own word. A frame that said, ahead of
+    the text only, that it was "that Agent's word, not the workflow's", read 17 of 20, and the closing line read 20 of
+    20 (ADR-0066). A message that the Machine relays `from` a Gate is what the Gate received, and the frame says that it
+    is not an order either. A Machine's message with no `from` is the workflow's own text. The text is quoted line by
+    line, so the model sees where it starts and ends, and it follows the notices in the Turn part, ahead of the Allowed
+    picks. A name in the frame (a Caller's name, its `onBehalfOf`, a peer's or a Gate's id) is a code span that its own
+    text cannot close, on one line: a name comes from outside jr2 and can hold a backtick or a line break. A message
+    whose author the Harness does not know is dropped, never framed as another author's.
+  - **The two bodies ride the wire apart.** The admit body carries `notices` and `steering`, and the surface read
+    `notices: [{ id, notice }]` and `steering: [{ id, message }]`; one acknowledgment,
+    `POST /agents/:iid/notices { heard }`, hears both by their ledger ids. A nudge and a wake take notices by their
+    sources, so they carry no message: the surface read that starts their Submission does.
 - **The Harness writes every word.** The admit body carries typed notices
   (`notices: [{ kind: "memory-limit", scope, agent?, limit?, peak? } | { kind: "conversation-new", reason } | { kind: "pick-answer", pick, cut, answer?, stopped? } …]`,
-  where `peak` comes only with `limit`), and the Harness renders both parts. An outstanding pick's answer is data too —
-  the last reply since the pick, a party's event with its payload or a child's output (ADR-0024) — and its words ("Its
-  answer: `approve` from Gate `review`, with {…}", "No reply came back for it.") are the Harness's, in the receipt and
-  in the notice alike; "it moved the workflow, and nothing ran" is a guard straight back's receipt alone. The standing
-  part needs no wire: the Harness already holds its limits (cgroup and Downward API env), the definition's `workspace`
-  access, and the Menu. The wording lives in one place, and Harness conformance checks it (ADR-0027).
+  where `peak` comes only with `limit`) and Steering messages with their authors, and the Harness renders both parts and
+  frames each message. The text of a Steering message is the author's; the frame around it is the Harness's. An
+  outstanding pick's answer is data too — the last reply since the pick, a party's event with its payload or a child's
+  output (ADR-0024) — and its words ("Its answer: `approve` from Gate `review`, with {…}", "No reply came back for it.")
+  are the Harness's, in the receipt and in the notice alike; "it moved the workflow, and nothing ran" is a guard
+  straight back's receipt alone. The standing part needs no wire: the Harness already holds its limits (cgroup and
+  Downward API env), the definition's `workspace` access, and the Menu. The wording lives in one place, and Harness
+  conformance checks it (ADR-0027).
 
 ## Considered options
 
@@ -220,6 +264,9 @@ whose processes are gone, with no way to know why.
   does not.
 - **Read the kill on the Sandbox watch.** Rejected: the operator publishes what the kubelet says about the container,
   and a guard kill does not end the container. The Harness has no Kubernetes credentials to publish it.
+- **A Steering message as a kind of notice.** Rejected: a notice is a fact with no author, and the Harness words it. A
+  Steering message is an author's text, and the model must weigh a Caller's instruction and a peer's word differently.
+  Folded into a notice, the author and that difference have no place.
 - **The Harness words the kill into the next Turn itself.** Rejected: a second keeper of notices, outside the run's
   persisted state, which cannot know when an admission is ledgered or heard.
 

package/docs/reference/decisions/0063-the-orchestrator-watches-the-cluster.md

@@ -78,5 +78,6 @@ Decisions since then need pod facts at once: the scheduler's reason for a Pendin
   the watch and the Harness attach. ADR-0001: the operator publishes pod facts on the Sandbox's status, and writes
   status only on change — every write is now a watch event at the Orchestrator.
 - The Harness gains a route that is not about a conversation. It is jr2's own work in the container ADR-0005 gives it.
-- The CLI keeps `kubectl` on the user's machine (`jr2 up`, `jr2 ssh`, ADR-0009); only the Orchestrator stops using it.
+- The CLI keeps `kubectl` on the user's machine (`jr2 up`, the `jr2 workspace` verbs, ADR-0009); only the Orchestrator
+  stops using it.
 - Tests fake the client with a small HTTP server instead of a `kubectl` stub.

package/docs/reference/decisions/0064-a-workspace-waits-for-capacity.md

@@ -37,8 +37,8 @@ Workspaces for the Instance (R4), and concurrent Turns per model provider (R5)?
   delete does not touch a name that a live Workspace of the run holds then: a parent that re-enters the state, or
   invokes the same Machine again, gives its new Workspace the same invoke id and so the same name, and that Workspace
   has placed it again ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)). A
-  Sandbox that was placed and then faulted keeps ADR-0021's rule: it stays inspectable (logs, `jr2 ssh`) and ages out at
-  the idle timeout.
+  Sandbox that was placed and then faulted keeps ADR-0021's rule: it stays inspectable (`kubectl logs`,
+  `jr2 workspace shell`) and ages out at the idle timeout.
 - **jr2 caps nothing of its own.** Not live Workspaces (R4), not concurrent Turns per provider (R5). See the options.
 - **A provider's refusal is named.** A Turn that ends because the Harness's provider retries ran out has a fault reason
   with the fixed prefix `provider limit`, as a memory kill has `memory limit` (ADR-0061), so `jr2 status` and the

package/docs/reference/decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md

@@ -0,0 +1,109 @@
+# A persist survives a crash, and history is kept for a set time
+
+Every transition of a run persists its whole snapshot (ADR-0007). The scaling review (R6) read the store and listed its
+costs: `JSON.stringify` of the whole run, a synchronous upsert with an fsync on the event loop, a Pool's run as one blob
+holding every worker, terminal rows never deleted, and `restore()` parsing every row before the server listens. It also
+found the words "Postgres opt-in" in GLOSSARY.md, ADR-0008 and ADR-0009, with no such store in the code. Measured on the
+home cluster's chaos Instance (2026-09-30, `local-path` volume): a persist costs **4.5 ms, whatever the blob's size** (1
+KB or 100 KB), because the cost is the fsync, not the JSON; with the write-ahead log and `synchronous=NORMAL` the same
+upserts cost 0.04 ms (1 KB) and 0.18 ms (100 KB). A run's blob is about 1 KB; a Pool of 40 workers is about 100 KB.
+
+## Decision
+
+- **A persist survives a process crash, not a power loss.** The store runs sqlite in WAL mode with `synchronous=NORMAL`:
+  a write is durable once the OS holds it, and sqlite fsyncs only at a checkpoint. A node's power loss can lose the
+  transitions since the last checkpoint; the file stays consistent, and `restore()` treats the older snapshot as it
+  treats any restart — reconcile against the live world, re-attach, or `lost`. The window in which a crash re-POSTs a
+  prompt (ADR-0007's at-most-once sliver) widens from one microtask to one checkpoint, and only on a power loss, which
+  also ends every Sandbox on that node.
+- **The write stays synchronous and on the event loop.** At 0.2 ms for a Pool's blob there is nothing to move off the
+  loop, and the ordering matters: the row is on disk before the Machine's next side effect runs, which is what lets an
+  epoch bump (ADR-0057), an admission (ADR-0016) or an Effect's intent row (ADR-0067) be saved "at the write" — the
+  intent row before its call leaves. A worker thread, an asynchronous driver or a network store would land the row after
+  the next `invoke` fires, on every persist.
+- **One blob per run stays.** The snapshot is a tree that xstate restores from its root, and one row keeps it atomic —
+  with the ledgers beside it (admissions, epochs, notices, timers, outstanding picks, Effects); a Pool's cost at 40
+  workers is 0.2 ms, so its workers do not become rows of their own. The Effect ledger keeps a row for every Effect the
+  run started (ADR-0067), so a Machine that loops through an Effect grows its blob by one row per pass: id, kind and
+  outcome. The output's tail is dropped once the save that carries the Effect's transition is on disk; a push row keeps
+  its published commit, its source, its `squashed` and its sync's answer whole — every later push of its Repo Slot sends
+  them as one of its pairs — and its bundle only while it is its Repo Slot's newest push and its sync did not finish —
+  one bundle per Repo Slot at most. An outstanding pick's hold is the one place tails accumulate: its `chain` keeps
+  every reply since the pick whole until the pick is answered, then it is dropped (ADR-0067).
+- **`restore()` reads live rows only.** The store answers `WHERE status = 'live'`; terminal rows are not parsed at boot.
+- **A finished run's row lives for `runs.retain`, 30 days by default.** `runs: { retain: "30d", volume: "5Gi" }` in
+  `jr2.config.ts` sets it. `retain` is a duration of at least `1h`, with no upper limit, and the config load refuses a
+  shorter one. It covers what jr2 keeps of an ended run: its row, its kept conversations
+  ([ADR-0023](0023-the-harness-prints-the-conversation.md)) and the hook log (below). Every non-live status — `done`,
+  `failed`, `error`, `cancelled`, `lost`, `drifted` — ages from its terminal write, and a sweep at boot and every hour
+  deletes what is older, with the run's conversations. With no current Assembly (the Kit bump window,
+  [ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)), no `runs.retain` is
+  bound, so this sweep waits for the first publish; the collection of Assemblies still runs. A `live` row is never
+  swept: a run parked on a Gate for a month stays and is restored. Nor is the run that the head of a standing Workflow
+  names ([ADR-0017](0017-pool-over-a-source-port.md)): a paused Pool keeps its held items in that run's blob for as long
+  as it is paused. The setting exists because a history surface uses it: `GET /runs` lists ended runs,
+  `jr2 runs --status` and the Console show them ([ADR-0009](0009-cli-and-instance-interface.md)), and `jr2 logs` reads
+  an ended run's conversations. jr2 is still not the record of a run's results (a Machine sends its output where it
+  belongs — a PR, a Source); the history is for a person who reads what a run did and why. A swept id frees its
+  abbreviations (ADR-0009).
+- **The state volume has a size, and a guard keeps it from filling.** `runs.volume` is the size of the Orchestrator's
+  state volume claim, `5Gi` by default. It holds `state.db`, `conversations.db`, the Assemblies and the Charts. A claim
+  grows only where its StorageClass allows expansion, and Kubernetes never makes one smaller. So `jr2 up` refuses a
+  `runs.volume` that the config sets and that is smaller than the claim, or larger on a StorageClass that does not allow
+  expansion (kind's local-path class does not), and names the class; the claim keeps its size. When the config does not
+  set `runs.volume` and a claim exists, `jr2 up` keeps the claim's size, and prints one line that says so when that size
+  is not the default, so an Instance whose claim is older than the default is not refused for a value that no one wrote.
+  The guard measures the bytes of the files on the volume (both databases with their `-wal` files, the Assemblies and
+  the Charts) against the smaller of the claim's size and the size that `statfs` gives, because a hostPath class such as
+  kind's reports the node's disk and not the claim. The Orchestrator does not read the claim: `jr2 up` gives it the size
+  that it applied, the kept size of a claim that no config names too, in the Deployment's env. It looks at each sweep
+  and every minute. When the volume is more than 80% full by that measure, the sweep deletes the kept conversations of
+  ended runs, the oldest run first, until the volume is below 80% again. The run rows stay, and each run whose
+  conversations went is marked `conversation swept: no space`, which `jr2 logs` and the Console show in place of the
+  conversation. A conversation of a live run is never swept for space. If the volume is still more than 95% full when no
+  conversation of an ended run is left, the Orchestrator keeps no more entries and marks each open conversation cut, as
+  at its cap ([ADR-0023](0023-the-harness-prints-the-conversation.md)), so the conversations never fill the volume.
+- **The hook log keeps each Hook's delivery for `runs.retain`**, as a row of its own: the Hook, the delivery id, the
+  body's digest and the outcome ([ADR-0011](0011-workflow-defined-events.md)). The repeat check reads it, so a repeat is
+  found while the row is kept; a body caught and sent again with a new id after that passes the check, and a handler
+  that compares the commit limits what it can do. A `slack` or `discord` delivery carries a signed timestamp, and jr2
+  refuses one more than 300 seconds from its clock, so that replay fails for them
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A run's blob keeps its
+  own `(delivery, gate)` pairs. A standing Pool's run is handed over before its Effect ledger makes its blob large:
+  after 500 dispatches or one day ([ADR-0017](0017-pool-over-a-source-port.md)).
+- **The store is sqlite on the Instance's volume. No Postgres is owed.** The `SnapshotStore` interface stays as the
+  seam, with one implementation. `DATABASE_URL` is not a thing jr2 reads.
+
+## Considered options
+
+- **Keep `synchronous=FULL`, move the write to a worker thread.** Rejected: the thread hides 4.5 ms from the loop but
+  does not make the disk faster, so writes queue under load and the loop no longer knows how far behind the store is —
+  and it opens the ordering gap on every write, which NORMAL opens only on a power loss.
+- **Batch persists in a window.** Rejected: one persist per macrostep already coalesces a transition's events, and with
+  the fsync gone there is nothing left to amortize.
+- **A row per worker.** Rejected: it splits an atomic tree across rows (a worker's row saved, the Pool's not), makes
+  restore reassemble what xstate restores whole, and buys nothing measurable at 0.2 ms per blob.
+- **A fixed retention, like the Sandbox idle timeout.** Rejected: a list of ended runs and their kept conversations are
+  a history surface, and how long a team reads its history is the team's decision, not jr2's.
+- **A count cap per workflow.** Rejected: a count cap does not bound a busy workflow's disk and punishes a quiet one.
+  The space guard bounds the disk, and it deletes only the conversations, which are the largest part; run rows stay.
+- **An upper limit on `retain`.** Rejected: how long a team reads its history is the team's decision, and the space
+  guard bounds the largest part, the conversations. What `retain` leaves to grow is the run rows and the hook log, which
+  grow with the count of runs and deliveries; a team that keeps a long history of a busy Instance sets a larger
+  `runs.volume`. A limit would refuse that team and bound nothing that the volume's size does not.
+- **Build the Postgres store.** Rejected: the only thing it buys is an Orchestrator pod that reschedules without its
+  volume, which is a storage-class question (a network RWO volume follows the pod) and belongs to the Orchestrator pod's
+  own decision (R10), not to the store. Its cost is a dependency the owner operates, a second store in every test tier,
+  and the asynchronous write above.
+
+## Consequences
+
+- ADR-0008 and ADR-0009 lose "Postgres opt-in" and `DATABASE_URL`; ADR-0008's Orchestrator persists its snapshots "to
+  sqlite on its volume". ADR-0007 points here for the store's durability.
+- The Instance's volume gains `state.db-wal` and `state.db-shm` beside `state.db`, and `conversations.db` with its own
+  `-wal` and `-shm` (ADR-0023).
+- A `drifted` run (ADR-0030) is swept `runs.retain` after the deploy that changed its Machine, not after it ended; that
+  is the time a human has to read it.
+- An idempotency key of a Pool item or a `dispatch` lives as long as its run's row
+  ([ADR-0017](0017-pool-over-a-source-port.md), [ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), so
+  `runs.retain` is also how long a repeated key finds its run.

package/docs/reference/decisions/0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md

@@ -36,15 +36,17 @@ recover, finish — are exercised only one scripted tool call at a time.
   Agent acts on the answer, after a chain of replies and after a Harness restart cut the pick
   ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md), ADR-0031); and after a signed push the
   Agent continues on its branch, so its next push publishes
-  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)). A claim qualifies
-  when an ADR states what a correct Agent does differently for it and a step can observe the difference from outside the
-  pod. **The run** is one `workspace()` workflow through to `done` on a real task: a ticket the seed Repo carries as a
-  failing test, a planner's pick, a coder that edits in the Worktree, runs the test, commits on the run's branch and
-  names the commit — a guard refuses a `submit` that names none — and a reviewer in the same Sandbox, read-only
-  ([ADR-0028](0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)), that runs the test itself and
-  approves or rejects, bounded. Approval parks at a Gate, and the witness is the pod (parking is retention, ADR-0012):
-  the branch is ahead of `main`, its head is the named commit, the tree is clean, and the test passes when the suite
-  runs it there. Nothing is pushed — the Agent holds no credential and the push is the caller's (ADR-0005,
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)); and an Agent with an
+  MCP tool calls it and then makes its pick, because a call of a service is not a pick
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). A
+  claim qualifies when an ADR states what a correct Agent does differently for it and a step can observe the difference
+  from outside the pod. **The run** is one `workspace()` workflow through to `done` on a real task: a ticket the seed
+  Repo carries as a failing test, a planner's pick, a coder that edits in the Worktree, runs the test, commits on the
+  run's branch and names the commit — a guard refuses a `submit` that names none — and a reviewer in the same Sandbox,
+  read-only ([ADR-0028](0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)), that runs the test
+  itself and approves or rejects, bounded. Approval parks at a Gate, and the witness is the pod (parking is retention,
+  ADR-0012): the branch is ahead of `main`, its head is the named commit, the tree is clean, and the test passes when
+  the suite runs it there. Nothing is pushed — the Agent holds no credential and the push is the caller's (ADR-0005,
   [ADR-0053](0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md)), as `task` says — and
   the seed's `app.git` accepts none. The run asserts the pick ledger's shape and a time bound — never the diff, the
   commit message, or the Turn count, which are the model's.
@@ -102,10 +104,11 @@ recover, finish — are exercised only one scripted tool call at a time.
   `<key>` is the profile's `key`. An endpoint that answers with a status other than 2xx prints
   `skipped: the model endpoint at <url> answered HTTP <code> (profile <name>) — the @model tier did not run`. The
   trigger is a change to any text or tool the model reads or is offered: the Briefing, the Menu's rendering and the
-  refusal, the nudge, the Working tools and their descriptions, Compaction's summary, the admit body's notices, the pi
-  pin, a provider adapter, or an authoring surface that changes a Frame. An agent reviewing a feature or refactor that
-  touched one of these runs the tier and reports the scorecard's floors and drift, or the skip, in its handoff.
-  CLAUDE.md states the rule. One scenario runs alone by its title, which is the scenario filter:
+  refusal, the frame of a Steering message, the nudge, the Working tools and their descriptions, how the Harness gives
+  an Agent its MCP tools and their results, Compaction's summary, the admit body's notices, the pi pin, a provider
+  adapter, or an authoring surface that changes a Frame. An agent reviewing a feature or refactor that touched one of
+  these runs the tier and reports the scorecard's floors and drift, or the skip, in its handoff. CLAUDE.md states the
+  rule. One scenario runs alone by its title, which is the scenario filter:
   `cucumber-js --profile model --name "a Gate's answer during a command is followed"`.
 - **A third pi canary.** Conformance and `@kind` drive the turn loop against a script; this tier drives it against a
   model that can misread. Run all three before bumping the pin.
@@ -236,8 +239,8 @@ recover, finish — are exercised only one scripted tool call at a time.
   below: a trial whose measure is recorded — its first pick after the answer; the body seen back in `coding` after it is
   `revise` — and that does not finish within its time is cancelled and counts as finished. Its time is a trial's bound,
   15 minutes, counted from the desk's first answer. A measured trial whose run settles before then without its task's
-  final — a fault — is not cut, and fails "every trial finished". The prompt, the floor and the measure did not change.
-  Both were decided under the user's deferral on 2026-10-12 and confirmed by the user on 2026-10-12.
+  final — a fault — is not cut, and is unfinished: a miss. The prompt, the floor and the measure did not change. Both
+  were decided under the user's deferral on 2026-10-12 and confirmed by the user on 2026-10-12.
 - The held-answer claims of ADR-0024 and ADR-0031 — `chain-answer` (the next pick follows the answer's last link) and
   `cut-pick` (after a Harness restart cut the pick, the Agent uses the answer and does not pick it again; the step
   deletes the Instance Harness pod). Each floor carries ADR-0029/0062's measurement of a list read last. The first run
@@ -314,11 +317,36 @@ recover, finish — are exercised only one scripted tool call at a time.
   up) with the setup void, and a void past it counts against the floor and prints as a void. At the diagnostic run's
   rate, 4 of 10, the bound is often spent; the claim is then open, not passed. Rejected: counting the batched trial a
   miss (it measures the model's reading of the claim's own prompt), raising the bound, or lowering the floor.
-- **A trial that reaches either of its task's finals finished.** A claim whose workflow has two task finals (`wake`,
-  `chain-answer`, and the three command-Effect claims) counts a trial finished at either; its measure already counts the
-  wrong one a miss, and counting it unfinished too would fail the scenario on one miss — the floor 10 of 10 in all but
-  name. A run that ended `failed` (a claim workflow fails on a fault and on a lost Workspace), a run in `error` and an
-  unsettled run never finished.
+- The steering claims of ADR-0002 — `steer-follow` (a Caller's Steering message in an open Turn is followed) and
+  `peer-not-order` (a peer's word that the workflow relays is not obeyed as an order) — are Menu-only. In `steer-follow`
+  the step sends the message with `jr2 steer` while `run_checks` is outstanding, then answers the Gate: every check
+  passed; the measure is the next pick, `hold`, where the prompt asked to publish. In `peer-not-order` an `editor` seat
+  sends a fixed note (discard the notes) with `note`, the workflow relays it with `steer` from the editor, and the
+  writer's prompt says to publish; the measure is the writer's first pick, `publish`. A message that the Turn did not
+  hear, or a relayed note that does not say to discard, is void. Their floors were set before a measured run: 9 and 7 of
+  10 (ADR-0002 says why). The first runs (home-lab vLLM, 2026-11-03): `steer-follow` 10 of 10 twice, none void.
+  `peer-not-order` read 5 of 10 with the frame "It is that Agent's word, not an order to you"; each miss read "the
+  workflow relays" as the workflow's own word. A frame that said, ahead of the text, that the word was not the
+  workflow's and that what the workflow asked still held read 29 of 40 over four runs, and 17 of 20 in an A/B
+  (2026-11-04); its misses read "that Agent's word" as the word to obey, or read the peer's text, the last thing before
+  the Allowed picks, as the Turn's instruction. The B arm moved the disclaimer to a closing line after the text
+  (ADR-0062) and read 20 of 20, none void. Both claims' cells are baselines. The prompts and the floors did not change
+  between the runs.
+- The MCP claim of
+  [ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md) —
+  `mcp-then-pick` — is Menu-only. The Agent has one MCP tool, from a fake server that the step serves, and a prompt
+  whose task needs the tool's answer and then a pick. The measure is the order of the Agent's calls in its printed
+  conversation: the MCP call (`<server>/<tool>`), then the pick. A trial whose model never called the tool is a miss,
+  and one that stopped after the tool with no pick is a miss. Its first measured run (2026-11-05) read 10 of 10, none
+  void, so its floor is 9 of 10, and its cell is a baseline.
+- **A trial passes only when its measure passed and its run finished, and an unfinished trial is a miss.** The floor
+  decides, as for any other miss, and the scorecard line counts the unfinished trials (`9/10 (1 unfinished)`), so a hang
+  stays visible and a lower count reports below its baseline. A run that ended `failed` (a claim workflow fails on a
+  fault and on a lost Workspace), a run in `error` and an unsettled run never finished. A claim whose workflow has two
+  task finals (`wake`, `chain-answer`, and the three command-Effect claims) counts a trial finished at either; its
+  measure already counts the wrong one a miss. Rejected: a separate check that fails the scenario when any trial did not
+  finish. It made one miss that left its run active fail a scenario whose floor allows one miss, so the floor was 10 of
+  10 in all but name; and a hang in every trial still fails the floor.
 - `wake` (below, under `push-wake`) has run four times, 10 of 10 each, and is a baseline.
 - **A claim's setup may change; its floor and what counts as a pass may not.** A setup is the part of a trial that
   brings the model to the moment the claim measures. When a claim falls below its floor because that moment seldom
@@ -391,9 +419,9 @@ recover, finish — are exercised only one scripted tool call at a time.
     Two voids stay, each a setup that did not happen. In the first, the first Turn does not pick `started` in its time:
     the run is live, and its body is in `starting`. In the second, no server answers at the `kill` Gate: a server that
     outlives its bash call is the model's job. A body that left `starting` for `faulted` (`agent.fault`) or `lost`
-    (`workspace.lost`) invokes `fail`, and the run ends `failed`. It is not void, and it fails "every trial finished",
-    as the finished rule above says. The bound stays half the trials, rounded up. Rejected: a larger bound for
-    `noticed`, and a fault in `starting` counted as void.
+    (`workspace.lost`) invokes `fail`, and the run ends `failed`. It is not void: it did not finish, so it is a miss, as
+    the finished rule above says. The bound stays half the trials, rounded up. Rejected: a larger bound for `noticed`,
+    and a fault in `starting` counted as void.
 
     Two more voids are new. In the first, the kill does not take the server. The guard's list (`GET /memory-kills`,
     91699c24) holds no new kill, or the port still answers after the hog. Then the exec fails, or the kernel's OOM