@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -45,11 +45,13 @@ loudly narrated, safe to re-run:
   ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). Referenced-but-unmanaged Secrets
   (`envFrom` refs, git credentials) are **preflighted**: `up` fails naming the missing Secret with the exact creation
   hint — converting the `CreateContainerConfigError` hang into an immediate error. Sealed Secrets/External Secrets ride
-  this seam untouched: jr2's contract is "a Secret named X exists", however it got there. A credential the Harness uses
-  is a held secret ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): `up` writes a
-  literal value into `jr2-held-secrets-<pod>` for each pod that names it, which only that pod's Custodian mounts, and
-  checks that a referenced Secret and key exist. Like the signing key, the held-secret CA (`jr2-held-ca`) is kept across
-  converges — minted on first need, never rotated by `up` — because a live pod trusts it.
+  this seam untouched: jr2's contract is "a Secret named X exists", however it got there. `up` also refuses a held
+  secret's name that is a key of an `envFrom` Secret, and names the Secret, the key and the held secret (ADR-0059, R14).
+  A credential the Harness uses is a held secret
+  ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): `up` writes a literal value into
+  `jr2-held-secrets-<pod>` for each pod that names it, which only that pod's Custodian mounts, and checks that a
+  referenced Secret and key exist. Like the signing key, the held-secret CA (`jr2-held-ca`) is kept across converges —
+  minted on first need, never rotated by `up` — because a live pod trusts it.
 - **Repos**: `up`'s walk of the registered Machines collects every bound Repo Slot (ADR-0049, ADR-0051) — to refuse an
   open slot nobody bound, and to see which urls need a key. The Orchestrator creates one `Repo` resource per url at
   boot, and the operator's cache agent clones each onto the nodes that need it (ADR-0004). There is no `repos` config
@@ -59,11 +61,17 @@ loudly narrated, safe to re-run:
   in-cluster deploy keypair (the recommended default, public key printed to register), a local key, or one pasted on
   stdin ([ADR-0047](0047-the-git-ssh-key-source-is-the-users-choice.md)) — declining bails. A personal key never enters
   a cluster silently: only by that explicit, warned choice.
-- **Provider preflight**: `up` checks each provider that a carried model names. It checks from inside the cluster, with
-  one trivial tool-call completion. An endpoint that the pods cannot reach, a wrong or missing key, or a vLLM without
-  `--enable-auto-tool-choice` then fails at converge time, not as `agent.fault` in a run. Reachability is the user's
-  concern (`localhost` never works from a pod; a LAN address does on kind). The check must take the path that the
-  Harness takes. If it does not, a pass means nothing.
+- **Landlock**: `up` refuses to converge while a Sandbox node lacks Landlock. It reads the pods of the Repo cache
+  agent's DaemonSet, which probe Landlock on each Sandbox node, within the rollout wait it already makes for the cache.
+  It is an ordinary converge failure: it names each node whose agent reports none, the probe's reason, and the fix (keep
+  the node out with `sandbox.nodeSelector` or a taint, ADR-0052, or enable Landlock); a run after the fix converges
+  ([ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)).
+- **Provider preflight**: `up` checks each provider that a carried model names, and the tool list of each remote MCP
+  server that an Agent names (below). It checks from inside the cluster, with one trivial tool-call completion for a
+  model. An endpoint that the pods cannot reach, a wrong or missing key, or a vLLM without `--enable-auto-tool-choice`
+  then fails at converge time, not as `agent.fault` in a run. Reachability is the user's concern (`localhost` never
+  works from a pod; a LAN address does on kind). The check must take the path that the Harness takes. If it does not, a
+  pass means nothing.
   - **One path for every provider.** `up` checks the custom provider (`harness.provider`, ADR-0018) and a provider of
     pi's catalog (for example `anthropic/…`) in the same way. A key of either is a held secret, and only a Custodian can
     use it ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). So no key enters a pod
@@ -75,14 +83,17 @@ loudly narrated, safe to re-run:
     the config, each model's result says why, in words.
   - **The check pod.** It is a Harness pod with no Harness in it. It has a Custodian and the stock Harness image's
     `provider-preflight.ts`. The function that composes the Custodian of every Harness pod composes this Custodian too.
-    Its token is a value that the Orchestrator never signed. `provider-preflight.ts` gets the env of the Harness
-    container: the harness config, `harness.env`, `harness.envFrom`, the Stand-ins, the proxy and the trust. pi resolves
+    Its token is a value that the Orchestrator never signed. Its Stand-ins are secret and its own: `jr2 up` mints them
+    with the signing key, as it does for the Instance Harness
+    ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). The check pod runs no Workspace
+    code, so it may hold them in env. `provider-preflight.ts` gets the env of the Harness container, with the Stand-ins
+    in it: the harness config, `harness.env`, `harness.envFrom`, the Stand-ins, the proxy and the trust. pi resolves
     each model and uses its api, as in a Turn. The `harness.catalog` gateway applies. The key never enters the check
     container, its argv or its log.
   - **Its own objects.** The check pod reads no object of the Instance. `up` writes copies from the values on the host:
     - a ConfigMap with the Custodian's files, the program and the harness config;
     - a ConfigMap with the trust bundles;
