@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -15,11 +15,13 @@ 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()`.
+  a Gate's input, an Agent's Frame. The plain `gate` actor is off the surface too. `jr2Setup` registers it, and a state
+  invokes it as `src: "gate"`, so no author writes the value. The `gate()` factory of a Gate slot that hears a Hook is
+  on the surface, because an author writes it in `actors` ([ADR-0011](0011-workflow-defined-events.md)); the walk knows
+  such a slot by identity, not only by `src === "gate"`. 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.
@@ -73,14 +75,14 @@ another Agent slot (a nested Turn: its picks are its own) or a `gate` (its trans
 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
+`source` Gate, on its root, takes the writing on `parked`). The consumer names neither, and the Menu's `mcp__jr2__` tool
+names appear 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
@@ -89,7 +91,9 @@ 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):
+(`defineEvent({ audience?: "agent" | "external" | "any" })`, no default). One case reads as `external`: an event in a
+Gate slot's `delivers` whose def leaves the audience unset, so a Hook's event is never on the Menu of an Agent below
+that Gate ([ADR-0011](0011-workflow-defined-events.md)):
 
 | Transition written on                                                                             | Unset audience: who may send                                         |
 | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |

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

@@ -9,35 +9,219 @@ done — was ~90 lines of hand-rolled bookkeeping in the jr-parity exercise (`ac
 `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.
 
+The webhook round of 2026-11-03 added the other half: work that starts from the outside. An alert service sends one
+alert, and each alert needs one run of a triage Workflow. A forge labels an issue, and each labeled issue needs one run
+of a ticket Workflow. A Hook ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md))
+never starts a run itself. It reaches two things that exist: a Gate, which answers a run
+([ADR-0011](0011-workflow-defined-events.md)), and a Source, which brings items. So this ADR gives the Source a push
+half, lets a Pool's worker be a run of another Workflow, and lets such a Pool stand.
+
 ## `pool(worker, spec)` — a machine factory, like `workspace()`
 
-`pool(worker, { source, itemId, cap, itemInput, onDrained, failures })` returns a plain machine that owns
+`pool(worker, { source, itemId, cap, itemInput, onDrained, failures, standing })` 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
+`xstate.done.actor.*` wildcard — zero casts), `stopChild` bookkeeping, the Source's 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 worker is a child Machine or a `dispatch(...)` slot, never a bare Workflow name.** A child Machine runs inside the
+Pool's run, as it always did. A `dispatch` slot ([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)) makes
+each item a run of its own: `pool(dispatch("triage", { input: triageDoor, wait: true }), { … })`. The two worker kinds
+differ in five places — a worker's defect, a cancel of the Pool, what `customize` reaches, the life of an item's key,
+and where the Gates are — and each difference is one that ADR-0071 states between a child and a dispatched run. So they
+belong to the worker kind, and the word `dispatch` at the call site shows them. `pool("triage", …)` would hide all five
+behind a string, so jr2 does not offer it. Inside, one claim loop serves both kinds with two internal policies.
+
 ## The source port is generalized; Work Source is one adapter
 
-The pool draws from a **Source** port — `next({ active, settled, input }) → 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. `input` is the Pool's input and `settled` holds the ids of the finished and failed items, so a Source
-can fan out over a plan with no state of its own. 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.
+The pool draws from a **Source** port in one of three forms:
+
+- **Pull**: `next({ active, settled, input }) → item | null`, plus an optional `wake` event def (for `jr2 send`) and
+  `pollEvery` (the set changes under the Pool). `input` is the Pool's input and `settled` holds the ids of the finished
+  and failed items, so a Source can fan out over a plan with no state of its own.
+- **Read**: `read`, an `http` Effect marked `idempotent: true` or a promise (`pool()` refuses another Effect,
+  [ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), as a Gate's look does),
+  and `items`, which turns its answer into the items in order (by default the answer itself, when it is a list). The
+  read's input is the Pool's input. It is the re-queried set, read through an Effect, so the read can spend a secret
+  that the Instance Effector holds ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), which
+  a `next` in the Orchestrator cannot. A promise read holds no secret, and the default tier reads with one. A failed
+  read gives no items.
+- **Push**: `item`, a zod schema, and `hooks` whose handlers carry each item. Nothing can be read again: each item comes
+  in a delivery, and the Pool holds it (below).
+
+A pull or a read Source can hear a Hook too. Its `hooks` handlers give `reread()`: read the set again now. **When a
+Source can read, the read is the truth**: a delivery only says "read again", and an item that lost its label while it
+waited is not in the next read. A handler of a Source has the shape of a Gate's (by Hook kind, then event key) and reads
+`{ payload, caller, delivery, input }`. It gives `reread()`, `carry(item)` or `skip(reason)`, and never a bare
+`undefined`: a delivery that brings nothing has a reason that a person can read in the Hook's answer, the hook log and
+`jr2 hooks`. A throw is a skip with the error as its reason. `skip` is for a Source's handlers only; a Gate's handler
+gives an event or `undefined`. A verdict that the Source's form cannot take (`carry` from a pull or a read Source,
+`reread` from a push Source) and an item that the `item` schema refuses are each a skip, with the reason. **An item
+whose `itemId` throws or gives no id gets no worker, in each form of Source.** In a delivery to a push Source, it is a
+skip with the reason. In a read, the read skips that item, with a `pool` mark `skipped` on the feed that says which item
+and why, and it claims the rest. A read at each `pollEvery` finds the item again, so jr2 marks each such item one time
+in a run's life. Else one item with no id would make each read give no items, with no mark, and no item of that Source
+would start. A `next` gives one item at a time, so its item with no id ends the run `error`, and the streak below pauses
+the Pool when that does not stop. Mechanically the push half is the Pool's `source` Gate, which heard only `wake`
+before, so the Hook's fan-in reaches it as it reaches any open Gate (ADR-0011). A Source may also give
+`reply(verdict, { caller })`: pure, from its own verdict to plain text or `undefined`, which the person who acted on a
+chat service reads, and nobody else; a `skipped` text shows only when no other target gave one (ADR-0011). The verdict
+is the line of `sources`, and for `held`, `existing` and `hold-full` also the parsed `item`. A paused Pool has no run,
+so no `reply` runs for `paused`. The reply after the work is a plain `http` Effect of the Machine.
+
+The claim loop has three paths: `next`, the read, and the held items. A `reread`, a `wake` or a settled worker that
+comes during a read (or during a call of `next`) sets a latch, and the loop reads once more after that read, so no
+change is lost. Reads coalesce: one read claims every free slot, and the loop does not read after each claim and each
+settled item one by one. The Pool drops a known id before it claims, so a read that finds an active or settled item
+starts nothing. For a Pool of runs, an item that started a run has one record of "settled": the store's key check
+(below). An item that ended with no run (`start-refused`, `dispatch-error`, `unreachable`) has no row in the store, so
+the Pool counts its key as known for the rest of its run's life: else the read that its own settle starts would claim it
+again at once, with no pause and no end, and one item that the callee's door refuses would hold the Orchestrator's event
+loop. The next run of the Pool (a hand-over or a resume) tries such an item again, so a publish that fixes the door or
+the `itemInput` takes it. The Pool keeps no settled keys past its own run's life: it keeps the run and the status of
+each item that ended in that life, which the bound of a standing run limits, and which a `next` reads as `settled`. A
+`next` that gives an item whose run ended before gets that run (`existing`), whose wait ends at once, so the item
+settles and is not asked for again.
 
