@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -30,20 +30,35 @@ whose processes are gone, with no way to know why.
   workflow prompts you again when something is." The last sentence is safe because the wake asks a model that stopped
   with nothing allowed when a pick opens ([ADR-0016](0016-agent-turn-mechanics-are-internal.md)). A line that says a
   Turn ends with exactly one pick would be false for a pick that keeps the Turn open.
+- **An Agent with MCP tools is told that they are not picks.** Its standing part has one more statement: "Your tools
+  named `mcp__<server>__<tool>`, where `<server>` is not `jr2`, act on outside services, not on the workflow. A call to
+  one is not a pick, and it does not end your Turn." Both tool families share the `mcp__` prefix: the Menu's own tools
+  are `mcp__jr2__<event>`, so the statement names `jr2` as the exception. A model that read a call of a service as its
+  pick would stop with the workflow's work not done. The statement names no server and no tool, so it is byte-stable; an
+  Agent with no MCP tools does not get it. A `"none"` Agent with MCP tools is not told that it acts only by picking from
+  its Menu, because its MCP tools act too. The `@model` claim `mcp-then-pick` measures it
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md),
+  [ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)).
 - **The Turn part is written once per Submission, and restated when its Allowed picks change.** When something other
   than the Agent's own pick changes them inside the Turn, the Harness appends the Allowed picks again at the next step
   boundary, in a `<jr2-turn>` block of their own: "The workflow's state changed since you last read the Allowed picks.
   Allowed now: …" ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). It is
-  appended, never a rewrite of the first, so the cache argument above holds for it too. It carries no notice: notices
-  are for the next Turn in their scope. It carries a pick's briefing when the restatement opens that pick.
+  appended, never a rewrite of the first, so the cache argument above holds for it too. It carries a pick's briefing
+  when the restatement opens that pick. The same read at a step boundary returns the conversation's pending notices, and
+  the Harness appends them in the same way (below).
 - **The Turn part comes last, because a model obeys what it read last.** Measured on the home-lab vLLM model: with a
   prompt that argued for a pick the Turn did not allow, the Allowed picks placed ahead of the prompt were obeyed 0/10
   (thinking off) and 5/10 (thinking on); placed after it, 10/10 both. Wording made no difference. The author's task
   still reads first, as it would with no jr2.
 - **Always on.** No author can turn it off: every fact in it passes the rule above, so removing one can only make the
   Agent act worse. An `instructions` that repeats a fact is harmless.
-- **A notice is delivered once**, on the next admission in its scope that takes it, then cleared. That is the next Turn,
-  or, for a guard kill that the Agent of an open Turn was not told, that Turn's nudge or wake (below).
+- **A notice is heard once by each member of its audience.** A member takes it at its next admission, or at a step
+  boundary of an open Turn: the surface read of the open Turn returns the conversation's pending notices, and the
+  Harness appends them, as it appends a changed Allowed-picks list
+  ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md), ADR-0002). For a guard
+  kill that the Agent of an open Turn was not told, a member also takes it at that Turn's nudge or wake (below). A
+  conversation is an Instance ID ([ADR-0057](0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md)): a fresh
+  Turn, a runaway reroll and a burned conversation's successor each start a new one.
   - **Conversation scope** ("this conversation is new; earlier context is gone") goes to that Agent's next Turn. So does
     a pick's answer that never reached its call
     ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)): the route left the Agent's state, and