-    - a Secret with the token and the literal values of the held secrets;
+    - a Secret with the token, the check pod's Stand-ins and the literal values of the held secrets;
     - a Secret with the leaves;
     - a Secret with the literal `harness.env` values.
 
@@ -96,8 +107,8 @@ loudly narrated, safe to re-run:
       model runs where the Instance Harness runs.
     - The held set: a pod that holds a secret sends its HTTPS through its Custodian, and a tunnel carries a host that no
       secret is bound to. A pod that holds no secret sends its HTTPS direct. So the check pod holds the held set of the
-      first pod of its class, and the keys that the other pods of the class hold. A class that holds nothing gets a
-      check pod that holds nothing.
+      first pod of its class, and the keys and the MCP server secrets that the other pods of the class hold. A class
+      that holds nothing gets a check pod that holds nothing.
 
     When no pod of the class holds a key of the provider, the check pod holds none. Then pi refuses the call
     (`not configured`), and the converge fails. A signing credential in `harness.env` reaches the check pod, as it
@@ -105,6 +116,16 @@ loudly narrated, safe to re-run:
     knows, and for which jr2 knows no key name, is checked with no held key, as a Turn runs it. The check pod has the
     priority class of the Sandbox tier, as the Harness pods have (ADR-0060).
 
+  - **MCP servers.** The check pod also checks each remote MCP server that an Agent of its class names
+    ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). It
+    reads the server's `tools/list` through its Custodian, with the Stand-in of the server's secret, as a Turn reads it.
+    An allowlisted tool name that the list does not have fails the converge, and the result names the server and the
+    tool. A server that refuses the request (a 401 or a 403: a wrong or expired token) fails the converge, as a model
+    key that the provider refuses does. A server that does not answer is a warning: the first Turn of a conversation
+    fails with a named error when the server does not answer then. A stdio server is not checked: it runs as Workspace
+    code in the Sandbox, and the check pod runs none. Each server has 60 s for its whole listing, after the models. Two
+    literals set it, `PREFLIGHT_MCP_BUDGET_SECONDS` in `preflight-line.ts` and `CHECK_MCP_SECONDS` in `up.ts`, and a
+    test holds them equal. The pod writes the list, and `up` compares it with the allowlists.
   - **The request.** The check's request shares these with a Turn's: the model, its api, its endpoint and key, the
     completion limit (what pi-ai sends for a Turn), the retries, no forced tool, and the level of a definition with no
     `thinkingLevel` (`off`: no `reasoning` is sent). It does not share these: it has no system prompt, one tool, no
@@ -185,16 +206,18 @@ loudly narrated, safe to re-run:
 
     It never deletes the objects of another Instance.
 
-  - **Skipping it.** `jr2 up --skip-provider-preflight` runs no check pod. A check can fail when the model works, for
-    example when a model loads for longer than the check waits. That fault must not stop every converge until jr2 is
-    fixed. The skip is never silent: `up` writes one warning line, which names each model that it did not check. `up`
-    still deletes the leftovers of earlier runs, because their Secrets can hold a key. The flag has no config key,
-    because no flag of `up` has one (CI gives `--yes` as a flag). A model that does not work then fails in a run, as
-    `agent.fault`.
+  - **Skipping it.** `jr2 up --skip-provider-preflight` runs no check pod, so it checks no model and no MCP server's
+    tool list. A check can fail when the model works, for example when a model loads for longer than the check waits.
+    That fault must not stop every converge until jr2 is fixed. The skip is never silent: `up` writes one warning line,
+    which names each model and each MCP server that it did not check. `up` still deletes the leftovers of earlier runs,
+    because their Secrets can hold a key. The flag has no config key, because no flag of `up` has one (CI gives `--yes`
+    as a flag). A model that does not work then fails in a run, as `agent.fault`.
   - **A limit.** The check pod has labels of its own. It does not get the labels of a Harness pod: the Instance Harness
     Service selects its pods by label, and would send Turns to the check pod. So a NetworkPolicy that selects Harness
     pods by label does not select the check pod. When such a policy closes the egress of the Harness pods, the check can
-    pass while a Turn fails.
+    pass while a Turn fails. jr2's own egress policy, which closes the cloud metadata addresses
+    ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)), gives the check pod one
+    of its own, so it does not have this limit.
 
 **`jr2 down`** removes the instance from the cluster. It asks for confirmation unless `--yes` is given (for CI). `--all`
 takes the operator too.
