@jr2/orchestrator 0.3.0 → 0.5.1

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

@@ -0,0 +1,237 @@
+# The Harness is jr2's own server: flue retires, the wire stays
+
+jr2 has been programming around its Harness, not with it. The evidence is the ADR trail itself.
+[ADR-0018](0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)'s entire codegen-at-pod-start mechanism —
+generated shims, a boot-time `flue build`, agent names frozen at that build — exists because flue offers no programmatic
+server assembly; its own Considered options says so. [ADR-0026](0026-a-turn-that-is-over-is-never-prompted.md) was
+forced by a foreign advisory session jr2 never asked for, and records a rejection ("there is nothing on the wire to
+branch on") that is only true because someone else writes the wire.
+[ADR-0023](0023-the-harness-prints-the-conversation.md)'s printer needed a loopback SSE client plus a 40-attempt
+404-chase against flue's own parking behavior. The `flue-contract` tier ([ADR-0010](0010-bdd-acceptance-tests.md)) holds
+a test asserting a defect we are waiting on someone else to fix: on pinned beta.9, an abort landing mid-stream erases
+the assistant message from every later turn — fixed only on flue's unreleased line. And the Agent tool-restriction gap
+has no seat in beta.9 at all: `SandboxFactory.tools` replaces the whole list, the default tools are private to a bundled
+chunk, and ADR-0018's recorded escape hatch — "eject to a real flue project" — un-decides ADR-0018.
+
+Waiting was the standing plan, and flue 2.0 ends it. The 2.0 nightlies do export tool constructors, but as part of a
+rewrite: `defineAgent` is gone (an `AgentFunction` with hooks replaces it), `connectMcpServer` is renamed, the workflow
+exports are absent from the runtime index, and the schema resets. `latest` has sat frozen at `1.0.0-beta.9` for a month
+while all activity lands on an unannounced 2.0 line. That is a framework heading somewhere else, carrying our defect fix
+with it.
+
+Meanwhile the thing jr2 actually needs from flue is small, and jr2 already owns its specification. The Orchestrator
+imports `@flue/sdk` in exactly one module (`flue-client.ts`), uses three verbs — send, wait, abort — behind
+`AgentRunPort`, and persists a three-string admission handle. The stub Harness (`stub-harness.ts`) is a hand-written,
+SDK-verified model of the five wire endpoints. And the base flue builds on is public: `@earendil-works/pi-agent-core`
+(MIT, independent of flue's authors) — from which flue imports only the low-level `Agent` loop and reimplements the
+rest. jr2 takes the same slim core: pi-agent-core gives the `Agent` loop, its tool hooks (`beforeToolCall`,
+`finishTurn`, `prepareRequest`), the abort, the steering queue and an in-process event stream. The tool-restriction gap
+does not exist for a caller that owns tool assembly. jr2 owns the rest: the engine part on disk, Compaction
+([ADR-0036](0036-a-turn-compacts-its-own-context-mid-flight.md)) and the six Working tools, whose text the model reads.
+
+## Decision
+
+- **jr2 owns its Harness: `@jr2/harness` at `packages/harness`**, built on `@earendil-works/pi-agent-core` +
+  `@earendil-works/pi-ai` (pinned exact; a minor can break, and pi 1.0 removed the session, Compaction and the coding
+  tools from pi-agent-core) and Hono, which the repo already uses. The stock image keeps its tag
+  (`jr2-harness:<kitversion>`) and every operator contract: numeric uid, binding `:8080` is Ready, `git` in the image —
+  plus `ripgrep` for the grep tool.
+- **pi is the engine, not the contract.** The Harness keeps its contract in jr2's own shapes. One seam (`Engine`,
+  `engine.ts`) is the interface between the Turn and the engine. The Turn gives the engine one Submission's run: the
+  model, the thinking level, the system prompt, the tools, the context and the prompt. It hears the run as events
+  (`message_end`, `step_boundary`, `tool_start`, `tool_end`), and it can `steer` and `abort` the run. It counts the
+  Runaway watch's steps at `tool_start` (ADR-0035): the engine sends `tool_start` for every call of a model answer, in
+  order, before it checks the tool or the arguments, and the event carries the call's name and arguments. A listener can
+  abort the run there. Inside the run, the Turn decides through four hooks:
+  - `convertToLlm`: the messages that the provider gets.
+  - `beforeRequest`: Compaction (ADR-0036).
+  - `beforeToolCall`: the blocks of ADR-0024 (a second pick of one model answer, and a call after a pick that ended the
+    Turn), and the block of a tripped runaway watch (ADR-0035). A block can also abort the run.
+  - `endsRun`: the end of the run at the step boundary, after a trip or when the Turn is over.
+
+  The engine runs the tool calls of one model answer one at a time, in the order the model wrote them. A call's
+  `beforeToolCall` comes after the result of the call before it is complete. This rule is part of the seam, not a choice
+  of pi's. pi's own default is `parallel`, which starts each call before the call ahead of it ends. So the pi adapter
+  sets `toolExecution: "sequential"`. The reason is a measurement on the real Anthropic API (Haiku 5.5, 2026-10-22), in
+  the `@model` claim `continue-after-signed-push`
+  ([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:
+  - 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
+    engine tells a model answer (`message_end`) before it asks `beforeToolCall` about a call of it. And it asks only
+    about a call of a tool the run has, with valid arguments. So the first pick is the first that reached
+    `beforeToolCall` in that model answer. A call of an unknown tool, or with invalid arguments, gets the engine's own
+    error, and it is never the first pick. A list of the model answer's calls would name such a call, and it would need
+    an id that some providers do not send.
+  - A call after a pick whose answer ended the Turn does not run: `beforeToolCall` blocks it. `endsRun` then ends the
+    run at the step boundary, so no model request follows. The Submission does not settle then: it waits for the
+    Orchestrator's sweep, which says how the Turn ended (ADR-0024), at most 10 s.
+  - After an abort or a Runaway's trip ([ADR-0035](0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md)), the
+    calls before it have run. The engine runs no later call of that model answer and gives it no result. When the run
+    ends, the Turn writes jr2's answer for each such call in the engine part: "This call did not run: your turn ended
+    before it started." Without it, pi-ai answers "No result provided", which does not say whether the call ran.
+    [ADR-0031](0031-menu-only-agents-run-on-the-instance-harness.md) gives the restart's case.
+  - Each "did not run" result is an error result: a blocked call, and a call that the run never started. The call did
+    not do its work, and the model may make it again. A cut or unsent pick's answer (ADR-0031) is not an error, and
+    neither is the answer of a pick that the Harness may have delivered (ADR-0002), because an error reads as a failed
+    pick, and a cut pick may have run.
+
+  The seam's tools, events and hooks are jr2's types. The seam's messages are pi-ai's provider messages, plus jr2's
+  Compaction summary. pi-ai is the provider library, not the engine (see below), so these shapes are not the engine's.
+  An adapter (`EngineAdapter`) opens the conversation's engine part and makes its engine. `pi-engine.ts` is the one
+  adapter, and the one module that imports pi-agent-core. It holds pi's `Agent` loop, its hooks and events, and the
+  leading system message that carries the system prompt and the tool declarations (pi 1.x's way).
+
+  The engine part (ADR-0031) is engine-named: the adapter chooses its directory (`engine/pi`). Its format is jr2's
+  transcript (`transcript.ts`), not pi's, because pi 1.x keeps no conversation. The Turn and Compaction (ADR-0036) read
+  and write it. So the adapter does not own the format. It owns the name. The name is the guard: only the engine that
+  wrote a part is known to read it correctly, because that engine's loop decides what goes into it. So a Harness on
+  another engine opens another directory, does not read pi's part, and continues from the record's history.
+
+  pi-ai is the provider library that every engine sends its requests through, so the Harness uses it directly:
+  - the model catalog and the custom provider (`provider.ts`);
+  - the message and tool-declaration types;
+  - TypeBox `Type` for the Working tools' schemas (pi-ai coerces the arguments of a TypeBox schema differently from
+    those of a plain JSON Schema);
+  - `uuidv7`, for two ids that go to a provider as a prompt-cache key (pi-ai's `sessionId`): the engine part's id, and
+    the id of each Compaction summary request;
+  - `contentText`: the summary request joins a message's text by pi-ai's rule, as pi 0.82.1 did;
+  - `retryAssistantCall`: the summary call retries by the same rule as each provider request.
+
+  A second engine is a second adapter. One module chooses the Harness's adapter (`engine-choice.ts`), and the Turn names
+  no adapter: a test rig can pass another (`TurnDeps.engineAdapter`). So a second engine changes `engine-choice.ts`, not
+  the Turn. The Working tools, the printer, the transcript and Compaction do not change.
+
+- **Assembly is runtime construction, not codegen.** `main.ts` constructs the server and listens; each admission carries
+  its Agent's definition (ADR-0049), validated loudly and re-read per Submission. `boot.mjs`, the generated shims, the
+  boot-time `flue build`, and the readiness lag it caused are deleted, and so — later — was the `JR2_AGENTS_JSON` roster
+  this cut read at boot. The ADR-0018 contract — stock image, user-owned plain-data definitions — survives with its
+  mechanism simplified.
+- **The wire stays, and becomes normative.** The five endpoints the stub documents (`POST /agents/:name/:id`,
+  updates/history views, long-poll, `POST .../abort {cause?, submissionId?} → {aborted}`) and the three-string admission
+  `{streamUrl, offset, submissionId}` (jr2 now mints its own opaque values) are jr2's protocol, not flue's. The stub
+  Harness, the admission ledger ([ADR-0016](0016-agent-turn-mechanics-are-internal.md)), `AgentRunPort`, and every
+  mechanics/`@kind` assertion came through the move from flue byte-identical. Later decisions changed them in place. The
+  sweep's cause and the outcome `ended` ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md))
+  changed the stub's settlements, the port's `abort`, and the mechanics and `@kind` assertions of a Turn that its own
+  pick ended. Long-poll is the only wait transport; the SDK's `?wait=result` and SSE paths are not part of the contract.
+  The admit body is `{message, model?, thinkingLevel?}` — the optional dials
+  ([ADR-0018](0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)) are this Submission's override layer
+  over the Agent's definition, omitted when unset, and an unresolvable one is a 400 at admission rather than a
+  Submission that settles `failed` — a one-line addition precisely because the protocol is jr2's own.
+
+- **The re-owned semantics are stated, not inherited:**
+  - **Per-instance queue: accept and queue.** A Submission is promoted when it is the first unsettled Submission of its
+    conversation; admission order. [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)'s correction
+    — flue queues, and the ordered abort depends on it — is now a design jr2 asserts rather than a behavior it
+    discovered.
+  - **Abort sweeps, and says its cause.** The active Submission and everything queued at the moment the abort is
+    processed settle in admission order. The response answers `{aborted: boolean}` (`false` on an idle instance).
+    Arrival order at the Harness is the order; the client-side pending-abort await (ADR-0024) stays as the cross-request
+    guarantee. The body is optional, and it is the Orchestrator's judgment of how the Turn ended:
+    - `{cause: "pick", submissionId}` says that the Turn's own pick ended it. The active Submission settles `ended` when
+      the body names it.
+    - Every other body settles it `aborted`: no body, a body that does not parse, a cause the Harness does not know, or
+      a `submissionId` of another Submission (or none).
+    - The active Submission may still be running. Or its run may have ended because a pick found the Turn over, and it
+      waits for this sweep. Either way the sweep settles it. When no sweep comes within 10 s, it settles `aborted` and
+      says so.
+    - A queued Submission never ran, so it settles `aborted` for every cause.
+    - An Orchestrator from before the field still works on the wire. But it gives no cause, so its Turns settle
+      `aborted`, every time.
+  - **Settlement is `completed | ended | failed | aborted`**, and the Orchestrator is the one judge of how a Turn ended
+    (ADR-0024). `completed`: the run returned, and the Turn is still open, so the Agent's Actor asks again (the nudge or
+    the wake, ADR-0016). `ended`: the Turn's own pick ended the Turn, and the sweep said `cause: "pick"`. The pick may
+    be from an earlier Submission of the same Turn: a nudge or a wake starts a new Submission in the same Turn.
+    `failed`: the run threw, a Runaway included
+    ([ADR-0035](0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md)). `aborted`: something else ended the Turn,
+    or no sweep came in time, or it was over before it started
+    ([ADR-0026](0026-a-turn-that-is-over-is-never-prompted.md)). `failed` and `aborted` carry an error, `aborted` the
+    type `{type: "submission_aborted"}` — continuity with what ADR-0024/0025 recorded. `completed` and `ended` carry
+    none: nothing went wrong. A Settlement also carries its Submission's `usage`: the input, output, cache-read and
+    cache-write tokens and the cost, summed over the Submission's model answers. The cost is pi-ai's, from its catalog
+    rates, so a `harness.provider` model with no rates costs 0. A Compaction summary's model call is not in it. The
+    field is optional. A Submission whose model never answered carries none, and so does one lost with a restarted
+    Harness, because its spend was lost with it. The reason is the `@model` tier
+    ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)): it records the
+    tokens and the cost of each trial, and the Settlement is the one place outside the pod that knows them. The
+    Orchestrator does not read it yet.
+  - **An unknown conversation is 404**, on both views. `POST` creates (that is admission), except an admission with
+    `kept: true`, which is 404 (with `kept: false` in the body) on an unknown conversation and creates nothing
+    ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)); abort answers `{aborted: false}`. This is
+    a deliberate divergence from the stub, which answers every read with an empty stream: the stub is inert by design,
+    but a real Harness that answered a lost conversation with silence would park a re-attached `wait` forever. Honesty
+    about loss beats an endless poll.
+  - **The durability contract is explicit: a conversation lives as long as its Sandbox, and on the Instance Harness as
+    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-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
+    `mcp__jr2__<name>` naming — shipped instructions and the printer's prefix-stripping depend on it — though no MCP
+    carries them ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). The
+    retire-the-previous idiom and ADR-0023's 404-chase existed to work around flue API gaps that are gone.
+- **The Orchestrator side shrinks.** `harness-client.ts` replaces `flue-client.ts`: a fetch client for the three verbs,
+  with `wait` as a long-poll loop from the admitted offset (capped backoff, indefinite reconnect — pod death is
+  `workspace.lost`'s job) that resolves on `completed` alone and raises a typed `SettlementFault` on
+  `failed`/`ended`/`aborted`/404 (an `ended` reaches only an actor that its own pick already stopped, and a stopped
+  actor drops it). `actor.ts` did not change in the move from flue: the port, the admission shape, the nudge loop, and
+  the abort ordering stayed as they were. ADR-0024's sweep cause later changed it in two places. The port's `abort`
+  takes the cause and the Submission it names, and the Actor's `abandon` reads the cause before its registration goes.
+
+## Considered options
+
+- **Wait for flue 2.0.** Rejected: unreleased, unscheduled, and a rewrite of the surfaces jr2 generates against
+  (`defineAgent`, MCP wiring, routing). The structural problems — foreign advisory sessions, no programmatic assembly —
+  are architecture, not backlog. Meanwhile the pinned defect erases assistant messages on real abort timings.
+- **Fork flue at beta.9.** Rejected: ~17K lines of built output plus a CLI codegen owned to keep seven imported symbols,
+  diverging from a codebase whose maintainers are mid-rewrite — the defect fix would have to be backported from a line
+  that left. And its durability layer, the one genuinely load-bearing-looking piece, is in-memory as jr2 deploys it.
+- **Fresh on pi, new wire.** Rejected: redesigning the protocol throws away the tested contract, the stub, the ledger
+  shape, and the mechanics tier for no identified semantic gain. The wire was never the problem; the runtime behind it
+  was.
+- **Fresh on pi, wire kept** — chosen.
+- **Run in order only a model answer that holds a Menu pick** (pi's per-tool `executionMode: "sequential"` on each Menu
+  tool), and the other model answers in parallel. Rejected. It is narrower, and independent reads keep their speed. But
+  it leaves the race between Working tools: a `write` and the `bash` test run that reads its file. Also, the seam would
+  have no rule of its own: the order would be a fact of which tools a model answer holds.
+- **Give `beforeToolCall` the names of the calls ahead of the call in its model answer** (`earlier`), for the first-pick
+  rule. Rejected. The list names a call that the engine did not prepare (an unknown tool, invalid arguments), so the
+  rule blocked a valid pick behind it. And the position of a call in the list needs the call's id, which a provider can
+  leave empty.
+
+## Consequences
+
+- **Deleted**: `packages/orchestrator/harness/` (boot.mjs, the flue project skeleton, the boot build and its readiness
+  lag), the printer's loopback client and 404-chase, ADR-0026's foreign-advisory rationale (the decision stands on its
+  other leg: the turn-start race), and the "eject to a real flue project" escape hatch — which means the tool contract
+  must now be answered, not re-deferred
+  ([ADR-0028](0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)).
+- **Kept verbatim**: the wire, the stub as the mechanics fixture, `AgentRunPort` and the admission ledger, ADR-0024's
+  rule, receipt, and ordering, and the container split — restated in jr2 terms: the pod's credentials live in a separate
+  container (the Custodian, ADR-0059) _because working tools execute in the Harness container_, so the
+  credential-isolation premise survives while `local()` leaves the vocabulary.
+- **The `flue-contract` tier dissolves into the conformance suite.** Its rig — scripted OpenAI-compatible provider, the
+  Menu over a real socket to a killable fake Orchestrator, real server — moves into `packages/harness/test/` and runs in
+  the default `test` gate: the opt-in-ness existed only because the tier owned a foreign pin and build. Its claims
+  become jr2 requirements, with the pinned-defect assertion inverted: an abort mid-stream must **not** erase the
+  assistant message. This suite is the first canary for pi bumps; `@kind` (ADR-0038) drives the same turn loop in a real
+  pod against a scripted model, and `@model`
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)) against a real one —
+  run all three before bumping the pin.
+- **The pinning risk moves; it does not vanish.** pi releases often and a minor can break. The pin is exact, a bump is a
+  deliberate kit change gated by the conformance suite, and the breaking surface is now the `Agent` loop's hooks and
+  pi-ai's provider adapters — not a code generator, a CLI build, and a process-global registry. What pi removed jr2 now
+  owns, so a bump cannot move it: the Working tools keep their text, and Compaction its algorithm.
+- **Migration is phased behind the wire.** Because both ends speak the same protocol, the image swap and the
+  Orchestrator client swap are independent commits, each leaving every tier green; an old Orchestrator drives the new
+  image and vice versa. `@flue/*` leaves the repo when the last pin (the retired contract tier) is deleted.

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