@@ -53,29 +68,43 @@ whose processes are gone, with no way to know why.
     and that stopped it" (`stopped`), with an earlier link's reply when one came. No pick-answer notice says the work
     ran to its end. A fresh picking Turn has no such conversation, and its answer is no notice.
   - **Workspace scope** ("the Sandbox's processes were killed at its memory limit during `coder`'s Turn; `/dev/shm` was
-    cleared. Anything that was running in the Sandbox at that time is gone.") goes to the next admission of any Agent in
-    that Workspace that takes it. One kill is one notice, however many Turns saw it. Only a kill read on a stream while
-    its wait is live names the Turn whose Submission ran. Both forms end with the whole Sandbox, because every process
-    in it died, a shared Workspace's too, and in the past tense, because the Agent may hear it after processes started
-    again. A kill read from the pod's list names no Turn and says nothing of when or whose: "the Sandbox's processes
-    were killed at its memory limit (peak X of Y); /dev/shm was cleared. Anything that was running in the Sandbox at
-    that time is gone." The list cannot say whose Turn a kill ended: the kill may land after a state exits, or end an
-    attach, a sync or a command. A kernel kill read from the Sandbox's last end (below) says the same, with the limit
-    and no peak: "the Sandbox's processes were killed at its memory limit of Y; …". A Menu-only Agent outside a
-    Workspace receives conversation notices only.
+    cleared. Anything that was running in the Sandbox at that time is gone.") goes to an **audience** that the ledger
+    fixes when it raises the notice. The rule is: an Agent hears a kill if it was there for it.
+    1. Each conversation admitted in that Workspace before the kill that can still take a Turn: the conversation of an
+       open Turn, which hears it at its next step boundary, or a continued conversation, which hears it at its next
+       Turn. A fresh Turn that already ended is not in the audience.
+    2. When the kill cut a specific Turn — a kill read on that Turn's stream names it — that Agent's next Turn, fresh or
+       continued: the retry of the broken work.
+    3. Minus each conversation whose own `bash` answer returned the kill's verdict (`told`, below). That answer told it
+       already.
+
+    Each member hears the notice once. The notice retires when every member has heard it. A conversation that starts
+    after the kill does not hear it, except the retry of (2). So a Pool of coders in one Workspace
+    ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)) all hear a kill that cut their work.
+    Only a kill read on a stream while its wait is live names the Turn whose Submission ran. Both forms end with the
+    whole Sandbox, because every process in it died, a shared Workspace's too, and in the past tense, because the Agent
+    may hear it after processes started again. A kill read from the pod's list names no Turn and says nothing of when or
+    whose: "the Sandbox's processes were killed at its memory limit (peak X of Y); /dev/shm was cleared. Anything that
+    was running in the Sandbox at that time is gone." The list cannot say whose Turn a kill ended: the kill may land
+    after a state exits, or end an attach, a sync or a command. A kernel kill read from the Sandbox's last end (below)
+    says the same, with the limit and no peak: "the Sandbox's processes were killed at its memory limit of Y; …". A
+    Menu-only Agent outside a Workspace receives conversation notices only.
+
   - A notice never replaces a fault. The Machine still receives `agent.fault` and decides (ADR-0016); the notice makes
     sure the next Agent is not working blind.
