@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -1,4 +1,4 @@
-# Observation is open; run state and control need the Instance token
+# Observation is open; run state and control need a Caller's scope
 
 [ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md) minted two tokens and scoped them
 for **delivery** — a Sandbox token may deliver to its own agent registrations, an Instance token may deliver to gates.
@@ -16,20 +16,44 @@ Building `jr2 visualize` (the Machine renderer and its live run highlighting) fo
 
 ```
 open           /workflows, /workflows/:name/machine, /viz/*        structure
+               /console/config (the login's issuers, ADR-0032)     public values
                /workflows/:name/runs, …/runs/:runId/events         OBSERVATION (new)
 authenticated  /agents/:iid/*                                      the Agent's surface  [Sandbox token]
-instanceOnly   /runs, /runs/:id, /runs/:id/events (GET + POST)     run state + control  [Instance token]
-               POST /workflows/:name/runs                          starting a run (ADR-0058)
-               /runs/:id/gates/:gate/events                        gates (ADR-0011/0013)
+guarded        each route below, opened by one scope of a Caller   run state + control  [a Caller, ADR-0078]
 ```
 
-- **Run state and run control are the Instance token's alone.** `authenticated` accepts _any_ token we minted, so a
-  Sandbox token — the one credential that sits in a pod an Agent shares a network namespace with — could read **every**
-  run's context (other features' branches, ticket bodies, review verdicts, Harness endpoints) and **CANCEL any run**.
-  Neither is on the Agent's surface, no more than a gate is: ADR-0013 scopes that token to delivering into registrations
-  recorded against its _own_ Sandbox. This closes the same class of hole ADR-0013 closed for gates, on the routes it did
-  not name. The band is named for the credential it requires, not for a role — "operator" in this repo is the Kubernetes
-  operator (ADR-0001).
+- **Run state and run control are a Caller's, and each route needs one scope.** `authenticated` accepts _any_ token we
+  minted, so a Sandbox token — the one credential that sits in a pod an Agent shares a network namespace with — could
+  read **every** run's context (other features' branches, ticket bodies, review verdicts, Harness endpoints) and
+  **CANCEL any run**. Neither is on the Agent's surface, no more than a gate is: ADR-0013 scopes that token to
+  delivering into registrations recorded against its _own_ Sandbox. This closes the same class of hole ADR-0013 closed
+  for gates, on the routes it did not name. The guarded band takes only a Caller
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): a Sandbox token is never
+  one. Each route of the band needs one scope, checked against the Workflow of the run or the door that it addresses:
+
+  ```
+  start    POST /workflows/:name/runs, POST /workflows/:wrapper/charts/:name/runs
+  read     GET /runs (summaries of the runs of its Workflows, live and ended), GET /runs/:id (the whole status),
+           GET /runs/:id/events, GET /runs/:id/conversations[/:iid[/events]] (the kept conversations, ADR-0023)
+  answer   POST /runs/:id/gates/:gate/events, GET /gates (the open Gates it may answer), and the `gates` of GET /runs/:id
+  cancel   POST /runs/:id/events (CANCEL)
+  steer    POST /runs/:id/steering, GET /runs/:id/agents (the slot list { agent, open, steerable }, ADR-0002)
+  ```
+
+  `answer` alone opens a run's `gates` and their routing, and never its `context`: a person who answers a Gate reads the
+  Gate's `meta`, which the author wrote for that person. So `GET /runs/:id` gives `read` the status and `answer` the
+  `gates`; with `answer` alone the answer is the run's observation (below) and its `gates`. `GET /runs` leaves out the
+  runs of the Workflows that the Caller may not read; it refuses no run, and refuses only a Caller with no `read` scope
+  at all (ADR-0078). `answer` can name single Gates of a Workflow (ADR-0078). Then the gate POST refuses another Gate of
+  that Workflow, and `GET /gates` (its entries are ADR-0011's) and the `gates` of `GET /runs/:id` list only the Gates
+  that the Caller may answer. Neither gives the run's `context`. `GET /runs/resolve` answers ids to a Caller with any
+  scope, for the Workflows of its scopes. `GET /whoami` answers any Caller. A route that no scope names stays the
+  Instance token's: the runtime Chart routes (`PUT` and `DELETE /workflows/:wrapper/charts/:name`), `GET /repos`, a
+  Hook's log (`GET /hooks/:name`, which can hold a payload's fields and a handler's words), and the Instance-token door
+  on `/agents/:iid/*` (ADR-0013) except the conversation route, which takes only a control token
+  ([ADR-0023](0023-the-harness-prints-the-conversation.md)). `POST /hooks/:name` is outside the bands: the Hook's own
+  verifier authenticates it ([ADR-0011](0011-workflow-defined-events.md)). The band is named for what it checks, not for
+  a role — "operator" in this repo is the Kubernetes operator (ADR-0001).
 
 - **The observer gets a PROJECTION, not a credential.** `RunObservation` is
   `{ runId, workflow, status, value, children }` — identity, and where in the Machine the run is. What is absent is the
@@ -48,16 +72,15 @@ instanceOnly   /runs, /runs/:id, /runs/:id/events (GET + POST)     run state + c
 
 ## Considered options
 
-- **Give the page a token.** It would have to be the **Instance** token — gates, cancel, every run's context — handed to
-  whatever can load a URL. Putting it in `jr2.config.ts` (checked in) is worse still, and the token is minted per boot,
-  so the page would not have it anyway. Rejected: the visualizer needs to _see_ a run, and seeing is not a subset of the
-  credential that steers it. That mismatch is the whole reason a projection exists.
+- **Give the page a token.** It would be a credential — gates, cancel, every run's context — handed to whatever can load
+  a URL. Putting it in `jr2.config.ts` (checked in) is worse still, and the token is minted per boot, so the page would
+  not have it anyway. Rejected: the visualizer needs to _see_ a run, and seeing is not a subset of the credential that
+  steers it. That mismatch is the whole reason a projection exists.
 - **Keep `/runs*` on `authenticated` and filter in the handler.** Rejected: the guard would then depend on every future
   handler remembering to redact. The band is a middleware precisely so the default is refusal.
 - **A fourth "observer" token.** Rejected: it buys nothing today (the observation surface carries no secret) and costs a
   minting, distribution, and revocation story. If observation ever needs to be _private_ — a deployed jr2 Application on
-  a shared network — that is the ADR to write, and it is the same open question ADR-0013 left about authn for non-kube
-  callers.
+  a shared network — the guarded band and ADR-0078's scopes are already where it goes.
 
 ## Consequences
 
@@ -66,11 +89,11 @@ instanceOnly   /runs, /runs/:id, /runs/:id/events (GET + POST)     run state + c
   now **403**. The test pinned the hole.
 - **The API is a cluster Service** (ADR-0019), so "open" means open to whoever can reach it — in-cluster peers, a
   port-forward, or an ingress — deliberately, since what is open is structure plus lit states. Anything that would
-  embarrass a user if seen belongs behind `instanceOnly`, and that is where it is.
-- **The CLI is unaffected.** It holds the Instance token from the in-cluster Secret (ADR-0019) and reads the guarded
-  routes, as before.
-- **Open, inherited from ADR-0013:** what a deployed jr2 Application uses for human callers. Whatever it is, the band
-  split survives it — only the credential in the `instanceOnly` band changes.
+  embarrass a user if seen belongs in the guarded band, and that is where it is.
+- **The CLI is unaffected.** It holds the Instance token from the in-cluster Secret (ADR-0019), which has every scope,
+  and reads the guarded routes, as before.
+- **A Caller without kube credentials is ADR-0078's:** a named token, a JWT, or a browser login. The band split holds
+  for every Caller; what the guarded band checks is one scope for each route.
 
 - **One scoped exception, and it does not live on this surface at all (ADR-0023).** The Harness prints each Agent's
   conversation — prompts, assistant text, thinking, tool calls, and the answer jr2 gave each Menu pick — to container
@@ -87,9 +110,12 @@ instanceOnly   /runs, /runs/:id, /runs/:id/events (GET + POST)     run state + c
   form; then it prints there as the model read it. The answer also carries an Effect's output as the model read it: a
   `command` Effect's output prints there up to the bound, and a Held value an upstream echoed into that output prints
   with it (ADR-0023, ADR-0059). What remains, deliberately, is that on a shared cluster the population who can read an
-  Agent's reasoning, and what its picks answered, is whoever can read pod logs. If that becomes unacceptable, the fix is
-  the read-through ADR-0023 declined to build — `instanceOnly`, on this surface, where the band already works.
+  Agent's reasoning, and what its picks answered, is whoever can read pod logs. The Orchestrator's kept copy of the same
+  conversation is not part of the exception: it is on this surface, behind `read`, and `jr2 logs` and the Console read
+  it there (ADR-0023). Thus `read` opens the same residual of a pick's answer for as long as the run is kept
+  (`runs.retain`, ADR-0065). If the pod-log audience becomes unacceptable, the print is what to turn off, and the record
+  stays.
 
-Evidence: `packages/orchestrator/src/http.ts` (the three middlewares), `run-host.ts` (`observe` / `RunObservation` /
-`RunChild`), `test/auth.test.ts` (the boundary), `test/http-viz.test.ts` (a planted secret never reaches the feed, at
-any depth of the child tree).
+Evidence: `packages/orchestrator/src/http.ts` (the middlewares), `run-host.ts` (`observe` / `RunObservation` /
+`RunChild`), `test/auth.test.ts` (the boundary), `test/callers.test.ts` (each scope on its routes),
+`test/http-viz.test.ts` (a planted secret never reaches the feed, at any depth of the child tree).

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

@@ -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                                         |
 | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
@@ -143,8 +147,14 @@ sends there, and every case with the Agent's state at Rest.
 **Load checks on modes and audience.** `createMachine` refuses a registered event that no state handles: it is in no
 derived set, so it is on no Menu and no Gate. It refuses a parallel region below a state that invokes an Agent — the
 Agent's state itself being parallel included, since its regions are below it: the shape is reserved for picks the Agent
-does not wait for, which jr2 does not build, and background work goes above the Agent's state. It warns — the Machine
-stays legal; the doc carries the warning, `jr2 up` prints it and the Console shows it with the seats — about a mode that
+does not wait for, which jr2 does not build, and background work goes above the Agent's state. It refuses one Agent slot
+invoked by two states that can be active together — two parallel regions, one state inside the other, or one state
+twice: a slot is one Agent of the Machine, so its two Turns would have one sender, which `sentBy` cannot tell apart, and
+one conversation, which `continue` cannot give to both. Two Agents at once are two slots (one definition can fill both),
+a child Machine in each region, or a Pool ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
+jr2 refuses this shape and does not support it as a special case, because jr2 can remove a refusal later without
+breaking a Machine, but a refusal that it adds later breaks each Machine that loads now. It warns — the Machine stays
+legal; the doc carries the warning, `jr2 up` prints it and the Console shows it with the seats — about a mode that
 nothing enters (not initial, and no state the Machine can enter has a transition into it or a state inside it — so
 neither the mode's own `initial` nor its transition into itself counts: its picks are on the Menu and never allowed; a
 transition into a history state enters that history state's default target, shallow or deep, or its parent's initial

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

@@ -21,7 +21,7 @@ restore re-attaches to a Submission whose model is already fixed server-side and
 `agentRun` walks `self._parent` to the nearest registered ancestor. Invoked-actor registration (not an entry action) is
 what makes this restore-safe: invoked actors restart on snapshot restore, entry actions do not. Not under a workspace →
 fail loudly, unless input carries an explicit `endpoint` (the dev-stub, workspace-less path). Body-facing workspace
-handles are `{ repos, branch }` ([ADR-0012](0012-workspace-wrapper-machine.md)).
+handles are `{ repos }`: each is a Repo Slot's folder ([ADR-0012](0012-workspace-wrapper-machine.md)).
 
 **[ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)'s token scoping survives and
 strengthens**: the registration records the Sandbox resolved from the enclosing wrapper — the same deterministic
@@ -108,12 +108,14 @@ modes — `continue` governs only what a _new invocation_ means. The author name
 conversation's identity is already on the page. (This corrects the jr-parity exercise's "same iid = jr's resume
 machinery, free" — an inversion of jr's actual semantics.)
 
-Two live invocations of one continued iid — parallel states — are refused at the registration table: one live surface
-per address. A Submission that arrives behind a live one on the Harness queues: prompts for one instance enter one
-per-instance queue in admission order, and a Submission is promoted only when it is the first unsettled one for its
-conversation (ADR-0027 states this as jr2's own semantics). A queued prompt waits behind work that may never finish,
-which is why [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) both ends the turn and orders the
-abort ahead of the next `send`.
+Two live invocations of one continued iid are refused: one live surface per address. The load walk refuses the shape
+that makes them, one Agent slot in two states that can be active together
+([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)), and the registration table refuses a second registration
+of one address as a second guard. A Submission that arrives behind a live one on the Harness queues: prompts for one
+instance enter one per-instance queue in admission order, and a Submission is promoted only when it is the first
+unsettled one for its conversation (ADR-0027 states this as jr2's own semantics). A queued prompt waits behind work that
+may never finish, which is why [ADR-0024](0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md) both ends the
+turn and orders the abort ahead of the next `send`.
 
 The minting doctrine — addresses are computed by jr2, never by the workflow — covers gate ids too: a gate with no
 authored id derives one from its actor path below the run root, through the same walk `mintIid` uses (`actorPath` in

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

@@ -9,33 +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) → item | null`, plus an optional `wake` event def (webhook /
-`jr2 send` push seam) and `pollEvery` (the set mutates underneath us) — a queue, a generator, or a re-queried set. tk's
-claim actor is one adapter; GLOSSARY.md's **Work Source** reframes as _the Source adapter for tickets_, and the
-Ready-set doctrine (re-query, never materialize) survives as that adapter's semantics, not the primitive's.
+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
@@ -67,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).