@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/reference/decisions/0014-observation-is-open-run-state-is-not.md

@@ -0,0 +1,95 @@
+# Observation is open; run state and control need the Instance token
+
+[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md) minted two tokens and scoped them
+for **delivery** — a Sandbox token may deliver to its own agent registrations, an Instance token may deliver to gates.
+It said nothing about who may **read** a run or **cancel** one, and the code took the obvious shortcut: `authenticated`,
+meaning any token we minted. That is a hole. It also left the visualizer with no way in at all, which is the same
+question from the other side.
+
+Building `jr2 visualize` (the Machine renderer and its live run highlighting) forced both halves at once: the page is a
+**browser**, and a browser holds no token. So this ADR splits the HTTP surface into **three bands**, and adds an
+**observation projection** — the page gets a view instead of a credential.
+
+## Decision
+
+**Three bands, and the middleware is what says which.**
+
+```
+open           /workflows, /workflows/:name/machine, /viz/*        structure
+               /workflows/:name/runs, …/runs/:runId/events         OBSERVATION (new)
+authenticated  /agents/:iid/*                                      the Agent's surface  [Sandbox token]
+instanceOnly   /runs, /runs/:id, /runs/:id/events (GET + POST)     run state + control  [Instance token]
+               POST /workflows/:name/runs                          starting a run (ADR-0058)
+               /runs/:id/gates/:gate/events                        gates (ADR-0011/0013)
+```
+
+- **Run state and run control are the Instance token's alone.** `authenticated` accepts _any_ token we minted, so a
+  Sandbox token — the one credential that sits in a pod an Agent shares a network namespace with — could read **every**
+  run's context (other features' branches, ticket bodies, review verdicts, Harness endpoints) and **CANCEL any run**.
+  Neither is on the Agent's surface, no more than a gate is: ADR-0013 scopes that token to delivering into registrations
+  recorded against its _own_ Sandbox. This closes the same class of hole ADR-0013 closed for gates, on the routes it did
+  not name. The band is named for the credential it requires, not for a role — "operator" in this repo is the Kubernetes
+  operator (ADR-0001).
+
+- **The observer gets a PROJECTION, not a credential.** `RunObservation` is
+  `{ runId, workflow, status, value, children }` — identity, and where in the Machine the run is. What is absent is the
+  point: `context` is the workflow's working data, and `instanceId`/`fault` name live infrastructure and leak error
+  text. A state `value` (and the `children` tree of state values below it) is a tree of state **keys** — it is
+  structure, and structure is already open at `/workflows/:name/machine`. So an observer learns nothing here it could
+  not read from the Machine doc, except **which states are lit**. `observe()` is the one place that line is drawn, and
+  `RunChild` has no context field at any depth — the redaction surface cannot grow by forgetting.
+
+- **Observation is scoped to one workflow**, because that is what an observer already knows (it is in the page's path).
+  There is no listing of everything an Orchestrator happens to be running, and the feed serves **live runs only** —
+  reading a settled run's terminal status through the store stays on `/runs/:id`, which is guarded.
+
+- **An `emit`'s payload does not cross.** The observation feed carries an emit's `type` alone: an author's emit payload
+  is author data, the same class of thing as context.
+
+## Considered options
+
+- **Give the page a token.** It would have to be the **Instance** token — gates, cancel, every run's context — handed to
+  whatever can load a URL. Putting it in `jr2.config.ts` (checked in) is worse still, and the token is minted per boot,
+  so the page would not have it anyway. Rejected: the visualizer needs to _see_ a run, and seeing is not a subset of the
+  credential that steers it. That mismatch is the whole reason a projection exists.
+- **Keep `/runs*` on `authenticated` and filter in the handler.** Rejected: the guard would then depend on every future
+  handler remembering to redact. The band is a middleware precisely so the default is refusal.
+- **A fourth "observer" token.** Rejected: it buys nothing today (the observation surface carries no secret) and costs a
+  minting, distribution, and revocation story. If observation ever needs to be _private_ — a deployed jr2 Application on
+  a shared network — that is the ADR to write, and it is the same open question ADR-0013 left about authn for non-kube
+  callers.
+
+## Consequences
+
+- **`auth.test.ts` changed its mind.** Its prose already said "Observation and control are the operator's, not the
+  Agent's" directly above assertions that a Sandbox token gets **200** on a run read and **200** on CANCEL. Those are
+  now **403**. The test pinned the hole.
+- **The API is a cluster Service** (ADR-0019), so "open" means open to whoever can reach it — in-cluster peers, a
+  port-forward, or an ingress — deliberately, since what is open is structure plus lit states. Anything that would
+  embarrass a user if seen belongs behind `instanceOnly`, and that is where it is.
+- **The CLI is unaffected.** It holds the Instance token from the in-cluster Secret (ADR-0019) and reads the guarded
+  routes, as before.
+- **Open, inherited from ADR-0013:** what a deployed jr2 Application uses for human callers. Whatever it is, the band
+  split survives it — only the credential in the `instanceOnly` band changes.
+
+- **One scoped exception, and it does not live on this surface at all (ADR-0023).** The Harness prints each Agent's
+  conversation — prompts, assistant text, thinking, tool calls, and the answer jr2 gave each Menu pick — to container
+  stdout, which leaves the pod for the cluster's log plane and lands in front of a reader this document never gets to
+  check. That is a real exception to the rule above, and it is stated rather than reasoned away. Two things bound it. It
+  is **not a new band**: the HTTP surface is untouched, nothing here is served, and a reader gets it from
+  `kubectl logs`, holding cluster log access instead of a jr2 credential. And **a Working tool's results are excluded**
+  — the file contents, command output, API responses it returns never print, so the mechanical leak (an Agent `cat`s a
+  config while debugging and its secrets ride a log shipper into 30-day retention) is off the table, leaving what an
+  Agent reasons aloud and what jr2 answered its picks. What an Effector returns in that answer is scrubbed before it
+  signs it as ADR-0068 claims: no secret the Effector holds, in the forms it sent or in common encodings. The scrub does
+  not try to catch a transformed secret (a hash, a truncation, an encoding it does not list), a partial echo, or a side
+  channel, and a credentialed command's child reads the secret its command names, so it can print that secret in such a
+  form; then it prints there as the model read it. The answer also carries an Effect's output as the model read it: a
+  `command` Effect's output prints there up to the bound, and a Held value an upstream echoed into that output prints
+  with it (ADR-0023, ADR-0059). What remains, deliberately, is that on a shared cluster the population who can read an
+  Agent's reasoning, and what its picks answered, is whoever can read pod logs. If that becomes unacceptable, the fix is
+  the read-through ADR-0023 declined to build — `instanceOnly`, on this surface, where the band already works.
+
+Evidence: `packages/orchestrator/src/http.ts` (the three middlewares), `run-host.ts` (`observe` / `RunObservation` /
+`RunChild`), `test/auth.test.ts` (the boundary), `test/http-viz.test.ts` (a planted secret never reaches the feed, at
+any depth of the child tree).

package/docs/reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md

@@ -0,0 +1,265 @@
+# Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine
+
+The jr-parity exercise produced a working model but a bad consumer API: mechanism plumbing (manifests, tool lists,
+event-union bookkeeping) dominated the workflow. The redesign grill (2026-07-13/14, full record in
+[docs/design/workflow-api/](https://github.com/snapwich/jr2/blob/71ebe36/docs/design/workflow-api/proposal.md)) settled
+the split: **the consumer writes pure workflow — states, transitions, prompts, policy — and jr2 absorbs everything else
+through convention.** This ADR covers the Authoring surface; [ADR-0016](0016-agent-turn-mechanics-are-internal.md)
+covers the agent turn; [ADR-0017](0017-pool-over-a-source-port.md) covers the run loop.
+
+## The root of `@jr2/orchestrator` is the Authoring surface
+
+A workflow authors against one package: `jr2Setup`, `defineEvent`, `agent`, `workspace`, the Effects, `customize` and
+`defineConfig` all import from `@jr2/orchestrator`. Its root exports the Authoring surface (GLOSSARY.md) and nothing
+else.
+
+- **The rule.** A name is on the surface when an author writes it in a workflow module or in `jr2.config.ts`. No other
+  name is. A name that an author only gets by inference stays off the surface: the event union that `jr2Setup` derives,
+  a Gate's input, an Agent's Frame. The `gate` actor is off the surface too. `jr2Setup` registers it, and a state
+  invokes it as `src: "gate"`, so no author writes the value. A type is on the surface when an author must write its
+  name, for example `Workspaced`, `HostInjectedInput`, `AgentDefinition`, and the types of the parts that `customize()`
+  takes. `JR2Config` is on the surface too: the `jr2.config.ts` Reference documents its fields, and an author names it
+  to type a config that is built outside `defineConfig()`.
+- **Named exports only.** `src/index.ts` names each export (`export { a } from …`, `export type { T } from …`), in
+  groups by topic, and has no `export *`. Thus an Assistant that reads the file sees the full surface, and each change
+  to the surface is a line in a diff.
+- **A test pins it.** `test/authoring-surface.test.ts` makes sure that `index.ts` has no `export *`, that the root's
+  runtime values are equal to a sorted list in the test, and that the type names in the `export` lists of `index.ts` are
+  equal to a second sorted list. A name that is added or removed fails the test until the list changes. The same test
+  makes sure that `@jr2/machines` and each Instance-shaped folder import the root only.
+- **The kit's own packages import `@jr2/orchestrator/internal`.** It holds the surface and all that the kit shares: the
+  run host, the HTTP API, the Harness wire, the Custodian, the Effector wire, the cluster names. It is not for authors,
+  and it has no stability promise: any name in it can change in any release. A Machine that the kit ships
+  (`@jr2/machines`) and each Instance-shaped folder in the repo import the root only. The `exports` map has `.`,
+  `./internal` and `./tsconfig.instance.json`, and nothing else. Thus an Instance that imports a deep path, such as
+  `@jr2/orchestrator/src/run-host.ts`, does not resolve it, in `tsc` or in Node.
+
+## `jr2Setup`: an xstate `setup()` analog, not a DSL
+
+`jr2Setup({ types, events: [defs], actors, actions, guards })` is statically imported and returns xstate's **public
+`SetupReturn`** — `.createMachine()` yields a plain `StateMachine`, Stately-inspectable and `.provide()`-testable, with
+no jr2 runtime needed to construct it (proven by compiled experiment against xstate 5.32.2; consumer surface has zero
+casts). It:
+
+- injects the mechanism events (`agent.fault`, `workspace.lost`) into the event union and derives the workflow event
+  types from the zod defs — hand-written `EventFrom` unions retire;
+- pre-registers the jr2 actors (`agentRun`, `gate`) with typed inputs;
+- takes the defs **as values**, which lets it validate at `createMachine` time that every event key appearing anywhere
+  in the machine maps to a def — closing xstate's nested-`on` typo hole (unknown keys in nested states typecheck
+  silently upstream) with a load-time failure;
+- attaches the vocabulary to the machine (`vocabularyOf(machine)`, a WeakMap keyed on `machine.config` — the object
+  xstate's `.provide()` passes through, so a clone keeps it, and the returned machine stays bit-identical). **The
+  `export const events` manifest retires**, and the workflow module contract shrinks to `export const machine` (revising
+  [ADR-0011](0011-workflow-defined-events.md)'s named-exports contract): the defs ride the Machine, and the actors that
+  need them resolve names off the Machine that INVOKED them (ADR-0011, ADR-0049) — the host copies nothing at
+  registration, and the only other reader is the Machine doc the Console renders. ADR-0011's anti-global-registry
+  argument is preserved — attribution flows through the machine, per-Machine by construction.
+
+`events` is optional, and so is the whole argument: a Machine with no Vocabulary leaves `events` out, or calls
+`jr2Setup()`, and its event type is the Mechanism events alone. Such a Machine still uses `jr2Setup` when it declares a
+door ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)), because xstate's `setup()` does not read the
+`input` of `createMachine`. An empty Vocabulary is the default, not `readonly EventDef[]`, so the type of `event` does
+not widen to every event name. A required `events` was considered and rejected: `events: []` tells the reader nothing,
+and the compiler gave a missing `events` as a large structural diff of `SetupReturn`, not as the name of the missing
+key.
+
+## Agent menus and gate accepts derive from the machine
+
+A state that invokes an Agent slot derives the workflow events its Turn may pick: its own transitions, its ancestors'
+(bubbled, per statechart semantics), and the transitions written on the states below it — its **modes**. xstate hands an
+event to the deepest active state that handles it, and a false guard there falls through to the parent, so a pick
+written on a child is one the Turn can take while that child is active. The descent stops at a child that invokes
+another Agent slot (a nested Turn: its picks are its own) or a `gate` (its transitions are the Gate's accepted set), and
+leaves out everything below that child; a child that runs anything else stays in. A state that invokes `gate` gets its
+accepted set from its own and its ancestors' transitions and those written on its plain children, by the same descent:
+position gives a Gate the writings below it that no other party answers for, as it gives an Agent its modes (the Pool's
+wake Gate, on its root, takes the writing on `parked`). The consumer names neither; MCP appears nowhere in workflow
+code. Mechanics: the **vocabulary** derivation is static, in `jr2Setup.createMachine` — a config walk wraps each
+invoke's `input` to append the derived names, so names still ride serializable input and the ADR-0007 restore path and
+invoke-time validation are unchanged. The same walk unions the derived sets of every state that invokes an Agent of one
+name into that Agent's **Menu** — its tools, fixed for a conversation so the provider's prompt cache survives a change
+of state. The walk reads transition _keys_ and so cannot see guards, which is why what a Turn may pick is not static on
+top of it: `agentSurface` asks the invoking machine's guards, and the Turn is told its **Allowed picks** — the derived
+set, less every event that the live snapshot, in its active mode, would not take
+([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md) owns the rationale).
+Authoring is untouched by the split: a workflow names no tools in either leg. The same walk feeds `jr2 visualize` ("this
+state's agent can call X, Y"). Dotted names (`agent.*`, `workspace.lost`, `xstate.*`, `after`) are mechanically
+excluded.
+
+**A transition belongs to the party that its state, or the nearest state above it, invokes.** The party is the Agent
+slot or the `gate` that state invokes, or both when one state invokes both; root transitions, with no such state above,
+belong to both. That is who may send an event whose def leaves `audience` unset
+(`defineEvent({ audience?: "agent" | "external" | "any" })`, no default):
+
+| Transition written on                                                                             | Unset audience: who may send                                         |
+| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| A state that invokes an Agent, or a mode below it                                                 | That Agent                                                           |
+| A state that invokes a Gate                                                                       | The Gate's caller                                                    |
+| A state that invokes both                                                                         | Both                                                                 |
+| A state that invokes anything else (a child Machine, a wrapper body, any other actor), or nothing | The party of the nearest invoking state above; none above means both |
+
+So child or sibling says only "same Turn or not"
+([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)): an in-Turn Gate's caller sends the Gate's
+events and not the Agent's picks, and a nested Agent does not get the outer Agent's picks. **Write an audience only to
+give a pick to the other party, or to hold a root pick back.** An explicit `audience` overrides by kind over the whole
+reach: `agent` reaches every Agent whose reach holds a writing of the event, `external` every Gate's, `any` both — so
+`submit: "any"` lets an in-Turn Gate's caller send the Agent's pick, and `report_blocked: "agent"` keeps a root pick
+from the Gates. A def means one thing: its description must be true at every writing its party can reach, and two
+meanings are two defs. The reach itself is unchanged by the rule — own and ancestors, plus the states below with no
+party-invoking state between (an Agent's modes, a Gate's plain children) — and the rule only filters inside it, so no
+case widens who can send a pick; a test scans every shipped Machine and fixture for it, both the derived names and the
+writings each party may take at run time. The walk computes every party's seat — per state, who may send what — and the
+Machine's doc carries it; `jr2 up` prints it for every registered Machine and every Machine it composes, and the Console
+shows the same lines, folded beside the workflow's diagram (structure, so tokenless too). An explicit `accepts:` on a
+Gate's input remains an escape hatch.
+
+**`sentBy(id)`: a writing that declines other senders.** Every event a party delivers carries its sender (ADR-0011):
+`sender: { party, id }`, the Agent's slot or the Gate's invoke id. `jr2Setup` registers one guard, `jr2.sentBy`, and the
+author writes it on a writing as `guard: sentBy("coder")` — a named guard with params, alone or inside `and([...])`. It
+is true for an event whose `sender.id` is `id` and for an event with no sender (the Machine's own: `raise`, `sendTo`
+itself, a child's `sendParent`), and false otherwise, so xstate's own selection moves outward to the next writing of the
+name. It can only make a writing decline; it never gives a writing to a party — position does. `id` is an Agent slot or
+a Gate's invoke id of this Machine, and a `sentBy` that names neither is refused at load, like an unknown event key.
+Under `or()` or `not()`, or in an author's own guard that reads `event.sender`, it works at run time but the walk cannot
+read it. A `.provide()` test sends as a party by writing the field: `{ type, sender: { party, id } }`.
+
+**A delivery never runs another party's writing.** Audience says who may send a name; xstate selects which writing runs,
+deepest active first, whoever sent it. So at delivery the real event — its payload and its sender — goes through
+xstate's own selection (`getTransitionData`) before the Machine sees it, and if a writing selected is one the sender may
+not take by the position rule above, the event is refused: an Agent's pick is answered `moved: false` and not delivered
+(ADR-0029), a Gate's caller gets 409 with what the Gate takes now (ADR-0013). The lists ask the same question the same
+way, payload-blind: an Agent's Allowed picks and a Gate's `acceptsNow` are the names whose selection, for an event that
+carries the sender and with every guard that reads the payload counted as passing, moves something and holds only
+writings the sender may take. A guard that reads the payload is unknown there and passes the party question; it is never
+the fail-open of a party check skipped, because delivery asks again with the real payload. The payload-blind selection
+is a copy of xstate 5.32.2's (`transitionNode`, `StateNode.next`, `evaluateGuard`, the members of `and`/`or`/`not`),
+pinned against `getTransitionData` in the default test run — the canary for an xstate bump. Without a `sentBy`, nothing
+misroutes: the shallower party is refused while the deeper writing is active, and the walk warns (below). When the
+deeper party runs BELOW an Agent's state — a Gate, a nested Agent — the Agent's state is not at Rest, so the Agent's
+picks are refused before the selection is asked
+([ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)); the selection decides the Gate's caller's
+sends there, and every case with the Agent's state at Rest.
+
+**Load checks on modes and audience.** `createMachine` refuses a registered event that no state handles: it is in no
+derived set, so it is on no Menu and no Gate. It refuses a parallel region below a state that invokes an Agent — the
+Agent's state itself being parallel included, since its regions are below it: the shape is reserved for picks the Agent
+does not wait for, which jr2 does not build, and background work goes above the Agent's state. It warns — the Machine
+stays legal; the doc carries the warning, `jr2 up` prints it and the Console shows it with the seats — about a mode that
+nothing enters (not initial, and no state the Machine can enter has a transition into it or a state inside it — so
+neither the mode's own `initial` nor its transition into itself counts: its picks are on the Menu and never allowed; a
+transition into a history state enters that history state's default target, shallow or deep, or its parent's initial
+state when it names none, and a default target the walk cannot resolve is its own warning); about a Gate above an
+Agent's state that takes an unset-audience writing the Agent reaches (the one narrowing of the audience rule an author
+may not expect); about two parties' writings of one name that can be active together; about one party's writings of one
+name that mean two things; and about two shapes below an Agent's state that keep it from Rest, so every pick of the
+Agent waits (ADR-0024): a Gate whose answer has no target (the Gate stays open after it), and a long-lived invoke — one
+that runs until its state exits, not a promise, an Effect, a Gate, an Agent or a child Machine. A child with no `onDone`
+that strands the Agent in it — a one-way mode — is legal and silent on purpose, an Effect child included.
+
+**Load check on the output of a run.** xstate v5 gives a run one output: the `output` at the root of the Machine. The
+`output` of a final state directly below the root goes to that root `output` as `event.output`, and to nothing else.
+Thus a Machine with an `output` on such a final state and no root `output` ends with no output, and `types.output` does
+not stop it. It was the most frequent error in the Machines that Assistants wrote, and an Assistant then told its user a
+result that the run did not have. Thus the load walk refuses that shape: `createMachine` and the parts walk at `jr2 up`
+and at the boot, so a Machine built with xstate's own `setup()`, and a child Machine, are refused too. The refusal names
+each such final state and the two fixes: an `output` at the root from `context`, or
+`output: ({ event }) => event.output` at the root, which passes on the output of the final state. A final state inside a
+compound state is legal: its `output` is the `event.output` of the `onDone` of that state. A Machine with no `output`
+anywhere is legal: its result is in its `context`, and it tells nothing false about an output. Considered and rejected:
+a warning (a run with no output is never what the author meant, and a warning does not stop the false result); and a
+root `output` that jr2 adds when there is none (it would make jr2 Machines behave differently from xstate Machines, and
+a Machine that a different xstate host runs would lose its output again).
+
+**Load checks on Effects** (ADR-0067). `createMachine` refuses a state below an Agent's state that invokes something and
+that nothing enters: what it invokes never runs (a mode nothing enters is only the warning above). Both checks read one
+reachability walk, history defaults included; where a history default the walk cannot resolve may enter such a state,
+the walk does not know, and it warns instead of refusing. Both checks look below a state that invokes an Effect or a
+child Machine, and stop at one that invokes another Agent or a Gate. Where a pick enters a state that invokes an Effect,
+every param of the pick must be read by something — the check is per state, not per invoke — by the input of any invoke
+of that state, an Effect's or not, so a second invoke beside the state's work counts (`fromPick` reads each param that
+is a key of the Effect's input, a command's argv slots, and each one its `fill` reads; on an invoke that is no Effect it
+reads every param, and on a command whose argv is Open it reads every param too, since the argv's slots are the
+composer's — `customize()` runs this check again when it binds the argv and refuses there a param the bound argv does
+not read, and gives the bound Machine the warnings the walk gives for that argv
+([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)); a plain mapper is probed with
+a recording event), by the entering transition's guard (inline, named, or inside `and`/`or`/`not`), or by an `assign` on
+the entering transition or on the entry of a state it enters — else the Agent supplies it and nothing uses it: refused.
+A pick enters what xstate enters: its target, the target's ancestors below the transition's domain, and their initial
+descendants — and what an eventless `always` on a state it entered enters next, in the same macrostep with the same
+event, whose guard and actions count as the entering transition's. So a pick that targets a compound state enters the
+child that invokes, a pick that targets a child enters the ancestor that invokes, a pick that targets a state whose
+`always` moves on enters where it moves, and a transition inside the invoking state does not enter it. A pick is a
+writing an Agent may send (the position rule above); a Gate's event is a human's, and its params are not checked. The
+walk does not carry a pick's params across a timer: where an `after` on a state the pick entered moves on to a state
+that invokes an Effect, the Effect's input and every guard and action from the timer on read the timer's event, so only
+a guard or `assign` before the timer reads them — a param that must cross is stored with `assign` on the pick's
+transition, and one nothing stores is refused. A pick that targets a history state enters what was last active, which
+the walk cannot know: where that may be a state that invokes an Effect, the pick's params there are unchecked, and it
+warns. A guard and an assign are pure by contract, so the probe runs them; it runs no other action. TypeScript does not
+catch a `fromPick` param that is no key of the input: it accepts an extra key on a spread. It refuses a `fill` that sets
+a key that is also a param (the Machine's value would drop the Agent's), and a `fromPick` of a pick other than the event
+that enters the state. Code the probe cannot or does not run may read a param, so it gives a warning, never a refusal: a
+mapper, guard or assign that throws in the probe, and — where a param is left unread — any other action on the entering
+transition or on the entry of a state it enters, named in the warning. Its params are unchecked. It warns where an
+Agent's state answers on a mode's entry (`answer`) and an Effect below it has no `onDone`: the Effect settles in place,
+that mode is not entered again, and the Agent reads the Effect's output, not the answer. A pick that enters no Effect,
+directly or across a timer, is not checked for its params.
+
+- **Two parties' writings of one name that can be active together** — one above the other on one path, or in parallel
+  regions — where the deeper writing (each other region's, for parallel regions) does not decline the other sender with
+  a `sentBy` the walk can read. xstate would select it for the other party's event, so delivery refuses that event while
+  both are active. The warning names both writings and shows the corrected line, with the guard on the DEEPER writing,
+  because xstate selects deepest first and only a declining deeper writing lets selection move outward:
+
+  ```
+  "approve" on "s2.release" (Gate "review-1") and on "s2.release.work.draft" (Agent "coder") can be active together;
+  Gate "review-1"'s "approve" would run Agent "coder"'s writing, so jr2 refuses it while both are active. Make the
+  deeper writing decline other senders:
+    draft: { on: { approve: { guard: sentBy("coder"), target: "#s2.doneB" } } }
+  ```
+
+  A root writing is both parties', so the root-writing shape — a root `cancel`, a Gate below it, the Agent's `cancel` in
+  a mode — is the same case: the line goes on the mode's writing, and the Gate's caller's `cancel` then runs the root
+  writing. The Agent's writing above a party seated BELOW the Agent's state — a Gate, a nested Agent — is not the case:
+  while that party runs, the Agent's state is not at Rest, so every pick of the Agent is refused whatever its guard, and
+  a `sentBy` on the deeper writing would change nothing; the walk does not warn there. Siblings (a mode and a Gate's or
+  another Agent's sibling state) are not the case: neither writing is ever selected for the other, and delivery answers
+  a send there like any pick the state does not take. A Gate whose invoke id the walk derived is named so in the line;
+  giving its invoke an `id` names it. A `sentBy` under `or()` or `not()` leaves the warning in place.
+
+- **One def, one meaning.** One party's writings of one name on one path with different targets: its sender reads one
+  description for both, and only the deepest active writing runs. The warning says to make the def's description true at
+  each writing or to give them distinct names. xstate's own transition `description` rides the Machine doc beside each
+  writing.
+
+Known limits, not built: two states on one path that invoke one Agent slot share one sender id, so `sentBy` cannot tell
+their Turns apart; and a child Machine that forwards a party's event to its parent (`sendParent`) hands it the child's
+sender, whose id names a slot or Gate of the child — if the parent has one of that name, `sentBy` matches it. Only
+author code forwards an event.
+
+Considered and rejected for modes: a Menu per mode (the tools block would change inside a conversation and bill its
+history again — ADR-0029), and refusing picks written below an Agent's state at build (that shape is a mode).
+
+Considered and rejected for the audience: a default of `any` with a convention to tag the sensitive events (an in-Turn
+Gate's caller could then send every pick of the Agent above it unless each was tagged `agent`, and a nested Agent got
+the outer Agent's picks); a fixed default of `agent` (every Gate event then needs a tag, and the nested leak stays); and
+a knob on the Gate (`accepts: "own"`), which fixes the Gate side only. The rule above reads the transition's position,
+not a mark written in it, so it is not the per-transition demarcation rejected below.
+
+Considered and rejected: per-transition demarcation (xstate transitions have no typed metadata slot for it without
+inventing jr2-only config inside the transition table — a DSL by the back door) and purely structural
+own-transitions-only derivation (breaks ADR-0011's blessed handle-`report_blocked`-once-at-an-ancestor idiom). Position
+stays the default and the owner of every writing. `sentBy` is not demarcation: it is an ordinary xstate guard, written
+only where a writing must decline other senders, and it cannot give a writing to anyone.
+
+## Why there is no injection model (the retired ADR-0003)
+
+jr2's first composability story — "workflows are templates of injected providers": Machines reference their moving parts
+as named xstate slots, filled at deployment via `provide({ actors, actions, guards })`, with noop defaults — was tried
+and retired (its ADR, 0003, is deleted; this section is its record). It never composed: xstate's `provide()` fills only
+the machine it is called on and **cannot reach actors inside child machines**, so host-side injection cannot compose
+past one level — and the host has injected nothing since ADR-0011's static-import doctrine ("actor logic is code; live
+things are built per-invocation from serializable input"). Workflows author machines against statically-imported
+mechanisms. What survives of the idea: the kernel "everything pluggable is an xstate actor", and `.provide()` as the
+unit-test seam. The mock-vs-real swap it wanted lives at the wire instead (ADR-0011's stub Harness). GLOSSARY.md's
+**Template** and **Provider** entries retired with it.

package/docs/reference/decisions/0016-agent-turn-mechanics-are-internal.md

@@ -0,0 +1,124 @@
+# Agent-turn mechanics are jr2-internal: ambient coordinates, host-side offsets, absorbed retries, fresh sessions
+
+Second of the workflow-API redesign trio ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md) has the context;
+full record in
+[docs/design/workflow-api/](https://github.com/snapwich/jr2/blob/71ebe36/docs/design/workflow-api/proposal.md)).
+`agentRun`'s consumer input shrinks to workflow vocabulary — `{ agent, prompt }` plus opt-ins below — because everything
+else it used to take was jr2 handing the consumer values jr2 already had. Each absorption follows, with what it deletes
+from a jr-shaped workflow.
+
+The opt-ins include two optional dials, `model` and `thinkingLevel`
+([ADR-0018](0018-instance-agents-are-definitions-jr2-assembles-the-harness.md) draws the identity-vs-dial line and
+states where each is validated). The **absorption principle is what admits them**: what this ADR absorbed was values jr2
+already held and was handing back to the consumer to hand in again — mechanism wearing a consumer's clothes. A dial is
+the opposite case: a genuine per-call choice that jr2 cannot derive, because Agents are instance-scoped and only the
+invoking workflow knows how hard this turn is. Both are serializable strings, so they ride the persisted child input; a
+restore re-attaches to a Submission whose model is already fixed server-side and never re-resolves them.
+
+## Ambient endpoint and sandbox (deletes the `turn()` helper and all handle threading)
+
+`workspace()`'s `running` state co-invokes a registrar actor that records its handles in a `WeakMap<ActorRef, Handles>`;
+`agentRun` walks `self._parent` to the nearest registered ancestor. Invoked-actor registration (not an entry action) is
+what makes this restore-safe: invoked actors restart on snapshot restore, entry actions do not. Not under a workspace →
+fail loudly, unless input carries an explicit `endpoint` (the dev-stub, workspace-less path). Body-facing workspace
+handles are `{ repos, branch }` ([ADR-0012](0012-workspace-wrapper-machine.md)).
+
+**[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)'s token scoping survives and
+strengthens**: the registration records the Sandbox resolved from the enclosing wrapper — the same deterministic
+`workspaceName()` the token was minted for — so the consumer can no longer forget to pass it (the baba71f incident:
+`sandbox` omitted, every tool call 403'd, fail-closed but silent). The parent chain resolves the _enclosing_ wrapper
+structurally, never a sibling's; cross-feature event injection stays impossible.
+
+## Offsets live in a host ledger (deletes `context.offsets` and the `agent.offset` event)
+
+`agentRun` reports `iid → offset` through the run binding into a ledger persisted beside the snapshot in the same
+`RunBlob` save. Iids are globally unique, so restore's recursive nested-context offset folding dies with the context
+leg; restore still rewrites the child's persisted input ([ADR-0007](0007-durable-machine-state.md)'s invariant stands
+verbatim — only the offset's location moved). The Harness wire does the heavy lifting
+([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)): `wait` reconnects from the admitted
+offset, and `abort` is the deliberate terminal cancel ([ADR-0002](0002-duplex-streaming-actor.md)).
+
+The ledger's key is the iid, and an iid is not a Turn. Two Turns that continue one conversation share it, and nothing
+removes a Turn's entry when the Turn ends. So the input mapper also mints a **Turn ID** (`turnId`), one per invocation,
+and it persists with the child's input. The actor stamps it on every admission that it ledgers. The restore re-attaches
+a child only to an admission with the child's own Turn ID. An admission with another Turn ID is an earlier Turn's: the
+child's admission was not ledgered, so the child keeps its prompt and is admitted again. If its admit reached the
+Harness before the crash, the prompt is then sent twice. This is ADR-0007's known durability edge, an at-most-once
+re-POST, and it now applies to a continued Turn as it does to a first one. Before the Turn ID, a crash in that window
+restored the Turn onto the earlier Turn's Submission. The Turn then followed a stream that was not its own, and its
+prompt was never sent. A plain `setup()` Machine that passes finalized input mints no Turn ID, and the key alone
+decides.
+
+## Retries and nudges are absorbed; the workflow sees one terminal `agent.fault` (deletes the retry bookkeeping)
+
+Two fault classes, deliberately not one knob ([ADR-0035](0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md)
+later adds the third: runaway):
+
+- **Infra faults** (stream drop, pod restart, provider error): provider-stream retry lives inside the turn in the
+  Harness, and `wait` reconnects from the offset ledger without a deadline; a restarted Harness or a lost Workspace ends
+  the Turn through the Sandbox watch (ADR-0021), and a Harness that answers 404 is a lost conversation (ADR-0027). The
+  one exception is a restarted Harness while the Agent's state is busy, or with a pick's answer unread: that cuts the
+  Turn and faults nothing — the actor waits for Rest and **re-admits** on the same conversation, with the answer as a
+  notice (ADR-0024, ADR-0031). A re-admission is mechanism, like a nudge: telemetry on the feed, no marker, and it
+  spends no budget, because the model did nothing wrong.
+- **No-signal** (the agent stops while its Turn is still open — jr's dominant failure mode): the wire treats that as a
+  normal completed Submission, so recovery is jr2's. **The ask-again rule**: while the Turn is open, a model that
+  stopped is asked again once its Allowed picks are not empty, and never with an empty list. A delivered pick does not
+  end the question — a pick with no target, or one into a mode, keeps the Turn open (ADR-0024) — only the Turn ending
+  does. One rule, asked at three moments:
+  - **The step boundary.** Inside the Submission, the Harness restates the Turn part when the Allowed picks changed
+    since the model last read them (ADR-0029); that message keeps the engine's loop going and costs no Submission. It
+    never restates an empty list to a model that stopped.
+  - **The nudge.** The Submission settled with picks left: the Agent's Actor admits a **nudge** on the same conversation
+    — "Your previous turn ended, and the workflow is still waiting for your pick." — absorbing ADR-0006's "forced final
+    pick is a Machine-level re-prompt" into the actor.
+  - **The wake.** The Submission settled with none left: the model stopped correctly, and the Turn waits on a Gate, a
+    child's invoke or a timer — the Allowed picks are empty while the Agent's state is not at Rest (ADR-0024). The actor
+    watches the invoking Machine and admits the same nudge the first time its Allowed picks are not empty, read after
+    the mailbox drains like Rest itself, so a state that sends to itself on its way to more work wakes nobody. The watch
+    ends with the state, so a Turn that ended is never woken, and a Turn that was never meant to pick waits until its
+    state exits.
+
+  The nudge and the wake are one Submission kind and spend one budget: a Machine that opens and closes picks under a
+  stopped model cannot ask it without bound. All three read one Allowed list, the one the surface serves (ADR-0029).
+  Their admission is for the conversation the Turn holds, so it says `kept` (ADR-0062). A Harness that lost the
+  conversation while the Turn waited refuses it and seats none, and the Turn is admitted again on a new conversation
+  with its task, or faults when it has no task to send. That ask was spent already, so the budget counts it once.
+
+Budgets are defaulted knobs, not Machine context. Exhaustion emits the single terminal `agent.fault { reason }`; where
+it routes (escalation, a triage/investigator state, a Failure) is workflow policy, but it must route in a Machine: the
+walk refuses a state that invokes an Agent with no `agent.fault` route on itself or an ancestor, and an `agent.fault`
+that no transition takes faults the run
+([ADR-0074](0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md)). In a Chart the route is
+optional: the Open body sends an unrouted fault to the Machine that invoked it, whose route takes it
+([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)). Attempts surface as run-feed/visualize telemetry projected
+to `{ child, attempt }` — no iids on the open observation feed ([ADR-0014](0014-observation-is-open-run-state-is-not.md)
+unchanged).
+
+## Sessions are fresh by default; continuation is opt-in
+
+jr's most deliberate design decision is the **lossy handoff** — every relaunch is a fresh session; revision coders read
+the notes and the code, never the prior agent's conversation. That is the default: each `agentRun` invocation is a new
+conversation. `continue: true` opts into continuation
+([ADR-0057](0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md)): the Turn lands on this Agent's one
+conversation in this Machine instance, iid `<run>/<machine actor path>/<agent>` plus the epoch jr2 bumps on a terminal
+fault; the per-invocation prompt lands as the next user turn; the tool menu still re-derives from the invoking state
+(one conversation travels across the states of its Machine). Mid-turn restore re-attaches the in-flight turn in both
+modes — `continue` governs only what a _new invocation_ means. The author names nothing: in a state machine the
+conversation's identity is already on the page. (This corrects the jr-parity exercise's "same iid = jr's resume
+machinery, free" — an inversion of jr's actual semantics.)
+
+Two live invocations of one continued iid — parallel states — are refused at the registration table: one live surface
+per address. A Submission that arrives behind a live one on the Harness queues: prompts for one instance enter one
+per-instance queue in admission order, and a Submission is promoted only when it is the first unsettled one for its
+conversation (ADR-0027 states this as jr2's own semantics). A queued prompt waits behind work that may never finish,
+which is why [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) both ends the turn and orders the
+abort ahead of the next `send`.
+
+The minting doctrine — addresses are computed by jr2, never by the workflow — covers gate ids too: a gate with no
+authored id derives one from its actor path below the run root, through the same walk `mintIid` uses (`actorPath` in
+registration.ts; ADR-0011). The two mint at different seats for a reason: iids must be minted in the input mapper
+because minting has a random component (the fresh-session suffix) and a ledger read (the continued conversation's epoch)
+— the input is what persists — while a path-derived gate id is deterministic from machine structure, so it is recomputed
+at every actor (re)start and is restore-stable by construction. The mapper rule is about non-determinism, not a blanket
+rule about where ids are born.

package/docs/reference/decisions/0017-pool-over-a-source-port.md

@@ -0,0 +1,69 @@
+# The run loop is a jr2 `pool` over a generalized source port
+
+Third of the workflow-API redesign trio ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md),
+[ADR-0016](0016-agent-turn-mechanics-are-internal.md); full record in
+[docs/design/workflow-api/](https://github.com/snapwich/jr2/blob/71ebe36/docs/design/workflow-api/proposal.md)). The top
+of every jr-shaped workflow — claim ready items, run one child per item under a cap, wake on push or poll, settle when
+done — was ~90 lines of hand-rolled bookkeeping in the jr-parity exercise (`active[]`, `spawnChild`/`stopChild`,
+`xstate.done.actor.*` casts, the discover/saturated/settling/idle choreography, and a comment-enforced "keep
+`spawnChild` top-level or visualize goes blind" footgun). No xstate-ecosystem primitive exists for this (verified: the
+canonical v5 pattern _is_ the hand-rolled loop), so jr2 ships one.
+
+## `pool(worker, spec)` — a machine factory, like `workspace()`
+
+`pool(worker, { source, itemId, cap, itemInput, onDrained, failures })` returns a plain machine that owns
+spawn-under-cap, stable child identity, typed completion collection (`DoneActorEvent<Output, string>` + the
+`xstate.done.actor.*` wildcard — zero casts), `stopChild` bookkeeping, the wake gate, and the re-query timer. The one
+top-level `spawnChild` lives in jr2's pool code, once — the visualize footgun is dissolved by construction, and
+everything durable is a registered string src (xstate cannot persist inline-src children, which independently forces
+this shape). The pool composes: it returns a plain machine and can itself be nested as a child. The typed idioms
+(wildcard done events, `assertEvent`, outcome-in-context root output) ship as documented patterns regardless, so
+outgrowing the pool means hand-rolling without penalty, not fighting a framework.
+
+## The source port is generalized; Work Source is one adapter
+
+The pool draws from a **Source** port — `next(active) → item | null`, plus an optional `wake` event def (webhook /
+`jr2 send` push seam) and `pollEvery` (the set mutates underneath us) — a queue, a generator, or a re-queried set. tk's
+claim actor is one adapter; GLOSSARY.md's **Work Source** reframes as _the Source adapter for tickets_, and the
+Ready-set doctrine (re-query, never materialize) survives as that adapter's semantics, not the primitive's.
+
+A Work Source — `tk`, GitHub issues, Jira, a task queue — is a behavior port, not a canonical data schema: verbs like
+`claimNext`, `updateStatus` and `comment`, each gated by a capability the adapter advertises. It owns the dependency
+graph and hands out the Ready-set, the currently-unblocked items in dependency order, so the Machine never encodes a
+dependency edge. The Ready-set mutates during execution — items can be reopened or created mid-run — so it is not a
+static FIFO queue.
+
+## Terminal triage is three-valued, surfaced as status
+
+Forced by parking-is-retention (ADR-0012) plus workflows whose children park on gates (escalation, human review):
+
+- **drained** — source empty and all children settled → final, or the run ends `failed` when items failed (below);
+- **deadlocked** — open-but-never-ready items with nothing progressing → surfaced distinctly (jr exit 2), not an
+  indistinguishable idle poll, or the run ends `failed` when items failed (below);
+- **waiting** — children parked in gates → the run stays open and the gates list is the "what needs me" surface (jr exit
+  3).
+
+The pool can make this call because it owns both the source and the children — the strongest single argument for the
+primitive over an authored loop. Triage surfaces as run _status_ (feed, `jr2 runs`), not machine events; a
+`pool.deadlock` event can be added if a workflow ever needs to react rather than a human.
+
+## The pool catches a worker's Failure
+
+A worker that fails ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)) ends
+only its own item. The pool catches the Failure on `xstate.error.actor.*`, keeps its payload in `failures` by item id,
+stops that worker, and claims again: the output is `{ status, items, failures }`. The pool is a kit-owned parent, so an
+author cannot give it an `onError`; if it let the Failure go up, one lost `task` would end the whole run `failed`, and
+the host would delete the Sandbox of each sibling, also one that waits at its `review` Gate with commits that it did not
+push. That breaks parking-is-retention for work that did not fail. A defect in a worker still goes up and ends the run
+`error`.
+
+The option `failures: "fail" | "report"` says how a pool ends when one or more items failed. It catches each worker's
+Failure in both modes, so one failed item never stops its siblings. With `"fail"`, the default, a pool that ends
+`drained` or `deadlocked` with failures invokes `fail` with the reason `"<n> of <m> items failed"` and the detail
+`{ status, items, failures }`, so the run ends `failed` and `jr2 run` exits 1. At either end no worker is live, because
+a pool with a live worker parks, so the Failure deletes no sibling's Sandbox. With `"report"`, the pool ends `done` and
+`failures` in its output says which items did not succeed: for a pool whose job is to try each item, where a failed item
+is a correct answer. The default is `"fail"` because `done` means that the work succeeded (ADR-0073), and a CI loop must
+not exit 0 while every item failed. The deadlock is the usual end of a dependency backlog with a failure: a Source over
+a tracker keeps the failed item open, so its dependents never become ready. The `status` in the detail tells the two
+ends apart, and the two details have one shape.