-A Work Source — `tk`, GitHub issues, Jira, a task queue — is a behavior port, not a canonical data schema: verbs like
+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.
+static FIFO queue. An adapter can give both halves of a Source: its read and its Hook's handlers, so the mapping from
+the service's data to an item is written once.
+
+## A pushed item is held until the Pool claims it
+
+- **The Pool holds each carried item in its run's blob**, in the order of arrival, until it claims it. An item that
+  leaves for a worker is no longer held: the worker, by its key, is the record. The Hook's answer leaves after the save
+  that records the item, so a `held` answer is durable.
+- **The key check comes before the hold.** An item whose key a held item, an active worker, or a run of the worker's
+  Workflow holds is `existing`, and the answer names the run when one holds it.
+- **`hold` bounds the held items**, 1000 by default. Above it, the Hook's answer is 429 (for a chat command, 200 with a
+  text that says why, ADR-0011) and the hook log keeps the delivery. The 1000 is not measured.
+- **What a push loses**: a delivery while the Orchestrator is down, while no Assembly is current (503), while the Pool
+  is paused (`paused`), and above `hold`. A read Source loses nothing, because the next read finds the item.
+- **A 429 does not claim the delivery's id.** The hook log keeps it as `hold-full`, and a repeat is found only by a
+  delivery that the door claimed (ADR-0011), so the service's send again is heard: a Gate that took it passes it over by
+  the run's answers, and a Pool that holds its item answers `existing`.
+- **A Source's verdict on a delivery** is one of `held`, `existing`, `hold-full`, `reread`, `skipped` and `paused`, and
+  it goes in the delivery's outcome as a line of `sources` (ADR-0011).
+
+## A Pool of runs, and a Pool that stands
+
+A Pool whose worker is a `dispatch` slot keys each item's run by `itemId`, scoped to the callee Workflow
+([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)): every Pool, every hand-over and every `jr2 run` that
+gives the same key for that Workflow gets the same run while its row lives, live and for `runs.retain` after it ends
+([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)). `cap` counts the live runs that
+this Pool dispatched, so its slot must say `wait: true`: with `started` alone, the Pool cannot know when a run ends. A
+run that ends in any way frees its slot. A run that ends `failed`, `error`, `cancelled`, `lost` or `drifted`, or a start
+that the door refuses, is a failure of its item, and never the Pool's `error`: the run is not the Pool's child. A cancel
+of the Pool never cancels its runs (ADR-0071), and `customize(pool, { agents })` reaches nothing in them
+([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)). The Pool spawns its slot with the item's id as
+the spawn id, and the Effect sends that id as the key, not its ledger row id. The run's `dispatchedBy` gains `key`, and,
+for a carried item, `hook: { name, delivery, onBehalfOf? }`, so `jr2 status` prints which Pool, key and delivery started
+it. Neither is on the open band (ADR-0014): a key is the workflow's data. A run that a read claimed names no delivery:
+the Pool's feed says why an item did or did not start, with a `pool` mark for each start (`started`), each end
+(`settled`, with the run's status, `start-refused` or `dispatch-error`), each held item that a hand-over drops
+(`carry-refused`) and each item of a read that has no id (`skipped`). A `wait` that the slot's timeout ends while the
+run is still live (`status: "live"`) is sent again under its key, so the wait follows the run and `cap` still counts it.
+
+**`standing: true` makes a Pool of runs stand.** It is two things:
+
+- **Parking.** A standing Pool never ends by itself. It has no `drained` and no `deadlocked` end, no output and no
+  `failures` mode. When it has no work it waits for a delivery, a `reread` or its `pollEvery`. An item that ends is a
+  `settled` mark on the feed, with the run's status.
+- **The standing run.** jr2 keeps one live run of the Workflow under the current Assembly
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). Nobody starts it: jr2
+  starts it at boot and at the publish that adds it, and `jr2 run` of it is refused, except to resume it (below). A
+  dispatch to a standing Workflow is refused 409. jr2 **hands it over** to a new run at every publish, at drift, after
+  `error` (with back-off), and when its blob passes its bound. At every publish, because the Assembly is one hash and a
+  handler has no stamp of its own. The bound is 500 items taken or one day: each item taken is a dispatch, which keeps a
+  row in the Effect ledger for the run's life (ADR-0067), about 217 bytes, so 500 is about 110 KB a save. The bound
+  counts the items that the run took, not the keys that a hand-over carried to it: each carried key is sent again, so a
+  count of the ledger's rows would hand a run with a `cap` at the bound over again at once. **A run at the bound in
+  which no item that it took itself started a run is handed over as a run that ended `error` is**: after the back-off,
+  and it counts in the streak below. An item that ends with no run (`start-refused`, `dispatch-error`, `unreachable`,
+  `unknown`) is known only for its run's life (above), so a backlog of as many such items as the bound fills the bound
+  again in each new run. A hand-over at once would then loop with no pause and no end, and would hold the event loop.
+  jr2 ends that run `done`, with no `handedOverTo`, and starts the next run after the back-off. A run in which one item
+  that it took started a run (or found its run under its key) is handed over at once, and the count starts again. A
+  carried key does not count: the hand-over sends it again and it finds a run that an earlier run started, so a callee
+  run that lives for hours would hide the loop for as long as it lives. While each item that the run took is still in
+  flight, jr2 does not yet know, so it waits for the save of the first answer. The back-off before the hand-over after
+  the `n`-th counted run in a row is 1 s, 4 s, then 16 s. The numbers are not measured. The hand-over carries the held
+  items, parsed by the new Assembly's `item` schema (an item that does not parse is dropped, with a `carry-refused`
+  mark), and the active keys: the new run sends each one again with `wait: true`, the door answers `existing`, and the
+  wait follows that run, so `cap` still counts it. A held item is mapped by the new `itemInput`. A hand-over ends the
+  old run `done`, and its record carries `handedOverTo: <new run id>`: a standing Pool has no output, so its stint is
+  done. The start of the new run and the end of the old one are one synchronous step. A delivery that a Source hears
+  across that step (its key lookup awaits the store) goes on to the new run's Source, so the door never claims a
+  delivery that no run holds. jr2 keeps the **head** of each standing Workflow in a table of the store: its newest run,
+  when that run started, how many counted runs in a row ended, and why it is paused. jr2 writes the head in the same
+  step as the start. The sweep of rows older than `runs.retain`
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)) never deletes the run that a head
+  names, so a paused Pool keeps its held items for as long as it is paused. A Workflow that a publish removes, or that
+  no longer stands, gets no hand-over: its live run holds its Assembly and runs on, as any run does (ADR-0069), until a
+  person cancels it. A standing run has no Caller: its record's `startedBy` is `{ kind: "jr2", why }`, with `why` one of
+  `boot`, `publish`, `hand-over` and `resume`
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)).
+- **A cancel is a pause.** `jr2 send <run> --event CANCEL` of a standing run ends that run `cancelled`
+  ([ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)) and pauses its Workflow: jr2 starts it again at no boot and no
+  publish until `jr2 run <workflow>` resumes it. `jr2 up` and `jr2 status` print the Pool as paused, with the number of
+  items it holds. They read it from `GET /assembly` and from the answer of the publish, whose `standing` list gives each
+  standing Workflow's state (`live`, `paused` or `waiting`), its run and its count of held items. It holds no key and no
+  item, so it is on the open band with the held Assemblies ([ADR-0014](0014-observation-is-open-run-state-is-not.md)). A
+  paused Pool has no live run: its held items and active keys stay in the blob of the cancelled run. A resume is a
+  hand-over from that run, so the new run takes them and claims under `cap`, and a read Source reads again. The new run
+  records the Caller of the `jr2 run` that resumed it as `resumedBy`. On the wire the resume is
+  `POST /workflows/<workflow>/runs`, which answers `201 { runId, instanceId, resumed: true }`, and 409 while the
+  Workflow is live or waits out a back-off. `jr2 run <workflow> --drop-held` (`?drop-held=true`) resumes with no held
+  item, so a person can remove a poison item or a queue that they paused on purpose; a read Source then finds again what
+  is still true. A delivery to a paused Pool gets `paused`, and nothing is held, so a push Source loses it and a read
+  Source finds it at the resume. A delivery to a standing Pool in its back-off (no live run, and not paused) makes the
+  door answer 503 (ADR-0011), so the service sends it again. **One rule counts a run in the streak**, for each end that
+  hands over after the back-off: `error`, `failed` (a `fail()` of the Machine,
+  [ADR-0073](0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md), which jr2 treats as
+  `error`) and the bound with no run started. A run in which an item that it took itself, not a carried key, started a
+  run starts the count again, and is handed over after 1 s. Any other run counts. So a run that took only items that the
+  callee's door refused, and then ended `error`, counts. After 3 hand-overs from counted runs in a row, jr2 pauses the
+  Pool when the next counted run ends, so a poison item, or a backlog that the callee's door refuses, cannot loop
+  without end. The pause says why: `errors` when the last run ended `error` or `failed`, and `bound` when it took its
+  bound; `jr2 status` and the Orchestrator's log line name that end. The 3 is not measured. The Pool's context keeps the
+  keys that the hand-over carried, so jr2 tells them from the items that the run took.
+
+**What the load walk refuses**, with its fix in the message:
+
+- `standing: true` on a Pool of child Machines: a child cannot be handed over.
+- `standing: true` on a Pool that is not the top Machine of its Workflow: jr2 keeps one run for each standing Workflow,
+  so the Workflow is the Pool. The fix is to move the Pool to its own file in `workflows/`.
+- A Pool of runs that does not stand. A batch of runs (a Pool of runs that a Caller starts and that ends) is not offered
+  now: its `itemId` is a key that lives for `runs.retain` past the run, so a second batch in that time does no work. To
+  add it later does not break anything.
+- A Pool of runs whose `dispatch` slot has no `wait: true`, or has a `target`: a foreign worker is not designed.
+- A Pool of runs with no `cap`. The author must choose it; a Pool of child Machines keeps its default of 1.
+- A push Source on a Pool that ends when it drains, which would end `drained` at once. The types refuse it too.
+- A worker that is a bare Workflow name.
+
+**What `jr2 up` prints and warns.** For each standing Pool, it prints the chain from each Hook that reaches it to the
+callee: `sentry → alerts → triage`. It warns when two standing Pools dispatch to one Workflow: `cap` is per Pool, so one
+issue with two labels can take a slot in each, and the caps add.
+
+**The callee must end the level.** A read Source re-reads a level, such as "the open issues with the label `jr2`". When
+the callee's run ends and the label stays, the key keeps the item from a second run while the run's row lives.
+`runs.retain` after the run ended (30 days by default), the row is swept, and the next read starts the item again. So
+the callee (or the person) removes the label. A drifted callee holds its key for `runs.retain`, and nothing starts that
+item again without a person.
 
 ## 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):