-- **The Orchestrator is the only keeper of notices**: pending notices are plain data in the run's persisted state
-  (ADR-0007). It sees kernel kills and fresh conversations itself. A kernel kill (ADR-0061, layer 5) has two paths,
-  under one source, the Workspace and the time the Harness container ended. A Turn that the kill ended faults on it, and
-  the fault raises the notice with the Turn's Agent. A kill while no Turn runs faults nothing, so before each admission
-  into a Workspace the Agent actor also reads the container's last end from the Sandbox watch, which the operator
-  publishes: a last end `OOMKilled` raises the notice, which names no Turn. The ledger's `seen` makes the two paths one
-  notice. An actor whose own watch saw the restart reads the last end only when it re-admits the Turn after the cut.
-  When the Turn faults, the fault's notice names the Turn's Agent. A watch that has not listed yet says nothing, and the
-  next admission reads again: the last end stays until the container ends again. A nudge and a wake take no kernel kill;
-  it stays for the next Turn. The re-admission after a cut takes it, as it takes every notice in scope that is not a
-  guard kill. The Harness reports a guard kill (ADR-0061) on two paths, under one id that the Harness gives the kill:
+
+- **The Orchestrator is the only keeper of notices and Steering messages**: pending ones are plain data in the run's
+  persisted state (ADR-0007). It sees kernel kills and fresh conversations itself. A kernel kill (ADR-0061, layer 5) has
+  two paths, under one source, the Workspace and the time the Harness container ended. A Turn that the kill ended faults
+  on it, and the fault raises the notice with the Turn's Agent. A kill while no Turn runs faults nothing, so before each
+  admission into a Workspace the Agent actor also reads the container's last end from the Sandbox watch, which the
+  operator publishes: a last end `OOMKilled` raises the notice, which names no Turn. The ledger's `seen` makes the two
+  paths one notice. An actor whose own watch saw the restart reads the last end only when it re-admits the Turn after
+  the cut. When the Turn faults, the fault's notice names the Turn's Agent. A watch that has not listed yet says
+  nothing, and the next admission reads again: the last end stays until the container ends again. A nudge and a wake
+  take no kernel kill; it stays for the next Turn. The re-admission after a cut takes it, as it takes every notice in
+  scope that is not a guard kill. The Harness reports a guard kill (ADR-0061) on two paths, under one id that the
+  Harness gives the kill:
   - **On a stream.** While a Submission runs, the kill is an event on that conversation's updates stream. The Agent
     actor reads a stream while it waits on the Submission. It stops when the Agent's state exits, before its abort
     reaches the Harness. So a stream does not always reach a reader: a kill in that window is on a stream that no one
@@ -89,13 +118,15 @@ whose processes are gone, with no way to know why.
     the only limit. A read that never left the Orchestrator, or a draining Harness's 503, is sent again in that time. A
     read that fails or times out is none, and the next admission reads again: the list keeps the kill. The Orchestrator
     logs one line when the reads from a Harness start to fail. It logs no line when a read works again, and it logs the
-    failure again only when a read fails after a read that worked. The Agent's uid can write the file, as it can the
-    conversation records: it can change only what its own Workspace is told. So a `peak` or a `limit` that is not a size
-    in the guard's form, or is long, is left out and logged, on the Harness's read of the file and on the Orchestrator's
-    read of the list and of a stream. The kill is kept, so a real kill is never lost, and its notice says no sizes: "the
-    Sandbox's processes were killed at its memory limit; /dev/shm was cleared. …". Only a kill with no id or no time, or
-    one outside the bounds below, is dropped. A stream event from an older Harness has no id; its source is then its
-    place on the stream, exactly as the Orchestrator raised it before.
+    failure again only when a read fails after a read that worked. The file is beside the Harness's conversations, which
+    no confined child can reach
+    ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). The bounds stay as a
+    second layer: a `peak` or a `limit` that is not a size in the guard's form, or is long, is left out and logged, on
+    the Harness's read of the file and on the Orchestrator's read of the list and of a stream. The kill is kept, so a
+    real kill is never lost, and its notice says no sizes: "the Sandbox's processes were killed at its memory limit;
+    /dev/shm was cleared. …". Only a kill with no id or no time, or one outside the bounds below, is dropped. A stream
+    event from an older Harness has no id; its source is then its place on the stream, exactly as the Orchestrator
+    raised it before.
 
   Both paths raise the notice with the same source, the Workspace and the kill's id. The ledger keeps every source it
   raised (`seen`) in the run's persisted state. So a kill read on both paths, or on two streams, is one notice. Each
@@ -107,71 +138,107 @@ whose processes are gone, with no way to know why.
   restart of the Orchestrator raises no kill twice. A restart of the Harness container keeps the file, which is on the
   pod's emptyDir with its conversations (ADR-0031). A lost pod takes the file with it, but then the Workspace is lost
   (ADR-0021). The list keeps the newest 16 kills, each with at most 32 conversations in `told`, and the Orchestrator
