@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0011-workflow-defined-events.md

@@ -58,7 +58,7 @@ lifecycle stay implemented once, in the registration table.
 
 ## External side: the same primitive over HTTP (`gate`), and each gate is a resource
 
-`gate` is the symmetric actor for **every non-agent caller** — humans (`jr2 send`, a UI), webhook translators, CI, other
+`gate` is the symmetric actor for **every non-agent caller** — humans (`jr2 send`, the Console), a Hook, CI, other
 systems. "Human" is policy, not mechanism, so the actor is not named for one caller. Each invocation is an addressable
 **gate**: input is `{ gate?, meta? }` — `gate` an optional authored id (the id is derived when absent — below), `meta`
 serializable caller/integration context (PR URL, title); its accepted set derives from the gated state's transitions,
@@ -72,11 +72,29 @@ scopes event resolution), so `gate: "F-12"` in two concurrent runs cannot collid
 Gate-as-resource is forced by concurrency: several children park simultaneously (three features in `humanReview` is the
 _normal_ case), all accepting `approve` — a run-level POST is ambiguous. And every real external surface already thinks
 in gates: a CLI listing shows pending decisions and acts on one; a UI inbox renders one card per gate (schemas drive the
-forms, `meta` drives the copy); a forge webhook translator finds its gate by matching `meta` (e.g. `prUrl`), which is
-why `meta` exists. Generalizing beyond humans also closes a hole hard-coded event types left: a push seam like "a
-work-source webhook wakes discovery" is just an idle state holding a gate accepting `work_ready` (the `wake` seam of
-ADR-0017). Two obvious later additions, both deferred: a cross-run inbox (`GET /gates`), and CLI segment-matching over
-derived gate ids (`--gate F-12` resolving an unambiguous segment, git-style like run-id prefixes).
+forms, `meta` drives the copy); a hooked Gate's own handler matches a forge's delivery against its `meta` (e.g. `pr`,
+below), which is why `meta` exists. Generalizing beyond humans also closes a hole hard-coded event types left: a push
+seam like "a Hook brings an item" is a Pool's `source` Gate ([ADR-0017](0017-pool-over-a-source-port.md)). The cross-run
+inbox is `GET /gates`: the open Gates of every live run that the Caller may answer, oldest first, with a `workflow`
+filter, each entry `{ runId, workflow, gate, path, accepts, acceptsNow, meta, openedAt, hook? }` (`hook` names the Hook
+kinds that the Gate hears, when it hears one) and never the run's `context`
+([ADR-0014](0014-observation-is-open-run-state-is-not.md)). A Gate that takes no event from a Caller, as a Pool's
+`source` Gate that hears only Hooks, is not in it: no person can answer it. `jr2 gates [--workflow]` prints it, and the
+Console's Gate cards read it. A stream of it is a later addition. CLI segment-matching over derived gate ids
+(`--gate F-12` resolving an unambiguous segment, git-style like run-id prefixes) is deferred.
+
+**The `answer` scope can name single Gates**, in the form of
+[ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md). It names a Gate by its invoke
+id, the one static name a Gate has in the Machine that invokes it, and the id that its events carry as their sender
+(below): the invoke `id` that the author wrote, or else the key path of its gated state below the root of that Machine
+(`body.humanReview`), with `.0`, `.1` after it when that state invokes more than one unnamed Gate. So `body.humanReview`
+names that Gate in every child of a Pool, and two gated states with one key at two paths of one Machine have two names.
+The name is not unique across the Workflow: a Workflow composes Machines by invoke
+([ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)), and two composed Machines that each gate a
+state `approve` give that name to two Gates. One per-Gate name covers every Gate of the Workflow that has that invoke
+id, and `jr2 up` refuses a per-Gate name that matches Gates in more than one Machine of the Workflow, so a scope never
+opens a Gate that its author did not see; the author writes an invoke `id` on one of them to tell them apart. It is not
+the caller-facing gate id, which is different in each child and which a workflow may compute.
 
 **The gate id is derived; authoring one is the exception.** Absent an authored `gate`, the id is the gate actor's own
 path below the run root, and jr2Setup's menu-derivation walk names an unnamed gate invoke with its state key path so the
@@ -102,15 +120,202 @@ vocabulary — workflows speak only `defineEvent` / `agentRun` / `gate`.
 
 **Every delivered event carries its sender.** The table writes `sender: { party: "agent" | "gate", id }` on each event
 it delivers, after the schema parse and from the registration alone: `id` is the Agent's slot, or the Gate's invoke id
