@jr2/orchestrator 0.6.0 → 0.7.0

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,10 +179,10 @@ 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
 
@@ -131,15 +197,29 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
   ([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,12 +233,13 @@ 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.
+- **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
@@ -166,10 +247,11 @@ replayable from any offset. The gap was a read decision, not a missing capabilit
 - **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

@@ -213,43 +213,44 @@ prevented it writing. An un-ended turn is a concurrent writer in a Workspace tha
   root Gate, an outside send), nor a child's error: every outcome of work is its output, and an error is a jr2 or config
   defect, so by default its message never reaches the model. The operator reads it: while a pick is outstanding, an
   error from a child below the Agent's state goes on the run's feed (`child-error`: the Agent, its pick, the child and
-  the message; Instance-token band, as `fault` is), and `jr2 run` and `jr2 logs` print it. An author who wants the Agent
-  told passes it explicitly: `answer(...)` on the `onError` route (ADR-0067), or an `onError` route to a state whose
-  prompt carries it. With none, the answer carries no reply, and its words say only that ("No reply came back for it"):
-  never that nothing ran, because a timer or an outside event may have stopped work that did run. The pick's `POST`
-  answers at once with `outstanding` and a delivery id, and the Harness long-polls the answer inside the one tool call
-  (ADR-0002, ADR-0013). A child that settles inside the pick's own send — a decision Machine that is final as it starts
-  — replies before the `POST` answers: when that reply leaves the workflow at Rest, or out of the Agent's state, the
-  `POST` itself is the answer, with `answered` and nothing to poll. So is a guard straight back: a pick that enters a
-  state and leaves it again inside its own send (an `always` back), with no reply, leaves the state value as it was, and
-  is answered with `straightBack` — the one answer that says "it moved the workflow, and nothing ran". An outstanding
-  pick's answer never carries it. A pick that changes the state value moved to a mode, and gets the plain receipt with
-  its Allowed picks; a pick with no target went nowhere, and gets the same, as does a pick whose target is the state it
-  was taken in (it enters nothing it leaves). Every receipt that leaves the Turn open (the plain receipt, a guard
-  straight back, and an answered pick back at Rest) ends its state part with the same words, "Your turn is not over.":
-  the plain receipt once said "the workflow is still in the state that asked for this turn, so it is not over yet", and
-  real Haiku 5.5 runs stopped after it, because "it" can be the workflow or the Turn. The refusals and the notices of a
-  cut or unsent pick keep their own words. A route that leaves the Agent's state ends the Turn like any other: the poll
-  reads `turnComplete`, the next state's prompt is the author's, and the answer is a `pick-answer` notice to the Agent
-  that picked: the next Turn of the conversation the picking Turn continued (`continue: true`, ADR-0062). A FRESH
-  picking Turn's conversation is never heard again, and a later continued Turn of the same slot never made the pick, so
-  its answer goes nowhere: the ledger keeps no notice for it. The route of a reply includes the events the Machine sends
-  itself AT ONCE while it runs (a `raise`, or a `sendTo(self)` with no delay, in `onDone` or in the next state's entry):
-  a reply whose route leaves the Agent's state that way is the answer, never stopped. Something other than the route can
-  leave the Agent's state while the pick's work still runs below it — a timer the Machine set (a Turn timeout `after`, a
-  named delay, a delayed `raise` or `sendTo(self)`), an event from outside the states below, a Gate's event, the Agent's
-  own end. The exit stops that work (an invoke is stopped when its state exits), and the answer says so (`stopped`): the
-  poll reads "The workflow left the state that asked for this turn while it ran your pick, and that stopped the pick's
-  work before it finished: your turn is over.", and the next continued Turn's notice reads "Your pick `X` did not
-  finish: the workflow left the state that asked for your last turn while it ran, and that stopped it." Both keep the
-  last reply an earlier link gave, if any, and state it: an earlier link's reply is never dropped because a later link
-  was stopped. The run host tells a fired timer from an event sent at once by the scheduler's own table: it watches what
-  the actor system arms, cancels and fires (`timers.ts`, the same xstate internals as the timer table, ADR-0007). Back
-  at Rest INSIDE the Agent's state — a per-step timeout `after` on the child state that exits the work — the answer is
-  the last reply since the pick, with the Allowed picks; with no reply since the pick, the answer carries none. A
-  restored hold is the Turn of the first registration of its address in the restored tree: a restore that ends that Turn
-  and starts another at the same address before anything settles answers the pick with `turnComplete`. There is no
-  default time bound on a held Turn; the Console shows each outstanding pick "held since".
+  the 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
+  guard straight back, and an answered pick back at Rest) ends its state part with the same words, "Your turn is not
+  over.": the plain receipt once said "the workflow is still in the state that asked for this turn, so it is not over
+  yet", and real Haiku 5.5 runs stopped after it, because "it" can be the workflow or the Turn. The refusals and the
+  notices of a cut or unsent pick keep their own words. A route that leaves the Agent's state ends the Turn like any
+  other: the poll reads `turnComplete`, the next state's prompt is the author's, and the answer is a `pick-answer`
+  notice to the Agent that picked: the next Turn of the conversation the picking Turn continued (`continue: true`,
+  ADR-0062). A FRESH picking Turn's conversation is never heard again, and a later continued Turn of the same slot never
+  made the pick, so its answer goes nowhere: the ledger keeps no notice for it. The route of a reply includes the events
+  the Machine sends itself AT ONCE while it runs (a `raise`, or a `sendTo(self)` with no delay, in `onDone` or in the
+  next state's entry): a reply whose route leaves the Agent's state that way is the answer, never stopped. Something
+  other than the route can leave the Agent's state while the pick's work still runs below it — a timer the Machine set
+  (a Turn timeout `after`, a named delay, a delayed `raise` or `sendTo(self)`), an event from outside the states below,
+  a Gate's event, the Agent's own end. The exit stops that work (an invoke is stopped when its state exits), and the
+  answer says so (`stopped`): the poll reads "The workflow left the state that asked for this turn while it ran your
+  pick, and that stopped the pick's work before it finished: your turn is over.", and the next continued Turn's notice
+  reads "Your pick `X` did not finish: the workflow left the state that asked for your last turn while it ran, and that
+  stopped it." Both keep the last reply an earlier link gave, if any, and state it: an earlier link's reply is never
+  dropped because a later link was stopped. The run host tells a fired timer from an event sent at once by the
+  scheduler's own table: it watches what the actor system arms, cancels and fires (`timers.ts`, the same xstate
+  internals as the timer table, ADR-0007). Back at Rest INSIDE the Agent's state — a per-step timeout `after` on the
+  child state that exits the work — the answer is the last reply since the pick, with the Allowed picks; with no reply
+  since the pick, the answer carries none. A restored hold is the Turn of the first registration of its address in the
+  restored tree: a restore that ends that Turn and starts another at the same address before anything settles answers
+  the pick with `turnComplete`. There is no default time bound on a held Turn; the Console shows each outstanding pick
+  "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,

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

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

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

@@ -57,8 +57,8 @@ does not exist for a caller that owns tool assembly. jr2 owns the rest: the engi
   ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)). The model sent
   `bash` with `git add … && git commit …` and the pick `publish` in one model answer. In 3 of 10 trials, `publish`
   pushed before the commit existed. A `write` and a `bash` test run in one model answer had the same race. The rule is