-  reads at most 256 KiB of it. The Agent's uid can write the file, so the two sides hold the same bounds: an `id` and an
-  `at` of at most 64, an `agent` and an `instanceId` of at most 128, and an `at` that parses as a time. A kill outside
-  them is dropped, and a `told` entry outside them is left out. The Harness counts the bytes of the JSON text, and the
-  Orchestrator counts characters, which are never more, so the Harness keeps no kill that the Orchestrator drops. The
-  Harness reads at most the last 256 KiB of the file. With these bounds the largest list is 149,259 bytes. When more
-  come between two admissions, the oldest is lost, and a newer kill tells the same thing. When more than 16 come in one
-  Turn, the Turn's mark leaves the list too, and every kill in the list then counts as after the mark; a nudge or a wake
-  of that Turn may then carry a kill from before it. The Instance Harness keeps no kill, because it holds no Workspace.
+  reads at most 256 KiB of it. The two sides hold the same bounds: an `id` and an `at` of at most 64, an `agent` and an
+  `instanceId` of at most 128, and an `at` that parses as a time. A kill outside them is dropped, and a `told` entry
+  outside them is left out. The Harness counts the bytes of the JSON text, and the Orchestrator counts characters, which
+  are never more, so the Harness keeps no kill that the Orchestrator drops. The Harness reads at most the last 256 KiB
+  of the file. With these bounds the largest list is 149,259 bytes. When more come between two admissions, the oldest is
+  lost, and a newer kill tells the same thing. When more than 16 come in one Turn, the Turn's mark leaves the list too,
+  and every kill in the list then counts as after the mark; a nudge or a wake of that Turn may then carry a kill from
+  before it. The Instance Harness keeps no kill, because it holds no Workspace.
 
   A notice counts as delivered when its admission is ledgered, so a restart before that point delivers it again and a