-(static in the Machine, the same after a restore — not the caller-facing gate id, which a workflow may compute). It is
-plain data on the event, so it rides the mailbox, a delayed event the run host persists beside the snapshot, and a
-restore; a restored registration writes it again from the persisted input and the invoke id. The Machine's own events
-(`raise`, `sendTo` itself) carry none. `defineEvent` refuses an input that declares `sender`, and both surfaces refuse a
-body that carries it (ADR-0013): no caller and no def can write it. What an author does with it is ADR-0015's.
+(static in the Machine, the same after a restore — not the caller-facing gate id, which a workflow may compute). A
+Gate's event also carries the **Caller** that answered it
+([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): `via`, `name` and
+`onBehalfOf`, with `checked` naming the fields that jr2 verified. `via` and `name` are always checked, because an
+authenticator made them; `onBehalfOf` is checked only for a Hook, whose signature covers the payload it comes from. The
+run records the same Caller as the answer's `answeredBy`. An event that a Gate's `look` gives (below) has the Gate as
+its Sender and no Caller. The Sender is plain data on the event, so it rides the mailbox, a delayed event the run host
+persists beside the snapshot, and a restore; a restored registration writes it again from the persisted input and the
+invoke id. The Machine's own events (`raise`, `sendTo` itself) carry none. `defineEvent` refuses an input that declares
+`sender`, and both surfaces refuse a body that carries it (ADR-0013): no caller and no def can write it. What an author
+does with it is ADR-0015's.
 
 `CANCEL` stays reserved as the run-level infra interrupt. jr's "exit 3 and let the human drive the bash script" becomes
 "park in a durable state that advertises its human surface."
 
+## A Gate hears a Hook, and looks before it waits
+
+A Hook ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)) is a door for one
+outside service. Its delivery is not an event of any Machine: a Gate makes one of it, or ignores it. So a hooked Gate is
+an extension of the Gate, not a second concept. It has the same derived id, accepted set, Sender, Console card and
+`jr2 send` path as any Gate. The Hook checks the delivery and decides nothing; only a Gate's handler or its look makes
+an event for a run.
+
+- **A Gate slot declares what it hears.** `actors: { review: gate({ meta, delivers, hooks, look, reply }) }`, and the
+  state invokes it by its key:
+  `invoke: { src: "review", input: ({ context }) => ({ meta: { pr: context.pr, sha: context.sha } }) }`. A plain Gate
+  stays `src: "gate"`. `meta` is a zod schema of the meta that the invoking state sets. The Gate checks the meta when it
+  opens, and the handlers and the look read it typed. It is a schema and not a type argument, because TypeScript does
+  not infer `delivers` when an author names one type argument.
+- **`delivers` lists the events that the handlers and the look can give.** The load walk refuses one that is not in the
+  Gate's derived accepted set. The Chart door refuses one that is not in the Chart's Vocabulary
+  ([ADR-0070](0070-a-machine-lends-its-parts-to-a-chart.md)). An event in `delivers` is `audience: "external"` unless
+  its def sets an audience, so an Agent below the Gate never has it on its Menu, and the author does not have to know
+  this ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)). This default can change what a Menu shows, so the
+  change that builds it runs the `@model` tier
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)).
+- **A handler for each Hook kind and event key.** `hooks: { github: { "pull_request_review.submitted": handler } }`. The
+  key is the kind's id and the event key that the kind reads from the delivery (ADR-0078), never a Hook's name: two
+  Hooks of one kind (two organizations, two secrets) reach the same handlers. The table is typed at compile time: each
+  kind module that the program imports adds its id and its payload types to `interface HookKinds` by declaration
+  merging, and a key that no kind in scope gives does not compile. There is no registry at run time: the door matches a
+  delivery by the kind's id and the event key, exactly. A kind's schema key can end in `.*` (`"block_actions.*"`) to
+  type each key with that prefix, but a handler names the full key (`"block_actions.approve"`): a handler key that holds
+  `*` does not compile, and `gate()` and `source()` refuse it, so the load walk refuses its Workflow. No handler hears a
+  handshake. A handler reads `{ payload, meta, caller }`, where `payload` is the decoded body after the kind's schema
+  parsed it (below). Its type is the schema's output, so a handler reads only the fields that the schema names. It is
+  pure and synchronous, as a guard is: no I/O, no Promise, no clock. It matches the payload against the Gate's `meta`
+  (for a review, the PR's url and the pushed commit) and gives one plain event of `delivers`, such as
+  `{ type: "approve", by }`, typed by that list, or `undefined` to ignore the delivery. The Orchestrator parses the
+  event with its def's schema and asks the run whether it takes it from this Gate now, as it does for `jr2 send`
+  (ADR-0013). There are no correlation keys: each delivery calls every open handler of its kind and event key.
+- **A look reads the fact that the Gate waits for.** `look: { read, input, every?, until }`. `read` is an `http` Effect
+  marked `idempotent: true`, or a promise actor, which a Machine can invoke anyway; `gate()` refuses another Effect
+  ([ADR-0067](0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)). The promise is for
+  the default test tier, which has no Instance Effector, and for a fact inside the Instance. A read of a service outside
+  the Instance is an `http` read, because the Orchestrator makes no call out of the Instance for a run. The read is a
+  child of the Gate in the run's actor system, so an `http` read goes through the run's Instance Effector and its
+  ledger, and `jr2 up` places it as it places an Effect slot. The look runs once after the Gate registers: a change
+  before the read is in its answer, and a change after the Gate registered reaches the Gate as a delivery. It runs again
+  after each restore, and every `every` (10 minutes by default) while the Gate is open. `until` gives an event of
+  `delivers`, or `undefined` for "not yet". So a delivery that came before the Gate opened, a delivery lost while the
+  Orchestrator was down, and a restart all come to the same read, and the author writes no idiom for them. The run takes
+  a looked event only when it takes it from this Gate now, as for `jr2 send`. A read that fails, an `until` that throws,
+  and an event that the run does not take now are each a line in the Orchestrator's log, and the look reads again at the
+  next `every`: a look never faults the run. A looked event has the Gate as its Sender and no `answeredBy`: the look is
+  the Machine's own read, not a Caller. The per-run feed marks it `looked`, behind the token as a Turn marker is, before
+  the delivery, because a delivery can end the run in its own send. The look stops after the run takes its event, until
+  the Gate opens again, because a look reads a level: a Gate that stays open after its event would get the same event
+  every `every`. So a state that goes back to its own Gate must change the `meta` (a new `sha`), or it loops. A restore
+  opens the Gate again, so a Gate that stayed open after its event looks one more time after a restore.
+- **`look: "none"` for a Gate that hears a command.** A `/retry` comment is an edge, not a level, so there is no fact to
+  read. A lost delivery of a command stays lost.
+- **`jr2 up` warns about a hooked Gate with no look and no `after` on its state**, and does not refuse: a delivery lost
+  in an outage then stops the run until a person answers the Gate. The fix is one line, a look or `look: "none"`.
+- **A bad delivery marks the feed and never faults the run.** A handler that throws, an event that is not in `delivers`,
+  and an event that the run does not take now each put a `hook-refused` mark on the run's feed and a line in the
+  answer's `refused`. The run goes on. A refusal that the author wants the person to read is a throw in the handler,
+  with the reason as its message.
+- **`reply` gives the text that the person who acted reads**, for a kind whose answer a person reads (`slack`,
+  `discord`; not `github`, and not a Slack event). `reply(outcome, { meta, caller })` is pure and synchronous, as a
+  handler is. `outcome` is that Gate's own: `delivered` with the event, or `refused` with the reason. It gives plain
+  text or `undefined`, never a service's JSON, and the kind escapes the text and puts it in its envelope (below). It
+  runs after the run answers, because only then is `refused` known, so the text is not in the handler's return. A Gate
+  whose handler gave `undefined` was not a target, and its `reply` does not run: a click on one message does not make
+  the other open Gates of that key speak. A throw gives no text, and the hook log keeps the error. Only the person who
+  acted sees the text. A message that everyone sees is a change of shared state, so it is an Effect of the Machine. So
+  is the reply after the work: a plain `http` Effect with a bot token, such as Slack's `chat.postMessage`, never the
+  delivery's `response_url`, which takes 5 posts in 30 minutes.
+- **A packaged Machine writes its handlers and leaves its look Open.** A forge's payload is public, so a package writes
+  the handlers for each forge that it supports, and handlers are never Open. It imports the kinds that it hears, so
+  their payload types are in scope where it is compiled. A look needs a url and a token, so a package leaves
+  `look: open` ([ADR-0054](0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)). The composer
+  binds it with `customize(m, { gates: { review: { look, hooks } } })`, which also adds or replaces a handler by kind
+  and event key; `null` removes one. An Open look that nobody binds gets the warning above, not a refusal, so a person
+  can still answer the Gate with `jr2 send`. A forge part gives the handlers and the look for one fact (a review
+  verdict, CI on a commit). It takes event defs and secrets, never a Hook's name, and each verdict compares the commit,
+  not only the PR. It types its handlers by the kind's schemas, so a field that it reads is a field that the kind
+  parses.
+- **A parked run keeps the handlers, the look and the `reply` of the Assembly that it holds**
+  ([ADR-0069](0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)): they are code in the
+  Assembly, and the Gate's input stays data, so a restore registers the Gate again as before.
+
+## The Hook's door
+
+- **`POST /hooks/:name`.** Each Hook that `jr2.config.ts` declares has one stable address, which a service is set up
+  with once. The Hook's verifier authenticates the route, outside the bands of ADR-0014 (ADR-0078). A delivery that
+  fails it, or whose signed timestamp is more than 300 seconds from the door's clock, gets 401, and nothing else
+  happens. The window is jr2's, the same for every kind. A name that the current config does not declare gets 404. With
+  no current Assembly the door answers 503 before the verifier, because no config says which Hooks exist. A body above 2
+  MiB gets 413, after the name and before the verifier. The door reads no more of the body than the limit, because this
+  is the one route with no bearer token that takes a body, and a `mac` check sends the body to the Instance Effector as
+  base64, which its wire limits to 4 MiB. Without the limit, a large delivery that is correctly signed would get a
+  false 503. The hook log keeps a `too-large` line, which claims no delivery id. A `mac` check that the Instance
+  Effector cannot answer (none is deployed, or no replica answers) is 503 too, so the service can send again: the
+  Orchestrator holds no secret to check with
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)).
+- **The kind's handshake comes after the verifier.** A Slack `url_verification` gets `{ "challenge": … }`, and a Discord
+  `PING` gets `{ "type": 1 }`. A handshake reaches no handler, and the hook log keeps it as `handshake`. A request that
+  the kind cannot read (its `read` throws, or gives no id or no event key) gets 400, and the hook log keeps the error as
+  `unreadable`.
+- **The door parses the payload before the fan-out.** A Hook kind gives a zod schema for each event key, and the door
+  parses the decoded body with the schema of the delivery's key. Each object in a schema is a loose object, and a schema
+  names only the fields that handlers need. So a field that the service adds breaks nothing, and a named field that is
+  missing or of the wrong type fails the parse. A failed parse reaches no handler. The hook log keeps a
+  `payload-refused` line with zod's issues, and the answer names the kind and the event key in
+  `payloadRefused: { kind, key, issues }`. The status is 200, because a second try fails the same way. A key that the
+  kind gives no schema for is not parsed, and it reaches nothing, because no handler can hear it.
+- **A repeat is found by the delivery id AND the body's digest.** A delivery whose id or digest the hook log holds gets
+  200 with `seen: true`, and nothing is delivered. The check is for each Hook, because two Hooks can get one body (an
+  organization's webhook and a repository's). Only a delivery that the door claimed counts: a handshake, a
+  `payload-refused` line, an `unreadable` line, a `hold-full` line (a 429, below) and a `no-live-run` line (a 503,
+  below) never make a repeat, so a refused payload that comes again is parsed again, and a delivery that every Source
+  was too full to hold is heard again. The check and the claim are one synchronous step, so of two copies that come at
+  once, one is delivered. A service may or may not send a delivery again; the design depends on neither, because the
+  look finds what a lost delivery said.
+- **The fan-in reaches open Gates only.** A delivery goes to every open Gate, in every live run of a Workflow that the
+  Hook may answer, whose handlers hear its kind and event key, and to nothing else. A Pool's `source` Gate is one of
+  them ([ADR-0017](0017-pool-over-a-source-port.md)). So a Hook answers a Gate of a run, or brings items to a Source. It
+  never starts a run, and it never names one.
+- **The answer is the outcome.** 200 with
+  `{ delivery, seen, delivered: [{ run, workflow, gate, event }], refused: [{ run, gate, event?, reason }], ignored, sources, payloadRefused? }`:
+  `ignored` counts the open Gates whose handler gave nothing, and `sources` holds each Source's verdict (ADR-0017). A
+  delivery that reached nothing gets 200 with `delivered: []`. After the verifier, the fan-out always runs first. Then
+  the answer is 429 when every Source's verdict is `hold-full`, and 503 only in two cases: a standing Pool that hears
+  this kind and event key has no live run and is not paused, or the delivery followed a standing Pool's hand-overs to
+  the new run's Source 3 times and the Pool handed its run over again (ADR-0017). In the second case the Pool can have a
+  live run: the delivery stops following it, so that it cannot follow without end. Neither 503 claims the delivery's id,
+  so the service's send again is heard. The 503s that come before the verifier are in the door's rule above. So a Pool
+  in back-off does not stop the review Gates of other runs. This is the answer of a kind whose answer no person reads: a
+  forge, or a Slack event, which keeps its 429 and 503 so that Slack sends it again.
+- **A person reads the answer to a chat command or click.** For a Slack command or click and a Discord interaction, the
+  kind's envelope takes the place of the outcome, and the hook log keeps the outcome. The text joins the `reply` of
+  every target: Sources first (what the act brought), then Gates (what the act answered), and in each by Workflow name,
+  then by run id. Empty texts and exact repeats are dropped. A text from a `skipped` verdict shows only when no other
+  target gave a text, because a skip says "not for me". Every target speaks, and not one winner, because the outcome is
+  already a list and the load walk cannot see which Gates will be open. When no target gives a text, the door writes one
+  from the outcome: a repeat, a delivery that reached nothing, a payload that the parse refused, or what the fan-in did
+  (a Gate that took an event, a Pool that is paused). For a 429 or a 503 of the fan-in, the door adds a line with the
+  cause after the targets' texts, so the text always says why. This text is the same for every service, so the kind
+  never sees the outcome. A paused Pool has no run, so no `reply` of it runs: the door's text says that it is paused.
+  The 503s and the 404 that come before the verifier stay as they are, because the door cannot know who reads the answer
+  before the kind reads a verified request. The door cuts the text to the limit that the kind gives (Discord: 2000
+  characters), and the kind puts it in its envelope. The envelope shows the text to the person who acted, and to nobody
+  else: Slack `{ "response_type": "ephemeral", "text": … }`, Discord
+  `{ "type": 4, "data": { "content": …, "flags": 64 } }`. The text is plain: no Block Kit blocks, no Discord embeds and
+  no `in_channel` in v1. A rich reply adds later without a break.
+- **Such an answer is 200.** Where the rules above give 429 or 503, a delivery whose answer a person reads gets 200, and
+  its text says why. A non-200 shows the person the service's own error, which says nothing about what jr2 did. The hook
+  log keeps the status that the rules give. A failed verifier stays 401.
+- **The reply to a Slack click goes to its `response_url`.** Slack shows no text from the answer to a Block Kit click:
+  that answer can only be an empty 200. So the `slack` kind's envelope for a click is an empty 200 and a follow-up, as
+  data: a post of the text to the click's `response_url`. The door answers the empty 200, and then makes the post
+  through the Instance Effector's `http` call
+  ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)): to a host that the kind declares
+  (`hooks.slack.com`), with no secret (the url is in the verified payload), one try. The door refuses a url that does
+  not start with one of the kind's `posts`, and posts nothing. A failed or refused post is a `follow-up` line in the
+  hook log. A `reply` that threw is in its delivery's line, as `replyErrors`. It is the answer by another road, with no
+  slot, no ledger row and no run. No Machine can post it, because a click that reaches nothing has no run.
+- **No deferred answer.** The text is a verdict or an outcome, which is ready when the answer leaves. The work never is.
+  Discord's deferred answer (type 5) would make the run's result the answer, but its token lives 15 minutes, a run is
+  often longer, and a deferred answer that nobody edits stays "thinking". When the door misses the service's 3 seconds,
+  the person sees the service's error, the hook log keeps what jr2 did, and a held item still runs.
+- **The hook log keeps each delivery for `runs.retain`**
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)): its Hook, id, digest, outcome and
+  the status that the rules give, a `payload-refused` delivery with zod's issues, a Source's skip with its reason, a
+  `reply` that threw, and a failed follow-up post. `jr2 hooks <name>` prints it, newest first, from `GET /hooks/:name`,
+  which takes the Instance token alone ([ADR-0014](0014-observation-is-open-run-state-is-not.md)): a line can hold a
+  payload's fields and a handler's words. A run's blob keeps its `(delivery, gate)` pairs as the `delivery` of each
+  answer that a Hook gave (the run's last 100 answers, ADR-0078), so a restore never gives one delivery twice to one
+  Gate.
+- **Tests.** The default tier drives `POST /hooks/:name` with a `token` and an `ed25519` verifier against hooked Gates
+  and a Pool's Source, with the handshakes, the parse, the join of the replies and the envelopes. It has no Instance
+  Effector, so the `@kind` tier drives a `mac` verifier through the Instance Effector, and a look whose `http` read runs
+  there ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md) lists the facts of
+  the services that the build must check).
+
 ## Static imports; live objects constructed per-invocation from input
 
 Everything above is reachable by plain `import`. We rejected two alternatives:
@@ -126,6 +331,42 @@ The doctrine that makes static import work, sharpening ADR-0007: **actor logic i
 per-invocation from serializable input** — the Harness client from an endpoint, the kube client from ambient config.
 Tests mock by `machine.provide()` at the layer under test.
 
+## Considered options for a Hook's delivery
+
+- **Correlation keys**: a Gate states keys (`{ pr }`, `{ sha }`), a Hook event carries them, and the door routes by
+  them. Not now: the fan-out calls every open handler of the kind and event key, and keys can come later as an index,
+  without a break, when a measurement shows the need.
+- **A kept buffer**: the door keeps each Hook event for a time and gives it to a Gate that opens later. Rejected: it
+  gives edges again in the order that they arrived, so an old verdict can come after a newer one. The look reads the
+  level instead.
+- **A Listener**: an actor at a Machine's root, `listen(kind, { delivers, on, hold })`, that turns each delivery into
+  one of its own events and holds it until the Machine takes it. Rejected: it is a second concept beside the Gate, and a
+  third party of Sender, outside the position rule of ADR-0015.
+- **A Lookout**: a delivery only wakes an Effect slot, which reads the fact with an idempotent read and settles on it,
+  so the payload never decides. Rejected as the only form: it is the soundest, and the hardest to write. Each wait needs
+  a read and a schema, and a service with nothing to read needs a second form. Its read is the Gate's `look`.
+- **Payloads typed only**: a kind gives a TypeScript type for each event key, and the door parses nothing. Rejected: the
+  type then promises what nothing checks, and a fault in it shows in the handler of every Workflow, as a `hook-refused`
+  mark far from its cause, instead of at the kind.
+- **Handlers as a list of `on(kind, handlers)` calls**, which needs no `HookKinds`. Rejected: TypeScript lost the Gate's
+  `meta` type through the nested generic call, and the handler's `meta` was `never`.
+- **A brand on a handler's return** (`deliver(approve, { by })`). Rejected: a plain event typed by `delivers` gets the
+  same checks from the compiler and the walk, with one name less.
+- **The reply text in the handler's return.** Rejected: the handler runs before the run answers, so it cannot know
+  `refused`.
+- **`reply` in the Hook's config**, a function of the whole outcome. Rejected: the config is not the Assembly, it knows
+  no Workflow, and a publish does not hand it over.
+- **The author's envelope** (`{ response_type, text }`, a Discord type), or a `reply` for each kind. Rejected: every
+  author learns two services for one text, and a message that the channel sees is shared state, which is an Effect.
+- **A reply that changes the message** (Discord type 7, Slack `replace_original`). Rejected: a click that counts for
+  nothing would remove the buttons for everyone. The Machine's update of the message follows its state.
+- **One winner** among the targets' texts (the first target, or a load-walk refusal of two). Rejected: it hides what
+  happened at the other targets, and the walk cannot see which Gates will be open.
+- **No text for a Slack click**, only the Machine's update. Rejected: a click that reaches nothing, or that the run
+  refuses, then shows nothing at all.
+- **A deadline fallback** (a deferred answer at 2.5 s, and the text posted later). Not now: the door is fast by design,
+  and the fallback adds a timer and a second road for a rare case.
+
 ## Consequences
 
 - Addresses are computed by jr2, never by the workflow — iids always (ADR-0016): fresh per invocation by default (the
@@ -138,4 +379,7 @@ Tests mock by `machine.provide()` at the layer under test.
   only**, which pass `endpoint` directly in run input — e2e drives their Machines by playing the Harness's Menu against
   `/agents/<iid>/*` with no cluster. Workflows that invoke `workspace()` always get real Sandboxes (the data plane is
   never faked — ADR-0009); their e2e tier requires kind.
-- Unsolicited mid-turn steering remains the residual hard case (ADR-0002/0006).
+- A Caller's free text to an Agent is a Steering message ([ADR-0002](0002-duplex-streaming-actor.md)), never a workflow
+  event: it is in no Vocabulary, and no Gate takes it.
+- Not set yet: a time budget for the handlers, which run in the Orchestrator's event loop for each open Gate of their
+  kind and event key.

package/docs/reference/decisions/0012-workspace-wrapper-machine.md

@@ -1,15 +1,15 @@
 # `workspace()` wraps a body Machine and owns only Sandbox lifecycle
 
 jr2 provides Workspaces as a helper so workflows never provision Sandboxes themselves:
-`workspace(body, { input, repos, spec })` is a statically-imported factory (per
-[ADR-0011](0011-workflow-defined-events.md)'s import doctrine) returning a Machine that provisions a Sandbox and its
-worktrees, runs the author's **body** Machine inside it, and tears the Sandbox down when the body finishes. This makes
-GLOSSARY.md's "Workspace = child Machine bound to a unit of work" concrete.
+`workspace(body, { input, repos })` is a statically-imported factory (per [ADR-0011](0011-workflow-defined-events.md)'s
+import doctrine) returning a Machine that provisions a Sandbox and clones its Repos, runs the author's **body** Machine
+inside it, and tears the Sandbox down when the body finishes. This makes GLOSSARY.md's "Workspace = child Machine bound
+to a unit of work" concrete.
 
 ```
 placing:       create Sandbox CR → await the pod scheduled, no deadline (ADR-0064)
-provisioning:  await phase: Ready (watched, ADR-0063) → Harness /attach repos/worktrees (ADR-0004)
-running:       invoke body; input = parent input + { workspace: { repos, branch } }
+provisioning:  await phase: Ready (watched, ADR-0063) → Harness /attach repos (ADR-0004)
+running:       invoke body; input = parent input + { workspace: { repos } }
 teardown:      destroy the CR
 done:          final; workspace output = body output
 ```
@@ -25,29 +25,29 @@ already is. When the guarantee still fails (`kill -9`, hard cancel), the operato
 (ADR-0001) — the reason ADR-0001 made the CR the durable desired state. Author-assembled provisioning/cleanup states
 (the obvious alternative) put the guarantee in every workflow's hands to forget, on every error path.
 
-## Boundary: the spec speaks workspace vocabulary only
+## Boundary: the options speak workspace vocabulary only
 
-The spec — `{ branch, workGroup?, reviewSha? }` — is mapped from the parent's context by the author, but its _shape_ is
-workspace-domain: the branch to cut, and what the attach needs to cut it. The branch itself is the author's: its name
-and its granularity (per feature, per task, from a ticket, from run input) are the Machine's policy, not jr2's; the
-workspace only cuts it. Which Repos to attach is not per-run at all: they are slots on the wrapper's options
+The wrapper's options are workspace-domain. Which Repos to attach is not per-run at all: they are slots on the options
 (`repos: { target: open, docs: { url, ref } }`, ADR-0051), static so `jr2 up` can see them, each bound by the Machine,
-by a composer's `customize`, or by a mapper over the door. Workflow configuration (review rounds, budgets, ticket data)
-passes through to the body untouched; the workspace never sees it. In return the body gets what it needs to operate
-inside the Sandbox: `{ repos: Record<slot, path>, branch }`, the handles keyed by the slots the wrapper declared, in
-declaration order. No handle names a primary checkout: which tree an Agent works in is a fact about that Agent's Turn,
-which the body states (ADR-0051). The Harness `endpoint` and the Sandbox name are mechanism-facing, not body-facing —
-`agentRun` resolves them **ambiently** from the enclosing wrapper (a registrar actor co-invoked in `running`, ADR-0016),
-so the body cannot mis-thread them. Keeping this boundary is what lets one helper serve any workflow rather than
-coupling to coding-shaped ones.
+by a composer's `customize`, or by a mapper over the door. The Workspace only clones. A branch and a Worktree are the
+body's: their names and their granularity (per feature, per task, from a ticket, from run input) are the Machine's
+policy, not jr2's, and the body cuts each Worktree with `worktree()`
+([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)). Workflow configuration (review rounds,
+budgets, ticket data) passes through to the body untouched; the workspace never sees it. In return the body gets what it
+needs to operate inside the Sandbox: `{ repos: Record<slot, path> }`, the handles keyed by the slots the wrapper
+declared, in declaration order. A handle is the slot's folder, `/work/<slot>`, and not a Worktree. No handle names a
+primary checkout: which tree an Agent works in is a fact about that Agent's Turn, which the body states (ADR-0051). The
+Harness `endpoint` and the Sandbox name are mechanism-facing, not body-facing — `agentRun` resolves them **ambiently**
+from the enclosing wrapper (a registrar actor co-invoked in `running`, ADR-0016), so the body cannot mis-thread them.
+Keeping this boundary is what lets one helper serve any workflow rather than coupling to coding-shaped ones.
 
-The wrapper's `input` beside it is the door the spec maps FROM — the wrapper's own declared run-input schema, which also
-types the mapping ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)). It sits on the wrapper and not on
-the body precisely because of the injection above: the body's input is the door plus `workspace`, which no caller sends.
-That same composition is what the door checks the body against, one way only — the body may not demand more than the
-wrapper hands it; demanding less is safe — so the injection is a compile-time contract, not just a comment. The host's
-own injection into a root machine's input (`instanceId`) counts as handed over for that check, because whether it
-actually reaches this body depends on where the wrapper sits and no type can see that
+The wrapper's `input` is its door — the wrapper's own declared run-input schema, which also types a per-run slot's
+mapper ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)). It sits on the wrapper and not on the body
+precisely because of the injection above: the body's input is the door plus `workspace`, which no caller sends. That
+same composition is what the door checks the body against, one way only — the body may not demand more than the wrapper
+hands it; demanding less is safe — so the injection is a compile-time contract, not just a comment. The host's own
+injection into a root machine's input (`instanceId`) counts as handed over for that check, because whether it actually
+reaches this body depends on where the wrapper sits and no type can see that
 ([ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)).
 
 ## An Effect runs in its Workspace: the Harness container or the Sandbox Effector