-  for all tools, the Working tools and the Menu. The cost is that independent reads of one model answer do not run at
-  the same time. Four facts follow:
+  for all tools: the Working tools, the MCP tools and the Menu. The cost is that independent reads of one model answer
+  do not run at the same time. Four facts follow:
   - Only the first pick of a model answer runs
     ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)). The model wrote a later one before it
     read the first one's answer. The seam states two more facts, so that the Turn can find the first pick by itself. The
@@ -177,10 +177,11 @@ does not exist for a caller that owns tool assembly. jr2 owns the rest: the engi
     long as its run** (ADR-0031). The Harness persists each conversation to a directory as it goes and rebuilds it on
     boot, so a Harness restart inside a living pod keeps it; a Submission in flight at the restart settles `failed`.
     What is durable across a lost pod is Orchestrator-side — the admission ledger and snapshot
-    ([ADR-0007](0007-durable-machine-state.md)), and `wait`'s reconnect-from-offset. A conversation that is gone
-    surfaces as 404 → fault → workflow policy, the same family as `workspace.lost`. Provider-stream retry moves inside
-    the turn: the Harness states 2 retries, and pi-ai runs them (`maxRetries`) — the seat ADR-0016 delegated to flue's
-    `durability{}`.
+    ([ADR-0007](0007-durable-machine-state.md)), `wait`'s reconnect-from-offset, and the kept conversation, which a
+    person reads and no Turn continues from ([ADR-0023](0023-the-harness-prints-the-conversation.md)). A conversation
+    that is gone surfaces as 404 → fault → workflow policy, the same family as `workspace.lost`. Provider-stream retry
+    moves inside the turn: the Harness states 2 retries, and pi-ai runs them (`maxRetries`) — the seat ADR-0016
+    delegated to flue's `durability{}`.
   - **[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)'s enabling fact is reproduced
     as explicit code.** Each Submission reads `$JR2_CUSTODIAN_URL/agents/<iid>/surface` afresh and presents it to pi as
     the Menu, so the menu is per-turn with no push channel, no turn index, no second port. Menu tools keep the

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