@@ -217,8 +240,9 @@ takes the operator too.
   instance error with "not deployed here — right context?". This is the guardrail against silently pointing at the wrong
   cluster, without a state file that can itself go stale.
 - **CLI transport**: run-verbs port-forward the Orchestrator Service via the kube API for the duration of the command
-  and read the Instance token from its Secret — kube RBAC is the real gate. `--url`/`JR2_URL` (+ token env) is the
-  escape hatch for ingress-exposed instances and callers without cluster creds.
+  and read the Instance token from its Secret — kube RBAC is the real gate. `--url`/`JR2_URL` (+ token env, any Caller's
+  credential, [ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)) is the escape
+  hatch for ingress-exposed instances and callers without cluster creds.
 - **A dead ADDRESS and an absent IDENTITY are two faults, and resolution names which.** They share a verb and a context
   but not a fix: one is the network, the other is `jr2 up`. A cluster that answered and holds no instance Secret is "not
   deployed here — right context?"; a cluster that could not answer at all is "cannot reach the cluster — context X: …",
@@ -262,9 +286,11 @@ from env.
 
 ## Consequences
 
-- The everyday story is two commands ever: `jr2 init`, `jr2 up`. The full CLI: `init`, `up`, `down`, `gc` (ADR-0039),
-  `run`, `runs`, `status`, `logs`, `send`, `kit push` (ADR-0044), plus the workspace verbs `ls`, `ssh`, `rm` (ADR-0009;
-  decided, not yet in the binary).
+- The everyday story is two commands ever: `jr2 init`, `jr2 up`. The rest of the CLI is in ADR-0009's table, and the
+  workspace verbs `workspace ls|shell|forward|rm` are among them.
+- **The workspace verbs are not run-verbs.** They address the Sandbox CRs of the current context with its kube
+  credentials alone: no port-forward to the Orchestrator, no Instance token and no Caller scope. So they work when the
+  Orchestrator is down, and kube RBAC on the Sandbox CRs and their pods is the whole gate.
 - **Simplification must not surprise**: `up` prompts exactly when meeting a cluster that isn't yet home, and run-verbs
   print the context they're talking to — the ambient-context magic stays visible.
 - The snapshot store (sqlite) moves onto a PVC in the instance's namespace; `.jr2/` shrinks to scratch.

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

@@ -31,7 +31,8 @@ end. And a restarted Harness answered a `continue` with no memory of the convers
   Sandbox goes to the terminal phase **`Lost`**, with the pod's own reason and message (for a deleted pod, the last it
   saw). It never returns to `Pending` and is never given a second pod: `work` is an `emptyDir`, so a new pod could
   continue nothing, and it would hold a whole Size for nobody while hiding the loss. The CR stays, so `jr2 status` can
-  say why, until teardown or the idle GC.
+  say why, until teardown or the idle GC. A Sandbox delete waits for its pod, because a retry can take the name of a pod
+  that is still going away.
 - **The operator judges identity, because it knows which pod it created.** It still publishes `status.podUID`; the
   Orchestrator reads `Lost`, not a UID comparison.
 - **The watch answers; the lease asserts.** The Orchestrator watches its Sandboxes
@@ -56,6 +57,19 @@ end. And a restarted Harness answered a `continue` with no memory of the convers
   attached pod. Its lifetime is the state's lifetime, which xstate already manages: it re-invokes on snapshot restore,
   so restore-reconcile stops being a special case and becomes the first tick of the normal loop; and it stops on every
   exit — body final, run stopped, run faulted.