@@ -0,0 +1,89 @@
+# What an Agent may do to the Workspace is part of its definition
+
+jr2 is exact about what an Agent may **say** and silent about what it may **do**. The control plane is a menu the
+Machine sets per turn — derived from the invoking state's transitions
+([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)), served from a separate container
+([ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)), unforgettable by construction
+([ADR-0016](0016-agent-turn-mechanics-are-internal.md)). The data plane is one identical working toolset with full write
+access to the shared Workspace, for every Agent, in every state.
+
+The gap is not hypothetical. In a live `task-with-review` run (2026-07-27), the coder found nothing to do and committed
+nothing; the reviewer then edited `README.md`, set a `user.email`, committed, and approved its own commit — against
+instructions that say "Do not modify the code yourself".
+[ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) already established what that means: the same
+prompt, model, and state produce compliance on one run and not the next, "which is what rules out fixing this with
+words." The prose ban is a persona, not a boundary. ADR-0024 also named the stakes — an Agent with write access is a
+concurrent writer in a Workspace the Machine believes is single-threaded — and
+[ADR-0012](0012-workspace-wrapper-machine.md) puts coder and reviewer in that one Workspace on purpose.
+
+Under the retired flue runtime this had no seat — its tool list was take-it-or-replace-it, and the only recorded out was
+ejecting to a foreign harness project. [ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)
+retires that constraint: jr2 assembles the working tools per Submission, so what an Agent may do is finally something a
+definition can state.
+
+## Decision
+
+- **`AgentDefinition` gains `workspace?: "write" | "read" | "none"`, default `"write"`.** One word that describes the
+  persona — a reviewer reads, a decisioner needs no Workspace at all — not a tool inventory. It is deliberately **not**
+  named `tools`: that word already means the control-plane menu at the invoke seam (`actor.ts`'s escape hatch) and would
+  name the Harness's menu rather than the Agent. And it is named for the thing accessed: the field was first shipped as
+  `access`, and `"none"` exposed the dropped word as load-bearing — access _to what?_ The object was always the
+  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
+  [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.)
+- **The tool layer enforces the honest path.** `access: "read"` withholds `write` and `edit` from the assembled working
+  tools (the tool set that the Harness gives the loop for each Submission). `bash` stays — the reviewer's own
+  instructions require running the tests — and the ADR says plainly what that means: a shell can write, so the tool
+  layer states intent and stops the honest path. It is known leaky, and it is not the guarantee.
+- **The worktree layer contains the blast radius: a reviewer works in a detached review worktree.** The attach step —
+  already jr2-owned (`sandbox-kubectl.ts`'s `attachScript`) — adds a worktree at the sha under review with a detached
+  HEAD, sibling to the branch worktree per the Project layout. A write there cannot move the branch or dirty the coder's
+  worktree; a rogue commit lands on a detached HEAD and evaporates with the checkout. This is not a permission boundary
+  — it is containment, the property ADR-0024 bought for turns, bought for the filesystem.
+- **Two layers, one structure: the tool list is the hint, the worktree is the guarantee** — the same shape as ADR-0024's
+  receipt (hint) and abort (guarantee). Neither layer alone: tools without the worktree leak through bash; the worktree
+  without tools invites the model to fight its checkout instead of declining politely.
+- **The reviewing state requests the review worktree per round.** The sha under review moves between rounds, so the
+  detached worktree is attached (idempotently, by sha) on entry to the reviewing state, and its path frames the
+  reviewer's turn — cwd and prompt — instead of the branch worktree. The exact Workspace-port verb is settled at
+  implementation; what is decided here is the seat: worktree mechanics stay in the attach step and the Workspace
+  wrapper, never in Agent instructions.
+
+## Considered options
+
+- **Prose alone** (today). Rejected by the incident; the coin flip is already on record.
+- **A `SessionEnv` wrapper that throws on denied operations.** The right stopgap against the retired runtime's fixed
+  toolset — ~20 lines, no drift — and moot the day jr2 owns tool assembly. Building and testing a mechanism the
+  replacement deletes was the argument for folding this decision into ADR-0027.
+- **Wait for flue 2.0's tool exports.** Rejected with ADR-0027.
+- **A read-only filesystem for the reviewer.** Rejected: the reviewer must run tests and builds, which write caches,
+  `node_modules`, temp files. Read-only breaks the persona's own job description.
+- **A separate reviewer Sandbox.** Rejected: it pays a pod per review round and breaks ADR-0012's premise — coder and
+  reviewer share one Workspace so the review sees exactly the bytes the coder produced, on the shared clone's economics.
+- **Naming the field `tools: ["read", "grep", ...]`.** Rejected: it names the Harness's menu, breaks when a tool is
+  renamed, and says nothing about the Agent. `workspace` describes the persona's relationship to the thing it works in;
+  the tool list is derived mechanism.
+- **Keeping the name `access`.** Rejected when `"none"` arrived: without the object in the name, `access: "none"` reads
+  as "no access to anything," which is false — the Agent has its full Menu. `workspace: "none"` states exactly what is
+  absent, and doubles as the placement statement above.
+
+## Consequences
+
+- **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.
+- **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
+  on `event.head === context.head`. Self-reported and unenforced — but it catches the exact incident above, and it needs
+  nothing from this ADR.

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

@@ -0,0 +1,154 @@
+# A Menu is fixed for a conversation, and a Turn is told its Allowed picks
+
+[ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md) derives what an Agent may pick from the invoking state's
+transitions. Its config walk reads transition **keys** and nothing else, so a guard is invisible to it. Two failures
+follow from where that answer is put.
+
+**A pick that moves nothing reads as progress.** An event whose every transition is guarded false validates, reaches the
+invoking state, and moves nothing. The receipt said _"the workflow is still in the state that asked for this turn"_ —
+the same sentence a successful in-state move produces.
+[ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) exists because a receipt that says nothing
+actionable gets answered by calling again.
+
+**A tools block that changes bills the whole conversation again.** The first fix for the failure above narrowed the
+tools block to what the guards would accept, per Submission. But provider prompt caches are prefix caches in the order
+tools → system → messages: Anthropic invalidates every level when a tool definition changes, and vLLM and
+OpenAI-compatible chat templates render the tools into the head of the prompt. Measured on the home-lab vLLM Instance
+(2026-09-28, a 24.8k-token history): the next Turn with the same tools hit 24288 cached tokens; with one pick added, 0;
+with the same picks reordered, 0. A continued conversation (`continue: true`, ADR-0057) changes state by design — a
+coder in `implement` may `finish`, the same coder in `fix` may `finish` or `dispute` — so every such step prefilled the
+whole history again. It also left the history calling tools the request no longer defined.
+
+## 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).
+- **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
+  something, and every writing it selects must be the Agent's (ADR-0015). Read off the live snapshot, they follow the
+  active mode as well as the guards; the Menu stays byte-identical in every mode. They are EMPTY while the Agent's state
+  is not at Rest — something it started runs below it, or a timer holds — because every pick is refused then
+  ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)); an outstanding pick's answer carries them
+  read after the route. The surface serves both (`GET /agents/:iid/surface` → `menu` and `allowed`); the Harness
+  presents `menu` as the tools block and states `allowed` in the Briefing's Turn part, after the Frame's prompt
+  ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). It rides the newest message, so it never
+  touches the cached prefix. The Briefing's standing part says how to read every such list: a pick is a call that the
+  newest "Allowed now" lists, and each pick's answer says if the Turn is over.
+- **The Orchestrator enforces, at delivery, and only there.** A pick while the Agent's state is not at Rest is refused
+  before anything else, `finish` included (ADR-0024). A pick off the Menu is refused. A pick on the Menu is not refused
+  before delivery: one inside the invoking state's derived set that the Machine does not take — a pick of another mode
+  included — is delivered and answered `moved: false`; one that only another state of this Agent handles is answered
+  `moved: false` whatever its arguments, and never reaches the Machine, because only a state the Agent does not own (a
+  nested Agent's, a Gate's) could act on it there (ADR-0015). A pick whose selection, with its real payload, holds
+  another party's writing — a mode and a sibling Gate's or nested Agent's state that write the same name, say — is
+  answered `moved: false` the same way and does not reach the Machine (ADR-0015). Every answer carries `allowed`, read
+  **after** the delivery, and the Harness renders it ("Allowed now: `finish`"). A `moved: false` pick outside `allowed`
+  gets the **correction receipt** — "`<pick>` is not allowed in the workflow's current state, whatever its arguments.
+  Your turn is not over. Do not repeat this call — pick one of the allowed tools." — because the state refused it and
+  new arguments cannot help; one inside `allowed` was refused by a guard that read its payload, and its receipt says to
+  change the arguments. The Harness does not pre-check: its list is as old as what it last read, and an in-state move
+  (`moved: true, turnComplete: false`) can change the guards and the mode mid-Turn.
+- **The Turn part is restated at a step boundary when the Allowed picks changed under the Agent.** A Gate's answer, an
+  outside event or a child's settled invoke the Agent did not pick can move the Machine while the Agent works with its
+  Working tools and picks nothing. So the Harness keeps the last Allowed-picks list the model read — the Turn part, then
+  every receipt and refusal — and after each model answer's tool results reads the surface once and compares the two as
+  sets. If they differ, it appends one message before the next model request: "The workflow's state changed since you
+  last read the Allowed picks. Allowed now: …", in a `<jr2-turn>` block. The Agent's own pick is never restated, because
+  its receipt already told the model. The read is one bounded attempt and a failure is silence; the next boundary asks
+  again. Nothing is read or said after the Turn ended or after an abort. The Harness knows the Turn ended from a pick's
+  answer (`turnComplete`, or a 404), not only from a read: under `continue: true` the next state re-registers the same
+  address before the abort lands, so a read there would answer for the next Turn. An empty list is not restated to a
+  model that stopped; the Orchestrator's wake asks it when a pick opens (ADR-0016's ask-again rule). The comparison is
+  engine-neutral (`between-steps.ts`); only the placement is the engine's — pi's between-steps input (`steer`). An
+  engine with no such input falls back to the next receipt. No route is added and no cap is set; the Orchestrator
+  already serves the truth on `GET /agents/:iid/surface`.
+- **Presentation stays in the Harness's neutral layer.** `menu.ts` renders the Allowed-picks text and every receipt; a
+  presenter (`menu-tools.ts` for pi) only maps Menu items to its tool API and places the text it is handed. A second
+  harness — one that takes MCP tools fixed per session and the prompt as text — needs a presenter, not a second Menu.
+
+**The guard question is asked twice, because the two askings can see different things.**
+
+- The Allowed picks: payload-blind, asked as the Agent's sender (`takesNow`, ADR-0015) — or `mayMove(invoker, name)`
+  where no seat can be read (a plain `setup()` actor tree). The pick has not happened, so there are no arguments to
+  judge.
+- Delivery: `wouldMove(invoker, event)` and xstate's own selection on the real event. The validated payload and the
+  sender are in hand, so the answer is exact.
+
+**A guard that reads the pick is never hidden.** A guard like `({ event }) => event.verdict === "approved"` answers
+`false` on a payload it was not given — by plain comparison against `undefined`, not by throwing. So the payload-blind
+reading passes the event behind a Proxy that records any read outside `type` and `sender`, per guard, and trusts a
+`false` only when the guard never looked. A guard that looked is allowed, and settled at delivery. This rests on xstate
+handing a guard the object passed to `can()`, unspread — pinned by a test asserting a payload-reading guard stays
+allowed. A future xstate that copies the event first would degrade this to allowing more, never less.
+
+**Both readings fail open.** No invoker, or a guard that throws, reads as allowed. A wrong `true` costs one refused
+pick; a wrong `false` tells an Agent its work is not wanted when the workflow would have taken it, and nothing recovers
+from that.
+
+**Absent `moved` is not `false`, and absent `allowed` is not empty.** The Harness ships as a stock image and the
+Orchestrator (ADR-0027), so the two can skew. A surface without `menu` is read as today's narrowed list, presented as
+tools.
+
+**A Gate's accepted set stays whole; `acceptsNow` sits beside it.** `GET /runs/:id` lists each Gate's `accepts` — every
+name it may ever send, with its schema, which drives a form — and `acceptsNow`, the same payload-blind question the
+Allowed picks ask, asked as the Gate's sender (ADR-0011). Neither is filtered to empty into a fault: a Gate whose
+`acceptsNow` is empty waits. A send the run would not take is refused 409 with `acceptsNow` (ADR-0013); a human reads
+the Gate's `meta` and the refusal and can tell why, which is precisely what an Agent needs the Allowed picks for.
+
+## Why the text comes after the prompt, and why refusal is not optional
+
+Measured on the home-lab vLLM model (Qwen3.6-35B-A3B, 10 trials per cell, a prompt arguing for a pick the Turn did not
+allow): with the whole Menu as tools and no statement, 0/10 first picks were allowed; with the Allowed picks stated
+**ahead** of the prompt, 0/10 (thinking off) and 5/10 (on), whatever the wording; stated **after** it, 10/10 both. On a
+weaker pull the statement alone sufficed. After one refusal naming the Allowed picks, 57 of 58 wrong picks recovered on
+the next call. So the statement carries the everyday case, and the refusal is the net under it. Narrowing the tools
+block was not perfect either: once the model invented a tool it had never been given.
+
+## Considered options
+
+- **Narrow the tools block per Turn** (this ADR's first form). Rejected: it breaks the prefix cache on every Menu
+  change, and the history then calls tools the request no longer defines — which models are observed to call anyway.
+- **Fix the tools per invoking state, drop guard narrowing.** Rejected: fixes the within-state case, not ADR-0057's
+  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.
+- **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.
+- **Refuse the delivery outright when `moved` is false.** Rejected for a guard that says no: `deliver` is the single
+  validation path behind both dialects, and the receipt already carries the distinction. A pick whose selection holds
+  another party's writing is a different class — delivering it would run that party's writing — so it is answered like a
+  pick off the invoking state's derived set, and never delivered.
+- **Filter mid-Turn and push `list_changed`.** Rejected: nothing pushes to the Harness (ADR-0013), and a list that moves
+  under an Agent invites the retry loop from the other direction.
+- **The Orchestrator pushes the restated Turn part over a new route.** Rejected: pi appends only at a step boundary, so
+  a push arrives no earlier than the Harness's read, and it needs a route that writes text into a conversation, change
+  detection over every run, and a copy of what the model read that an Orchestrator restart loses.
+- **Parse a JSON-text argument where the pick's schema declares an object** (pi's `prepareArguments`, before the engine
+  validates). Rejected, measured: on the home-lab instrument writing a Chart
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)) about one call in three carried the object as a string, and
+  0 of 89 such strings were JSON — each had its braces miscounted around a `{{...}}` reference — so the parse would have
+  fired on none. A leniency that no run can show working is not kept on a hypothesis; a model that stringifies cleanly
+  will show it in its own trials, and the ten lines come back with that number.
+- **The Allowed picks on every Working-tool result.** Rejected: a statement repeated where nothing changed is one the
+  model learns to skip.
+
+## 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).
+- **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.
+- **A workflow expresses "not available yet" with a guard alone,** and the Agent is told so rather than finding a tool
+  that silently does nothing.
+- **`on: { X: {} }` — targetless and actionless — is never allowed,** matching xstate's `can()`.
+- **The receipt declarations stay hand-synchronized** across `run-host.ts` and the Harness's `menu.ts`, now carrying
+  `allowed` too — the cost of the packages not importing each other.

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