@@ -31,9 +31,12 @@ definition can state.
   Workspace (it is this ADR's title). A string field, JSON-serializable, riding the existing ConfigMap channel unchanged
   (ADR-0018's constraint holds).
 - **`"none"` is the Menu-only Agent — and the value also names the Harness that hosts the Agent.** `"none"` withholds
-  the entire Working toolset: the Agent converses and picks from its Menu, nothing else — the decisioning persona (read
-  inputs, pick the next event). Because such an Agent touches no Workspace, it does not run in one: `"write"`/`"read"`
-  place a Turn on the enclosing Workspace's Harness; `"none"` places it on the
+  the entire Working toolset: the Agent converses, picks from its Menu and calls the MCP tools of the remote servers it
+  names
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)), and
+  runs no code — the decisioning persona (read inputs, pick the next event). "Menu-only" means "no Working tools": such
+  an Agent can also hold MCP tools. Because such an Agent touches no Workspace, it does not run in one:
+  `"write"`/`"read"` place a Turn on the enclosing Workspace's Harness; `"none"` places it on the
   [Instance Harness](0031-menu-only-agents-run-on-the-instance-harness.md), always — even when a `workspace()` encloses
   the invocation. Placement is definitional, which is this ADR's thesis extended one step: what an Agent may do to the
   Workspace decides where it runs. (`cwd` is moot for `"none"` — only Working tools consume it.)
@@ -50,6 +53,18 @@ definition can state.
 - **Two layers, one structure: the tool list is the hint, the worktree is the guarantee** — the same shape as ADR-0024's
   receipt (hint) and abort (guarantee). Neither layer alone: tools without the worktree leak through bash; the worktree
   without tools invites the model to fight its checkout instead of declining politely.
+- **An MCP allowlist is a guarantee about the credential, and jr2 offers it only where it can keep it.** An Agent's MCP
+  tools ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md))
+  spend the server's token, so the allowlist guards that token, not the Workspace. A remote server needs a list (tool
+  names, or `"*"`): the Harness offers and runs only those tools. Where Workspace code of the Sandbox in which the
+  Agent's Turns run can spend that secret, Workspace code can call every tool, so `jr2 up` refuses a list and takes only
+  `"*"`. That is the case when the Sandbox's `workspace()` grants the secret, when a credentialed `command` of that
+  Workspace names it, or when an `http` Effect of that Workspace whose body is a Worktree file names it: the Agent
+  writes that body ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). A `"none"` Agent's
+  Turns run on the Instance Harness, where no Workspace code runs, so it keeps its list. A stdio server runs as
+  Workspace code and gets no list. The token's own scopes are the outer limit. This is not the shape of
+  `workspace: "read"` above: there the tool list is the hint, because `bash` can write; here the list is the guarantee,
+  because no Workspace code can spend the secret.
 - **A state before the reviewing state cuts the review Worktree on each round.** The sha under review moves between
   rounds, so each round cuts the one folder again at the new sha. The cut forces the folder to the commit and cleans it
   with `-ffd`. Ignored files stay, because the reviewer runs the tests. The folder's path frames the reviewer's turn —
@@ -79,10 +94,11 @@ definition can state.
 - **The reviewer definition becomes `workspace: "read"`**, and the prose ban stays in its instructions as intent — the
   half of the contract a model reads — no longer as the mechanism. A decisioner becomes `workspace: "none"`.
 - **The definition stays plain data.** No code enters the ConfigMap channel; composition by re-export/spread (ADR-0018)
-  is preserved. Custom tool _implementations_ remain out of the contract — this decision adds a restriction vocabulary,
-  not an extension one. Growing extension tools is a separate, later decision.
-- **GLOSSARY.md arbitrates the three senses of "tools"**: the Menu (control plane — what an Agent may say) and Working
-  tools (data plane — what it may do) become glossary entries; unqualified "tools" joins the Avoid lists.
+  is preserved. Tool _implementations_ stay out of the contract — this decision adds a restriction vocabulary, not an
+  extension one. The extension is MCP: an Agent names servers, and a server holds the code (ADR-0079).
+- **GLOSSARY.md arbitrates the senses of "tools"**: the Menu (control plane — what an Agent may say), Working tools
+  (data plane — what it may do) and MCP tools (what it may do through a service, ADR-0079) are glossary entries;
+  unqualified "tools" joins the Avoid lists.
 - **The `@kind` tier gains the containment scenario**: from the review worktree, a write probe followed by a commit must
   leave the branch ref and the coder's worktree untouched.
 - **The zero-support guard stays available to workflows**: a workflow can still have both Agents report the sha and gate

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

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

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

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

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

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