+- **The Lease marks its hold on the CR.** The CR's first write sets the annotation `jr2.dev/hold: held`, and each
+  renewal writes it again. When the Lease stops for the body's final state, a fault, a cancel or a parent that leaves
+  the Workspace's state, it sets `jr2.dev/hold: released` and renews no more. A defect that a parent catches does not
+  stop the Lease, because xstate stops no child of a Machine that ended in error: at its next renewal the Lease sees
+  that its Workspace is over, and sets `released` then. A Lease does not set `released` on a name that a live Workspace
+  of the run holds: a parent that catches the defect can invoke the same Machine again, and the new Workspace gets the
+  same Sandbox name and a Lease of its own. A step of the wrapper from one state to the next writes nothing: the next
+  state has a Lease of its own. A park (`RunHost.stop`, [ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)) and a
+  process shutdown write nothing, so a crash keeps the mark `held` and the restored run's Lease writes it again. A
+  restore that ends a run `drifted` or `lost` without hosting it starts no Lease, so the Orchestrator sets `released` on
+  each CR with that run's `jr2.dev/run` label. So `jr2 workspace rm` tells a held Sandbox from a free one with the
+  cluster alone ([ADR-0009](0009-cli-and-instance-interface.md)): the keepalive's age cannot tell it, because a renewal
+  can be late by more than one interval and a few missed renewals are survivable.
 
 That last point deletes machinery rather than adding it. Three mechanisms with three different owners and lifetimes —
 the process-global heartbeat map, the one-shot probe, and `release(runId)` (which label-queried the cluster to stop
@@ -97,4 +111,4 @@ behavior `release()` was written to produce is emergent.
   independently. This falls out of invoking it beside the body rather than owning it at the host.
 - `SandboxPort` has no optional method: `renew` is a write, `continuity` is a subscription to the watch, and
   `memoryFault` (ADR-0061) answers undefined from a backend that cannot see the container. The `jr2.dev/run` label
-  survives for `jr2 ls` and as the watch's selector, no longer load-bearing for lease bookkeeping.
+  survives for the `jr2 workspace` verbs and as the watch's selector, no longer load-bearing for lease bookkeeping.

package/docs/reference/decisions/0022-observation-is-a-level-triggered-feed.md

@@ -34,8 +34,8 @@ can get away with fetching once, because a person can press a button; an API can
   so there is no gap to detect and no cursor to resume from. Same reconciliation idiom as the Lease (ADR-0021) and
   `jr2 up` (ADR-0019): say the whole truth, repeatedly, and let the reader converge.
 - **Two granularities, one vocabulary.** The per-run feed stays — tracking exactly one run is a legitimate thing to
-  want, and it is what `jr2 run` and `jr2 logs -f` already do. Every run-scoped frame carries `runId` even where the
-  route makes it redundant, so one parser serves both.
+  want, and it is what `jr2 run` and `jr2 watch` do. Every run-scoped frame carries `runId` even where the route makes
+  it redundant, so one parser serves both.
 - **`gone` is a fact, not an inference.** A run can leave the live set _without_ a terminal status: `stop()`
   deliberately leaves the stored status `"live"` so a later `restore()` picks the run back up. A client watching for
   `status === "done"` would show a stopped run as live forever, so departure is stated outright.
@@ -48,7 +48,7 @@ can get away with fetching once, because a person can press a button; an API can
   which is why it is wired to the handler's exit.
 - **A settled run is the client's own memory.** A run appears in the page's `settled` list iff _this page_ watched it
   leave. After a hard reload they are gone, and that is correct rather than a defect: serving a finished run's state to
-  an unauthenticated reader is a read-through, which stays behind the Instance token on `/runs/:id` (ADR-0014).
+  an unauthenticated reader is a read-through, which stays behind the `read` scope on `/runs/:id` (ADR-0014).
 - **`jr2 visualize` is deleted.** Its job was to find an orchestrator, forward a port, and open a browser. With the page
   now useful on its own, that is one `kubectl port-forward` the reader already knows how to run — and the command's
   ephemeral-fallback path was quietly forwarding to a _different_ instance than the deployed one. Its one unique piece
@@ -61,7 +61,7 @@ can get away with fetching once, because a person can press a button; an API can
   tick, and a reader that keeps up drains them before any ping judges it. Closing is safe because the feed is
   level-triggered: the client reconnects and receives the whole current truth, having missed no state — only activity
   (Emits, retries) that fell in the gap. A page reconnects with EventSource's own retry; the CLI (`jr2 run`,
-  `jr2 logs -f`) re-attaches any feed that ends before a terminal status, and never reads such an end as the run's —
+  `jr2 watch`) re-attaches any feed that ends before a terminal status, and never reads such an end as the run's —
   except `gone`: a run stopped before it settled (parked, ADR-0025) reads through as `active`, so its one-shot feed says
   `gone` after the status, and the CLI ends there instead of re-attaching in a loop. The server keeps no per-client
   queue and no slow-client accounting beyond counting the subscriber's writes (scaling review R10, 2026-09-30).

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

@@ -1,4 +1,4 @@
-# The Harness prints the conversation, and the reasoning is the part that prints
+# The Harness prints the conversation and the Orchestrator keeps it, and the reasoning is the part that prints
 
 A running workflow is watchable and its Agents are not. The visualizer shows which states are lit (ADR-0022); the run
 feed carries status and Emits (ADR-0009). What an Agent is actually _doing_ — what it read, what it tried, what it
@@ -16,12 +16,18 @@ both user and assistant messages, plus text, thinking, and tool-call content
 ([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)) — every line of that jq filter,
 replayable from any offset. The gap was a read decision, not a missing capability, and the fix is not new plumbing.
 