@@ -0,0 +1,100 @@
+# A snapshot names the Machine it was written under
+
+[ADR-0007](0007-durable-machine-state.md) persists a run's snapshot so a restarted Orchestrator resumes it.
+[ADR-0008](0008-orchestrator-as-deployed-app.md)/[ADR-0019](0019-one-converging-command-against-the-current-context.md)
+publish the Instance's Assembly to an Orchestrator whose volume outlives every publish
+([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). And a persisted run is
+matched to its workflow by **filename stem**: by name inside the Assembly its snapshot names, and, for a run that no
+Assembly started (an in-process test host), by name in the registry.
+
+Those three facts compose into a hole. Park a run at a Gate, edit `workflows/task.ts`, `jr2 up`. The name still
+resolves. The def found under it is a different Machine. Nothing checks, and — this is the part that decides the shape
+of the fix — **xstate does not validate a restored state value.** A snapshot whose `value` names a state the new chart
+does not have does not throw: `createActor` accepts it and the run starts with `value: undefined`, carrying on from
+nowhere. There is no downstream check to fall back on. Either restore refuses, or nothing does.
+
+## Decision
+
+**Every save stamps the shape of the Machine that wrote it; every restore compares before interpreting.** `RunBlob`
+gains `machine`, a 12-hex digest — the same width `jr2 up`'s content hash uses, and for the same reason: it is read by
+people in error messages more often than by code. A mismatch is refused before `reconcile`, because proving a Sandbox is
+alive for a run that cannot be read is wasted work.
+
+**The digest covers restorability, not behavior.** It is built from `machine-doc.ts`'s traversal — already deterministic
+(states sorted by `order`), JSON-pure, provider-independent, and descending into invoked and spawned child machines —
+projected down to the facts a snapshot has to agree with:
+
+- state ids, keys, types, nesting, and which child is `initial`;
+- each state's invokes by `id` **and** `src` (the id is the key in the persisted `children` map, so re-attach depends on
+  it — the most easily missed of the three, and a reason a `src`-only hash would not do);
+- every transition as `source|event|targets`, **sorted**, so reordering `on:` keys is not drift.
+
+Deliberately excluded: guard bodies, actions and assigns, prompts, descriptions. Editing a guard changes what a run does
+_next_; it does not make the snapshot unreadable. The alternative — any edit to a workflow strands its parked runs — is
+defensible in the abstract and unusable in practice: it makes `jr2 dev`'s reload a migration event and prompt-tuning a
+stop-the-world operation. **Drift means "I can no longer read what I saved," not "something changed."**
+
+**Absent means drift.** A blob written before the stamp existed cannot be vouched for, and the point is to never
+interpret one that cannot be. Greenfield, so a stale local `.jr2/state.db` is deleted, not migrated.
+
+**A drifted run is refused, kept, and readable.** Not `markLost`: that nulls the snapshot, and `read()` returns
+undefined for a null blob, so `jr2 status <id>` would answer `no run "<id>"` — a refusal indistinguishable from a run
+that never existed, on precisely the run a human most needs to look at. `drifted` is its own status, the snapshot is
+untouched, and `RunStatus` gains `reason`, which nothing on any HTTP route surfaced before. The refusal names the
+workflow and both digests.
+
+**A throw during restore is a different claim from drift, and is not recorded as one.** Drift is durable — the Machine
+will still have changed on the next boot. A `reconcile` failure is a kubectl blip, and condemning a run for it would
+make a transient fault permanent (or, via `markLost`, throw the snapshot away). Those rows are left `live` for the next
+boot to retry, reported through `onRestoreError`, and counted separately as `failed`.
+
+**One unresumable run is one run.** The restore loop is sequential, and a throw used to reject `restore()`, which
+rejects `startInstance`, which crash-loops the pod — taking every _later_ run in the store down with it, unrestored.
+Each run is now handled independently.
+
+**The boot announces what it did not resume.** `restore()` returns `{ reattached, lost, drifted, failed }`, and the
+entrypoint puts the last three on its announce line. A boot with no current Assembly lists its runs as `waiting`
+instead, and the first publish, which restores them, announces one line `{ assembly, lost?, drifted?, failed? }` when
+any was not resumed ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)).
+Resumed runs are routine and stay quiet. Without this, `drifted` is reachable only by asking after a run id nobody knows
+to ask about.
+
+## Considered options
+
+- **Hash the workflow module source, or the whole config including guards and actions.** Rejected — see above. Maximal
+  safety at the cost of making every workflow edit a migration.
+- **Reuse `JR2_CONTENT_HASH`**, which `jr2 up` already computes and injects. Rejected: it is a digest of the whole
+  staged bundle, so it moves on a lockfile bump, a README edit, or a kit upgrade — constant false drift — and it is
+  absent under `jr2 dev` entirely.
+- **Topology plus named guards** (`setup()` keys and named functions). Rejected: inline arrows collapse to `"inline"` in
+  the doc and would stay invisible, so the coverage is uneven in a way no one could predict from reading a workflow.
+- **A `machine_snapshots` schema column.** Rejected: `init()` is a single `CREATE TABLE IF NOT EXISTS` with no migration
+  mechanism, so a new column would silently not appear on an existing PVC. The blob is versioned by being JSON.
+- **Warn and resume anyway.** Rejected: there is no safe interpretation to fall back on. xstate resumes a missing state
+  as `undefined` rather than failing, so a warning would be the only signal, on a run already running wrong.
+- **Fold the workflow name into the digest.** Rejected: restore resolves the def by name first, inside the run's own
+  Assembly, so a rename never reaches the comparison — it would only make a rename look like a shape change on a run
+  that no longer resolves at all.
+
+## Consequences
+
+- **Editing a workflow strands nothing.** A run holds the Assembly it started under, through restarts too
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)), so a publish never
+  changes the Machine a live run resolves to. Drift is reached only when a held Assembly cannot be read any more: it
+  does not load under a bumped Kit version, or the volume lost it. The stamp still stands as the last check, because the
+  Assembly hash says which tree was loaded and the stamp says the Machine in it still has the shape it had.
+- **There is no migration path.** A drifted run can be read and cancelled; it cannot be adapted onto a new Machine. That
+  is deliberate for now — a migration story needs a way to express what a state maps to, which nothing here does.
+- **A run with an Open body keeps its wrapper's stamp.** A Chart
+  ([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.
+- **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.
+- **`fingerprintOf` is memoized per machine object** — `persist` runs on every snapshot microtask, and a dev reload's
+  fresh machine object correctly gets a fresh entry. That is not `vocabularyOf`'s key, which is `machine.config` so a
+  `.provide()` clone keeps the defs it was built with (ADR-0011); a shape has nothing to keep, being derived from the
+  config alone, so a clone recomputes the identical digest.