+Forced by parking-is-retention (ADR-0012) plus workflows whose children park on gates (escalation, human review). It
+holds for a Pool that does not stand:
 
 - **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
@@ -69,3 +253,33 @@ is a correct answer. The default is `"fail"` because `done` means that the work
 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.
+
+## Tests
+
+The default e2e tier (`features/standing-pool.feature`) and `pool-sources.test.ts` prove the standing Pool of runs: a
+push Source, the held items and `hold`, `cap`, `reread`, the latch and merged reads, a restart and a hand-over with no
+item lost or started twice, a hand-over across a changed callee door, and the key per Workflow. They read with a
+promise, because the default tier has no Instance Effector. The `@kind` tier proves a read through an `http` Effect.
+
+## Considered options
+
+- **An Intake**: a kit-shipped `intake({ routes })`, each `route({ start, input, hooks, look, cap })`, that jr2 keeps as
+  a **Standing Workflow**. Rejected: it needs three concepts (Intake, route, Start) and two GLOSSARY terms, and reuses
+  nothing that an author knows about a Pool, though it is a Pool inside. It writes the mapping from a delivery to a
+  start twice, once in the handler and once in the look, and its look starts an issue that lost its label while it
+  waited. One intake run serves every route, so its fault stops every route; a standing Pool for each Source keeps a
+  fault in one Source.
+- **A direct door**: a Hook that starts a run itself (`door()`, or a Listener's `startOn(machine, kind, …)`). Rejected:
+  it is the smallest form for one alert, but it cannot grow. A cap, a read of a level, a queue and an answer after a
+  start are each state over time, which a door does not have, and each needs a standing Machine. So an Instance gets two
+  ways to start a run. It also makes a Hook more than a door that checks and decides nothing (ADR-0078).
+- **A router that the author writes**: a hand-written standing Machine with `dispatch({ key })`, regions and a table of
+  runs in flight. Rejected: about 90 lines of mechanism for 25 lines of intent. When a judge wrote one alert's router
+  from it, the result had no hand-over and no routes for a child: its table went stale at each publish, and the first
+  refused start faulted it. A run holds its Assembly, so a router keeps its old handlers after a publish; a router that
+  ends `error` has no open Gate, so each later delivery reaches nothing; and a Kit bump drifts it and loses its backlog.
+- **Two factories over one Source port**: `pool()` for children and batches, and a second factory for standing Pools of
+  runs. Rejected: the split removes three rows from the table of differences, and costs a GLOSSARY term for the second
+  factory, which is the Intake again.
+- **A batch Pool of runs now.** Rejected for now, as above: no scenario needs it, and its key makes a second batch
+  within `runs.retain` do nothing. It adds later without a break.

package/docs/reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md

@@ -7,9 +7,9 @@ hands: the [ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-
 Submission — forget it and the Agent is silently mute, the same footgun class ADR-0016 removed from workflows), the
 ADR-0004/0012 sandbox geography (working tools execute in the Harness container against `/work`), the dependency pin
 that must match the Orchestrator's wire, and the image contracts the operator imposes (numeric uid, `:8080` = Ready, git
-present). The only content a user genuinely owns is the persona: model + instructions (+ someday tools/skills).
-GLOSSARY.md already promised the split — an Agent is a definition jr2 maps into the Harness, and the Instance folder
-holds only what a Machine cannot carry (ADR-0049/0050: the definition is one of the things it can).
+present). The only content a user genuinely owns is the Agent's definition: model + instructions, and the MCP servers it
+uses. GLOSSARY.md already promised the split — an Agent is a definition jr2 maps into the Harness, and the Instance
+folder holds only what a Machine cannot carry (ADR-0049/0050: the definition is one of the things it can).
 
 ## Decision
 