+**A conversation that lives only in its pod is gone when a person needs it.** A run that failed overnight is read the
+next day. By then its Sandbox is torn down (ADR-0012) or reaped (ADR-0021), and the log plane, if the cluster has one,
+is not jr2's and is not always there. So the print stays for the cluster's log plane, and the Orchestrator also keeps
+each conversation for as long as it keeps its run.
+
 ## Decision
 
 - **The Harness prints, and `kubectl logs` reads.** The Harness writes its own conversation to container stdout —
   in-process; the loopback subscription this originally required retired with the foreign runtime (ADR-0027).
-  `kubectl logs`, `stern`, `k9s`, and any log shipper work on it the day it lands, with no jr2 surface to build, learn,
-  or version.
+  `kubectl logs`, `stern`, `k9s`, and any log shipper work on it, with no jr2 surface between them and the pod. The
+  print stays when the Orchestrator keeps the conversation (below): a cluster that ships its logs reads every
+  conversation in one place, with its own retention.
 - **The Harness is the right seat because it already holds both halves of the label.** It knows its Agent's name and the
   iid arrives per Submission. So a line is `[<agent>] [<iid>] …` with no lookup, no correlation table, and no
   orchestrator round trip. Every line of a body carries both, the later lines of a body that spans lines too. The iid is
@@ -34,11 +40,14 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
   invisible to every other jr2 process there.
 - **Reasoning prints, and so does each pick's answer; a Working tool's result does not.** Prompts, assistant text,
   thinking, tool calls with truncated inputs, and the answer to each Menu pick. The file contents, command output, and
-  API responses a Working tool returns never print. This is one cut serving two purposes, which is why it is a boundary
-  and not an unfinished implementation: a Working tool's results are whatever the Agent happened to read, which is where
-  a leaked secret lands, and they are also most of the bytes. A pick's answer is one bounded text per pick, and the
-  bullet below states what it can still carry. Every user message the model reads prints as a prompt — the Frame's
-  prompt with its Turn part, a nudge, and a Turn part the Harness restated at a step boundary
+  API responses a Working tool returns never print, and neither does the result of an MCP tool
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)), for
+  the same reasons. An MCP call prints as `<server>/<tool>`, so it never prints as a pick does. This is one cut serving
+  two purposes, which is why it is a boundary and not an unfinished implementation: a Working tool's results are
+  whatever the Agent happened to read, which is where a leaked secret lands, and they are also most of the bytes. A
+  pick's answer is one bounded text per pick, and the bullet below states what it can still carry. Every user message
+  the model reads prints as a prompt — the Frame's prompt with its Turn part, a nudge, and a Turn part the Harness
+  restated at a step boundary
   ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)), which prints once as
   `[<agent>] [<iid>] [prompt] <jr2-turn>` where the model read it.
 - **A pick's answer prints after its call, as the model received it.** A Menu call's result is jr2's own text: the
@@ -91,6 +100,63 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
 - **The writer structures, the reader colorizes.** Lines carry a parseable prefix and no ANSI. jr's colors were correct
   for an fzf preview, which is a terminal; `kubectl logs` output is piped, grepped, and ingested, where escape codes are
   corruption. A future reader may colorize on `isatty`.
