@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md

@@ -0,0 +1,183 @@
+# A run starts a run through a `dispatch` Effect
+
+[ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md) made composition `import` plus invoke, one run
+and one run id, and rejected a run that starts a run "for no requirement that needs a second run id". The grill of
+2026-10-20 brought the requirement: a long-running Machine that watches the outside (a poll of GitHub issues, a webhook
+into a Gate) and, when something arrives, runs an existing Workflow on it, where that Workflow needs its own run: its
+own row in `jr2 runs`, its own durability and cancel, its own Workspaces, a life that is not the watcher's, and perhaps
+an Orchestrator that is not the watcher's. GitHub's `workflow_dispatch` through the API, an Argo Events sensor that
+submits a Workflow, and Temporal's own advice for a child in another namespace (an Activity that starts a workflow
+through the client) are all the same shape: a separate, independent run, started as an act of the caller. That is not
+composition and does not replace it. The two uses stay two mechanisms.
+
+## Decision
+
+- **`dispatch` is a fourth Effect kind**, beside `command`, `http` and `push`
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)): an actor slot,
+  `actors: { review: dispatch("review", { input?, wait?, target? }) }`, with a ledger row, at-most-once, stopped when
+  its state exits, `fromPick` between a pick and it, and its output the answer to the pick that led to it. An Agent that
+  "calls a workflow" is an ordinary pick whose state invokes the slot; nothing a model reads changes, so there is no
+  `@model` claim. **The callee is named as `jr2 run` names it**, `review` or `task/review-loop`, a string constant on
+  the slot and never an `arg()` a model fills: the name is authority, the input is data. A run needs a Workflow name
+  (status, drift, the Console), so a registered Workflow is the only thing a dispatch can start, which is why a name is
+  right here where ADR-0049 rejects it for a child: invoke-by-name resolves to a Machine inside the caller's run; a
+  dispatch resolves to a run of its own. One slot per callee; a Machine that calls two Workflows declares two slots.
+- **The invoke's input is the run's body, whole.** `input: ({ context }) => ({ ticket })` or
+  `input: fromPick(review, ({ context }) => ({ repo: context.repo }))` is the JSON that `POST /workflows/<name>/runs`
+  validates ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)), the same body `jr2 run --input` sends. A
+  one-shot Chart start is nothing special, `{ chart }` in the body; a named Chart is a name. Every knob is the slot's
+  (`wait`, `target`, `input`), so a run-start option that arrives later is a slot option or a door field, never a
+  wrapper around the body. Accepted with it: the pick's schema and the callee's door are two schemas the author keeps
+  aligned, and the idiom is to derive one from the other (`reviewDoor.pick({ branch: true })`); the handoff is by
+  reference, a url, a branch and a commit the callee's own Workspace clones, never a Worktree file, because the Effect
+  runs where no Worktree is; no secret rides the body (GitHub's `secrets: inherit` has no counterpart: the callee's
+  Assembly bound its own); `wait` is static, so a Machine that needs both forms declares two slots; the body is plain
+  JSON; and the callee's host-injected fields (`instanceId`) are the callee's host's, written after the parse. `input`
+  on the slot is an optional zod schema: the author's claim about the callee's door, which types the mapper and
+  `fromPick` and is what `jr2 up` compares (below). Without it the mapper returns `unknown` and the door alone checks.
+- **Two placements, read from the target, and the author writes none.** With no `target` the Effect runs in the
+  Orchestrator's own process and starts the run through the run host and the ledger directly, no wire and no token: the
+  Orchestrator holds the Instance token already
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)) and is the single writer of runs, so a
+  start that went out through an Effector and back in over HTTP would carry a token for nothing. That is a fourth
+  Placement, `orchestrator`, and this is the one Effect that has it. With a target,
+  `target: { url, token: secret("ops-instance") }`, the Effect runs in the Instance Effector, which gains a `dispatch`
+  kind, holds the token as an Effect secret and calls the foreign door; the url is an origin, scheme and host and a
+  port, and a path, a query or userinfo in it is refused at build, since the Effector appends the door's path and the
+  origin is what its fence (`effector.json`) names. A packaged Machine leaves it `target: open` and the composer binds
+  the url and the token together, one Open part, with `customize(m, { effects: { task: { target: { url, token } } } })`
+  ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)); `secret(open)` inside a
+  target is refused, since the whole target is the part. Another Instance may run another Kit version, so the HTTP door
+  is the only contract there. The token is the Instance token, which unlocks all control
+  ([ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)); a start-only token is a token kind of its own and
+  is deferred.
+- **Two settlements, `started` by default, and every outcome is output.** `{ outcome: "started", run }` settles when the
+  Orchestrator accepts the run; the watcher goes round again. `wait: true` settles
+  `{ outcome: "settled", run, status, output }` when that run ends, `status` in the store's own words (`done`, `failed`,
+  `error`, `cancelled`, `lost`, `drifted`, [ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)) and `output` the callee
+  Machine's (for `failed`, the Failure's `{ reason, detail }`,
+  [ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)), which `GET /runs/<id>`
+  serves for a run that is no longer live from this decision on (a live run serves `active` and no output). The slot's
+  `timeout` bounds the whole Effect, the start alone or the start and the wait: 30 s by default without `wait`, 10 min
+  with it, counted from the intent row's first write, so a restore never starts the bound over, and armed again in
+  steps, so a bound past Node's 24.8-day timer holds. A run still live when it runs out settles `status: "live"`, the
+  status the run had when the Effect stopped waiting: in-process the run host says it; in the Instance Effector the last
+  poll must have read the run live, and a wait whose last poll got no answer is `unknown`. In-process the run host tells
+  the wait through a settle hook keyed by the run id, not by its hosting, so a caller restored before its callee hears
+  it when the callee settles, and hears `lost` or `drifted` when restore marks it so; foreign, the Instance Effector
+  polls `GET /runs/<id>` every 5 s as a long-running Effect, which it keeps across an Orchestrator restart already, and
+  a DELETE of the Effect ends that poll and never touches the run. No callback from the callee: a callback needs the
+  callee to hold its caller's address and a token for it, which inverts the trust. A door refusal is OUTPUT,
+  `{ outcome: "refused", status, report }`, with the door's status — 400 for bad input, 404 for a name the current
+  Assembly lacks, 409 for an unrunnable named Chart or a key another Workflow's run holds, 422 for a Chart the door
+  refuses, 413 for a start over the bytes an Effector reads, 0 when the Effector refused it before anything was sent —
+  as a Chart refusal is ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)): the body may have come from a model,
+  and the report must be able to reach it through the Chain. A target no replica could reach is
+  `{ outcome: "unreachable" }`, output, as an `http` Effect's is (ADR-0067): nothing was started. The invoke's error is
+  kept for defects: no run host or Effector, input that fails the slot's schema, a refused or malformed wire.
+- **The two runs are independent.** Cancelling the caller never cancels the callee; the caller's end never ends it;
+  leaving the state stops a wait and never the run; the callee's Workspaces are its own. Temporal's parent-close policy
+  (`TERMINATE` by default, `REQUEST_CANCEL`, `ABANDON`) exists because a child there is both a run and a child, and its
+  default bites on every continue-as-new of a long-lived parent; here the coupled case is `import`, so there is no
+  policy. The link is a record. The callee's row carries `dispatchedBy { run, slot, effect, depth, instance? }`: the
+  caller's run and slot, the caller's ledger row id (the idempotency key, below), the dispatched run's own depth in the
+  chain, one below its caller and stated by the caller, so one meaning on the wire, in the binding and on the row, and
+  for a foreign caller its Orchestrator's name as opaque text — its namespace, never an Instance ID, which names an
+  Agent's conversation. The open band carries the routing (`run`, `slot`, `depth`, `instance`) and never the key, which
+  names the caller's ledger and stays behind the token. The caller's ledger row carries the run it started, written to
+  the intent row the moment the start's answer names it and kept past an abort, and the caller's status lists them as
+  `dispatched [{ slot, run, at }]`, the chain's other direction. `jr2 runs` carries `dispatchedBy` after the id,
+  `jr2 status` prints `dispatched by:` and `dispatched:` lines, and the Console shows both. The word is **dispatched
+  by**. The callee reads nothing of its caller from its input: a Machine that wants to tell its callee something passes
+  it as input like any caller.
+- **A chain of dispatches is unbounded.** A run may dispatch a Workflow that dispatches another, or itself: a run that
+  dispatches its own successor and ends is Temporal's continue-as-new, the honest way to keep a watcher's snapshot
+  small, and a depth ceiling would refuse it. A runaway chain is a resource problem the cluster owner's quota and
+  [ADR-0064](0064-a-workspace-waits-for-capacity.md)'s capacity wait bound; the depth on the row makes it readable. A
+  depth ceiling is named and deferred beside ADR-0070's spend ceiling.
+- **At-most-once across the wire, by construction.** ADR-0067 sends a start once where it may have arrived, and a
+  foreign start whose answer was lost had an unknown outcome. The ledger row's id rides every start as an idempotency
+  key, out of band — the `jr2-dispatched-by` header, the `dispatchedBy` record as JSON, never a body field the callee's
+  door would have to reserve — and `POST /workflows/<name>/runs` asks the key before anything else, so a re-sent start
+  answers its run even when the name would be refused now: 201 with the run for a new one, 200 with
+  `{ runId, instanceId, existing: true }` for a repeat, 409 when a run of ANOTHER Workflow holds the key (the caller
+  asked for one Workflow and would wait on a run of another), 400 when the header does not parse, and 500, never 404,
+  for any other throw, since a foreign caller reads a 404 as "nothing was started" (ADR-0033 as amended). The key lives
+  in the callee's blob, and the store copies it into a `dispatch_effect` column of its own at every save and indexes
+  that, not an expression index over `json_extract`: SQLite's JSON parser refuses a blob nested about a thousand deep,
+  and such an index would fail that row's save and every later open of the volume. A run restore marks `lost` keeps its
+  row and its blob, so its key keeps answering; the weekly sweep
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md)) removes the key with the row, and a re-send
+  after it starts a new run: known, and not guarded. In-process the ledger is consulted directly, through the same start
+  under the same key, with the starts in flight held so two arrivals of one key before the first save are one run. So a
+  dispatch is idempotent whatever its author writes: its intent row says `idempotent: true`, a restore that cannot tell
+  whether its start arrived sends it again under its key with what is left of the bound, the Instance Effector sends a
+  start whose answer was lost again under its key with backoff until the bound, and the Effector's rollout grace is
+  never stretched by a dispatch's wait. Once the answer names the run, the intent row carries it, the Effector's
+  `running` state carries it on the wire, and a restore with it starts nothing: it settles `started` at once, or resumes
+  the wait. Without it a watcher double-starts a run after a restart, which a human notices as two pull requests. What
+  it does not guard: a door at a Kit version before this decision ignores the header, so a re-send to it starts a second
+  run, and neither the Effector nor the preflight can tell. A capability check is named and deferred.
+- **`jr2 up` checks what it can see, and the severity follows who owns both sides.** For a same-Instance name the walk
+  resolves it in the Assembly and REFUSES a miss, naming the fix: on the host, among the Machines and the Chart files,
+  and a slashed name whose wrapper exists but whose Chart the host cannot see is a warning there, since a runtime Chart
+  lives on the Orchestrator's volume alone; at the publish door, among all three, and there the miss refuses the
+  publish. A dispatch of a runtime Chart under a wrapper the same publish adds takes two publishes, the wrapper first,
+  then the Chart's PUT, then the dispatch, and the refusal says so. A Workflow is named by its filename stem, so a stem
+  outside `[a-z0-9-]` is refused at load, naming the rename: `jr2 run`, the door's path and a `dispatch` slot name one
+  set of Workflows. ADR-0067's "a pick param nothing reads" check runs at `createMachine`, before any callee is known,
+  so it reads the slot's `input` schema's keys, and with no schema it reads nothing and skips; the Chart door, for a
+  lent dispatch with no schema, takes any object. The walk then compares the slot's `input` schema, if given, with the
+  callee's door and REFUSES a mismatch. For a foreign target it does `GET /workflows/<name>` from the host with NO
+  token, since the route is open band ([ADR-0014](0014-observation-is-open-run-state-is-not.md)) and the token is the
+  Effector's to carry, compares the served JSON Schema with the slot's schema the same way, and WARNS on no reach, a
+  miss, a mismatch, an answer that is no Workflow detail or a redirect, never refuses: the other Instance may be down,
+  reached only from inside its cluster, or published later, and a refusal would couple two Instances' publish order. The
+  token's own refusal is a run's to answer. **A match is compatibility, one direction**: every required field of the
+  door is in the slot's schema, required there too, with a compatible type, within the door's `enum`, `const` and
+  bounds, and every field of the slot's schema exists in the door, since a plain zod door strips the rest silently; the
+  slot's schema is read as what the driver sends (`io: "output"`, its defaults filled), the door as what it takes. It
+  compares within the JSON Schema subset ADR-0070 names (`type`, `properties`, `required`, `items`, `enum`, `const`, the
+  bounds); a schema that uses something outside it (`oneOf`, `$ref`) is reported "not compared", never guessed at, a
+  warning at `jr2 up` which the publish door, with no warnings channel, drops. **A dispatch resolves at run time against
+  the current Assembly**, as `jr2 run` does: a dispatched run is a new run and starts under the Assembly current then
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)), which may be newer than
+  the caller's. A publish that keeps the caller and drops the callee is refused by the walk, as above; one that drops
+  both leaves a live caller to answer `refused` with the 404's report when it dispatches; pinning a dispatch to the
+  caller's Assembly would run a Workflow the Instance no longer publishes.
+- **Tests.** The mechanics tier (socket-free, the stub Harness; `features/dispatch.feature`) owns the in-process path:
+  the ledger row and the listing both ways, `wait` and the served output, restore mid-wait with one run, cancel of the
+  caller with the callee live, the 400 and the 404 as output, the publish refusal of a miss, and two HTTP starts under
+  one key as one run. One `@kind` scenario has the Instance dispatch to ITSELF by url and token, so the Instance
+  Effector's foreign path, the key and the poll run with no second cluster, across an Orchestrator restart. No `@model`
+  claim: the four new pick answer texts are rendered by the generic path every Effect's answer takes.
+
+## Considered options
+
+- **Keep ADR-0049 and compose.** `import` plus invoke, a `workspace()` nested where the callee needs its own Sandbox,
+  and `pool()` for fan-out. It is still the answer for a coupled child. Rejected for this use because the callee cannot
+  have its own row, its own cancel, a life past the caller's, or another Orchestrator.
+- **A bare `http` Effect against the door.** Works today for a foreign Instance. Rejected: it puts the Instance token in
+  the author's hands for the same-Instance case, gives `jr2 up` nothing to check, and has no idempotency key.
+- **A sub-run as a child actor with its own id** (Temporal's child workflow). Rejected as ADR-0049 did: cross-run
+  correlation and cancel propagation inside one actor tree, for a run that must be independent anyway.
+- **A callback from the callee for `wait`.** Rejected above: it inverts who holds the token.
+- **A depth ceiling, or a static refusal of self-dispatch.** Rejected above: both refuse continue-as-new.
+- **The body wrapped as `{ input, options }`.** Rejected: it taxes every dispatch now for a run-start option the door
+  has never had.
+- **One `dispatch()` slot that takes the name as input.** Rejected: the name is authority and stays a constant.
+
+## Consequences
+
+- ADR-0049's "no sub-run" is restated, not reversed: a nested Machine is reached by `import`, never by name; a run that
+  starts a run is a `dispatch`, by name, and the two are different uses. ADR-0067 gains the kind and a fourth Placement,
+  `orchestrator`. ADR-0068's Instance Effector gains the `dispatch` kind, its stop route stops a dispatch's wait too,
+  and its `running` state carries the run. ADR-0033's door gains an idempotency key.
+- The GLOSSARY's **Effect** gains "or starts a run", and `_Avoid_: sub-run, child run, nested run, spawned run` for the
+  relation, which is **dispatched by**; its **Effector** and **Instance Effector** entries name the in-process exception
+  and the new kind.
+- `RunStatus` gains `output` for a run that is no longer live, `dispatchedBy` and `dispatched`; `RunObservation` the
+  routing of both, without the key.
+- An Open body may lend a `dispatch` slot as it lends any Effect (`lends.effects`), so a Chart can start a run of a
+  Workflow its wrapper chose; the Chart fills the body only.
+- Deferred, named: a start-only token; a depth ceiling; a capability check for a door that ignores the key.

package/docs/reference/decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md

@@ -0,0 +1,144 @@
+# The docs ship inside the Kit, and an Instance's `AGENTS.md` indexes them
+
+Most Machines will be written by an Assistant, not by a human: the human asks for a Machine and reviews its graph. No
+model's training data holds jr2's API, so an Assistant needs the docs for the exact Kit version the Instance resolves,
+and it must find them without being told to look. The docs-site grill of 2026-10 settled where those docs live and how
+an Assistant reaches them. Its evidence is Vercel's evals on APIs that are not in training data: a compressed docs index
+inline in `AGENTS.md` passed 100% of cases; skills passed 79% at best, because the agent did not invoke the skill in 56%
+of cases; no docs passed 53% ([Vercel](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)).
+Next.js ships the same design: its docs as Markdown inside the `next` package, and a managed block in the project's
+`AGENTS.md` ([Next.js](https://nextjs.org/docs/app/guides/ai-agents)).
+
+## Decision
+
+- **One Markdown source, three outputs.**
+  - **The bundle.** `@jr2/orchestrator` ships `docs/`: every page of the sitemap, the generated Reference, the Glossary
+    and the Decisions, as plain Markdown. No site-generator syntax reaches it. It is the main channel for an Assistant.
+    Each page is at its slug, such as `concepts/gates.md`, and each ADR is at `reference/decisions/<file>`. An Assistant
+    reads a page with its file tool, which cuts off a long file. So the Authoring surface is two parts:
+    `reference/authoring-surface.md`, a contents page that gives each name its kind and the first sentence of its TSDoc,
+    and `reference/authoring-surface/<anchor>.md`, one page for each export and for each type that a signature names.
+    One page of all the names is about 200 KB, and the contents page is less than 25 KB. No line of the contents page or
+    of an entry page is longer than 1,000 characters, so the type plumbing is a list, not a paragraph. When the contents
+    page passes 25 KB, first make the long first sentences shorter; if it still passes, give each group of the contents
+    page a page of its own, and make the contents page a list of the groups. The first sentence ends at a stop, not at a
+    colon, because the words before a colon often tell nothing alone ("An invoke."). A link to an entry goes to its
+    page. Each of the other generated Reference pages (CLI, config, machines, mechanism events, HTTP API) stays one
+    page. Each is less than 30 KB, the size that one read of a file tool shows, with one exception: the HTTP API page is
+    about 50 KB. It is one page because its routes come first and are less than 30 KB, so one read shows every route;
+    the types of the bodies come after the routes, and an Assistant reads one of them with an offset or by its heading.
+    When the routes pass 30 KB, give the types a page of their own. The alternative, a split of the HTTP API page now,
+    is rejected because a route and the types it names are then on two pages, and one read shows all routes already. The
+    Glossary and the Decisions are not generated, and this rule does not hold them: an ADR can be about 50 KB, and an
+    Assistant reads the one ADR that a page links to.
+  - **The `AGENTS.md` block.** A compressed index of the bundle, and an instruction in five parts. jr2 is newer than
+    your training data, so read the bundled docs before you write a Machine or config. Start with the guide "Write a
+    workflow" and the contents page of the Authoring surface. Read one page with each call of the file tool. Run
+    `npx --no jr2 check` before you give a change to the user. A final state means that the work succeeded; when it did
+    not, invoke `fail()`, and do not throw to fail. The Failure rule is in the block because no refusal can teach it:
+    the walk cannot see that a final state means "this did not succeed", or that a promise throws only to fail, and in
+    the eval of [ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md) three of the
+    four trials wrote a failure that ended `done` or `error`. The two entry pages in one read are more than about 30 KB,
+    and a file tool then shows only the start of the output. The check is in the block because `npm run typecheck` loads
+    no module. Thus it does not find a refusal of `createMachine`, `defineEvent` or `workspace()`. An Assistant that may
+    not run `jr2 up` gets those refusals only from `jr2 check` (ADR-0009). The command has `--no` because npx with no
+    TTY installs a missing package with no prompt. The package `jr2` on the npm registry is not jr2. With `--no`, npx
+    stops when the Instance has no local `jr2` bin, for example before `npm install`. `npm run check` also does not
+    fetch, but an Instance from an older scaffold has no `check` script. The index names each file of a directory, but
+    the Decisions folder and the Authoring surface folder each have one entry, which names the contents page of the
+    folder. Thus the line stays short.
+  - **The site**, on GitHub Pages. HTML for humans, and every page also at a `.md` URL, plus `llms.txt`, for tools that
+    read over the network.
+- **The docs ride `@jr2/orchestrator`, not a package of their own.** The Kit version _is_ the `@jr2/orchestrator` the
+  Instance resolves, so the bundle matches the code the Assistant writes against by construction. There is nothing else
+  to pin.
+- **`jr2 init` writes the block, and `jr2 up` keeps it current.** `init` writes `AGENTS.md` with the block between two
+  markers, and a `CLAUDE.md` that holds `@AGENTS.md`, because Claude Code reads `AGENTS.md` only when no `CLAUDE.md`
+  exists. `init` takes the block from the bundle of the CLI's own `@jr2/orchestrator` when that is the version it pins;
+  without that bundle it leaves the markers empty. An `AGENTS.md` or a `CLAUDE.md` that exists stays as it is, and
+  `init` says what to add to it. `up` rewrites the text between the markers when it differs from its Kit version's
+  block, changes nothing outside them, and prints one line: `AGENTS.md: jr2 block updated for <version>`. It does this
+  before the cluster work, so a converge that fails still updates the block. `up` is the verb because every upgrade ends
+  in `up`. A folder without the markers has opted out: `up` never creates the file or the markers, and no config key
+  exists for it. A broken marker pair is reported, and `up` does not change the file.
+- **The Reference is generated from the code wherever the code holds the facts.**
+
+  | Page                                                    | Source                                                 |
+  | ------------------------------------------------------- | ------------------------------------------------------ |
+  | Authoring surface: a contents page, and a page per name | TSDoc on the exports, exactly the root's list          |
+  | `@jr2/machines`                                         | TSDoc on the exports                                   |
+  | `jr2.config.ts`                                         | TSDoc on the `JR2Config` fields                        |
+  | CLI                                                     | a structured command table, which also prints `--help` |
+  | HTTP API                                                | the route table in `http.ts`, made data                |
+  | Mechanism events                                        | the code that defines them                             |
+  | Glossary, Decisions                                     | `GLOSSARY.md` and `docs/adr/`, rendered as they are    |
+
+  The TSDoc on an Authoring surface export is written for the author: what it does, what it refuses, what to read next,
+  and one example. Maintainer reasoning goes in `//` comments in the body. The packages ship their `.ts` source, so an
+  Assistant that follows an import into `node_modules` reads the same text the site shows. The Authoring surface is
+  exactly what `@jr2/orchestrator` exports from its root: what the kit's packages share is internal even where it can be
+  imported, and `@jr2/machines` is not part of it, because it ships Machines, not names to author with.
+
+- **`docs:build` assembles the bundle at pack time.** Its inputs are the hand-written pages in `docs/site/`, the
+  generated Reference, `GLOSSARY.md`, and `docs/adr/`. It runs in `@jr2/orchestrator`'s `prepack` and before the site
+  build. Its output is gitignored, and no generated file is committed. A link that leaves the docs set becomes a GitHub
+  URL at the release tag; a link that resolves nowhere fails the build. The `@dist` tier asserts that the packed bundle
+  exists and that the `AGENTS.md` from `jr2 init` indexes it.
+- **The site describes the latest release and deploys on its tag**, in a `pages` job in `release.yml` that needs the
+  release job, so a failed gate deploys nothing. It does not wait for the staged packages' approval
+  ([ADR-0055](0055-a-release-is-a-pushed-tag-and-the-publish-guard-is-the-credential.md)).
+- **VitePress builds the site, from the pages as they are.** The source format is VitePress's own Markdown, so a page
+  renders on GitHub and in the site, and an error names the file that a writer edits. `docs:build` accepts four forms of
+  it, and makes each one plain for the bundle: an aside, the provider tabs, a code group, and a `<<<` code import. It
+  refuses every other form, so no generator syntax reaches the bundle. The provider tabs are `::: tabs key:provider`
+  from `vitepress-plugin-tabs`, not VitePress's `::: code-group`: a provider tab holds prose as well as code, and the
+  plugin keeps the reader's choice on each page, which a code group does not. `docs:build` refuses tabs with another
+  key, and a `<<<` of a file outside `docs/site/examples/`, which `pnpm typecheck` checks. A `mermaid` fence is a theme
+  component that imports mermaid only on a page with a diagram. The site has local search, a `sitemap.xml`, and the
+  `.md` URL of each page in a `<link rel="alternate">`.
+
+## Considered options
+
+- **Skills.** Rejected as the channel for API knowledge: the Vercel evals above, and an agent decides whether to invoke
+  a skill, where it always reads `AGENTS.md`. Skills stay possible for a multi-step job, such as an upgrade.
+- **A docs MCP server.** Rejected: one more process to run for text that can sit on disk. MCP is for acting on a running
+  system, not for reading docs.
+- **The site and `llms.txt` only.** Rejected: the site describes the latest release, and an Instance can pin an older
+  one. An Assistant also fetches over the network inconsistently, and some run without network.
+- **A separate `@jr2/docs` package.** Rejected: the Instance must install it and pin it to the Kit version, and a
+  mismatch is silent. Inside `@jr2/orchestrator`, it cannot mismatch.
+- **The Authoring surface as one page.** Rejected: an Assistant's file tool cuts it off, so it reads the first entries
+  and not the rest.
+- **An entry page named by its export, such as `Customize.md`.** Rejected: `customize` and `Customize` are both exports,
+  and on a file system that ignores case (macOS, Windows) the two are one file. A page is named by its anchor, which is
+  lower case and starts with `type-` for a type.
+- **A hand-written Reference.** Rejected: it drifts from the code, and the Reference is what an Assistant trusts most.
+- **Copies of the Glossary and the ADRs committed inside the package**, kept equal by a drift check. Rejected: two
+  copies of one text, to avoid one pack-time step.
+- **`AGENTS.md` written once by `init`.** Rejected: it goes stale at the first upgrade. **A `jr2 docs` command to
+  refresh it** is rejected too: a step that someone must remember.
+- **Deploy when npm serves the version** — an hourly job that compares `npm view` with the deployed version. Rejected:
+  more machinery to close a window of minutes.
+- **Astro Starlight.** Built to the same bundle, and compared with VitePress on the same pages. It had better search and
+  a lighter page, which VitePress gets with a small search fix and a mermaid component. Rejected: its tabs and code
+  imports are MDX components, so 28 pages become `.mdx` that GitHub shows as source text, and a page carries more than
+  twice the generator lines.
+
+## Consequences
+
+- `jr2 up` writes into the Instance folder, and only between the markers.
+- `@jr2/orchestrator` gains its first pack-time step. Its source still ships as `.ts`; only `docs/` is assembled.
+- The Orchestrator's Kit image packs `@jr2/orchestrator` with `npm pack --ignore-scripts`, and its build context drops
+  `docs/`: the `prepack` needs pnpm and the whole repo, which the image stage has not, and the Orchestrator's process
+  never reads the bundle. So the image holds no docs, and a local `docs:build` does not move its tag
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)).
+- The tarball grows by the docs, most of it the ADRs (about 0.7 MB of text today).
+- A TSDoc edit on the Authoring surface is a docs edit. `--help` and the CLI Reference come from one table, so they
+  cannot disagree.
+- A docs fix goes live with the next release, not on merge.
+- A rejected stage leaves the site describing a version that npm does not serve, until the next tag. Accepted: the
+  window is short, and a rejected stage is rare.
+- The bundle is plain Markdown, so a change of the site generator changes `build/vitepress.ts` and the pages' forms, and
+  nothing that an Assistant reads.
+- VitePress 1.x is on Vite 5, with dev-server advisories that the site cannot fix. The site is static, so they reach
+  only `docs:dev`. A move to VitePress 2 is a later change.

package/docs/reference/decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md

@@ -0,0 +1,122 @@
+# A Machine fails a run with `fail()`, and an uncaught Failure ends it `failed`
+
+A run ended `done` when its Machine got to a final state, and that did not say that the work succeeded. No Machine could
+end a run as a failure. An eval in which an Assistant writes jr2 Workflows showed the gap: three of the four
+ticket-to-pr trials wanted a failure that is not `done`. Two threw from a plain `fromPromise` ("the planner changed the
+code", "the push failed"). The run then ended `error`, with the message in `fault`, no output and the Sandbox kept, so
+an operator could not tell a kit bug from a failed ticket. One trial wrote `failed` and `lost` final states with the
+comment "the run faults rather than lie about a decision", and that run ended `done`. The fourth put a
+`failed: "<reason>"` variant in its output union, which every reader of the run then had to know about.
+
+## Decision
+
+- **A Failure is the end that a Machine chooses for work that did not succeed.** A Machine makes one with the Part
+  `fail()`: `actors: { fail: fail() }`, invoked as `src: "fail"` from any state, at any depth. Its input is
+  `{ reason: string; detail?: unknown }`: `reason` is text for a person, and `detail` is optional JSON for a machine
+  reader. The Part throws an error with a brand. The brand is a registry key (`Symbol.for`), because an Instance can
+  load a second copy of the kit, and both copies must read the same brand. The kit does not export it, and an author
+  makes a Failure only with `fail()`. It is a Part and not an Effect, because it does no work outside the Machine. The
+  slot name is the author's; the docs use `fail`, never `abort`, which is a Settlement's word and the wire's.
+- **A Failure goes up by xstate's own error rules.** It goes from the state that invokes `fail` to each parent Machine
+  in turn, and an `onError` on the way catches it, as a `catch` does. `isFailure(error)` tells a Failure from a defect
+  and narrows it to the payload:
+  `onError: [{ guard: ({ event }) => isFailure(event.error), target: "replan" }, { target: "defect" }]`. In a Chart, the
+  same guard is `jr2.failure`: every Chart has it, as every Chart has `jr2.sentBy`, because it is a predicate and gives
+  no capability.
+- **An uncaught Failure ends the run `failed`.** `failed` is a Run status of its own, beside `done` and `error`. `fault`
+  stays empty, and the run's output is the payload, not a value of the Machine's output type. `jr2 status` and the
+  Console show the reason, and the Console gives `failed` a color that is not the red of `error`.
+- **A Failure deletes the Sandbox.** A Failure is a chosen end, as `done` is, and each kept Sandbox holds its whole Size
+  ([ADR-0060](0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)) until its Lease lapses. `workspace()`
+  catches a Failure from its body: `running` gets `onError` guarded by `isFailure` to a `failing` state, which runs the
+  same `destroy` as `teardown` and then invokes `fail` again with the same payload. So `workspace()` still owns the
+  Sandbox's life ([ADR-0012](0012-workspace-wrapper-machine.md)), a caught Failure leaves no Sandbox behind, and the
+  parent gets the Failure unchanged. A defect still goes up with no `onError`, and its Sandbox stays as evidence. The
+  host deletes every Sandbox of a run that ends `failed`, after the stop, as `cancel` does
+  ([ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)); after the wrapper's own delete, that is only a backstop. When a
+  Machine above catches the Failure, the host stops the children of the Machine that the Failure ended, and after the
+  stop it deletes their Sandboxes, because a stop skips `teardown`. It does not delete a name that a live Workspace of
+  the run holds then, and nor does a Workspace that was stopped in `placing`
+  ([ADR-0064](0064-a-workspace-waits-for-capacity.md)): a parent that invokes the same Machine again gives the new
+  Workspace the same invoke id, and so the same Sandbox name. That new Workspace takes over the Sandbox and its
+  Worktrees, as a restore does, with the work of the failed attempt still in it. To keep the work for a person to read,
+  the Machine waits at a Gate before it fails.
+- **`jr2 run` exits 0 only for `done`.** It exits 1 for every other end: `failed`, `error`, `cancelled`, `lost`,
+  `drifted`, and a run that was parked before it settled. Exit code 2 stays the CLI's code for a usage error. The status
+  line on stderr tells which end it was, and `jr2 status --json` tells a script.
+- **A `dispatch` parent reads `failed` as a status.** `settled.status` gets `failed`, on the in-process path and in the
+  foreign `DispatchOutput` shape ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), and `output` is the
+  payload.
+- **Each state that can fail the run is static.** The walk finds each state that invokes a `fail()` slot, also in a
+  nested Machine. `jr2 up`, `jr2 check` and the Machine doc list them, as they list Gates and Effects.
+- **A Machine lends `fail` to a Chart as it lends `gate`**: `lends: { fail: true }`
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)). The Machine decides if a Chart can end its run as a
+  Failure, and it can catch one with an `onError` on its Open body state.
+- **A plain throw stays a defect.** Logic that throws ends the run `error`, as before. jr2 cannot see in the walk that a
+  promise only throws, so the docs say it: to fail, invoke `fail`; never throw to fail, and a final state means `done`.
+- **A decision of a person fails the run only when it ends the run.** The rule is about the state where the run ends. A
+  `reject` that sends the work back is a usual route. A decision that ends the run, such as a `reject` at a Gate or a
+  `roll_back`, goes to a state that invokes `fail` with the reason of the person, not to a final state, and
+  `{ outcome: "rejected" }` leaves the output unions. A Machine whose job is the decision itself, such as a triage where
+  "no" is a correct answer, keeps a final state and puts the decision in its output.
+- **The shipped `task` Machine fails when its Sandbox is lost.** Its `lost` state invokes `fail` and is no longer final,
+  and `outcome` leaves `TaskOutput`, which is `{ branch }`. A parent that read `outcome: "lost"` now catches the
+  Failure. `pool()` is such a parent: it keeps a worker's Failure in `failures` and goes on, so that one lost worker
+  does not delete the Sandboxes of its siblings ([ADR-0017](0017-pool-over-a-source-port.md)). When it ends with
+  failures, `drained` or `deadlocked`, it fails the run with the reason `"<n> of <m> items failed"` and the detail
+  `{ status, items, failures }`, unless its option `failures` is `"report"`: then it ends `done`, with the failures in
+  its output. The docs examples whose final states mean "this did not succeed" change in the same way.
+- **A restart replays a Failure.** The state that invokes `fail` persists as any state does
+  ([ADR-0007](0007-durable-machine-state.md)), and on restore `fail` runs again and throws again.
+
+## Considered options
+
+- **A failure is only the Workflow's output** (the fourth trial's shape). Rejected: the `jr2 run` exit code, the Sandbox
+  decision and the Console must react the same way for every Workflow, and none of them can read a Workflow's own output
+  shape. Each CI script would parse the output of each Workflow.
+- **`jr2 run --fail-on <path>`.** Rejected: it puts a fact of the run in one client, so the Console and `dispatch` do
+  not see it.
+- **A tag, `run.failed`, on a top-level final state.** Plain xstate and static, and it was this ADR's first form.
+  Rejected: only the root's final state can give the status, so each level between the failure and the root must carry
+  it. xstate's done event carries only the output, so `workspace()` would need a second, tagged final state and a fact
+  in its context; the Chart wrapper would need a new outcome; each nested Machine would map its child's output to a
+  tagged final state of its own. A throw needs none of that, because xstate already sends an unhandled error up through
+  each parent.
+- **An output shape that jr2 reads**, such as `{ failed: reason }`. Rejected: it gives jr2's meaning to a key in the
+  author's own data, which is hidden mechanism ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)), and it
+  takes part of the output type from the author.
+- **The unbranded throw** that the trials wrote. Rejected: it ends `error` with no output, and nobody can tell it from a
+  defect.
+- **A separate exit code for `failed`.** Rejected: CI needs to know that the run did not succeed, and the status tells
+  which end it was.
+- **A typed `fail<T>()`** with an input schema. Not now: it adds a type parameter to the Authoring surface, and no trial
+  needed a typed `detail`.
+- **`fail` in every Chart, with no lend.** Rejected: the Machine decides which ends a Chart can choose, as it decides if
+  a Chart can wait at a Gate.
+- **A failed run keeps its Sandbox**, as a fault does. Rejected: a fault keeps it because nobody chose that end; a
+  Failure is chosen, a CI loop of failed tickets would fill the cluster, and a Gate keeps the work when the author wants
+  it.
+- **Another word than `failed`**, because a Settlement has a `failed` value too. Rejected: `failed` is the word CI and
+  people use, the two are about different things (a run and a Submission), and each glossary entry names its subject.
+
+## Consequences
+
+- **`onError` carries two things**: a defect or a Failure, which `isFailure` separates
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)). A broad
+  `onError: "retry"` catches a Failure too, as a broad `catch` does.
+- **A failed run's output has the kit's shape**, so `DispatchOutput` has a branch for `failed` and a parent reads the
+  payload there.
+- **An uncaught Failure stops the tree** as an error does: exit actions and `teardown` above the failing state do not
+  run, and the host does their cleanup.
+- **`done` now means that the work succeeded**, by the convention that the docs teach: a Machine that did not succeed
+  fails.
+- The e2e and `@model` settle loops treat every status that is not `live` as settled (`features/lib/run-settled.ts`), so
+  a `failed`, `cancelled` or `lost` run does not poll until the timeout. The Workflow fixtures of the `@kind` and
+  `@model` tiers that end in a `faulted` or `lost` final state invoke `fail`. A trial's note prints the Failure of a
+  `failed` run: `EXPLAINED_STATUSES` in `features/lib/model-status.ts` lists `failed` with the other statuses that it
+  explains, and `model-finished.ts` counts only `done` as finished. The Chart fixtures keep their final states: no
+  wrapper that runs them lends `fail`, and they test the door and the routing, not how a run ends.
+- The change touches what a model reads (the docs, the AGENTS.md index, the fixtures' Machines), so the `@model` tier
+  runs before it is done
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)), and the agents-md
+  eval runs against it.