@@ -53,6 +53,12 @@ holds only what a Machine cannot carry (ADR-0049/0050: the definition is one of
   Stand-in. `harness.provider.apiKey` is one implicitly: the held secret `JR2_PROVIDER_API_KEY`, bound to `baseUrl`'s
   host, so it leaves the `jr2-harness-env` Secret and `baseUrl` must be `https://` when a key is set. A known model key
   in `harness.env`, or in an `envFrom` Secret, is refused.
+- **MCP is the one extension contract for tools.** Beyond its Working tools and its Menu, an Agent gets tools only from
+  the MCP servers that its definition names (`mcp`), and jr2 has no tool API of its own
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). The
+  definition names a server by the name that the `mcp` block of `jr2.config.ts` gives it, never by its url or its
+  secret: as `harness` declares reach for models, the `mcp` block declares reach for tools, and the definition makes the
+  choice.
 - **A catalog provider can be moved to a gateway, and stays a catalog provider.** `harness.catalog.<id>.baseUrl`
   replaces the base URL of every model of one pi catalog provider — a LiteLLM gateway in front of Bedrock, for
   `anthropic/…`. The catalog keeps its limits, cost and thinking levels; only the endpoint moves. It is reach, not a
@@ -99,11 +105,13 @@ Definitions keep converge-time safety; overrides pay the later check for the fle
 
 ## Consequences
 