+- **The Harness also sends the conversation's entries to the Orchestrator, during the Turn.** The entries are jr2's own
+  shape, not pi's: one entry for each body that the print makes, with the same cut — a prompt, the model's text, its
+  thinking, a call with its input cut to the print's bound, a pick's answer, a mechanic line — and never a Working
+  tool's result or an MCP tool's result. A body that spans lines is one entry. Only a body that carries an iid is an
+  entry. The narrative echo (below) is not: the Orchestrator already holds those events in its feed. An entry is
+  `{ id, seq, at, agent, kind, text }`: `kind` is the body's label (`prompt`, `text`, `thinking`, a tool's printed name,
+  `<pick> answer`, `compacted`), `text` is the rest of the body, and the Orchestrator sets `agent` from its ledger.
+  `seq` goes up for as long as the iid is kept. A new record starts it at the clock, not at 0, because a conversation
+  that the Harness lost with its pod starts again under the same iid, and its new entries must come after the old ones.
+  An entry is made when it is complete (at `message_end` for the model's words), so text and thinking deltas are not in
+  it. The Harness writes each entry locally first, and then sends the entries in batches to the Orchestrator while the
+  Turn runs, on `POST /agents/<iid>/conversation`, through its Custodian, with its pod's control token
+  ([ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md),
+  [ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): a Sandbox's control token, or the
+  Instance Harness's own control token, which is signed for its placement. The Instance token is never one of them. The
+  route takes entries only for an iid that the run's admission ledger places in the token's pod, and only when the slot
+  that the Harness states is the ledger's
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). It checks the ledger, not
+  the live registration: the ledger outlives the Turn and the run's end, so a batch that comes after the Turn's sweep or
+  after the run ended is still kept, and those are the entries that tell how a run ended. The Harness starts a send of
+  its pending entries when the model's answer ends (before its picks run) and at a Turn's end, and does not wait for it.
+  On SIGTERM it tries again for a few seconds. In a Sandbox the Custodian can exit first
+  ([ADR-0001](0001-operator-owned-generic-sandbox.md)), so the entries since the last send (about one second) can be
+  lost. While a live run's ledger does not name the iid yet (the batch came before the admission's save), the route
+  answers 409 and the Harness sends the batch again. The Instance-token door of ADR-0013 does not open it: a holder of
+  the Instance token can speak as an Agent, but it cannot write an Agent's kept conversation. Each entry's `seq` makes a
+  send idempotent: the Orchestrator keeps each `seq` of a conversation once, so a batch that the Harness sends again
+  after a failure or a restart adds nothing twice. A batch that fails stays in the local copy and goes with the next
+  batch. Menu-only Agents send the same way, from the Instance Harness
+  ([ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md)). The kept conversation holds what the print holds:
+  no Working tool's result and no MCP tool's result, but the residual of a pick's answer stated above (a Held value that
+  an upstream echoed into a `command` Effect's output, an Effect secret in a form that the scrub does not catch). The
+  Orchestrator keeps that residual for `runs.retain`, behind `read`.
+- **The Orchestrator keeps it in `conversations.db`.** It is a second SQLite file beside `state.db` on the
+  Orchestrator's state volume ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)), with
+  plain JSON rows, so a person or a tool can query it with SQLite alone. It is a second file because its writes are
+  larger and more frequent than a snapshot's, and its sweep frees pages: neither must slow the snapshot's synchronous
+  write. The file sets `auto_vacuum = INCREMENTAL` at its creation, and each sweep frees the pages that it emptied, so
+  the file gets smaller after a sweep. A kept conversation has a cap of 8 MiB. When an entry would go above it, the
+  Orchestrator keeps no more entries of that conversation and writes one marker entry that says so, and the
+  conversation's `cut` is true. The cap keeps the start of a long conversation, which is the part that tells why the
+  Agent did what it did. A kept conversation goes with its run: when ADR-0065's sweep deletes the run's row, it deletes
+  the run's conversations, and the space guard there deletes the oldest kept conversations of ended runs first. There is
+  no compression in the kept conversations now. Compression can come later and stays internal: Node's own zstd on the
+  entry text, with the queryable columns kept.
+- **`jr2 logs` and the Console read the kept conversation.** `GET /runs/:runId/conversations` lists a run's
+  conversations, `[{ agent, slot, instanceId, open, bytes, cut }]`.
+  `GET /runs/:runId/conversations/:instanceId?after=<seq>` gives the entries after a sequence number, and `.../events`
+  follows a conversation as SSE while it is open (the iid is URL-encoded in the path, because it holds `/`). A
+  conversation is open while a Turn of it is registered on a live run; the feed ends a few seconds after it is not open,
+  so the batch that a Turn's end sends is still read. A conversation that the space guard swept lists
+  `swept: "no space"`, and its run says `swept: "conversation swept: no space"` in `GET /runs/:runId` and `GET /runs`.
+  The `read` scope opens all three ([ADR-0014](0014-observation-is-open-run-state-is-not.md)).
+  `jr2 logs <run> [agent] [-f]` prints the run's conversations, or one Agent slot's, in the printed form of this ADR,
+  Menu-only Agents too, and `-f` follows them until the run ends ([ADR-0009](0009-cli-and-instance-interface.md)). The
+  Console shows a conversation in its bottom drawer ([ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)).
+  An ended run reads the same as a live one, for as long as the run is kept.
 - **A Harness also prints the run's narrative — feed events the Orchestrator pushes to an echo endpoint.** A Workspace's
   pod log should read as the whole story of the run that owns it: not just the conversations hosted there, but the
   decisions and Emits that happened around them — a ticket claimed before the Workspace existed, a Menu pick a
@@ -113,33 +179,47 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
   transition. The replay buffer follows the same rule: it keeps the markers and Emits (bounded) and the latest status,
   so the preamble reads "the story so far, and where the run stands now" — old statuses are not interleaved between old
   markers; the live tail keeps the interleaving (scaling review R10, 2026-09-30).