-  restart after it does not. Delivered is not yet heard: if the Orchestrator ends the Turn before the Harness reads its
-  surface, the Harness never prompts it (ADR-0026), so the Orchestrator raises that admission's notices again. This
-  holds for a nudge and a wake too: each one must have its surface read again before its notices count as heard. An
-  admission that fails leaves the earlier admission's notices heard. A nudge and a wake re-prompt the Turn within
-  itself, so they take no notice of the kind a Turn takes. They take only the guard kills of the list that come after
-  the newest kill whose `told` names their conversation. That `bash` answer told the Agent that all its processes died,
-  so it covers every kill up to it. They also take no kill from before the Turn started. Such a kill would tell the
-  Agent that processes it started in this Turn died. The Turn's first read of the list sets its mark: the id of the
-  newest kill it saw, or "none". The mark is ledgered with every admission of the Turn, and a restore reads it back, so
-  a nudge or a wake takes only kills after it. Only when the first read failed is the Turn's start the mark, ledgered
-  the same way, with one second allowed for a pod clock that runs behind. A read that failed is "could not tell", never
-  an empty list, so it sets no mark. The kills they do not take stay pending for the next Turn. The re-admission after a
-  Harness restart cut the Turn continues the same Turn, so it takes every notice in scope except the guard kills that
-  this rule leaves out. When its read could not tell, it takes no guard kill at all, as a nudge then takes none: it
-  cannot know which kills its own `bash` reported. The notices that the Turn's admissions carried since the Harness last
-  read the Turn's surface are pending again first, each with the source it was raised with, and this re-admission
-  carries them whatever else its scope leaves out. A notice with no source merges only into a pending one with no
-  source, so an equal notice of another kill never takes its place. When such an unread admission carried the Turn's
-  task, the task follows the re-admit text. When the rebuilt Harness lost the conversation, nothing of the Turn is left:
-  every notice that the Turn's admissions carried is pending again whatever the surface reads said, the re-admission
-  takes every notice in scope, as a Turn's admission does, and the Turn's task follows the re-admit text. It says once
-  that the conversation is new. A restore drops the prompt from a Turn's input, so the task rides the ledgered admission
-  too; a lost conversation with no task to send faults the Turn instead. Whether the Harness still holds the
-  conversation is asked again for up to 30 seconds while the new container does not listen yet or drains, and only then
-  is the answer taken as "held". The continue path asks the same way, so a continued Turn after a restart can wait up to
-  30 seconds before its admission. A Harness in CrashLoopBackOff can take longer than that: the answer is then "held",
-  and it can be wrong. So every admission to a conversation that the Harness was taken to keep says so with
-  `kept: true`: the re-admission after a cut, a continued Turn, and a nudge or a wake. A Harness that keeps no such
-  conversation refuses it with 404 and `kept: false` in the body, and seats none. The Orchestrator takes only that 404
-  as the refusal; another 404 is a failed admission. Without the refusal the Harness would seat a new conversation, and
-  a model on an empty context would read "continue your task" with no task. On the refusal the Turn takes the path of a
-  lost conversation. The re-admission is admitted as a Turn, with the task after the re-admit text and the notice that
-  the conversation is new, or faults when it has no task to send. A continued Turn is told that its conversation is new,
-  and is admitted again. A nudge or a wake is admitted again as a Turn: its prompt is the task alone, because nothing
-  was cut, with the notice that the conversation is new and every notice in scope. Every notice that the Turn's
-  admissions carried is pending again first, as for a lost conversation after a cut. With no task to send, the Turn
-  faults. The Instance Harness's restart is on no watch, so this refusal is the only way a nudge or a wake learns of it.
-  What the Turn's admissions carried, and whether the Harness read their surface, is kept in the Orchestrator's memory
-  alone: after a restore of the Orchestrator before a surface read, nothing is raised again. A fresh Turn's "this
-  conversation is new", which rides an admission alone, is carried again by the next re-admission when the Harness has
-  not read the one before.
+  restart after it does not. A notice at a step boundary has no admission. The surface read of the open Turn reserves it
+  for that member, and it counts as delivered, and heard, when the Harness acknowledges the append. When the Turn ends
+  with no acknowledgment, the reservation is released, and the notice is pending again for that member. A reservation
+  lives in the Orchestrator's memory only, so a restart forgets it: the notice is pending again, and the next read or
+  admission carries it. So a conversation can hear a notice twice after a crash, as for an admission. Delivered is not
+  yet heard: if the Orchestrator ends the Turn before the Harness reads its surface, the Harness never prompts it
+  (ADR-0026), so the Orchestrator raises that admission's notices again. This holds for a nudge and a wake too: each one
+  must have its surface read again before its notices count as heard. An admission that fails leaves the earlier
+  admission's notices heard. A nudge and a wake re-prompt the Turn within itself. Of the notices, they take only the
+  guard kills of the list that come after the newest kill whose `told` names their conversation. That `bash` answer told
+  the Agent that all its processes died, so it covers every kill up to it. They also take no kill from before the Turn
+  started. Such a kill would tell the Agent that processes it started in this Turn died. The Turn's first read of the
+  list sets its mark: the id of the newest kill it saw, or "none". The mark is ledgered with every admission of the
+  Turn, and a restore reads it back, so a nudge or a wake takes only kills after it. Only when the first read failed is
+  the Turn's start the mark, ledgered the same way, with one second allowed for a pod clock that runs behind. A read
+  that failed is "could not tell", never an empty list, so it sets no mark. The kills they do not take stay pending for
+  the next Turn. The re-admission after a Harness restart cut the Turn continues the same Turn, so it takes every notice
+  in scope except the guard kills that this rule leaves out. When its read could not tell, it takes no guard kill at
+  all, as a nudge then takes none: it cannot know which kills its own `bash` reported. The notices that the Turn's
+  admissions carried since the Harness last read the Turn's surface are pending again first, each with the source it was
+  raised with, and this re-admission carries them whatever else its scope leaves out. A notice with no source merges
+  only into a pending one with no source, so an equal notice of another kill never takes its place. When such an unread
+  admission carried the Turn's task, the task follows the re-admit text. When the rebuilt Harness lost the conversation,
+  nothing of the Turn is left: every notice that the Turn's admissions carried is pending again whatever the surface
+  reads said, the re-admission takes every notice in scope, as a Turn's admission does, and the Turn's task follows the
+  re-admit text. It says once that the conversation is new. A restore drops the prompt from a Turn's input, so the task
+  rides the ledgered admission too; a lost conversation with no task to send faults the Turn instead. Whether the
+  Harness still holds the conversation is asked again for up to 30 seconds while the new container does not listen yet
+  or drains, and only then is the answer taken as "held". The continue path asks the same way, so a continued Turn after
+  a restart can wait up to 30 seconds before its admission. A Harness in CrashLoopBackOff can take longer than that: the
+  answer is then "held", and it can be wrong. So every admission to a conversation that the Harness was taken to keep
+  says so with `kept: true`: the re-admission after a cut, a continued Turn, and a nudge or a wake. A Harness that keeps
+  no such conversation refuses it with 404 and `kept: false` in the body, and seats none. The Orchestrator takes only
+  that 404 as the refusal; another 404 is a failed admission. Without the refusal the Harness would seat a new
+  conversation, and a model on an empty context would read "continue your task" with no task. On the refusal the Turn
+  takes the path of a lost conversation. The re-admission is admitted as a Turn, with the task after the re-admit text
+  and the notice that the conversation is new, or faults when it has no task to send. A continued Turn is told that its
+  conversation is new, and is admitted again. A nudge or a wake is admitted again as a Turn: its prompt is the task
+  alone, because nothing was cut, with the notice that the conversation is new and every notice in scope. Every notice
+  that the Turn's admissions carried is pending again first, as for a lost conversation after a cut. With no task to
+  send, the Turn faults. The Instance Harness's restart is on no watch, so this refusal is the only way a nudge or a
+  wake learns of it. What the Turn's admissions carried, and whether the Harness read their surface, is kept in the
+  Orchestrator's memory alone: after a restore of the Orchestrator before a surface read, nothing is raised again. A
+  fresh Turn's "this conversation is new", which rides an admission alone, is carried again by the next re-admission
+  when the Harness has not read the one before.
 