-- The definition contract is data-only: what an Agent may do to the Workspace is part of it (`access`, ADR-0028); custom
-  tools/skills/subagents have no seat yet. When someone needs them, the contract grows deliberately — there is no eject
-  hatch to a foreign harness project (ADR-0027 deleted it).
+- The definition contract is data-only: what an Agent may do to the Workspace is part of it (`access`, ADR-0028), and so
+  are the MCP servers it uses (ADR-0079); an author's own tool is an MCP server. Skills and subagents have no seat yet.
+  When someone needs them, the contract grows deliberately — there is no eject hatch to a foreign harness project
+  (ADR-0027 deleted it).
 - Because definitions are plain data, stock ones compose with no API: a Machine carries `agent(coder)`, and a consumer
-  retunes it with `customize(machine, { agents: { coder: { model: "…" } } })` (ADR-0049, ADR-0009).
+  retunes it with `customize(machine, { agents: { coder: { model: "…" } } })` (ADR-0049, ADR-0009), or rebinds its
+  servers with `{ mcp: [...] }` in the same place.
 - An invalid definition fails at admission, loudly, naming the slot: a model no registry resolves, a malformed field. A
   Machine with no Agent slots is valid — a `workspace()` body parking a Sandbox (ADR-0012) invokes none. Readiness is
   binding `:8080`, with no boot build ahead of it (ADR-0027).