-- **Pod-bound, and jr2 promises nothing beyond the pod.** A conversation lives as long as its Sandbox (ADR-0027,
-  ADR-0031), so a Sandbox teardown (ADR-0012) or a lost Workspace (ADR-0021) takes it with it — the same contract
-  ADR-0012 already set for the pod-local clone. A cluster that ships logs will outlive the pod anyway; that is the log
-  plane's property, not a jr2 guarantee, and no jr2 behavior may come to depend on it.
+- **The print lasts as long as the pod; the kept conversation lasts as long as the run.** A pod's log goes with its
+  Sandbox (ADR-0012, ADR-0021) and rotates at the kubelet's bound; a cluster that ships logs keeps them by its own
+  rules, and no jr2 behavior depends on that. The kept conversation is jr2's: it is kept while its run is kept
+  (`runs.retain`, ADR-0065), and `jr2 logs` reads it after the Sandbox is gone.
 
 ## Considered options
 
 - **Per-`agentRun` containers, or a pod per Agent.** Rejected on lifetime before merit: the container list is fixed when
   the CR is created, before the body has run, while `agentRun` is a per-turn invocation. Pre-declaring per _Agent_ is
-  possible but pays N resident copies of a Harness image that deliberately carries the agent toolchain (ADR-0005) to run
-  one at a time. It buys no isolation — containers in a pod share the network namespace, so it does not even fix the
-  port contention that motivates it (ADR-0005:31) — and the git contention it would address is prohibited anyway
-  (ADR-0004:95). What it actually buys is `kubectl logs -c <agent>`: a container, to avoid a prefix.
+  possible but pays N resident copies of a Harness image that deliberately carries the agent toolchain (ADR-0005). It
+  buys no isolation — containers in a pod share the network namespace, so it does not even fix the port contention that
+  motivates it (ADR-0005:31) — and it does not remove the git contention, because the containers share one `/work` and
+  one clone (ADR-0004). What it actually buys is `kubectl logs -c <agent>`: a container, to avoid a prefix.
 - **A trace from the Custodian.** Tempting, and wrong on the facts. The Custodian carries the Menu's reads and the
   Agent's picks — a handful of deliveries per turn — and the model calls, and it logs names only, never a body
   ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). The Agent's working tools execute in
   the Harness, never touching it. A Custodian trace shows `action=intercept … method=POST` and none of the four things
   worth watching.
-- **Tee the stream host-side, in the Orchestrator** (the one place holding an admission and an open stream). Genuinely
-  viable, and better on governance: addressable by run, and `instanceOnly` puts it behind the band ADR-0014 already
-  enforces. Rejected as the larger build for the smaller reader — it needs an API, a CLI, and a format, to serve a
-  reader `kubectl` already serves. Not foreclosed: it reads the same stream, so it remains the answer if the exception
-  below stops being acceptable.
-- **Persist transcripts beside the run snapshot.** Rejected: the Harness already serves the stream replayable from any
-  offset for the life of the pod (ADR-0027), and jr2 holds the coordinates in the admission ledger (`run-host.ts:651`);
-  copying the contents buys retention in exchange for owning growth, retention policy, and a redaction surface, in a
-  store defaulting to sqlite.
+- **Keep no conversation past its pod.** The Harness serves the stream from any offset for the life of the pod
+  (ADR-0027), and a copy costs growth, a retention policy and a redaction surface. Rejected: a conversation that goes
+  with its pod is gone when a person needs it most, after a run failed. What a copy costs is bounded: `runs.retain` sets
+  the retention (ADR-0065), a cap for each conversation and a space guard bound the growth, and a kept conversation
+  holds only what the print holds: never a Working tool's or an MCP tool's result, but the residual of a pick's answer
+  stated above, behind `read` for `runs.retain`.
+- **The Orchestrator reads the Harness's stream and writes the kept conversation.** Rejected: the Orchestrator holds a
+  stream only while it waits on a Submission, so a restart of the Orchestrator loses what the stream sent in the gap,
+  and the Orchestrator would have to render pi's events, which is the Harness's craft. The Harness makes the print, so
+  it makes the entries, with the same cut.
+- **Read the conversation from the pod logs.** Rejected: the Orchestrator has no RBAC on Pods and must not get it for
+  this, and the kubelet rotates a log at 10Mi, so a long Turn loses its start before anyone reads it.
+- **Copy the conversation at the end of the run.** Rejected: a pod that dies (an eviction, a lost node, a memory kill)
+  takes the copy with it, and that is the run a person wants to read. The entries go to the Orchestrator during the
+  Turn.
+- **A separate archive service.** Rejected for now: every system with a run store keeps its history in that store, fed
+  by the worker during the run, and a separate archive (Tekton Results, Temporal's archival, Argo's archive) is an
+  optional extra beside it. jr2 has a run store, so the store keeps the conversations, with no new component to deploy.
+- **Files, one for each conversation.** Rejected: a sweep, a cap, a list with sizes and a read after a sequence number
+  are each a query in SQLite, and each is code of jr2's own over files. SQLite is already the Orchestrator's store
+  (ADR-0065), and it gives the space back with an incremental vacuum.
+- **`sqlite-zstd` for compression.** Rejected: it is a native extension under the LGPL, which its author calls not ready
+  for production. Compression, when it comes, is Node's own zstd on the entry text.
 - **Print a Working tool's results, truncated.** Rejected: the first 200 bytes of a leaked config is where the good
   stuff is, and the volume it re-admits is what kubelet's 10Mi rotation would then silently discard — losing the _start_
   of a long turn, which is the part worth reading. A `command` Effect's output does print, inside its pick's answer and