package/docs/reference/decisions/0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md

@@ -0,0 +1,76 @@
+# An unrouted mechanism event is refused at load and faults the run
+
+jr2 sends `agent.fault` to the Machine that invoked an Agent when the Agent's Turn cannot go on
+([ADR-0016](0016-agent-turn-mechanics-are-internal.md)), and `workspace()` sends `workspace.lost` to its body when the
+Sandbox is gone ([ADR-0012](0012-workspace-wrapper-machine.md)). Both go by `sendBack`, and xstate drops an event that
+no active state handles. So a Machine that does not route `agent.fault` waits for ever in the Agent's state with a dead
+Agent, and a body that does not route `workspace.lost` shows healthy on the feed with no Sandbox
+([ADR-0022](0022-observation-is-a-level-triggered-feed.md)). Six of the 12 trials of an eval in which an Assistant
+writes jr2 Workflows did not route `agent.fault`. Each of those Machines loaded, and each could wait for ever.
+
+## Decision
+
+- **The walk refuses a Machine with no route for a mechanism event.** It refuses a state that invokes an Agent, or an
+  Open body that lends an Agent or allows a model, when that state and all its ancestors have no `agent.fault` route,
+  and a state of a `workspace()` body that the body can stay in when that state and all its ancestors have no
+  `workspace.lost` route. The states that a body can stay in are each leaf that is not final, and each compound state
+  whose nested final state has no `onDone` on the compound state: the body then stays in the compound state. An event
+  goes to the active leaves first, so a route on each leaf, or above it, is a route for the compound state above them. A
+  final state of the root ends the body, and a final state of a parallel region leaves the other regions active, so
+  neither is judged. One route on the root satisfies each rule. The `agent.fault` refusal is in
+  `jr2Setup().createMachine`, beside the lost-output refusal, so `jr2 check`, `jr2 up` and the Orchestrator's load all
+  show it. The `workspace.lost` refusal is in `workspace()`, which is the one place that knows that a Machine is a body.
+- **At runtime, a mechanism event that no transition took faults the run `error`.** The run host sees it in the
+  inspection stream: a microstep for `agent.fault` or `workspace.lost` with no transitions, in the Machine that got the
+  event (for `workspace.lost`, the body, because the wrapper always takes its own transition to forward it). `fault`
+  names the event, the state and the event's `reason`. This catches the route that the walk cannot judge: a guard that
+  is false when the event comes.
+- **In a Chart, the `agent.fault` route is optional, and the Machine that invoked the Open body routes the rest.** The
+  Open body sends an `agent.fault` that no transition of the Chart takes to the Machine that invoked it, unchanged:
+  `{ type: "agent.fault", instanceId, reason }`, with the Instance ID of the Chart's Agent
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)). It does not step the Chart. That Machine's `agent.fault`
+  route takes the event, as it takes the fault of an Agent of its own, and the exit from the Open body's state stops the
+  body. A route that does not exit the state keeps the Chart where it is, and the Chart's Agent is gone: the Chart goes
+  on only on its other events, or ends at its wall-clock ceiling, as a route with actions only does to a state of a
+  Machine. With no route that takes it, the runtime rule above faults the run. So one route on the root of a Machine is
+  the route for its own Agents and for the Agents of its Charts. An Agent of a child Machine sends to that Machine. The
+  Chart door does not refuse a Chart state with no route, and `jr2Setup().createMachine` does not refuse the Machine
+  that a Chart compiles to. Under an Open body that lends no `fail`, a Chart has no correct state for the route: a final
+  state means `done`, and a state that waits holds the run until the wall clock. The Chart wrapper, which is TypeScript
+  and checked by the walk, decides.
+- **Routed means that the runtime took a transition.** A route with actions only counts, because it can be a deliberate
+  `reenter: true` that invokes the Agent again. jr2 does not judge what a route does.
+- **An unrouted mechanism event ends the run `error`, never `failed`.** The Machine did not choose that end, so it is a
+  fault and not a Failure ([ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)),
+  and its Sandbox stays as evidence.
+
+## Considered options
+
+- **Drop the event, as before.** Rejected: the run waits for ever and looks live, and nothing tells a person why.
+- **Only the walk.** Rejected: a guarded route that is false at runtime still drops the event.
+- **Only the runtime.** Rejected: half of the trials would load and then fault on the first Agent fault, when the walk
+  can tell the author before the first run.
+- **Make `agent.fault` the Agent actor's error**, so that xstate faults the parent when no `onError` handles it.
+  Rejected: ADR-0016 and the Chart vocabulary route the event by name, and `onError` already carries defects and
+  Failures; an Agent's fault would be a third thing on it.
+- **A Chart's unrouted `agent.fault` ends the Open body as an error**, which the Chart wrapper catches with an `onError`
+  on its Open body state. Rejected: that error and a defect of the body are the same plain error, so the Chart wrapper
+  cannot fail the run for a Chart Agent's fault without failing it for a defect too, and one Machine routes the fault of
+  its own Agent on `agent.fault` and the fault of a Chart's Agent on `onError`.
+- **A mark on that error**, such as `isAgentFault(error)`, with a matching Chart guard. Rejected: a new name on the
+  Authoring surface, and still two routes for one event.
+- **Require the route in a Chart too**, with a line of the Chart door. Rejected: under an Open body that lends no
+  `fail`, the planner can write no correct target, and the trials of the `chart-refusal` claim wrote a `faulted` final
+  state, which ends the run `done`. A route the planner must write also adds a rule to the text that a model reads.
+
+## Consequences
+
+- The text "When no state routes it, xstate drops the event, and the run stays in the Agent's state" in the
+  `FaultTelemetry` TSDoc (`actor.ts`) and in `mechanism-events.md` changes to this rule.
+- A Machine in the docs, the templates or the fixtures that does not route a mechanism event gets a route, or the walk
+  refuses it.
+- A Chart needs no route, so the Chart fixtures and the Charts of the docs keep none that they do not use, and the Chart
+  briefing and the grammar's fragment do not show one. Their Chart wrappers route `agent.fault`, or the walk refuses
+  them.
+- An Assistant learns the rule from the refusal line of `jr2 check`, so the line names the state, the event and the
+  route to write.