package/docs/reference/decisions/0019-one-converging-command-against-the-current-context.md

@@ -66,11 +66,12 @@ loudly narrated, safe to re-run:
   It is an ordinary converge failure: it names each node whose agent reports none, the probe's reason, and the fix (keep
   the node out with `sandbox.nodeSelector` or a taint, ADR-0052, or enable Landlock); a run after the fix converges
   ([ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)).
-- **Provider preflight**: `up` checks each provider that a carried model names. It checks from inside the cluster, with
-  one trivial tool-call completion. An endpoint that the pods cannot reach, a wrong or missing key, or a vLLM without
-  `--enable-auto-tool-choice` then fails at converge time, not as `agent.fault` in a run. Reachability is the user's
-  concern (`localhost` never works from a pod; a LAN address does on kind). The check must take the path that the
-  Harness takes. If it does not, a pass means nothing.
+- **Provider preflight**: `up` checks each provider that a carried model names, and the tool list of each remote MCP
+  server that an Agent names (below). It checks from inside the cluster, with one trivial tool-call completion for a
+  model. An endpoint that the pods cannot reach, a wrong or missing key, or a vLLM without `--enable-auto-tool-choice`
+  then fails at converge time, not as `agent.fault` in a run. Reachability is the user's concern (`localhost` never
+  works from a pod; a LAN address does on kind). The check must take the path that the Harness takes. If it does not, a
+  pass means nothing.
   - **One path for every provider.** `up` checks the custom provider (`harness.provider`, ADR-0018) and a provider of
     pi's catalog (for example `anthropic/…`) in the same way. A key of either is a held secret, and only a Custodian can
     use it ([ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)). So no key enters a pod
@@ -106,8 +107,8 @@ loudly narrated, safe to re-run:
       model runs where the Instance Harness runs.
     - The held set: a pod that holds a secret sends its HTTPS through its Custodian, and a tunnel carries a host that no
       secret is bound to. A pod that holds no secret sends its HTTPS direct. So the check pod holds the held set of the
-      first pod of its class, and the keys that the other pods of the class hold. A class that holds nothing gets a
-      check pod that holds nothing.
+      first pod of its class, and the keys and the MCP server secrets that the other pods of the class hold. A class
+      that holds nothing gets a check pod that holds nothing.
 
     When no pod of the class holds a key of the provider, the check pod holds none. Then pi refuses the call
     (`not configured`), and the converge fails. A signing credential in `harness.env` reaches the check pod, as it
@@ -115,6 +116,16 @@ loudly narrated, safe to re-run:
     knows, and for which jr2 knows no key name, is checked with no held key, as a Turn runs it. The check pod has the
     priority class of the Sandbox tier, as the Harness pods have (ADR-0060).
 
+  - **MCP servers.** The check pod also checks each remote MCP server that an Agent of its class names
+    ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). It
+    reads the server's `tools/list` through its Custodian, with the Stand-in of the server's secret, as a Turn reads it.
+    An allowlisted tool name that the list does not have fails the converge, and the result names the server and the
+    tool. A server that refuses the request (a 401 or a 403: a wrong or expired token) fails the converge, as a model
+    key that the provider refuses does. A server that does not answer is a warning: the first Turn of a conversation
+    fails with a named error when the server does not answer then. A stdio server is not checked: it runs as Workspace
+    code in the Sandbox, and the check pod runs none. Each server has 60 s for its whole listing, after the models. Two
+    literals set it, `PREFLIGHT_MCP_BUDGET_SECONDS` in `preflight-line.ts` and `CHECK_MCP_SECONDS` in `up.ts`, and a
+    test holds them equal. The pod writes the list, and `up` compares it with the allowlists.
   - **The request.** The check's request shares these with a Turn's: the model, its api, its endpoint and key, the
     completion limit (what pi-ai sends for a Turn), the retries, no forced tool, and the level of a definition with no
     `thinkingLevel` (`off`: no `reasoning` is sent). It does not share these: it has no system prompt, one tool, no