-  A continued Turn of the same conversation is told, as a notice, a kill that its own `bash` call answered in an earlier
-  Turn. The Agent reads that kill twice, which is true and costs little. The `told` rule could later extend to the first
-  admission of a continued Turn too; it does not now, because a fresh Turn's conversation holds no earlier answer, and
-  the rule would then need the conversation in the ledger's scope.
+  A conversation whose own `bash` call answered a kill is not in that kill's audience, so it does not hear the kill
+  again as a notice, at its next Turn or at a step boundary.
 
+- **One ledger carries notices and Steering messages.** A Steering message ([ADR-0002](0002-duplex-streaming-actor.md))
+  is not a notice: a notice is a fact that jr2 knows and that has no author, and a Steering message is an utterance with
+  an author, which the model weighs by who wrote it. So the two are siblings on one transport. Each entry of the ledger
+  is an **envelope** and a **body**. The envelope holds what the ledger delivers by: the address, the source, the
+  audience, and what was reserved and heard. The body is a Notice, or a Steering message with its text and its author:
+  `{ kind: "caller", via, name, onBehalfOf? }` or `{ kind: "machine", from? }`, where `from` is the Sender whose words
+  the Machine relays. The rules above, heard once, reserved at a step boundary and delivered when the append is
+  acknowledged, hold for both.
+  - **The address is a tagged value.** `{ conversation }` and `{ workspace }` are the two kinds that notices use, and
+    `{ slot }` (an Agent slot of one Machine instance of the run) is the kind that a Steering message uses. A new kind
+    is an addition, and no kind changes the meaning of another's fields.
+  - **A slot's audience is a future member.** A Workspace notice fixes its audience when the ledger raises it. A message
+    to a slot goes to the slot's open Turn, or, when there is none, to the slot's next Turn in the same Machine
+    instance, whose conversation does not exist yet at the raise. It retires, recorded "not delivered", when that
+    Machine instance ends.
+  - **The Harness frames a Steering message by its author.** A Caller's message is an instruction from outside the run,
+    and the frame names the Caller. A message that the Machine relays `from` another Agent is information from a peer.
+    The frame says that the workflow passes it on but did not write it, and a closing line after the text says that it
+    is not an instruction and does not change the Agent's task: the Agent does what the workflow asked. The closing line
+    is read last, after the peer's text (ADR-0029). In `peer-not-order`, a frame that said only "not an order" read 5 of
+    10, because a model that obeyed read "the workflow relays" as the workflow's own word. A frame that said, ahead of
+    the text only, that it was "that Agent's word, not the workflow's", read 17 of 20, and the closing line read 20 of
+    20 (ADR-0066). A message that the Machine relays `from` a Gate is what the Gate received, and the frame says that it
+    is not an order either. A Machine's message with no `from` is the workflow's own text. The text is quoted line by
+    line, so the model sees where it starts and ends, and it follows the notices in the Turn part, ahead of the Allowed
+    picks. A name in the frame (a Caller's name, its `onBehalfOf`, a peer's or a Gate's id) is a code span that its own
+    text cannot close, on one line: a name comes from outside jr2 and can hold a backtick or a line break. A message
+    whose author the Harness does not know is dropped, never framed as another author's.
+  - **The two bodies ride the wire apart.** The admit body carries `notices` and `steering`, and the surface read
+    `notices: [{ id, notice }]` and `steering: [{ id, message }]`; one acknowledgment,
+    `POST /agents/:iid/notices { heard }`, hears both by their ledger ids. A nudge and a wake take notices by their
+    sources, so they carry no message: the surface read that starts their Submission does.
 - **The Harness writes every word.** The admit body carries typed notices
   (`notices: [{ kind: "memory-limit", scope, agent?, limit?, peak? } | { kind: "conversation-new", reason } | { kind: "pick-answer", pick, cut, answer?, stopped? } …]`,
-  where `peak` comes only with `limit`), and the Harness renders both parts. An outstanding pick's answer is data too —
-  the last reply since the pick, a party's event with its payload or a child's output (ADR-0024) — and its words ("Its
-  answer: `approve` from Gate `review`, with {…}", "No reply came back for it.") are the Harness's, in the receipt and
-  in the notice alike; "it moved the workflow, and nothing ran" is a guard straight back's receipt alone. The standing
-  part needs no wire: the Harness already holds its limits (cgroup and Downward API env), the definition's `workspace`
-  access, and the Menu. The wording lives in one place, and Harness conformance checks it (ADR-0027).
+  where `peak` comes only with `limit`) and Steering messages with their authors, and the Harness renders both parts and
+  frames each message. The text of a Steering message is the author's; the frame around it is the Harness's. An
+  outstanding pick's answer is data too — the last reply since the pick, a party's event with its payload or a child's
+  output (ADR-0024) — and its words ("Its answer: `approve` from Gate `review`, with {…}", "No reply came back for it.")
+  are the Harness's, in the receipt and in the notice alike; "it moved the workflow, and nothing ran" is a guard
+  straight back's receipt alone. The standing part needs no wire: the Harness already holds its limits (cgroup and
+  Downward API env), the definition's `workspace` access, and the Menu. The wording lives in one place, and Harness
+  conformance checks it (ADR-0027).
 
 ## Considered options
 