@@ -58,8 +58,8 @@ Worktree file and a `command` that names a secret run in that Workspace's Sandbo
 container ([ADR-0005](0005-sandbox-pod-composition.md),
 [ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)), which the provision adds only when an
 Effect below the `workspace()` is placed there; its image is the Sandbox Image unless the `workspace()` names
-`effector: { image }`. Each one's Worktree follows the Turn's rule (ADR-0057): the one Repo Slot's, or the slot it names
-with `slot`; a Workspace with several and none named refuses it. A push goes to that slot's Binding, and after every
+`effector: { image }`. Each one's Worktree follows the Turn's rule (ADR-0057): its input names it, and under Repo Slots
+it must. A push goes to the Binding of its Repo Slot, the one slot or the one its static `slot` names, and after every
 push whose published commit is not the Agent's own — signed copies, or one squashed commit, signed or not — the
 Workspace's Harness moves the Agent's branch to the published commits (the sync, ADR-0067). An Effect of these kinds
 outside any `workspace()` is refused at invoke, as an error, never as output. A `command` that names a secret runs
@@ -86,10 +86,17 @@ the same contract as a temp directory.
 
 ## Consequences
 
-- ADR-0004's single-active-Agent-per-Workspace invariant becomes structural: one sequential body per workspace, no lock
-  machinery.
-- The workspace labels the CR with its run (`jr2.dev/run`, `jr2.dev/workflow`), which is what `jr2 ls` groups by
-  (ADR-0009).
+- The body chooses how many Agents work in its Workspace (ADR-0004, ADR-0075). The wrapper has no lock machinery for
+  them.
+- The workspace labels the CR with its run, its Workflow and its path (`jr2.dev/run`, `jr2.dev/workflow`,
+  `jr2.dev/workspace`), and writes the exact path in the annotation `jr2.dev/workspace-path`. The path is the workspace
+  actor's path in the run's Machine: actor ids joined by `/`, and a Pool child's id is its item's id, which can hold any
+  character. A label value holds at most 63 characters from `[A-Za-z0-9._-]`, so the label holds a form of the path for
+  a selector only: each other character becomes `-`, leading and trailing characters that are not alphanumeric are
+  removed (a label value must start and end with one), and a value above 63 characters is cut and ends with a hash, as
+  the CR's name does. A person selects by it with `kubectl -l`; no jr2 reader does. The `jr2 workspace` verbs list the
+  CRs by `jr2.dev/run` and compare a handle, `<run-prefix>/<workspace path>`, with the annotation, with no Orchestrator
+  (ADR-0009). They do not select by a run prefix, because a label selector matches only a whole value.
 - **Lost workspace: the wrapper emits, the body decides.** While the body runs, a lease actor beside it renews the
   Sandbox's keepalive and follows the Sandbox watch for whether the workspace it attached to is still there (ADR-0021,
   ADR-0063) — continuously, and on snapshot restore as the first tick of that same loop rather than a separate

