@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/guides/run-one-worker-per-item.md

@@ -181,7 +181,7 @@ jr2 run issues --input '{"workers":2}'
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run e1effd33-9bf6-4137-ae70-3aa504910784 (issues) — attached
+run 7c248a11-445a-4123-8ce2-834cb57706d7 (issues) — attached
   → active "discovering"
   → active "discovering"
   → active "discovering"
@@ -206,7 +206,8 @@ jr2 status <run id>
 ```text
 …
 → context kind-jr2 / namespace my-instance
-{"runId":"e1effd33-9bf6-4137-ae70-3aa504910784","workflow":"issues",…,"gates":[{"gate":"source",…},{"gate":"issue-3.body.review",…},{"gate":"issue-2.body.review",…}]}
+{"runId":"7c248a11-445a-4123-8ce2-834cb57706d7","workflow":"issues",…,"gates":[{"gate":"source",…},{"gate":"issue-3.body.review",…},{"gate":"issue-2.body.review",…}]}
+…
 ```
 
 In the JSON that it prints, `gates` holds each open Gate of the run:
@@ -234,7 +235,7 @@ jr2 send <run id> --gate issue-2.body.review --event approve
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered approve to gate "issue-2.body.review" on e1effd33-9bf6-4137-ae70-3aa504910784
+delivered approve to gate "issue-2.body.review" on 7c248a11-445a-4123-8ce2-834cb57706d7
 ```
 
 The Pool then calls `next` again, and starts a worker for the next issue.
@@ -255,12 +256,18 @@ jr2 send <run id> --gate source --event issues_changed
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered issues_changed to gate "source" on e1effd33-9bf6-4137-ae70-3aa504910784
+delivered issues_changed to gate "source" on 7c248a11-445a-4123-8ce2-834cb57706d7
 ```
 