@@ -195,12 +206,12 @@ loudly narrated, safe to re-run:
 
     It never deletes the objects of another Instance.
 
-  - **Skipping it.** `jr2 up --skip-provider-preflight` runs no check pod. A check can fail when the model works, for
-    example when a model loads for longer than the check waits. That fault must not stop every converge until jr2 is
-    fixed. The skip is never silent: `up` writes one warning line, which names each model that it did not check. `up`
-    still deletes the leftovers of earlier runs, because their Secrets can hold a key. The flag has no config key,
-    because no flag of `up` has one (CI gives `--yes` as a flag). A model that does not work then fails in a run, as
-    `agent.fault`.
+  - **Skipping it.** `jr2 up --skip-provider-preflight` runs no check pod, so it checks no model and no MCP server's
+    tool list. A check can fail when the model works, for example when a model loads for longer than the check waits.
+    That fault must not stop every converge until jr2 is fixed. The skip is never silent: `up` writes one warning line,
+    which names each model and each MCP server that it did not check. `up` still deletes the leftovers of earlier runs,
+    because their Secrets can hold a key. The flag has no config key, because no flag of `up` has one (CI gives `--yes`
+    as a flag). A model that does not work then fails in a run, as `agent.fault`.
   - **A limit.** The check pod has labels of its own. It does not get the labels of a Harness pod: the Instance Harness
     Service selects its pods by label, and would send Turns to the check pod. So a NetworkPolicy that selects Harness
     pods by label does not select the check pod. When such a policy closes the egress of the Harness pods, the check can
@@ -229,8 +240,9 @@ takes the operator too.
   instance error with "not deployed here — right context?". This is the guardrail against silently pointing at the wrong
   cluster, without a state file that can itself go stale.
 - **CLI transport**: run-verbs port-forward the Orchestrator Service via the kube API for the duration of the command
-  and read the Instance token from its Secret — kube RBAC is the real gate. `--url`/`JR2_URL` (+ token env) is the
-  escape hatch for ingress-exposed instances and callers without cluster creds.
+  and read the Instance token from its Secret — kube RBAC is the real gate. `--url`/`JR2_URL` (+ token env, any Caller's
+  credential, [ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)) is the escape
+  hatch for ingress-exposed instances and callers without cluster creds.
 - **A dead ADDRESS and an absent IDENTITY are two faults, and resolution names which.** They share a verb and a context
   but not a fix: one is the network, the other is `jr2 up`. A cluster that answered and holds no instance Secret is "not
   deployed here — right context?"; a cluster that could not answer at all is "cannot reach the cluster — context X: …",
@@ -274,9 +286,11 @@ from env.
 
 ## Consequences
 
-- The everyday story is two commands ever: `jr2 init`, `jr2 up`. The full CLI: `init`, `up`, `down`, `gc` (ADR-0039),
-  `run`, `runs`, `status`, `logs`, `send`, `kit push` (ADR-0044), plus the workspace verbs `ls`, `ssh`, `rm` (ADR-0009;
-  decided, not yet in the binary).
+- The everyday story is two commands ever: `jr2 init`, `jr2 up`. The rest of the CLI is in ADR-0009's table, and the
+  workspace verbs `workspace ls|shell|forward|rm` are among them.
+- **The workspace verbs are not run-verbs.** They address the Sandbox CRs of the current context with its kube
+  credentials alone: no port-forward to the Orchestrator, no Instance token and no Caller scope. So they work when the
+  Orchestrator is down, and kube RBAC on the Sandbox CRs and their pods is the whole gate.
 - **Simplification must not surprise**: `up` prompts exactly when meeting a cluster that isn't yet home, and run-verbs
   print the context they're talking to — the ambient-context magic stays visible.
 - The snapshot store (sqlite) moves onto a PVC in the instance's namespace; `.jr2/` shrinks to scratch.

package/docs/reference/decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md

@@ -57,6 +57,19 @@ end. And a restarted Harness answered a `continue` with no memory of the convers
   attached pod. Its lifetime is the state's lifetime, which xstate already manages: it re-invokes on snapshot restore,
   so restore-reconcile stops being a special case and becomes the first tick of the normal loop; and it stops on every
   exit — body final, run stopped, run faulted.