package/docs/reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md

@@ -25,16 +25,22 @@ is needed either (ADR-0006).
 ## Decision
 
 - **The Custodian carries the Agent's Menu, and holds the credential that makes it work.** It is a jr2-composed
-  container in every Harness pod ([ADR-0005](0005-sandbox-pod-composition.md)). The Sandbox token is mounted into it as
-  a file, and into no other container. The Harness container holds the token's Stand-in,
-  `JR2_SANDBOX_TOKEN=jr2-held-JR2_SANDBOX_TOKEN`, and reaches the Orchestrator only through the Custodian's control
-  listener on `127.0.0.1:8081`. The Custodian forwards four routes, with the token put in place of the Stand-in, and
-  answers every other route itself:
+  container in every Harness pod ([ADR-0005](0005-sandbox-pod-composition.md)). A Sandbox has two tokens, its **Sandbox
+  tokens**: the **control token** and the **fetch token**, mounted into the Custodian as files, and into no other
+  container. The Harness process holds the control token's Stand-in, which is secret: a file that no process it confines
+  can read, in no child's env
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). The fetch token's Stand-in
+  is public, `jr2-held-JR2_SANDBOX_TOKEN`, and `jr2-upload-pack` holds it as a constant. The Harness reaches the
+  Orchestrator only through the Custodian: the agent routes on its control socket, `/run/jr2/custodian/control.sock`,
+  which no confined program can replace (ADR-0076), and the fetch on `127.0.0.1:8081`. The Custodian forwards six
+  routes, with each route's own token put in place of its Stand-in, and answers every other route itself:
 
   ```
   GET  /agents/<iid>/surface          the Menu                            → the Orchestrator
   POST /agents/<iid>/events           a pick                              → the Orchestrator
   GET  /agents/<iid>/deliveries/<id>  an outstanding pick's answer        → the Orchestrator
+  POST /agents/<iid>/notices          a step boundary's notices heard     → the Orchestrator
+  POST /agents/<iid>/conversation     a batch of the conversation's entries (ADR-0023) → the Orchestrator
   POST /fetch                         the ask (ADR-0053), for THIS pod's Sandbox → POST /sandboxes/<name>/fetch
   anything else                       404
   ```