-Without the event, the Pool calls `next` again when a worker finishes, or after `pollEvery`. A webhook can send the same
+Without the event, the Pool calls `next` again when a worker finishes, or after `pollEvery`. A script can send the same
 event with [`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events).
 
+A [Hook](../reference/glossary.md#hook) can tell the Pool too. Give the Source a `hooks` handler for the forge's event,
+for example `github` and `issues.labeled`, that gives [`reread()`](../reference/authoring-surface/reread.md), or
+[`skip(reason)`](../reference/authoring-surface/skip.md) for a label that is not `jr2`. Then each delivery of the Hook
+makes the Pool call `next` at once. [Pools and Sources](../concepts/pools-and-sources.md#a-hook-reaches-a-source) tells
+how.
+
 ## The end of the run
 
 When the last worker finishes and no issue is ready, the run ends. In the first terminal, `jr2 run` prints the last
@@ -270,7 +277,7 @@ state of the Pool, then the status of the run as JSON:
 …
   → active "discovering"
   → done "drained"
-{"runId":"e1effd33-9bf6-4137-ae70-3aa504910784","workflow":"issues","instanceId":"db9712c8-7c19-4d18-8fb1-8c01d326808f","status":"done","value":"drained","context":{"runInput":{"workers":2,"instanceId":"db9712c8-7c19-4d18-8fb1-8c01d326808f"},"cap":2,"active":[],"items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{},"status":"drained"},"children":[],"waiting":[],"held":[],"assembly":"ca3b0e760c85","output":{"status":"drained","items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{}}}
+{"runId":"7c248a11-445a-4123-8ce2-834cb57706d7","workflow":"issues","instanceId":"1d3090c8-645b-4e22-b343-68d548aab5f4","startedAt":"2026-11-06T19:20:02.886Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"done","value":"drained","context":{"runInput":{"workers":2,"instanceId":"1d3090c8-645b-4e22-b343-68d548aab5f4"},"cap":2,"active":[],"items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{},"held":[],"ready":[],"claimed":{},"again":[],"latch":false,"taken":3,"carried":[],"refused":[],"status":"drained"},"children":[],"waiting":[],"held":[],"answers":[{"gate":"issue-2.body.review","type":"approve","at":"2026-11-06T19:21:49.638Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}},{"gate":"source","type":"issues_changed","at":"2026-11-06T19:21:57.842Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}},{"gate":"issue-3.body.review","type":"approve","at":"2026-11-06T19:22:03.493Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}},{"gate":"issue-1.body.review","type":"approve","at":"2026-11-06T19:22:33.752Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}],"assembly":"f5bb024883b4","output":{"status":"drained","items":{"issue-2":{"branch":"jr2/issue-2"},"issue-3":{"branch":"jr2/issue-3"},"issue-1":{"branch":"jr2/issue-1"}},"failures":{}},"worktrees":[{"slot":"app","path":"/work/app/task","branch":"jr2/issue-3"},{"slot":"app","path":"/work/app/task","branch":"jr2/issue-2"},{"slot":"app","path":"/work/app/task","branch":"jr2/issue-1"}]}
 ```
 
 In the JSON, `context.items` holds the output of each worker that finished, by item id. `context.failures` holds the
@@ -306,9 +313,8 @@ In the JSON, `context.items` holds the output of each worker that finished, by i
   starts with ``task: no `branch` on the door and no Instance ID to derive one from``.
 - Without `cap`, one worker runs at a time. Each `task` worker has its own
   [Workspace](../reference/glossary.md#workspace). Thus the run has `cap` Sandboxes or fewer at one time.
-- The Pool takes the `wake` event only while it waits: workers run, and no item is ready. At other times,
-  [`jr2 send`](../reference/cli.md#send) refuses it:
-  `error: gate "source" is open, and the run does not take "<event>" now: no writing of it would move the run with this payload — not delivered (takes now: nothing)`.
+- The Pool takes the `wake` event at any time while the run is open. While it waits, it calls `next` at once. While
+  `next` runs, it calls `next` once more after that call, so that the change is not lost.
 - `onDrained` takes only `"final"`: the run ends.
 
 ## Read next

package/docs/guides/set-an-agents-access-and-dials.md

@@ -360,6 +360,8 @@ Dial. Thus:
 - `jr2 up` gives each pod the model key of the providers that the definitions of its Agents name. For an Agent in a
   Sandbox, use a Dial model of a provider that a definition in that Sandbox names. For a Menu-only Agent, use a provider
   that a Menu-only definition of the Instance names.
+- In the same way, `jr2 up` gives each pod the secret of each MCP server that the definitions of its Agents name. The
+  [MCP tools](../reference/glossary.md#mcp-tools) of an Agent come from its definition only. A Turn cannot change them.
 
 ## Continue a conversation
 

package/docs/guides/start-a-run-for-each-alert.md

@@ -0,0 +1,290 @@
+---
+title: Start a run for each alert
+description: Make a standing Pool that starts one run for each alert that an outside service sends to a Hook.
+---
+
+# Start a run for each alert
+
+Start one run of a [Workflow](../reference/glossary.md#workflow) for each alert that an alert service sends to a
+[Hook](../reference/glossary.md#hook).
+
+The example has three Workflows and one Hook. The alert service sends each new issue to the Hook `sentry`. The Workflow
+`alerts` is a standing [Pool](../reference/glossary.md#pool) of runs: its push Source holds each alert, and the Pool
+starts one run of `triage` for each alert, with at most 8 live at one time. A `triage` run waits until a person takes
+the alert or dismisses it.
+
+`@jr2/orchestrator/hooks/webhook` has `webhook()`, which makes the kind of a service that jr2 ships no kind for. It is
+part of `@jr2/orchestrator`, so your [Instance](../reference/glossary.md#instance) installs nothing more.
+
+## Write the kind of the service
+
+The alert service signs the raw body with a shared secret, and puts the HMAC-SHA256 in hex in the header
+`sentry-hook-signature`. The header `sentry-hook-resource` and the field `action` give the event key, such as
+`issue.created`. The header `request-id` is the id of the delivery. Save the kind as `hooks/sentry.ts`, beside
+`workflows/`, because it is not a Workflow:
+
+```ts
+import { z } from "zod";
+import { webhook } from "@jr2/orchestrator/hooks/webhook";
+
+// An alert service that jr2 ships no kind for. The service signs the raw body with a shared secret
+// (sha256, hex) in the header sentry-hook-signature. The event key is the resource and its action,
+// such as issue.created. The module is in `hooks/`, not in `workflows/`, because it is not a Workflow.
+export const sentry = webhook({
+  id: "sentry",
+  events: {
+    "issue.created": z.looseObject({
+      data: z.looseObject({
+        issue: z.looseObject({ id: z.string(), title: z.string(), level: z.string() }),
+      }),
+    }),
+  },
+  verify: { mac: { header: "sentry-hook-signature" } },
+  key: { name: { header: "sentry-hook-resource" }, action: { json: "action" } },
+  delivery: { header: "request-id" },
+});
+
+declare module "@jr2/orchestrator/hooks" {
+  interface HookKinds {
+    sentry: typeof sentry;
+  }
+}
+```
+
+The `declare module` block adds the kind to the types of the handlers. A handler for an event key that the kind does not
+give does not compile.
+
+## Write the Workflow of one alert
+
+Save `workflows/triage.ts`. Its door takes the issue id and the title of one alert:
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { defineEvent, jr2Setup } from "@jr2/orchestrator";
+
+// The two answers of the person on call.
+const take = defineEvent({
+  name: "take",
+  description: "I take this alert.",
+  input: z.object({ who: z.string().min(1) }),
+});
+const dismiss = defineEvent({
+  name: "dismiss",
+  description: "This alert needs no work. Say why.",
+  input: z.object({ reason: z.string().min(1) }),
+});
+
+type Context = { issue: string; title: string; who?: string };
+
+// One run for each alert. The run waits until a person takes the alert or dismisses it.
+export const machine = jr2Setup({
+  types: {} as { input: { issue: string; title: string }; context: Context },
+  events: [take, dismiss],
+}).createMachine({
+  id: "triage",
+  // The door: the alerts Pool sends this input for each alert.
+  input: z.object({ issue: z.string(), title: z.string() }),
+  context: ({ input }) => ({ issue: input.issue, title: input.title }),
+  initial: "waiting",
+  states: {
+    waiting: {
+      invoke: {
+        src: "gate",
+        input: ({ context }) => ({ meta: { issue: context.issue, title: context.title } }),
+      },
+      on: {
+        take: { target: "taken", actions: assign({ who: ({ event }) => event.who }) },
+        dismiss: "dismissed",
+      },
+    },
+    taken: { type: "final" },
+    dismissed: { type: "final" },
+  },
+});
+```
+
+## Write the standing Pool
+
+Save `workflows/alerts.ts`:
+
+```ts
+import { z } from "zod";
+import { carry, dispatch, pool, skip, source } from "@jr2/orchestrator";
+import type {} from "../hooks/sentry.ts";
+
+// The door of the triage Workflow: each alert is one run of it.
+const triageDoor = z.object({ issue: z.string(), title: z.string() });
+
+// A push Source: each Hook delivery carries an alert, and the Pool holds it until a slot is free.
+const alerts = source({
+  item: z.object({ issue: z.string(), title: z.string(), level: z.string() }),
+  hooks: {
+    sentry: {
+      "issue.created": ({ payload }) => {
+        const issue = payload.data.issue;
+        if (issue.level !== "error" && issue.level !== "fatal") return skip(`level is ${issue.level}`);
+        return carry({ issue: issue.id, title: issue.title, level: issue.level });
+      },
+    },
+  },
+});
+
+// A standing Pool of runs: one triage run for each alert, at most 8 live at once.
+export const machine = pool(dispatch("triage", { input: triageDoor, wait: true }), {
+  id: "alerts",
+  standing: true,
+  source: alerts,
+  itemId: (alert) => `sentry-${alert.issue}`,
+  cap: 8,
+  itemInput: (alert) => ({ issue: alert.issue, title: alert.title }),
+});
+```
+
+- The Source has `item` and `hooks`, and no read: it is a push Source. Its handler gives `carry(item)` for an alert of
+  the level `error` or `fatal`, and `skip(reason)` for the other levels.
+- The worker is `dispatch("triage", { input, wait: true })`, so each alert is a run of its own of `triage`.
+- `itemId` is the key of the run. A second delivery of the same alert finds the run of the first one, and starts no
+  second run.
+- `standing: true`: jr2 starts the run of the Pool, and keeps one live run of it.
+
+## Declare the Hook
+
+Add the Hook to `jr2.config.ts`, and its secret to the `secrets` list:
+
+```ts
+import { defineConfig, secret } from "@jr2/orchestrator";
+import { sentry } from "./hooks/sentry.ts";
+
+export default defineConfig({
+  // The Hook's secret is an entry of the list. jr2 up places SENTRY_HOOK in the Instance Effector.
+  secrets: [{ name: "SENTRY_HOOK", value: process.env.SENTRY_HOOK }],
+  hooks: {
+    // POST /hooks/sentry: the alert service signs each delivery with SENTRY_HOOK. The Hook brings
+    // items to the Pool of the alerts Workflow, through its source Gate, and to nothing more.
+    sentry: sentry({ secret: secret("SENTRY_HOOK"), may: { answer: ["alerts"] } }),
+  },
+});
+```
+
+`may.answer` names `alerts`, because the Hook brings items to the Pool through the Pool's `source` Gate. Put the secret
+in `.env`:
+
+```sh
+SENTRY_HOOK=<secret>
+```
+
+`<secret>` is a long random value. Give the alert service the same value.
+
+## Converge
+
+```sh
+jr2 up
+```
+
+```text
+…
+standing: sentry → alerts → triage
+…
+secret SENTRY_HOOK: an Effect secret in the Instance Effector (hook sentry)
+the Instance Effector: holds SENTRY_HOOK
+…
+standing alerts → triage: live, run 0d08bbbc-d34e-47fb-9b4b-8e788e328eb4, 0 held items
+…
+```
+
+`jr2 up` puts the secret in the [Instance Effector](../reference/glossary.md#instance-effector) only, which checks each
+signature. jr2 starts the run of `alerts` at this publish. Your run id is different.
+
+## Set up the alert service
+
+The address of the Hook is `POST /hooks/sentry` on the Orchestrator. `jr2 up` makes the Service `jr2-orchestrator` on
+port 4000, with no address outside the cluster. Give the Service an address that the alert service can reach, such as an
+ingress. Then give the service the URL `https://<host>/hooks/sentry` and the secret.
+
+## Send a test delivery
+
+You can sign a delivery yourself. Forward a port to the Orchestrator, and keep this command open:
+
+```sh
+kubectl -n <namespace> port-forward svc/jr2-orchestrator 4000:4000
+```
+
+In a second terminal, sign a body with the secret and send it:
+
+```sh
+BODY='{"action":"created","data":{"issue":{"id":"4505","title":"TypeError in checkout","level":"error"}}}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SENTRY_HOOK" | sed 's/^.* //')
+curl -s -X POST http://localhost:4000/hooks/sentry \
+  -H "Content-Type: application/json" \
+  -H "sentry-hook-resource: issue" \
+  -H "request-id: test-1" \
+  -H "sentry-hook-signature: $SIG" \
+  -d "$BODY"
+```
+
+```text
+{"delivery":"test-1","seen":false,"delivered":[],"refused":[],"ignored":0,"sources":[{"pool":"0d08bbbc-d34e-47fb-9b4b-8e788e328eb4","workflow":"alerts","source":"source","verdict":"held","key":"sentry-4505"}]}
+```
+
+The Pool holds the alert, and starts a run of `triage` for it when a slot is free. Send the same command again. The
+answer has `"seen":true`, because the Hook got the id `test-1` before, and the Pool starts no second run.
+
+## Follow the alerts
+
+[`jr2 runs`](../reference/cli.md#runs) lists the run of `triage` for the alert.
+[`jr2 status <run id>`](../reference/cli.md#status) of that run prints, in its `dispatched by:` line, the run of the
+Pool, the key `sentry-4505`, and the Hook delivery that carried the alert. The person on call answers its Gate:
+
+```sh
+jr2 send <run id> --gate waiting --event take --input '{"who":"<you>"}'
+```
+
+`<run id>` is the id of the `triage` run, and `<you>` is your name. To see what the door of the Hook did with each
+delivery that jr2 keeps (`runs.retain`, 30 days by default), print its log:
+
+```sh
+jr2 hooks sentry
+```
+
+To stop the alerts for a time, cancel the run of `alerts`. A cancel of a standing Pool is a pause: the Hook's answer has
+the verdict `paused`, and the Pool holds nothing. [`jr2 run alerts`](../reference/cli.md#run) resumes it.
+
+## Rules
+
+- `pool()` refuses a Pool of runs that does not stand:
+  ``pool("<id>"): a Pool of runs stands: give it `standing: true`. A Pool of runs that a Caller starts and that ends is not offered: its itemId is a key that lives for runs.retain past the run, so a second batch in that time does no work (ADR-0017)``
+- `pool()` refuses a `dispatch` slot without `wait: true`:
+  ``pool("<id>"): its dispatch slot for "<workflow>" has no `wait: true` — with `started` alone, the Pool cannot know when a run ends, and `cap` counts nothing (ADR-0017)``
+- `pool()` refuses a `dispatch` slot with a `target`:
+  ``pool("<id>"): its dispatch slot for "<workflow>" has a `target` — a Pool of runs on another Orchestrator is not designed: remove the target (ADR-0017)``
+- `pool()` refuses a Pool of runs without `cap`:
+  ``pool("<id>"): a Pool of runs states its `cap`, a whole number above 0: the most live runs at once (ADR-0017)``
+- `pool()` refuses a push Source on a Pool that does not stand:
+  `pool("<id>"): a push Source needs a standing Pool of runs: a Pool that ends when it drains would end at once (ADR-0017)`
+- `jr2 up` refuses a standing Pool that is not the top Machine of its Workflow:
+  `refusing: workflow "<workflow>": machine "<machine>" composes the standing Pool "<id>" — a standing Pool is the top Machine of its Workflow, because jr2 keeps one run of each standing Workflow: move the Pool to a file of its own in workflows/ (ADR-0017)`
+- `jr2 up` warns when two standing Pools dispatch to one Workflow:
+  ``warning: the standing Pools "<pool>" and "<pool>" each dispatch to "<workflow>": `cap` is for each Pool, so one item that two Sources carry can take a slot in each, and the caps add (ADR-0017)``
+- The Orchestrator refuses `jr2 run` of a standing Workflow whose run is live, with the status code `409`:
+  ``"<workflow>" is a standing Workflow, and its run <run id> is live: jr2 keeps its run, and `jr2 run` only resumes a paused one (ADR-0017)``
+- The Orchestrator refuses a `dispatch` to a standing Workflow:
+  `"<workflow>" is a standing Workflow: jr2 starts its run, and a dispatch cannot (ADR-0017)`
+- When the Pool holds `hold` items (1000 by default), the door answers 429 with the verdict `hold-full`, and the service
+  can send the delivery again.
+- While the Pool waits for the back-off of a hand-over, it has no live run, and the door answers 503.
+- A Hook whose `may.answer` does not name the Workflow of the Pool brings it nothing.
+
+## Read next
+
+- [Pools and Sources](../concepts/pools-and-sources.md)
+- [Callers and Hooks](../concepts/callers-and-hooks.md)
+- [Write a Hook kind](write-a-hook-kind.md), for a service that `webhook()` cannot read
+- [Start a run from a run](start-a-run-from-a-run.md)
+- Reference: [`pool()`](../reference/authoring-surface/pool.md), [`source()`](../reference/authoring-surface/source.md),
+  [`carry()`](../reference/authoring-surface/carry.md), [`skip()`](../reference/authoring-surface/skip.md),
+  [`dispatch()`](../reference/authoring-surface/dispatch.md) and [`webhook()`](../reference/hooks.md#webhook)
+- [ADR-0017](../reference/decisions/0017-pool-over-a-source-port.md): a standing Pool, and a Hook that brings items to
+  it
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): a
+  Hook, and `webhook()`

package/docs/guides/start-a-run-from-a-run.md

@@ -117,7 +117,7 @@ back to `listening`.
 
 ## See the runs
 
-[`jr2 runs`](../reference/cli.md#runs) lists the two runs. The run of `triage` has `dispatchedBy` after its id:
+[`jr2 runs`](../reference/cli.md#runs) lists the two runs. The run of `triage` has `dispatchedBy`:
 
 ```sh
 jr2 runs
@@ -126,29 +126,25 @@ jr2 runs
 ```text
 …
 → context kind-jr2 / namespace my-instance
-workflows:
-  intake (machine)
-  ping (machine)
-  triage (machine)
-[{"runId":"91ca85e1-5092-4e10-9ec6-d14e37811ca1","workflow":"intake","instanceId":"e51d124b-88e5-461c-b464-6a3660ee13dc","status":"active","value":"listening","context":{"started":["45b52048-0848-4015-ad56-6ff8ae33d817"],"request":"The greeting looks wrong sometimes.","last":{"outcome":"started","run":"45b52048-0848-4015-ad56-6ff8ae33d817"}},"children":[],"waiting":[],"held":[],"assembly":"3229103a2952","dispatched":[{"slot":"triage","run":"45b52048-0848-4015-ad56-6ff8ae33d817","at":"2026-10-24T06:20:43.465Z"}]},{"runId":"45b52048-0848-4015-ad56-6ff8ae33d817","dispatchedBy":{"run":"91ca85e1-5092-4e10-9ec6-d14e37811ca1","slot":"triage","effect":"08423831-751f-41e5-9d93-1fa063faaf61","depth":1},"workflow":"triage","instanceId":"a2ad6e54-6a52-45c2-81f4-89f408a27d1f","status":"active","value":"triaging","context":{"request":"The greeting looks wrong sometimes.","exchange":[]},"children":[],"waiting":[],"held":[],"assembly":"3229103a2952"}]
+[{"runId":"e8a74de7-f3f3-4621-876e-e5f117af5fff","workflow":"triage","status":"active","startedBy":{"kind":"run","run":"f45bed48-9950-4e63-9cda-4df368e9a62f","slot":"triage"},"startedAt":"2026-11-06T19:23:24.220Z","assembly":"19d0bf0cbe10","openGates":0,"dispatchedBy":{"run":"f45bed48-9950-4e63-9cda-4df368e9a62f","slot":"triage","effect":"c63bce4d-e353-4fee-9035-6b13dfac4917","depth":1}},{"runId":"f45bed48-9950-4e63-9cda-4df368e9a62f","workflow":"intake","status":"active","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"startedAt":"2026-11-06T19:23:21.744Z","assembly":"19d0bf0cbe10","openGates":1}]
 ```
 
-The first line, `…`, is the line `→ .env:`, with the keys that the CLI took from `.env`. The lines on stderr list the
-Workflows of the Instance. In `dispatchedBy`, `run` is the run that started it, `slot` is the slot of the Effect, and
-`effect` is the id of that Effect in the record of the run that started it. jr2 uses it as the key of the start, so that
-a start that jr2 sends again starts no second run. `depth` is the number of runs before it in the chain. `dispatched` of
-`intake` lists each run that it started. Your ids, your time and your hash are different.
+The first line, `…`, is the line `→ .env:`, with the keys that the CLI took from `.env`. In `dispatchedBy`, `run` is the
+run that started it, `slot` is the slot of the Effect, and `effect` is the id of that Effect in the record of the run
+that started it. jr2 uses it as the key of the start, so that a start that jr2 sends again starts no second run. `depth`
+is the number of runs before it in the chain. The list gives the newest start first, so `triage` comes before `intake`.
+`jr2 status` of `intake` shows `dispatched`: each run that it started. Your ids, your time and your hash are different.
 
 [`jr2 status`](../reference/cli.md#status) prints the link in both directions, on stderr. For the run of `intake`:
 
 ```text
-dispatched: 45b52048-0848-4015-ad56-6ff8ae33d817 (triage)
+dispatched: e8a74de7-f3f3-4621-876e-e5f117af5fff (triage)
 ```
 
 For the run of `triage`:
 
 ```text
-dispatched by: 91ca85e1-5092-4e10-9ec6-d14e37811ca1 (triage), depth 1
+dispatched by: f45bed48-9950-4e63-9cda-4df368e9a62f (triage), depth 1
 ```
 
 The two runs are independent. A `CANCEL` of `intake` does not cancel the run of `triage`. Answer the `clarify` Gate of
@@ -174,7 +170,9 @@ To start a run on the Orchestrator of a different [Instance](../reference/glossa
 definition: `target: { url: "https://ops.example.com", token: secret("ops-instance") }`.
 
 - `url` is the origin of the other Orchestrator: the scheme, the host and the port. It has no path.
-- `token` names a secret that holds the Instance token of the other Instance. Put the secret in the
+- `token` names a secret that holds the token of a [Caller](../reference/glossary.md#caller) of the other Instance, with
+  the `start` scope for the Workflow, and also `read` when `wait` is `true`. A named Caller token of the other Instance
+  that has only these scopes is the safest ([Give a Caller a scope](give-a-caller-a-scope.md)). Put the secret in the
   [`secrets`](../reference/config.md#secrets) list of `jr2.config.ts`, as for an `http` Effect. See
   [Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md).
 - The Effect runs in the [Instance Effector](../reference/glossary.md#instance-effector), which holds the token.
@@ -201,7 +199,7 @@ the token together:
 - The `url` of a target is an origin. The refusal starts with
   `dispatch("<name>", { target }): "<url>" is not an origin — write the scheme and the host, with a port if it is not the scheme's, and no path, query or userinfo`.
 - The `token` of a target is a secret:
-  `dispatch("<name>", { target }): the token is a secret("<name>") holding the target's Instance token (ADR-0071)`
+  `dispatch("<name>", { target }): the token is a secret("<name>") holding a Caller token of the target with start for the Workflow (ADR-0071)`
 - An Open target is the whole target, not its secret:
   ``dispatch("<name>", { target }): secret(open) in a target — the target is the Open part, not its secret: leave the whole target Open (`target: open`) and let the composer bind its url and token together (ADR-0071)``
 - With no target, the Assembly must have the Workflow. `jr2 up` stops:
@@ -214,11 +212,15 @@ the token together:
   `warning: workflow "<workflow>" dispatches "<wrapper>/<name>": the Assembly has no Chart file workflows/<wrapper>/<name>.chart.json`.
 - For a target, each problem that `jr2 up` finds is a warning. For example, when the other Orchestrator does not answer:
   `warning: dispatch "<name>" at <url>: no answer from this host (<error>) — the other Instance may be down, or reached only from inside its cluster; while no door answers, the dispatch settles "unreachable" (ADR-0071)`
+- When the input does not agree with the `input` schema of the slot, the invoke ends with an error, and no run starts.
+  The error starts with `dispatch "<slot>": its input does not match the slot's input schema —`. Before that, jr2 asks
+  for a run under the key of the start, with no target and with one. When a run has the key, the Effect gives that run,
+  and does not read the input. With a target, jr2 sends the key and no input, so the other Orchestrator starts nothing.
 - When the Orchestrator starts no run, the Effect ends with `refused`, not with an error. `report` holds the lines of
   the refusal, and `status` is its status code:
   - `400`: the Workflow does not take the input.
   - `404`: the current Assembly has no Workflow of that name.
-  - `409`: the named Chart cannot run now, or a run of a different Workflow has the key of this start.
+  - `409`: the named Chart cannot run now.
   - `413`: the start is larger than the Effector reads.
   - `422`: the door refuses the Chart in the input.
   - `0`: the Effector refused the start before it sent it.

package/docs/guides/start-a-run.md

@@ -29,9 +29,9 @@ jr2 run ping --input '{"message":"hi"}'
 
 ```text
 → context <context> / namespace <namespace>
-run e3972b4c-eef9-4e7d-9068-3556332d2ba6 (ping) — attached
+run 17b959ed-5200-4d98-adae-403dd706277b (ping) — attached
   → done "done"
-{"runId":"e3972b4c-eef9-4e7d-9068-3556332d2ba6","workflow":"ping","instanceId":"8e13475a-d325-45d4-bc64-0627086e97ba","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"16f4181d70d9"}
+{"runId":"17b959ed-5200-4d98-adae-403dd706277b","workflow":"ping","instanceId":"32e6e954-8cc5-4b52-b6df-6c9ef6533192","startedAt":"2026-11-06T19:16:12.219Z","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"50e6f81e3bfb","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}
 ```
 
 Your run id, your instance id and your `assembly` hash are different. When your Instance folder has a `.env` file, the
@@ -47,7 +47,7 @@ output starts with one more line, `→ .env:`, with the keys that the CLI took f
 - `jr2 run` stays attached until the run ends. A run that waits at a [Gate](../reference/glossary.md#gate) does not end,
   so `jr2 run` waits too. To answer the Gate, use a second terminal. See [Answer a Gate](answer-a-gate.md).
 - When you stop `jr2 run`, for example with Ctrl-C, the run continues in the Orchestrator. To attach again, run
-  `jr2 logs -f <run id>`.
+  `jr2 watch <run id>`.
 - `jr2 run` exits with `0` only when the run ends with the status `done`. It exits with `1` for each other end:
   `failed`, `error`, `cancelled`, `lost` and `drifted`, and also when the run stops before it ends. For a run that ends
   `failed`, the line `failed: <reason>` on stderr gives the reason.
@@ -65,15 +65,15 @@ jr2 run ping --input '{"message":"hi"}' --detach
 {"runId":"fc8b82d1-bd73-498d-9057-ef13cf962240"}
 ```
 
-Use the run id, or its first 4 characters or more, with `jr2 status`, `jr2 logs` and `jr2 send`.
+Use the run id, or its first 4 characters or more, with `jr2 status`, `jr2 watch`, `jr2 logs` and `jr2 send`.
 
 ## Start a run from the Console
 
-You need the Instance token to start a run from the Console. [Open the Console](open-the-console.md) tells how to open
-it and how to get the token.
+You need a credential with the `start` scope for the Workflow, such as the Instance token, to start a run from the
+Console. [Open the Console](open-the-console.md) tells how to open it, how to get the token and how to log in.
 
 1. Open the Console.
-2. Type the Instance token in the `instance token` box in the nav.
+2. Type the token in the `Caller token` box in the nav, or click `log in`.
 3. Push Enter. The badge beside the box shows `…`, then `live`.
 4. In the Fleet rail on the left, find the Workflow. Click `start` beside its name.
 5. Fill in the form. When the Machine declares its input, the form has one field for each property of the input. A field
@@ -94,7 +94,10 @@ cannot start one.
 ## Start a run with the HTTP API
 
 Send [`POST /workflows/:name/runs`](../reference/http-api.md#post-workflows-name-runs) to the Orchestrator, with the
-Instance token. The body is the run input. A script, a webhook handler or a CI job can start a run this way.
+token of a [Caller](../reference/glossary.md#caller) that has the `start` scope for the Workflow. The body is the run
+input. A script, a webhook handler or a CI job can start a run this way. A CI job uses a named Caller token, not the
+Instance token: [Give a Caller a scope](give-a-caller-a-scope.md) makes it. The example below uses the Instance token,
+because it can do everything.
 
 `jr2 up` makes the Service `jr2-orchestrator` on port 4000, with no address outside the cluster. Thus a caller outside
 the cluster uses a port forward, or an address that you make for the Service.
@@ -144,13 +147,14 @@ curl -s http://localhost:4000/workflows/ping -H "Accept: application/json"
 ```
 
 [`GET /workflows`](../reference/http-api.md#get-workflows) gives all the Workflows, each with where it comes from, and
-the named Charts of each Chart wrapper. It also needs no token. [`jr2 runs`](../reference/cli.md#runs) prints the same
-list on stderr.
+the named Charts of each Chart wrapper. It also needs no token. [`jr2 workflows`](../reference/cli.md#workflows) prints
+the same list.
 
 ### Use the CLI without the Instance folder
 
 The CLI can also speak to an Orchestrator at a URL. Then it does not look for the Instance folder or for a kubectl
-context. Give the URL in `--url`, or in `JR2_URL`. Give the Instance token in `JR2_TOKEN`:
+context. Give the URL in `--url`, or in `JR2_URL`. Give a credential in `JR2_TOKEN`: the Instance token, or the token of
+a [Caller](../reference/glossary.md#caller) with the `start` scope ([Give a Caller a scope](give-a-caller-a-scope.md)):
 
 ```sh
 JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 run ping --input '{"message":"hi"}' --detach
@@ -177,10 +181,12 @@ JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 run ping --input '{"message":
   `the body must be a JSON object`.
 - `jr2 run` starts no run when `--input` is not valid JSON. It prints `error: <message>`, where `<message>` is the
   message of the JSON parser, and exits with `1`.
-- The Orchestrator refuses a start without the Instance token, with the status code `401`: `unauthorized`.
+- The Orchestrator refuses a start with no valid credential, with the status code `401`: `unauthorized`.
 - The Orchestrator refuses a start with the token of a [Sandbox](../reference/glossary.md#sandbox), with the status code
-  `403`: `run state and control need the Instance token — a Sandbox token has neither`. Thus an
-  [Agent](../reference/glossary.md#agent) cannot start a run.
+  `403`: `this route needs a Caller, and a Sandbox token is not one: no Agent reaches run state, run control or a Gate`.
+  Thus an [Agent](../reference/glossary.md#agent) cannot start a run.
+- The Orchestrator refuses a start from a Caller that does not have the `start` scope for the Workflow, with the status
+  code `403`: `the Caller <via>/<name> needs the "start" scope for Workflow "<workflow>" (ADR-0078)`
 - `jr2 run` outside an Instance folder, with no `--url` and no `JR2_URL`, starts no run:
   `error: not inside a jr2 instance — no jr2.config.ts found walking up from cwd`
 - `jr2 run` starts no run when the namespace holds no Instance:
@@ -189,9 +195,9 @@ JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 run ping --input '{"message":
   ``error: no kube context — `kind create cluster` (or point kubectl at one), then `jr2 up` ``
 - When the connection to the Orchestrator ends before the run ends, for example when the Orchestrator stops, `jr2 run`
   prints `error: <message>` and exits with `1`. The run continues when the Orchestrator starts again. To attach again,
-  run `jr2 logs -f <run id>`.
+  run `jr2 watch <run id>`.
 - When the Orchestrator holds the run but did not continue it, `jr2 run` exits with `1`:
-  ``run <run id> is parked: stopped before it settled — `jr2 logs -f <run id>` follows it once restored``
+  ``run <run id> is parked: stopped before it settled — `jr2 watch <run id>` follows it once restored``
 
 ## Read next
 
@@ -201,7 +207,7 @@ JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 run ping --input '{"message":
   Orchestrator.
 - [ADR-0033](../reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md): the input that a Machine
   declares.
-- [ADR-0058](../reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md): why only the Instance token
-  starts a run.
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): the
+  Callers, and the `start` scope.
 - [Answer a Gate](answer-a-gate.md)
 - [Watch a run](watch-a-run.md)