@@ -197,6 +264,9 @@ whose processes are gone, with no way to know why.
   does not.
 - **Read the kill on the Sandbox watch.** Rejected: the operator publishes what the kubelet says about the container,
   and a guard kill does not end the container. The Harness has no Kubernetes credentials to publish it.
+- **A Steering message as a kind of notice.** Rejected: a notice is a fact with no author, and the Harness words it. A
+  Steering message is an author's text, and the model must weigh a Caller's instruction and a peer's word differently.
+  Folded into a notice, the author and that difference have no place.
 - **The Harness words the kill into the next Turn itself.** Rejected: a second keeper of notices, outside the run's
   persisted state, which cannot know when an admission is ledgered or heard.
 
@@ -209,4 +279,8 @@ whose processes are gone, with no way to know why.
 - The Briefing is how a Turn learns its Allowed picks: the tools block is the whole Menu, fixed for a conversation so it
   does not break the cache
   ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)).
+- A Workspace notice reaches each conversation that was there for the kill, and the retry of the Turn that it cut; an
+  open Turn hears it at its next step boundary, not only at its next admission (ADR-0002,
+  [ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). So a memory kill reaches
+  every coder of a Pool that shares one Workspace (ADR-0075).
 - GLOSSARY.md gains **Briefing**.

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

@@ -52,10 +52,9 @@ Decisions since then need pod facts at once: the scheduler's reason for a Pendin
   merge patch per Workspace every 5 minutes, ±20% jitter so Leases never renew in lockstep after a restart. It no longer
   carries detection.
 - **The attach is a Harness call, not an exec.** The Harness runs the attach — ACL stamp, `git clone --shared` from the
-  node cache, remotes, `git worktree add` — on `POST /attach { slots, branch }`, authenticated like every Harness call
-  (ADR-0058). No stream per Workspace crosses the API server, and **`pods/exec` leaves the Orchestrator's RBAC**. It
-  also binds work late: a pod already running receives its Repos and branch, the shape standby Sandboxes and Agent
-  Substrate need.
+  node cache, remotes — on `POST /attach { slots }`, authenticated like every Harness call (ADR-0058). No stream per
+  Workspace crosses the API server, and **`pods/exec` leaves the Orchestrator's RBAC**. It also binds work late: a pod
+  already running receives its Repos, the shape standby Sandboxes and Agent Substrate need.
 
 ## Considered options
 
@@ -70,8 +69,8 @@ Decisions since then need pod facts at once: the scheduler's reason for a Pendin
 - **A jr2 WebSocket API.** Nothing to add: a Kubernetes watch is already a pushed stream of events.
 - **Keep the attach as exec through the new client.** The exec protocol is the hardest part of any Kubernetes client, it
   keeps one stream per Workspace through the API server, and it keeps `pods/exec`.
-- **Attach from an init container.** Declarative, but it fixes the Repos and branch at pod creation, which rules out
-  late binding, and it must wait on a cache that exists only after scheduling.
+- **Attach from an init container.** Declarative, but it fixes the Repos at pod creation, which rules out late binding,
+  and it must wait on a cache that exists only after scheduling.
 
 ## Consequences
 
@@ -79,5 +78,6 @@ Decisions since then need pod facts at once: the scheduler's reason for a Pendin
   the watch and the Harness attach. ADR-0001: the operator publishes pod facts on the Sandbox's status, and writes
   status only on change — every write is now a watch event at the Orchestrator.
 - The Harness gains a route that is not about a conversation. It is jr2's own work in the container ADR-0005 gives it.
-- The CLI keeps `kubectl` on the user's machine (`jr2 up`, `jr2 ssh`, ADR-0009); only the Orchestrator stops using it.
+- The CLI keeps `kubectl` on the user's machine (`jr2 up`, the `jr2 workspace` verbs, ADR-0009); only the Orchestrator
+  stops using it.
 - Tests fake the client with a small HTTP server instead of a `kubectl` stub.

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

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

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

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