@@ -42,10 +48,10 @@ is needed either (ADR-0006).
   So the Agent's sole control-plane peer is a container it can reach but whose credential it cannot read. That is what
   makes ADR-0006's "the Agent never steers the workflow" **enforced** rather than advertised.
 
-- **The Harness presents the Menu to its model itself.** There is no MCP server and no MCP client. `menu.ts` turns each
-  accepted event into a Menu item, with the event's JSON Schema as its parameters, and turns a pick into one
-  `POST …/events` — and, for an outstanding pick, the polls of its delivery, inside the same tool call. The engine runs
-  one model answer's calls in the model's order
+- **The Harness presents the Menu to its model itself.** No MCP server serves the Menu, and no MCP client reads it.
+  `menu.ts` turns each accepted event into a Menu item, with the event's JSON Schema as its parameters, and turns a pick
+  into one `POST …/events` — and, for an outstanding pick, the polls of its delivery, inside the same tool call. The
+  engine runs one model answer's calls in the model's order
   ([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)), and only the first pick of a model
   answer runs. It imports nothing from pi: `menu-tools.ts` gives each item to pi as a tool. A harness that only speaks
   MCP would get a second presenter over the same `menu.ts`, not a second Menu. The receipt comes back as prose
@@ -55,14 +61,16 @@ is needed either (ADR-0006).
   keeps two thin HTTP surfaces, neither of them MCP:
 
   ```
-  # human / webhook / CI — the Gate resource of ADR-0011, authenticated
-  GET  /runs/:id                       → open gates: accepts + schemas + acceptsNow + meta  [Instance token]
-  POST /runs/:id/gates/:gate/events    → validate + deliver, or 409                   [Instance token]
+  # human / Hook / CI — the Gate resource of ADR-0011, a Caller's (ADR-0078)
+  GET  /runs/:id                       → open gates: accepts + schemas + acceptsNow + meta  [answer]
+  POST /runs/:id/gates/:gate/events    → validate + deliver, or 409                   [answer]
 
   # the Agent's, through its pod's Custodian
-  GET  /agents/:iid/surface            → Menu + Allowed picks + schemas + semantics [Sandbox token]
-  POST /agents/:iid/events             → validate + deliver → the receipt, or 409  [Sandbox token]
-  GET  /agents/:iid/deliveries/:id     → an outstanding pick's answer, long-polled [Sandbox token]
+  GET  /agents/:iid/surface            → Menu + Allowed picks + schemas + semantics [control token]
+  POST /agents/:iid/events             → validate + deliver → the receipt, or 409  [control token]
+  GET  /agents/:iid/deliveries/:id     → an outstanding pick's answer, long-polled [control token]
+  POST /agents/:iid/notices            → the notices a step boundary appended, heard (ADR-0062) [control token]
+  POST /agents/:iid/conversation       → a batch of the conversation's entries (ADR-0023)  [control token]
   ```
 
   The receipt is `{ delivered, event, moved, turnComplete, allowed, deliveryId }`. A pick the workflow is still running
