@jr2/orchestrator 0.4.1 → 0.5.1

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

@@ -0,0 +1,190 @@
+# Menu-only Agents run on the Instance Harness
+
+A workflow should be able to run an Agent whose whole job is a decision — read some inputs, pick the next event — with
+no Workspace, no worktree, and no per-run pod: the statelyai/agent shape, at conversational latency, on any configured
+model. jr2's Menu already _is_ that decision surface (the invoking state derives what the Agent may say —
+[ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)/[ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)),
+and the mechanism was already Sandbox-agnostic: `agentRun` needs only an endpoint URL, a registration may carry no
+Sandbox (`tokens.ts`), and the stub Harness proved a Harness is "only a different URL". What was missing was the
+hosting: the only real Harness anywhere was the one inside a Sandbox pod, so a Turn without a `workspace()` had nowhere
+to run. Adopting statelyai/agent instead was rejected outright — it would be a second, weaker agent mechanism (no
+Submission/Admission ledger, no re-attach, no Settlement, a menu that is not guard-narrowed) beside the one jr2 already
+built.
+
+## Decision
+
+- **One Instance Harness per instance, deployed by convention.** `jr2 up` converges a Harness StatefulSet + Service —
+  stock `jr2-harness:<kitversion>` image, same wire — whenever any Agent slot carried by a registered Machine
+  (ADR-0049's walk) declares `workspace: "none"`
+  ([ADR-0028](0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)). The scan is static and
+  definition-level, deliberately not workflow-level (workflow internals are not statically recoverable — the same line
+  ADR-0018 drew for model preflight); a declared-but-never-invoked `"none"` Agent over-deploys, erring toward "the
+  convention works when you need it". No config key names, sizes, addresses, or enables it.
+- **Placement is definition-wins, not nearest-wins.** A `workspace: "none"` Agent's Turn runs on the Instance Harness
+  _always_ — even invoked from inside a `workspace()`. It is ADR-0028's thesis extended one step: an Agent that touches
+  no Workspace has no reason to run in one, and a Sandbox — torn down at its Workspace's final state, replaced after an
+  eviction — is the wrong home for a conversation whose definition says it needs no Workspace. A conversation is an
+  Instance ID _on one Harness_ (the server holds the history), so placement must be a function of the definition, not of
+  where an invocation happens to sit; nearest-wins would make the Harness that holds a `"none"` conversation an accident
+  of authoring. Definition-wins also makes "which pod's logs" a function of the Agent alone.
+- **The cohesive per-run log is solved by projection, not placement.** The cost of definition-wins — decisions vanishing
+  from the Workspace pod's log — is repaid by [ADR-0023](0023-the-harness-prints-the-conversation.md)'s echo: the
+  enclosing Workspace's Harness prints the run's narrative (admission + pick markers for remotely-hosted Turns, Emits,
+  the backfilled preamble). Instance Harness log = every `"none"` conversation, instance-wide, interleaved (the less
+  useful top-to-bottom read, accepted); Workspace log = everything that ran there plus the narrative of the run that
+  owns it.
+- **The Instance Harness pod is Harness + Custodian — the one Harness shape, minus the Workspace.** No user container,
+  no `/work` volume, no attach step. The Custodian stays although `"none"` Agents cannot execute code (the
+  [ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md) rationale technically lapses):
+  the Harness has exactly one route to its Menu — the Custodian on `localhost` — and forking that path for one pod buys
+  a divergence in the component this ADR keeps deliberately uniform. The pod is composed by the same function a
+  Sandbox's is ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)), so its Custodian
+  carries the Instance Harness's model calls the same way. It holds only the model keys of the `"none"` Agents it hosts
+  — the keys their providers read — and none of the held secrets a `workspace()` lists: a `"none"` Agent cannot execute
+  code, so it had no way to use the rest. Its held objects are its own (`held-instance.json`,
+  `jr2-held-secrets-instance`). Defense-in-depth is the bonus, not the reason.
+- **The Instance Effector is the second Instance-level pod, beside it**
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), on the same convention: `jr2 up`
+  converges it when a registered Machine places an Effect there — an `http` Effect — and deletes it otherwise. It runs
+  the same `jr2-harness` image with `/opt/jr2/bin/effector` as its command, holds no conversation and runs no Agent, and
+  is a Deployment, not a StatefulSet: it keeps nothing, and a rollout must run the new pod beside the old one. No config
+  key names, sizes, addresses, or enables it.
+- **No image config at all.** The Harness image was once configured as `sandbox.image` because the Sandbox pod was the
+  only place a Harness ran — a misnomer once the Instance Harness exists, and config is the wrong seat regardless:
+  `jr2 up` builds and resolves every image it deploys ([ADR-0038](0038-jr2-up-builds-every-image-it-deploys.md)), and
+  the per-Workspace images (Sandbox Image, User Container) are static `workspace()` options carried by the Machine
+  itself ([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md),
+  [ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md),
+  [ADR-0005](0005-sandbox-pod-composition.md)). `sandbox.image`, the per-component image keys, and `operator.image`
+  dissolve; the `sandbox` config section disappears until something genuinely pod-shaped and user-tunable exists.
+
+## The Instance Harness holds a conversation as long as its run, and frees the rest
+
+The scaling review (R11, 2026-09-30) found the `conversations` map with no delete path: every Menu-only Agent instance
+of every run stayed until the pod restarted, and the restart lost every conversation at once. The research that preceded
+it checked Agent Substrate's own model against the primary sources: an actor is stateful, the platform snapshots its
+memory and its `DurableDir` volumes and resumes it on any worker, and its control plane holds metadata and snapshot
+pointers only; memory snapshots are tied to one template version, so the state with a documented path across a code
+change is a volume the actor reloads on a cold boot. These decisions take that shape.
+
+- **A conversation is persisted to a directory, and rebuilt from it on boot.** The Harness writes each conversation as
+  it goes: jr2's own record — the stream log, the Settlements, the history messages, in the wire's shapes — plus the
+  engine part, in a folder the engine names (`engine/<name>`), which the record does not read. Today it is jr2's
+  transcript (ADR-0027): `engine/pi/transcript.jsonl`, the pi-ai messages the model read and each Compaction. Rebuilding
+  reads jr2's record first; an engine that cannot read the engine part (another engine, another version) continues from
+  the history messages. The record is the contract; the engine part is not. A Submission in flight at the restart
+  settles `failed` (the typed error `harness_restarted`, which the Agent's Actor reads as "Turn lost") on the rebuilt
+  stream, so the Orchestrator reads a Settlement, not a 404, and the conversation's next Turn continues it.
+- **A restart while the Agent's state is busy cuts the Turn and is no fault.** When the Agent's state is not at Rest —
+  its pick is outstanding, or work it started in runs below it — or its pick's answer was read and never reached the
+  model, the Agent's Actor raises no `agent.fault` for a restart: the Machine would route it and stop the work the Turn
+  did not want stopped (ADR-0024). It waits for Rest, then re-admits the Agent on the same conversation, which the
+  rebuilt Harness holds: a jr2 prompt ("Your previous turn was cut: the process that ran you restarted while the
+  workflow was busy. The workflow did not stop. Continue your task from here.") with the answer as a `pick-answer`
+  notice (`cut: true`) in the Briefing's Turn part, and the Allowed picks after it (ADR-0062). The re-admission asks the
+  rebuilt Harness for the conversation first, as a continued Turn does: one it cannot read gets a `conversation-new`
+  notice ahead of the answer, and the notices pending for the Turn ride along. In the rebuilt engine part the cut Menu
+  call has no result; the Harness answers it in the history with jr2's text — the pick reached the workflow, which does
+  not run it twice, and its result comes in the next message — before pi-ai would answer "No result provided", which
+  reads as a failed pick. That text prints once in the rebuilt Harness's log, before its first prompt (ADR-0023). The
+  engine runs a model answer's calls in order
+  ([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)). So only the first call with no
+  result can have been out. Every call after it never started, a Working-tool call too. Each one gets jr2's text "This
+  call did not run: your turn ended before it started.", as an error result. A Menu call that an abort cut while the
+  model was still writing it (the abort lands mid-stream) did not reach the workflow: the engine runs no call of a
+  message the model did not finish. The Harness tells the two cuts apart by whether the call was delivered, read before
+  it re-tags an aborted message so that pi-ai replays it: a call in a finished message keeps the text above, and a call
+  in an aborted message gets jr2's text in the same form — the Turn was cut while the model was still writing this call,
+  it did not reach the workflow, nothing ran, and the model may call it again if the newest "Allowed now" still lists
+  it. That text prints once too, before the conversation's next prompt, in the same process or the next. The Harness
+  reads whether a call was delivered off its message, not off a record of the POST, and that is the limit of the test: a
+  SIGKILL of the Harness after the model finished the message and before the pick's POST reached the Orchestrator leaves
+  a call that never reached the workflow, and the rebuilt Harness answers it with the restart's text. Closing that
+  window needs a delivery record written before the POST, which is not built. A Menu call in a message that a provider
+  error ended mid-stream (stopReason `error`) is neither cut: pi runs no call of such a message (pi-agent-core 1.4.0
+  `agent-loop.js` line 148 returns after a message that ended `error` or `aborted`) and drops it from every later
+  request (pi-ai 1.4.0 `transform-messages.js` lines 172 to 180), so the Harness does not re-tag it and adds no answer
+  for its call: an answer would be a tool result with no call before it, which the providers refuse. The pick did not
+  reach the workflow, the Submission settles `failed` as any provider error does, and on the next request the model
+  reads no trace of the call and is free to make it again. A poll takes the answer only while its connection lives: the
+  killed Harness's last poll, still waiting at the Orchestrator, ends unanswered when its connection closes, so an
+  answer that lands after the kill, and before the rebuilt stream reports the restart, is still unread. The same holds
+  for a Sandbox's Harness, whose restart the watch sees (ADR-0021). A restart at Rest with nothing unread is the fault
+  it always was. Only the Turn's OWN pick counts as unread: a pick of an earlier Turn on the same continued address,
+  whose route left the Agent's state, was answered as a notice to this Turn, and a restart at Rest in this Turn is still
+  the fault. A route that leaves the Agent's state ends the Turn while it waits, as any route does.
+- **Both placements persist, to different volumes.** The Instance Harness to a PersistentVolumeClaim of its own; a
+  Sandbox's Harness to an emptyDir mounted into the Harness container alone (the User Container must not read it), so a
+  Harness container that restarts inside a living pod keeps its conversations. A pod that is gone takes the emptyDir
+  with it — that Workspace is `Lost` (ADR-0021), and no conversation persistence should say otherwise.
+- **The Instance Harness is a StatefulSet of one, with a per-ordinal volume.** The value is the stable volume; the
+  stable name is what N > 1 would pin a conversation to (the admission ledger already records its endpoint). N is a kit
+  value, 1 until a measured need; never an HPA, which would kill conversations on a scale-down and land a continuation
+  on a replica that never saw it. A rollout at N = 1 has no surge, so admissions are refused while the new pod starts;
+  the Orchestrator already absorbs an admission refused at the connection (ADR-0042), so a rollout delays a Turn and
+  faults nothing.
+- **A rollout drains Turns.** On SIGTERM the Harness stops admitting, finishes the Turns it holds (the queued ones too),
+  then exits; the termination grace is a Turn's worst case. A Turn still generating or running a tool keeps that
+  graceful wait. A Turn whose only pending work is an outstanding pick's poll — whatever the pick waits on: a Gate, an
+  Effect, a child Machine — is cut at once, or as soon as it comes to that: its answer can wait on a human (a Gate),
+  often the one who is stopping the Harness, so no grace period would help. The cut drops the poll unanswered (the
+  answer stays unread at the Orchestrator), leaves the Menu call without a result, asks the model nothing more, and
+  settles the Submission `failed`, `harness_restarted`, with everything queued behind it. To the Orchestrator it is a
+  restart while the Agent's state is busy (the bullet above): the pick stays outstanding, and once the workflow is back
+  at Rest jr2 re-admits the Agent on the same conversation with the answer, and the replacement Harness answers the cut
+  call with jr2's text. It refuses an admission with a 503 before it reads or queues anything, and closes that
+  connection, so the Orchestrator re-sends it on ADR-0042's ladder and the re-send dials the Service anew. Readiness
+  stays up (the probe is the Harness's own `/healthz`, which it keeps answering), and the dialed Service is a ClusterIP
+  one, which kube-proxy still routes to a terminating pod that serves while no other is ready — so reads keep answering
+  and a `wait` on the draining pod still reads its Settlement. A headless name would not: DNS stops naming a terminating
+  pod, so the StatefulSet's headless governing Service is a second one, dialed by no one. The Custodian is a native
+  sidecar, stopped only after the Harness exits, so the drain keeps its Menu and its model to the end. A deploy loses no
+  Turn and, with the volume, no conversation — as long as the drain and the replacement's start fit ADR-0042's window; a
+  longer one faults the waiting admission with the Harness's own 503 words.
+- **The Orchestrator states the live set; the Harness frees the rest.** After every restore and every 5 minutes (the
+  Lease's cadence) the Orchestrator tells the Instance Harness which conversations its live runs hold — from the
+  admission ledgers in memory, never from the store — and the Harness frees memory and files of every other one.
+  Level-triggered, idempotent, a missed statement costs nothing, and a crashed Orchestrator's leftovers go at its next
+  boot. No idle TTL: a run parked on a Gate for a day keeps its conversation, and nothing else can decide that. A
+  Sandbox's Harness is not told; its Workspace's teardown frees everything.
+- **The Orchestrator keeps holding handles only** (ADR-0007): no conversation state crosses to it. Storing sessions
+  centrally and re-sending them to a fresh pod was considered and rejected — it is the design Substrate does not have,
+  and it puts every Menu-only Turn's history on the single writer's path.
+
+## Considered options
+
+- **statelyai/agent (or any in-process decision actor).** Rejected above; the long form: every ADR from 0011 to 0029
+  would stop being the single story of how models drive Machines, and the copy would be the lesser one — its picks
+  bypass the Menu's guard-narrowing, its runs bypass the admission ledger, its failures bypass Settlement.
+- **Unconditional ambient fallback** (no enclosing `workspace()` → Instance Harness, for every Agent). Rejected: a coder
+  invoked outside its `workspace()` by mistake would run bash in the shared pod instead of failing loudly — precisely
+  the mistake today's error catches. The fallback is gated on `workspace: "none"`; everything else keeps the loud error,
+  now sharper ("agent `x` has `workspace: "write"` — invoke it inside a `workspace()`").
+- **Nearest-wins placement** (a `"none"` Agent invoked inside a `workspace()` runs on that Workspace's Harness).
+  Genuinely attractive — the Workspace pod log stays the one coherent story with zero new mechanism — and rejected on
+  the continuation amnesia above plus three lesser costs: decisioner turns die with workspace churn, share limits with
+  builds, and scatter one Agent's history across pods. The log story it bought is recovered by ADR-0023's echo.
+- **On-demand pod per workspace-less run.** Rejected: pays pod-start latency on the path whose whole point is a fast
+  pick.
+- **Hosting the Turn in the Orchestrator process.** Rejected: no pod logs, and it crosses the line the architecture
+  draws hardest — the Orchestrator holds handles; models act remotely.
+- **A host-local dev Harness.** Considered as a dev story and dropped when the premise died:
+  [ADR-0019](0019-one-converging-command-against-the-current-context.md) removed `jr2 dev` — there is no host dev mode
+  to serve. Local development of a decisioning workflow is `jr2 up` against kind, where the Instance Harness converges
+  like everything else; an instructions tweak rides the next admission, no image build. The stub Harness keeps its one
+  job: a test fixture reached by explicit `endpoint`.
+
+## Consequences
+
+- **The Agent's resolution grows one arm**: explicit `endpoint` (tests) → `workspace: "none"` → Instance Harness
+  (deterministic Service DNS) → enclosing `workspace()`'s ambient handles → loud error naming the definition's
+  `workspace` value.
+- **A `"none"` conversation survives the Instance Harness pod's restart**: the StatefulSet restores the endpoint and the
+  volume restores the history. A Turn in flight at the restart settles `failed`; nothing is continued silently — a Turn
+  whose state is busy is re-admitted with a prompt that says it was cut.
+- **An instance with no `"none"` definitions deploys nothing new.** The feature is invisible until the first
+  `agent({ ..., workspace: "none" })` a Machine carries, which is its entire user-facing surface.
+- **The harness conformance suite (ADR-0027) gains the Menu-only shape**: a Turn whose definition withholds every
+  Working tool, settled by pick alone — no infra, same scripted provider.
+- **GLOSSARY.md**: Harness's "inside a Sandbox" loosens to name the second placement; **Instance Harness** becomes a
+  glossary term.

package/docs/reference/decisions/0032-the-console-unlocks-with-the-instance-token.md

@@ -0,0 +1,61 @@
+# The Console unlocks with the Instance token, and the bands do not move
+
+[ADR-0014](0014-observation-is-open-run-state-is-not.md) built the three-band HTTP surface on one premise: the
+visualizer page is a browser, and a browser holds no token — so it got a projection instead of a credential, and "give
+the page a token" was explicitly rejected. That page is now growing into the **Console**: it starts runs and answers
+Gates, both of which are writes on the guarded surface. This ADR records how a browser earns those writes without moving
+a single band — and it can stay this small because of a fact ADR-0014 did not lean on: the Instance token is already one
+`kubectl get secret` away for exactly the audience the Console serves. There is no new distribution problem, only a new
+presentation surface.
+
+## Decision
+
+- **The human presents the token; the page never ships with one.** The Console's nav carries a password field. Empty,
+  the page is precisely ADR-0014's observer: open structure and observation, no control rendered. Filled, the page sends
+  `Authorization: Bearer` on the guarded surface — which unlocks both directions at once: the writes
+  (`POST /workflows/:name/runs`, `POST /runs/:id/gates/:gate/events`) and the `instanceOnly` reads the control UI needs
+  anyway (`GET /runs`, and `GET /runs/:id` — where `GateView` lives). The page as _served_ stays open and inert;
+  ADR-0014's rejection stands, because what it rejected was baking the credential into the page.
+- **The token lives in `sessionStorage`** — survives a reload, dies with the tab, never a cookie (no ambient credential,
+  no CSRF surface). It is validated on entry with a cheap guarded read so the field shows live/invalid immediately; any
+  later 401 drops the UI back to observer mode rather than failing per-widget.
+- **Gate discovery is a frame-triggered guarded read, not an open-band extension.** A Gate exists exactly while its
+  invoking state is entered (ADR-0011), and every entry/exit lands a status frame on the open workflow feed (ADR-0022) —
+  so on each frame, a token-holding Console re-fetches `GET /runs/:id` for the affected run and folds `gates` into its
+  store. Perfectly synchronized, no polling loop, and the observation projection is untouched. A delivery's success is
+  likewise confirmed by the next frame emptying the card, never by local bookkeeping.
+- **Page addresses content-negotiate; JSON is the default dialect.** `/` and `/workflows/:name` serve the Console shell
+  to `Accept: text/html` and JSON to everything else — so the workflow-detail resource keeps its natural address (the
+  run-input schema's home, [ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)) and no future page has to
+  squat on a mangled sibling path. Nothing existing moves: EventSource asks `text/event-stream`, and the Harness's Menu
+  and the CLI never ask for HTML. `/viz/*` is deleted (greenfield, no redirects); assets move to `/assets/*`, which also
+  retires the "a workflow named `assets` is shadowed" hazard.
+
+## Considered options
+
+- **`jr2 ui` — the CLI opens the browser through an authenticated local proxy.** A convenience layer worth building _on
+  top of_ the token field later, not a substitute: it has no answer for the deployed jr2 Application behind an ingress,
+  where the browser talks to the Service directly and the CLI is not in the path.
+- **A fourth, scoped credential** ("may answer gates, may not cancel or read context"). Still rejected, as in ADR-0014 —
+  but the calculus has narrowed: it becomes worth writing only when gate-answering is delegated to people who must _not_
+  hold cluster RBAC. That is a real future (an approval inbox for non-operators); it is not this one.
+- **Announce gates on the open observation feed** (even just `{runId, gate}`). Rejected: it widens the projection for a
+  convenience the token already solves, and the open band has an unresolved exposure question as it stands (spawn ids —
+  the ADR-0014 open call). The projection stays the one place the line is drawn.
+- **A `/ui` path prefix, or moving the API under `/api`.** Rejected for negotiation: the first is ceremony on the
+  address a human types, the second churns the Harness's Menu, the Custodian's route allowlist, the CLI, and the
+  ADR-0009/0013 route tables for cosmetics.
+
+## Consequences
+
+- **Zero new server surface except negotiation.** No new token, no new band, no new route class; `auth.test.ts`'s
+  boundary assertions are untouched. The server-side diff is: negotiate two addresses, serve the shell, retire `/viz/*`.
+- **Possession remains cluster RBAC.** Whoever can read the instance Secret could already do everything the Console
+  unlocks; the field changes where the token is typed, not who holds it.
+- **The XSS caveat is the real one and is bounded by what the page is:** a token in `sessionStorage` is readable by
+  scripts on the page, so the Console must keep serving only its own assets — no CDN, no third-party script, exactly the
+  constraint the viz page already lives under.
+- **GLOSSARY.md**: **Console** becomes a glossary term (visualizer, dashboard, UI, viz on its Avoid list).
+- **The Console's UX gets a browser tier** — `@console`-tagged Cucumber scenarios holding a Playwright page, in
+  `@jr2/e2e`, excluded from the default profile ([ADR-0010](0010-bdd-acceptance-tests.md) as amended). What the page
+  _believes_ stays unit-tested in `console-store.test.ts`; the browser tier asserts what a user does and sees.

package/docs/reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md

@@ -0,0 +1,127 @@
+# A Machine declares the input that starts it
+
+`POST /workflows/:name/runs` takes a JSON body and hands it to the machine as xstate `input` — unvalidated, and
+undescribed: the module contract is `export const machine` alone (ADR-0011/0015), so nothing at runtime says what a run
+of a given workflow should be started _with_. The Console's start form
+([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)) forced the question, but the gap predates it —
+`jr2 run` has the same blindness, and a typo'd input surfaces as a confusing mid-run failure instead of a refusal at the
+door. Meanwhile every event a machine _accepts_ already carries a zod schema, attached to the machine itself
+([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)'s vocabulary-on-the-machine). The input that starts a
+machine is the one piece of its vocabulary that pattern missed.
+
+## Decision
+
+- **The schema rides the machine, like the rest of the vocabulary.** `jr2Setup.createMachine` accepts an `input` (a zod
+  object) and attaches it the same way event defs ride today (WeakMap-keyed on `machine.config`, so a `.provide()` clone
+  keeps it — ADR-0011). `input` is deliberately xstate's own word for what a machine receives at creation — the
+  authoring surface teaches nothing new.
+- **A door that no one reads is refused.** The `setup()` of xstate keeps an `input` in the config of `createMachine`,
+  but it does not read it. TypeScript accepts that `input`. Thus a Machine that `setup()` made and that has a zod
+  `input` has no door. A run starts with any input, and the Console start form is only a field for JSON. `jr2 up` and
+  the publish door use the same walk (`doorRefusals`, ADR-0069). The walk refuses a registered Machine if its config has
+  a zod `input` and no door is attached to it. The refusal line gives the fix: make the Machine with `jr2Setup`. If the
+  Machine takes no workflow event, leave out `events` (ADR-0015). The walk tests the attached door, not the factory.
+  Thus a `workspace()` or `pool()` wrapper with its own door passes. A `.provide()` clone keeps the config of its
+  original, so the walk gets the same result for the clone. A Machine with no `input`, or with an `input` that is not
+  zod, can use `setup()`. The `ping` Workflow that `jr2 init` writes uses it. The walk checks the registered roots only,
+  because the `input` of a nested Machine is never the door (see below). `workspace()` refuses a body with a zod `input`
+  when you call it. It reads the config and the attached door, so it also refuses a body that `setup()` made. Considered
+  and rejected:
+  - Refuse all `setup()` Machines. This adds work to the first Workflow and gives nothing.
+  - Refuse at boot. Then an Assembly that is already published stops the Orchestrator. The walk refuses only the next
+    publish.
+  - Take a zod `input` on a `setup()` Machine as the door at load. The loader can read that `input`. But then there are
+    two ways to declare one door. Also, the zod schema stays in `machine.config`, and a schema must not go into the
+    fingerprint and serialization paths that read the config. And that Machine does not get the Vocabulary checks of
+    `jr2Setup`.
+- **A wrapper declares its own door; it never borrows its child's.** `workspace(body, { input, spec })` and
+  `pool(worker, { input, … })` each take an `input` of their own, and neither propagates one upward. The reason is the
+  same in both, at different strengths: a wrapper does not feed its child what a caller sent. `pool` is the sharp case —
+  a worker is fed per-item, never the run body, so propagating its schema would demand fields the pool never passes and
+  strip the pool-level fields `cap`/`itemInput` read. `workspace` is the mild one — its body gets the run input _plus_
+  the injected `workspace` handles, so the body's contract is the door PLUS a field no caller can send (the handles do
+  not exist until a Sandbox is provisioned and attached). Propagating it would make `createMachine({ input })` mean "my
+  input" on a bare machine and "my input minus what my wrapper injects" on a wrapped body — a context-dependent
+  contract, and a trap: a body that declared its input honestly, handles included, would 400 every valid run start. The
+  vocabulary does not propagate either — event names resolve against the Machine that invoked the actor, so a body keeps
+  its own defs and nothing is merged upward (ADR-0011, ADR-0049). The door is one more part a Machine carries and scopes
+  to itself. The composition the body needs a name for is exported instead:
+  `Workspaced<T, Slot> = WithoutEmptyIndex<T> & { workspace: WorkspaceHandles<Slot> }`, the handles keyed by the Repo
+  Slots the body names (ADR-0050, ADR-0051). A door with no fields gets the same name: `z.infer` of `z.object({})` is
+  `Record<string, never>`, an index signature that says each key holds `never`, and intersected with the handles it
+  makes each `assign` to the body's context a type error that does not name the cause. So `Workspaced` removes a string
+  index signature whose value is `never`, and only that: named fields beside it stay (`HostInjectedInput & …` keeps
+  `instanceId`), and an input that is a real map is not changed. A separate name for the empty door was the alternative;
+  it was rejected because the author then chooses between two names for one statement, and finds the second only after
+  the opaque error. A body that _still_ declares a schema is refused by `workspace()` with a message naming the fix:
+  nothing would ever serve or validate it, and a contract nobody enforces is worse than none.
+- **The door types the mapping, and constrains the body.** `WorkspaceOptions.spec` reads its `input` from the declared
+  schema (`z.infer`), so a workflow states its shape once and the workspace mapping is checked against it — the drift
+  this ADR exists to close, closed in the one place that used to re-declare the shape by hand. The same schema checks
+  the _body_, in **one direction only**: the body may not demand more than the wrapper will hand it, which is
+  `Workspaced<door, slots>`; demanding _less_ is safe, because it is fed a superset. So a body reading a field the door
+  never carries is a build error at the `workspace()` call instead of an `undefined` mid-run. The guard counts the raw
+  door as provided beside `Workspaced<door, slots>`: for the door `z.object({})` the two differ, and a body that writes
+  `z.infer<typeof door>`, alone or with the handles, stays legal. Comparing against `Workspaced` alone was the
+  alternative; it was rejected because it refused those bodies, which compiled before `Workspaced` removed the empty
+  index signature. One field sits outside that check, named as `HostInjectedInput`: the host adds `instanceId` to the
+  input of the machine a run _starts_ with, so a root-placed wrapper hands its body the door, the handles, _and_ that —
+  while a nested one does not, and no type can see which. It is not door material either (no caller sends it, `start`
+  overwrites it after the parse, nothing serves it), so widening the door would be the wrong fix. The guard takes the
+  permissive answer: it counts those keys as _provided_, so a body may declare the field honestly. Counting them as
+  provided rather than subtracting them from what the body demands is deliberate — subtraction would drop the keys from
+  the comparison and with them two cases the check owns: a body that mistypes `instanceId`, and a body whose input is a
+  union, which subtraction compares on its members' shared keys alone. The typed wrapper also checks the seam above it —
+  a parent invoking a nested `workspace()` has its input mapper checked against that wrapper's door, and gets the body's
+  output typed back. With no schema declared the door is permissive, so there is nothing to infer and the mapper's
+  argument is `unknown` — an honest "jr2 does not know", not `any`; a wrapper fed by something other than a caller (a
+  pool worker) states what it is fed by annotating the parameter, as `PoolSpec.cap`/`itemInput` do. `spec` takes the
+  same permissive answer as the guard: its `input` is the door plus `HostInjectedInput`, so a `spec` gives each run a
+  branch from `instanceId` with no cast, and a nested wrapper whose `spec` reads it needs a parent that gives it.
+  `Partial<HostInjectedInput>` was the alternative; it was rejected because each root `spec` would then write a fallback
+  for a value that is always there. The input of the wrapper stays the door alone, so no parent must send `instanceId`.
+  For the door `z.object({})` that input is `{}`, the door without its `Record<string, never>`, so a parent can give
+  `instanceId` to a nested `spec` that reads it; with the raw `z.infer` it could not, and the nested Workspace then
+  pushed each run to `fix/undefined`. `z.infer<…> & Partial<HostInjectedInput>` was the alternative; it was rejected
+  because the index signature makes `instanceId` `never` there too. A per-run Repo Slot's mapper keeps the door alone,
+  because a url does not come from a run's id.
+- **The schema is structure, so it is open.** Workflow-detail JSON (`GET /workflows/:name`, the address ADR-0032's
+  negotiation kept) serves it as JSON Schema — same band as the Machine doc, and what drives the Console's start form
+  before any token is entered. The _submit_ stays `authenticated`; schema open, trigger guarded.
+- **A declared schema is enforced at the door.** `POST /workflows/:name/runs` validates the body and 400s naming the
+  accepted shape — parity with what Gates already do for deliveries. No schema declared → accept anything (today's
+  behavior), and the Console falls back from a generated form to a raw-JSON textarea.
+- **The door takes an idempotency key, out of band.** A start may carry one in a header, never in the body (a body field
+  would be one every door had to reserve); a repeat with the same key answers with the run the first one made. A
+  `dispatch` Effect sends its ledger row's id ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), so a
+  start whose answer was lost is sent once where it may have arrived (ADR-0067) and makes one run. `jr2 run` and the
+  Console send none.
+
+## Considered options
+
+- **`export const input` beside `export const machine`.** Rejected: it re-opens what ADR-0015 closed — a workflow's
+  self-description split across module exports, when the machine object already carries every other piece of the
+  workflow's self-description.
+- **`workspace` propagates its body's schema onto the wrapper** (the shape this ADR first took, before `pool` forced the
+  question and `workspace` turned out to be the same species). Rejected: the wrapper's pass-through is not the body's
+  input — the body also gets the injected `workspace` field — so the propagated schema is right only for a body that
+  under-declares its own contract. Two ways to declare one door also cost more than the line of ceremony they save: an
+  author reading a wrapped workflow could not tell, without opening the factory, which declaration the runtime serves.
+- **Derive from xstate's `types.input`.** Impossible: TypeScript types are erased; there is nothing at runtime to serve
+  or validate with.
+- **Constrain the body by pinning its `TInput` slot** (`body: StateMachine<…, Workspaced<door, slots>, …>`). Rejected as
+  unsound, not as style: `StateMachine`'s members include methods, method parameters are bivariant, and a body demanding
+  _more_ than the door provides therefore compiles — the one case the constraint exists to catch. The shipped
+  formulation intersects the body with a conditional guard whose failure branch is an object type keyed by the sentence
+  to read, so the diagnostic names the fix rather than printing a structural diff.
+- **Require a schema on every workflow.** Rejected: it taxes the zero-ceremony hello-world for a guarantee only
+  input-taking workflows need. Absence is permissive, and permissive is what the wire already was.
+
+## Consequences
+
+- **Both entry points sharpen for free**: the Console generates its form from the same JSON Schema `jr2 run` can later
+  use to refuse bad input client-side before the POST.
+- **The open band grows a schema and nothing else** — the same class of thing as the Machine doc it sits beside;
+  ADR-0014's projection is untouched.
+- **Validation parity means error parity**: a bad run start and a bad gate delivery now fail the same way, a 400 naming
+  what is accepted.

package/docs/reference/decisions/0034-the-console-renders-with-preact-and-the-server-erases-the-types.md

@@ -0,0 +1,57 @@
+# The Console renders with Preact, and the server erases the types
+
+The Console ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)) outgrew its framework-free form: `main.js`
+reached ~1,500 lines, much of it hand-rolled DOM reconciliation (`memo()`, `paint()`, manual list diffing) — work a view
+library exists to own. Three standing constraints shaped the replacement: the repo is zero-build (Node 24 strips types;
+nothing compiles), the Console serves only its own assets (ADR-0032), and `@jr2/orchestrator` is a library that serves
+its files from disk wherever the process starts. A fourth arrived with this decision: Console source is TypeScript like
+everything else.
+
+## Decision
+
+- **Preact, called through `h()` — no JSX.** JSX is codegen, and codegen needs a compiler; `h()` calls are plain
+  TypeScript, typechecked against Preact's own types, so the views sit inside `tsc --noEmit` with no toolchain. Preact
+  is React's API and mental model in ~4KB, shipped as browser-native ESM the orchestrator can serve verbatim.
+- **Console source is `.ts`; the server erases the types.** The browser requests `/assets/*.ts` and receives the file
+  with its types replaced by whitespace (`ts-blank-space`), erased once and cached in memory. Erasure is not
+  compilation: positions are preserved, so browser stack traces point at the real source line with no sourcemaps, and
+  import specifiers keep their `.ts` extensions — the orchestrator does for the browser exactly what Node does for
+  itself. The failure class is gated where it belongs: what `ts-blank-space` cannot erase, `tsc --noEmit` already
+  rejected in CI.
+- **Vendor rides the dep edge.** Preact's ESM files are served at `/assets/vendor/*`, resolved through this package's
+  own dependency edge and mapped to bare specifiers by an import map in `page.html` — the elkjs precedent, extended. No
+  CDN, no third-party origin; ADR-0032's asset clause does not move.
+- **The store stays a pure reducer; the vdom replaces the painter.** `store.js` + `store.d.ts` collapse into one
+  `store.ts` read by both consumers (tests through Node's stripping, the browser through the server's). `dispatch` stays
+  the one door: fold the frame, render the app from the top, and let vdom diffing do what `memo()`/`paint()` did by
+  hand. Signals were rejected: finer-grained updates solve a performance problem SSE-paced frames do not have, at the
+  cost of the reducer's tests and the store-first language.
+- **The machine canvas stays an imperative island.** elk's layout is async and pan/zoom is a 60Hz transform; neither
+  wants a vdom. A component owns the `<svg>` by ref and the existing rendering code moves house without being rebuilt.
+
+## Considered options
+
+- **SolidJS** (the requested starting point). Its fine-grained reactivity lives in its compiler, and the compiler is
+  babel-only (`babel-plugin-jsx-dom-expressions`; `esbuild-plugin-solid` wraps babel rather than replacing it). Every
+  route to it costs an invariant: babel at runtime widens the production dep chain of the token-guarded package, vite
+  middleware puts a dev server in production as the asset pipeline, and a pack-time build hands the repo its only
+  toolchain plus the stale-artifact problem class. Solid without its compiler has no reason to exist.
+- **React.** Verified against the `react@19.2.8` / `react-dom@19.2.8` tarballs: still CJS
+  (`module.exports = require(...)` behind a `process.env.NODE_ENV` branch) — a browser evaluates neither. Self-serving
+  it means a resolve-and-bundle step at boot. Preact offers the same API for a page that ADR-0032 already bars from
+  React's real advantage, the third-party component ecosystem.
+- **Runtime vite.** Works mechanically (middleware mode); rejected because vite's dev server is explicitly not for
+  production serving, and it relocates compile errors to the worst place — a 500 from a deployed orchestrator instead of
+  a red CI step.
+- **`htm` tagged templates.** A no-build JSX-alike, but props inside template strings sit outside the type checker — an
+  untyped gap exactly where the Console's bugs live (rail rows, gate cards, schema forms). `h()` keeps the views typed.
+
+## Consequences
+
+- The erasable-syntax constraint (no enums, no constructor parameter properties) now applies to Console code, as it
+  already does to everything Node runs in this repo.
+- `ts-blank-space` and `preact` become production dependencies of `@jr2/orchestrator`; the package's `typecheck` must
+  cover `console/` with DOM types.
+- TSX later is additive — an `esbuild.transform()` at the same serve point — not a rework.
+- The refactor is behavior-preserving: `console-store.test.ts` retargets to `store.ts`, the `@console` browser tier and
+  the default e2e profile stay the acceptance bar, and no route moves except how `/assets/*` bytes are produced.

package/docs/reference/decisions/0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md

@@ -0,0 +1,92 @@
+# A runaway turn is ended by the Harness, rerolled once, then a fault
+
+[ADR-0016](0016-agent-turn-mechanics-are-internal.md) absorbed turn mechanics behind one terminal
+`agent.fault { reason }` and named two fault classes: **infra** (the turn broke — provider retries in the Harness, then
+fault) and **no-signal** (the turn ended without a menu pick — budgeted nudge in `agentRun`, then fault). Both assume
+the turn ends. Production found the third case: a turn that never does. Two live `task-with-review` runs degenerated — a
+reviewer handed an empty diff collapsed into ~100 byte-identical `grep` calls; a coder rewrote the same README
+indefinitely after committing real work. Nothing bounded either: `agentRun` awaits settlement, `nudgeBudget` covers only
+turns that end, and neither jr2's Harness nor the retired flue runtime ever capped steps.
+
+The investigation ruled the refactor out as the cause. Replays of both failure shapes against the live endpoint —
+including the exact empty-diff reviewer state — terminated 13/13 with max 2 consecutive identical calls, in both the
+current bare-instructions prompt and the flue-shaped one. The degeneration is stochastic model tail behavior,
+concentrated where a task gives the model nothing real to do. That shapes the design: the guard is liveness insurance
+against a tail event, not a correctness mechanism, and the recovery that works is a fresh roll of the dice.
+
+**Runaway** names what jr2 observed — the turn ran past the point where jr2 stops believing it will conclude — on the
+same principle as "no-signal": fault classes are named for the observation, not the model's inner pathology.
+"Degeneration" is the behavior the guard usually catches; the budget trigger also ends honest dithering that never
+collapses into repetition.
+
+## Decision
+
+- **Detection lives in the Harness turn loop** (`turn.ts`) — the one seat that watches steps as they happen; the
+  Orchestrator only sees the settlement, and a runaway never settles. Two triggers, both jr2-owned defaults with **no
+  author surface** (ADR-0016: budgets are defaulted knobs): a **step budget** (initial 256; healthy turns peaked at 53
+  on a trivial task, and an honest live bug-hunt burned 161 steps before exhausting its context) as the unconditional
+  backstop, and **K consecutive byte-identical tool calls** (initial K=4; healthy max observed 2, the production loop
+  ~100) as the early exit. If a surface is ever demanded, note it would be a Dial question (ADR-0018) — how hard to run
+  this one Turn — but no workflow has needed one. Both count tool calls alone. A step is a tool call that starts while
+  the Turn is live: the Harness counts it at the engine's `tool_start` event
+  ([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)), before the engine checks the tool or
+  the arguments. So these calls are steps: a call that runs; a call of an unknown tool, or with arguments that do not
+  validate, which gets the engine's own error; a pick that the Harness blocks as the second pick of its model answer
+  ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)); each call of a model answer that hit the
+  output limit, which the engine answers with an error and does not run; and the tripping call itself, which is counted
+  and does not run. A tripping call of a tool the run has, with valid arguments, reads `Operation aborted`. A tripping
+  call of an unknown tool, or with invalid arguments, reads the engine's own error for it. A model that repeats any of
+  them is a Runaway. Only one kind of call is not a step: a call after a pick that ended the Turn, which the Harness
+  blocks. The Turn that it would count for is over, so a trip cannot make an ended Turn a Runaway. A Turn part the
+  Harness restates at a step boundary
+  ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)) is not a step and
+  neither breaks nor extends an identical-call streak. An outstanding pick
+  ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)) is one call however long the workflow runs
+  it — the guard has no clock, so a held Turn is never a Runaway for waiting — and its answer **resets the
+  identical-call streak**: the world moved, so the same pick again is a new question. Four `run_tests` in a row, each
+  answered by a flaky suite, is a model reading answers, not a loop. A pick whose child replies inside the pick's own
+  send resets it the same way. A guard straight back does not: it is answered, but nothing ran and the state is where it
+  was, so the same pick four times is a Runaway.
+- **Tripping settles the Submission `failed` with `SettlementError.type: "runaway"`** and a legible message ("repeated
+  an identical tool call 4 times", "exceeded 256 steps"). A Runaway is a kind of failure, so it stays `failed`, and the
+  typed error is what lets `agentRun` switch on the class without parsing prose. A Turn that its own pick ended is a
+  different end, not a failure. So it has an outcome of its own, `ended`. `aborted` is a Turn that something else
+  stopped ([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)). A Runaway is neither: the Harness
+  ended a Turn that nothing had ended.
+- **`agentRun` retries once, as a fresh conversation, with the identical prompt.** The degenerate context is poisoned —
+  a model that just emitted a hundred identical calls conditions on them, so a nudge into the same conversation rerolls
+  loaded dice; the fresh session is ADR-0016's lossy handoff applied as recovery. The prompt carries no annotation:
+  mechanism must not bleed into the one thing the workflow authored, and the failure being stochastic means the fix is
+  the reroll, not different instructions. Budget 1 (a defaulted knob): a runaway retry costs an entire turn, and two
+  independent rolls both running away is evidence the task itself is pathological — that belongs with the workflow's
+  fault routing, not a third attempt.
+- **A `continue: true` invocation gets no retry — straight to the fault.** The one recovery jr2 knows is the identical
+  prompt on a fresh conversation, and a continued Turn's prompt is meaningless fresh. The fault retires that
+  conversation: jr2 bumps its epoch, so the next `continue` on the Agent lands on a virgin one (ADR-0057), and the fault
+  routing decides what to brief it with.
+- **Exhaustion emits the same single terminal `agent.fault { reason }`.** The workflow surface does not change; routing
+  (park at a Gate, re-invoke at a higher Dial) stays workflow policy, and `task-with-review`'s existing `agent.fault`
+  arm already handles it. Retry attempts surface as run-feed telemetry like nudge attempts.
+- **The claims are proven in the ADR-0027 conformance suite** — a scripted provider that loops deterministically is the
+  only tier that can produce a runaway on demand; it runs in the default `pnpm -r test` gate.
+
+## Considered options
+
+- **Windowed duplicate-fraction trigger** (catches A-B-A-B alternation early). Rejected for now: no observed instance,
+  the step budget backstops it, and it is the only trigger with a plausible false positive — read → edit → read of the
+  same path is an identical signature twice, legitimately.
+- **Retry into the same conversation** (nudge-style). Rejected: the poisoned-context argument above; a nudge explains
+  itself to a conversation that must continue, a runaway retry exists because the conversation must not.
+- **Workflow-side detection.** Rejected: workflows speak vocabulary, not step counts (ADR-0015/0016), and the
+  Orchestrator cannot see inside an unsettled turn without growing a new observation surface for mechanism.
+- **A per-Agent or per-Turn knob now.** Rejected: greenfield, no evidence any turn needs a bound other than the default;
+  adding surface first invites tuning before data exists.
+
+## Consequences
+
+- ADR-0016's taxonomy is three classes: infra, no-signal, runaway. Its "either budget exhausting emits the one terminal
+  fault" sentence now reads across three budgets.
+- A runaway that survives the reroll parks where `agent.fault` routes — for `task-with-review`, the `humanReview` Gate
+  with the runaway reason in `meta`, Sandbox intact for inspection.
+- The bound makes non-termination cost at most `(1 + retry) × step budget` instead of a context window; it does nothing
+  for output quality — a no-op task still yields invented churn, which is task authoring, not mechanics.