@@ -153,24 +233,25 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
   ADR-0058), so Emit payloads may ride it — the tokenless observation band still carries Emit types alone. What it does
   widen is the pod-log surface: a run's narrative becomes readable by whoever can read the Workspace pod's logs, the
   same audience the conversation bullet below already grants.
-- **A scoped exception to ADR-0014**, recorded there. Observation is open and everything sensitive sits behind
-  `instanceOnly`; this puts an Agent's reasoning, and the answers jr2 gave its picks, in front of whoever can read pod
-  logs. Excluding a Working tool's results bounds it to what an Agent reasons aloud and what jr2 told it, rather than
-  what it happened to read; what jr2 told it includes an Effect's output, so a `command` Effect's output and a Held
-  value echoed into it reach the log as they reach the model, and so does an Effect secret in a form an Effector's scrub
-  does not catch (a transformed secret, a partial echo; ADR-0068). Fine on kind; a real decision on a shared cluster.
-- **It depends on an invariant that is documented but not enforced.** One Agent at a time per Workspace (ADR-0004:95,
-  "structural since ADR-0012") is what makes two conversations never interleave on one container's stdout. Nothing
-  refuses a body that invokes concurrent `agentRun`s; such a body corrupts a shared `default/.git` before it garbles a
-  log, so enforcement is owed on its own merits — the ambient registrar (ADR-0012:32, ADR-0016) is the one thing that
-  sees every Agent in a Workspace, and the place to refuse a second concurrent admission.
+- **A scoped exception to ADR-0014**, recorded there. Observation is open and everything sensitive sits behind a
+  Caller's scope; the print puts an Agent's reasoning, and the answers jr2 gave its picks, in front of whoever can read
+  pod logs. The kept conversation is not part of the exception: it is behind `read`. Excluding a Working tool's results
+  bounds it to what an Agent reasons aloud and what jr2 told it, rather than what it happened to read; what jr2 told it
+  includes an Effect's output, so a `command` Effect's output and a Held value echoed into it reach the log as they
+  reach the model, and so does an Effect secret in a form an Effector's scrub does not catch (a transformed secret, a
+  partial echo; ADR-0068). Fine on kind; a real decision on a shared cluster.
+- **The conversations of concurrent Agents interleave in one log.** The author chooses how many Agents work in a
+  Workspace ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), so two conversations can
+  print at one time on one container's stdout. The prefix keeps them apart: every line carries its label and its iid, so
+  a reader keeps one conversation's lines by its iid.
 - **Truncation is load-bearing, not cosmetic.** Kubelet rotates container logs at 10Mi by default and drops the
   remainder. jr's filter capped `Bash` at 100 chars and unknown tools at 150 and reduced `Write`/`Edit` to a path; that
   was readability, and it is now also what keeps a long turn inside the window.
-- **Live tails may miss partial output.** Text and thinking deltas are best-effort live progress, with `message_end`
-  authoritative, so a reader that attaches mid-generation can miss earlier fragments until they arrive. Correct for a
-  watcher; anything wanting exactness reads the completed message.
-- **`jr2 logs` remains a status feed** and is now more confusingly named than before. Not renamed here — this ADR adds
-  no command — but the collision is real and belongs to whoever next touches that surface.
-- **The visualizer's eventual extension has a source.** When it grows past the graph, it reads the same stream; a page
-  is a third reader of one feed, not a third way of collecting the data.
+- **Live tails of the print may miss partial output.** Text and thinking deltas are best-effort live progress, with
+  `message_end` authoritative, so a reader that attaches mid-generation can miss earlier fragments until they arrive.
+  Correct for a watcher; anything wanting exactness reads the kept conversation, which holds the completed message.
+- **`jr2 logs` prints conversations, and `jr2 watch` prints a run's status feed**
+  ([ADR-0009](0009-cli-and-instance-interface.md)). A pod's log stays `kubectl logs`.
+- **The Orchestrator's state volume holds the kept conversations.** Its default size is `5Gi` (`runs.volume`, ADR-0065).
+- **The Console's conversation drawer has a source.** It reads the kept conversation through the routes above; it is a
+  reader of one store, not a second way of collecting the data.

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

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