@@ -86,25 +94,34 @@ is needed either (ADR-0006).
 - **Bearer tokens, because the boundary is otherwise theater.** The Harness container shares the pod's network
   namespace, so an Agent can `curl` the Orchestrator directly; a per-pod NetworkPolicy cannot distinguish it from the
   Custodian. Only authentication closes this.
-  - **Sandbox token** — minted per Sandbox at provision (a signed Sandbox name, so re-provision after a restart yields
-    the same token), delivered as a Secret mounted into the **Custodian container only**. User `harness.env`/`envFrom`
-    land on the Harness container, never the Custodian. Authorizes exactly: deliver to agent registrations **whose
-    Sandbox is this one**, and ask for this Sandbox's fetch. Never a Gate (they are not on that surface at all), never
-    another Sandbox. The Stand-in the Harness holds is refused on every route.
+  - **Control token and fetch token** — minted per Sandbox at provision (signed names, so re-provision after a restart
+    yields the same tokens), delivered as a Secret mounted into the **Custodian container only**. User
+    `harness.env`/`envFrom` land on the Harness container, never the Custodian. The control token authorizes exactly:
+    read and deliver to agent registrations **whose Sandbox is this one** and whose slot is the slot the Harness states
+    for the conversation (ADR-0076). The fetch token authorizes exactly: ask for this Sandbox's fetch. The Orchestrator
+    accepts each token only on its own routes. Neither reaches a Gate: a Gate refuses every principal of an Agent.
+    Neither reaches another Sandbox. A Stand-in is refused on every route.
   - **Instance token** — the human/CLI credential for Gates and run control. Minted into an in-cluster Secret at