+- **The Lease marks its hold on the CR.** The CR's first write sets the annotation `jr2.dev/hold: held`, and each
+  renewal writes it again. When the Lease stops for the body's final state, a fault, a cancel or a parent that leaves
+  the Workspace's state, it sets `jr2.dev/hold: released` and renews no more. A defect that a parent catches does not
+  stop the Lease, because xstate stops no child of a Machine that ended in error: at its next renewal the Lease sees
+  that its Workspace is over, and sets `released` then. A Lease does not set `released` on a name that a live Workspace
+  of the run holds: a parent that catches the defect can invoke the same Machine again, and the new Workspace gets the
+  same Sandbox name and a Lease of its own. A step of the wrapper from one state to the next writes nothing: the next
+  state has a Lease of its own. A park (`RunHost.stop`, [ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)) and a
+  process shutdown write nothing, so a crash keeps the mark `held` and the restored run's Lease writes it again. A
+  restore that ends a run `drifted` or `lost` without hosting it starts no Lease, so the Orchestrator sets `released` on
+  each CR with that run's `jr2.dev/run` label. So `jr2 workspace rm` tells a held Sandbox from a free one with the
+  cluster alone ([ADR-0009](0009-cli-and-instance-interface.md)): the keepalive's age cannot tell it, because a renewal
+  can be late by more than one interval and a few missed renewals are survivable.
 
 That last point deletes machinery rather than adding it. Three mechanisms with three different owners and lifetimes —
 the process-global heartbeat map, the one-shot probe, and `release(runId)` (which label-queried the cluster to stop
@@ -98,4 +111,4 @@ behavior `release()` was written to produce is emergent.
   independently. This falls out of invoking it beside the body rather than owning it at the host.
 - `SandboxPort` has no optional method: `renew` is a write, `continuity` is a subscription to the watch, and
   `memoryFault` (ADR-0061) answers undefined from a backend that cannot see the container. The `jr2.dev/run` label
-  survives for `jr2 ls` and as the watch's selector, no longer load-bearing for lease bookkeeping.
+  survives for the `jr2 workspace` verbs and as the watch's selector, no longer load-bearing for lease bookkeeping.

package/docs/reference/decisions/0022-observation-is-a-level-triggered-feed.md

@@ -34,8 +34,8 @@ can get away with fetching once, because a person can press a button; an API can
   so there is no gap to detect and no cursor to resume from. Same reconciliation idiom as the Lease (ADR-0021) and
   `jr2 up` (ADR-0019): say the whole truth, repeatedly, and let the reader converge.
 - **Two granularities, one vocabulary.** The per-run feed stays — tracking exactly one run is a legitimate thing to
-  want, and it is what `jr2 run` and `jr2 logs -f` already do. Every run-scoped frame carries `runId` even where the
-  route makes it redundant, so one parser serves both.
+  want, and it is what `jr2 run` and `jr2 watch` do. Every run-scoped frame carries `runId` even where the route makes
+  it redundant, so one parser serves both.
 - **`gone` is a fact, not an inference.** A run can leave the live set _without_ a terminal status: `stop()`
   deliberately leaves the stored status `"live"` so a later `restore()` picks the run back up. A client watching for
   `status === "done"` would show a stopped run as live forever, so departure is stated outright.
@@ -48,7 +48,7 @@ can get away with fetching once, because a person can press a button; an API can
   which is why it is wired to the handler's exit.
 - **A settled run is the client's own memory.** A run appears in the page's `settled` list iff _this page_ watched it
   leave. After a hard reload they are gone, and that is correct rather than a defect: serving a finished run's state to
-  an unauthenticated reader is a read-through, which stays behind the Instance token on `/runs/:id` (ADR-0014).
+  an unauthenticated reader is a read-through, which stays behind the `read` scope on `/runs/:id` (ADR-0014).
 - **`jr2 visualize` is deleted.** Its job was to find an orchestrator, forward a port, and open a browser. With the page
   now useful on its own, that is one `kubectl port-forward` the reader already knows how to run — and the command's
   ephemeral-fallback path was quietly forwarding to a _different_ instance than the deployed one. Its one unique piece
@@ -61,7 +61,7 @@ can get away with fetching once, because a person can press a button; an API can
   tick, and a reader that keeps up drains them before any ping judges it. Closing is safe because the feed is
   level-triggered: the client reconnects and receives the whole current truth, having missed no state — only activity
   (Emits, retries) that fell in the gap. A page reconnects with EventSource's own retry; the CLI (`jr2 run`,
-  `jr2 logs -f`) re-attaches any feed that ends before a terminal status, and never reads such an end as the run's —
+  `jr2 watch`) re-attaches any feed that ends before a terminal status, and never reads such an end as the run's —
   except `gone`: a run stopped before it settled (parked, ADR-0025) reads through as `active`, so its one-shot feed says
   `gone` after the status, and the CLI ends there instead of re-attaching in a loop. The server keeps no per-client
   queue and no slow-client accounting beyond counting the subscriber's writes (scaling review R10, 2026-09-30).