@jr2/orchestrator 0.6.0 → 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

@@ -88,8 +88,15 @@ the same contract as a temp directory.
 
 - 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 (`jr2.dev/run`, `jr2.dev/workflow`), which is what `jr2 ls` groups by
-  (ADR-0009).
+- 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

@@ -32,7 +32,7 @@ is needed either (ADR-0006).
   ([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 five
+  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:
 
   ```
@@ -40,6 +40,7 @@ is needed either (ADR-0006).
   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
   ```
@@ -47,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
@@ -60,15 +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 [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
@@ -100,7 +102,10 @@ is needed either (ADR-0006).
     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
@@ -143,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
@@ -151,7 +156,9 @@ 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.
+- **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
@@ -170,6 +177,5 @@ is needed either (ADR-0006).
   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.

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).