-    `jr2 up`; the CLI reads it over the kube API (RBAC is the gate) while port-forwarding the Service (ADR-0019).
+    `jr2 up`; the CLI reads it over the kube API (RBAC is the gate) while port-forwarding the Service (ADR-0019). It is
+    one Caller among others: a named Caller token, a JWT and a Hook reach Gates within their scopes
+    ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). No Caller is a
+    principal of an Agent.
   - **The Instance-token door.** The Instance token may also read any Agent's surface and deliver to it —
     `GET /agents/:iid/surface`, `POST /agents/:iid/events` — because it is the operator. That is the operator speaking
     AS the Agent: it reads the Agent's Menu and Allowed picks and its picks are judged as the Agent's — they carry the
     Agent's sender (ADR-0011) — and no audience filter applies, so it can send a pick no Gate's caller may send
     ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)). It is deliberate — it is how the e2e tier stands in
-    for an Agent — and it adds no party: neither `jr2 send` nor the Console offers it, and a Sandbox token never opens
+    for an Agent — and it adds no party: neither `jr2 send` nor the Console offers it, and a control token never opens
     it for a registration that is not its own.
   - An agent registration records its Sandbox **ambiently**: `agentRun` resolves the enclosing `workspace()` and records
     the same deterministic name the token was minted for (ADR-0016), so forgetting to pass it is unrepresentable (the
     pre-ambient version shipped exactly that footgun: `sandbox` omitted, every tool call 403'd — fail-closed but
     silent). A run-scoped token instead of a Sandbox-scoped one would be genuinely exploitable: derivable iids plus
-    readable ticket ids would let one feature's coder inject a `review_verdict` into another feature's reviewer.
+    readable ticket ids would let one feature's coder inject a `review_verdict` into another feature's reviewer. That
+    holds across Sandboxes, where another feature's Agents are in another pod. Within one Sandbox several Agents can
+    share it ([ADR-0075](0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)); there the Sandbox scope is
+    not enough, and ADR-0076 keeps the control credential where no Workspace code runs, so a coder's code cannot act as
+    the reviewer beside it.
 - **Reachability, narrowed to one caller.** The Orchestrator is always in-cluster (ADR-0019), so the route home is
   simply **Service DNS**, which the pod's maker writes into the Custodian's configuration — the Orchestrator at a
   Sandbox's provision, `jr2 up` for the Instance Harness. The Harness is told the Custodian's loopback address
@@ -131,7 +148,7 @@ is needed either (ADR-0006).
 - **The Orchestrator serves MCP, and the Custodian forwards it.** Rejected: it keeps the MCP transport and its session
   handling in the control plane and on both ends, to carry two plain HTTP calls.
 - **A uniform `/registrations/:address` API** for every caller. Rejected: it dissolves the run-scoped, discoverable Gate
-  resource ADR-0011 designed on purpose (a webhook translator finds its Gate by `meta.prUrl`; `GET /runs/:id` lists open
+  resource ADR-0011 designed on purpose (a hooked Gate's handler matches its own `meta.pr`; `GET /runs/:id` lists open
   decisions) in exchange for aesthetic symmetry.
 
 ## Consequences
@@ -139,19 +156,26 @@ is needed either (ADR-0006).
 - **The operator needs no change.** ADR-0001 made sidecars generic container fragments the operator schedules without
   understanding; the Custodian is exactly that. `kubeSandbox` composes it (plus the token Secret, written right after
   the CR with the CR as its owner from birth, so Kubernetes reaps it with the Sandbox and no path leaks it — ADR-0001).
-- **Nothing in jr2 speaks MCP.** The Orchestrator, the Harness and the CLI carry no MCP dependency.
-- **One container holds the Sandbox token and every model key.** A fault in the Custodian's engine is a fault in the one
-  container that holds both. ADR-0059 records the trade.
+- **The control plane speaks no MCP.** The Orchestrator and the CLI carry no MCP dependency, and no MCP carries the
+  Menu. The Harness and the Instance Effector speak MCP only as clients of an author's servers
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)).
+- **One container holds the Sandbox's tokens and every model key.** A fault in the Custodian's engine is a fault in the
+  one container that holds both. ADR-0059 records the trade.
 - **The `@kind` e2e tier owns the pod → Orchestrator leg** — the pod's Harness actually calls its tool through the
   Custodian, so a broken leg is a red test, and a Harness container that posts a pick straight to the Orchestrator with
   the Stand-in it holds is refused. The mechanics tier plays `/agents/:iid/*` from the host, which is honestly
   simulating the Harness's Menu, not an Agent.
+- **Per-agent identity within one Sandbox is ADR-0076.** A Sandbox-scoped credential that an Agent's code could read
+  would let one Agent in a shared Sandbox deliver a pick as another, and ADR-0075 makes a shared Sandbox normal. Only
+  the Harness process holds the control credential, and each process it starts in `/work` runs confined; the Harness
+  states each conversation's slot, and the Orchestrator checks it on the whole `/agents/:iid/*` set. The `@kind` tier
+  gains the sibling cases: a coder's `bash` finds no control credential, and code it plants that the reviewer's own
+  `bash` runs cannot deliver a pick as the reviewer.
 - **NetworkPolicy is a second layer, not the control.** It bounds where a pod may talk; only the token bounds what it
   may _do_. `jr2 up` converges ingress policies that admit only the Orchestrator to a Harness pod
   ([ADR-0058](0058-a-harness-answers-the-orchestrator-alone.md)); the Orchestrator itself is left reachable, because a
   Custodian in every Harness pod must reach it and no policy can tell the Custodian's packets from the Agent's.
 - **The Harness wire is authenticated in the other direction.** The Orchestrator bears a token derived for the placement
   on every Harness call, and the Harness holds only its digest (ADR-0058). Same signed-name idea, reversed caller.
-- **Open: authn for non-kube callers.** The Instance token rides kube RBAC for anyone with cluster creds; what an
-  ingress-exposed jr2 Application uses for human/webhook callers without them (`--url` mode) is out of scope here
-  (ADR-0014 inherits the same question).
+- **Callers without kube credentials are ADR-0078's.** The Instance token rides kube RBAC for anyone with cluster creds;
+  a Caller without them (`--url` mode, a browser, a Hook) holds a named token, a JWT or a Hook's signature.