@jr2/orchestrator 0.5.1 → 0.7.0

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)

package/docs/guides/steer-an-agent.md

@@ -0,0 +1,332 @@
+---
+title: Steer an Agent
+description: Send free text to one Agent of a live run, from the CLI, from HTTP, or from the Machine itself.
+---
+
+# Steer an Agent
+
+Send free text to one [Agent](../reference/glossary.md#agent) of a live run, from the CLI, from HTTP, or from the
+[Machine](../reference/glossary.md#machine) itself.
+
+A [Steering message](../reference/glossary.md#steering-message) is not a pick and not an event. No guard reads it, and
+no [Gate](../reference/glossary.md#gate) takes it. The Agent hears it one time, and nothing interrupts the Agent. Then
+the Agent decides what to do, and it acts on the run only with its picks. To move the run, answer a Gate:
+[Answer a Gate](answer-a-gate.md).
+
+The examples on this page use the [Workflow](../reference/glossary.md#workflow) `notes`. A writer writes release notes,
+and a reviewer reads them. When the reviewer sends a note, the Machine relays it to the writer as a Steering message.
+Save the file as `workflows/notes.ts` in your [Instance](../reference/glossary.md#instance). Then run `jr2 up`:
+
+**Anthropic**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, steer } from "@jr2/orchestrator";
+
+// The writer's pick: the draft is ready for review.
+const done = defineEvent({
+  name: "done",
+  description: "The draft is ready. Give the whole draft.",
+  input: z.object({ draft: z.string().min(1) }),
+});
+// The reviewer's two picks.
+const note = defineEvent({
+  name: "note",
+  description: "Send the draft back to the writer, with what to change.",
+  input: z.object({ text: z.string().min(1) }),
+});
+const approve = defineEvent({
+  name: "approve",
+  description: "The draft is good.",
+  input: z.object({}),
+});
+
+type Context = { version: string; draft?: string; fault?: string };
+
+export const machine = jr2Setup({
+  types: {} as { input: { version: string }; context: Context },
+  events: [done, note, approve],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write short release notes.",
+      workspace: "none",
+    }),
+    // A Caller cannot steer the reviewer. The Machine can.
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You review release notes for clear and correct words.",
+      workspace: "none",
+      steerable: false,
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "notes",
+  input: z.object({ version: z.string() }),
+  context: ({ input }) => ({ version: input.version }),
+  initial: "writing",
+  // A Turn that fails in either state ends the run `failed`, with the reason of the Turn.
+  on: { "agent.fault": { target: ".failed", actions: assign({ fault: ({ event }) => event.reason }) } },
+  states: {
+    writing: {
+      invoke: {
+        src: "writer",
+        // The writer continues its conversation, so it keeps its draft from Turn to Turn.
+        input: ({ context }) => ({ prompt: `Write the release notes for ${context.version}.`, continue: true }),
+      },
+      on: { done: { target: "reviewing", actions: assign({ draft: ({ event }) => event.draft }) } },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review these release notes:\n\n${context.draft ?? ""}` }),
+      },
+      on: {
+        // The reviewer's note goes to the writer's next Turn as a Steering message. `from` names the
+        // reviewer, so the writer reads it as information from a peer, not as an instruction.
+        note: {
+          target: "writing",
+          actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+        },
+        approve: "published",
+      },
+    },
+    published: { type: "final" },
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.fault ?? "the Turn failed" }) } },
+  },
+});
+```
+
+**Local**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, steer } from "@jr2/orchestrator";
+
+// The writer's pick: the draft is ready for review.
+const done = defineEvent({
+  name: "done",
+  description: "The draft is ready. Give the whole draft.",
+  input: z.object({ draft: z.string().min(1) }),
+});
+// The reviewer's two picks.
+const note = defineEvent({
+  name: "note",
+  description: "Send the draft back to the writer, with what to change.",
+  input: z.object({ text: z.string().min(1) }),
+});
+const approve = defineEvent({
+  name: "approve",
+  description: "The draft is good.",
+  input: z.object({}),
+});
+
+type Context = { version: string; draft?: string; fault?: string };
+
+export const machine = jr2Setup({
+  types: {} as { input: { version: string }; context: Context },
+  events: [done, note, approve],
+  actors: {
+    writer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You write short release notes.",
+      workspace: "none",
+    }),
+    // A Caller cannot steer the reviewer. The Machine can.
+    reviewer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You review release notes for clear and correct words.",
+      workspace: "none",
+      steerable: false,
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "notes",
+  input: z.object({ version: z.string() }),
+  context: ({ input }) => ({ version: input.version }),
+  initial: "writing",
+  // A Turn that fails in either state ends the run `failed`, with the reason of the Turn.
+  on: { "agent.fault": { target: ".failed", actions: assign({ fault: ({ event }) => event.reason }) } },
+  states: {
+    writing: {
+      invoke: {
+        src: "writer",
+        // The writer continues its conversation, so it keeps its draft from Turn to Turn.
+        input: ({ context }) => ({ prompt: `Write the release notes for ${context.version}.`, continue: true }),
+      },
+      on: { done: { target: "reviewing", actions: assign({ draft: ({ event }) => event.draft }) } },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review these release notes:\n\n${context.draft ?? ""}` }),
+      },
+      on: {
+        // The reviewer's note goes to the writer's next Turn as a Steering message. `from` names the
+        // reviewer, so the writer reads it as information from a peer, not as an instruction.
+        note: {
+          target: "writing",
+          actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+        },
+        approve: "published",
+      },
+    },
+    published: { type: "final" },
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.fault ?? "the Turn failed" }) } },
+  },
+});
+```
+
+The Agents use the model of the tab.
+
+In the commands, replace these values:
+
+- `<namespace>`: the namespace of your Instance. It is the [`name`](../reference/config.md#name) in `jr2.config.ts`.
+  When `jr2.config.ts` sets no `name`, it is the name of the Instance folder.
+- `<run id>`: the run id, or its first 4 characters or more. `jr2 run` prints the run id in the line
+  `run <run id> (<workflow>) — attached`.
+
+Give each `jr2` command in the Instance folder.
+
+## Start a run
+
+```sh
+jr2 run notes --input '{"version":"1.4.0"}'
+```
+
+```text
+→ context <context> / namespace <namespace>
+run 7058fde8-4c32-4513-82f0-e6c095d8707b (notes) — attached
+  → active "writing"
+  → active "writing"
+```
+
+Your run id is different. Give the commands in the next steps in a second terminal.
+
+## Find the Agent slot
+
+A message goes to an Agent slot: the path of the Machine and the name of the Agent. The Agents of the root Machine have
+the path `root`. An Agent in a child Machine has the path of that Machine, such as `review/reviewer`. Give
+[`jr2 steer`](../reference/cli.md#steer) the run id alone to list the slots:
+
+```sh
+jr2 steer 7058
+```
+
+```text
+→ context <context> / namespace <namespace>
+[{"agent":"root/writer","open":true,"steerable":true},{"agent":"root/reviewer","open":false,"steerable":false}]
+```
+
+- `open` is `true` when a [Turn](../reference/glossary.md#turn) of the slot is open now.
+- `steerable` is `false` when the definition of the Agent says `steerable: false`. A Caller cannot steer it.
+
+The list has each Agent of each Machine instance that is live now, also an Agent with no open Turn.
+
+## Send the message
+
+```sh
+jr2 steer 7058 root/writer "Put the breaking change first."
+```
+
+```text
+→ context <context> / namespace <namespace>
+sent a Steering message to root/writer on 7058fde8-4c32-4513-82f0-e6c095d8707b: its open Turn hears it at its next step boundary, or its next Turn hears it if this Turn ends first
+```
+
+Then one of these things occurs:
+
+- When a Turn of the slot is open, the Harness adds the message to the Turn before the next model request.
+- When the Turn ends with a pick before its next model request, the message waits for the next Turn of the slot.
+- When no Turn of the slot is open, the message waits. The next Turn of the slot in the same Machine instance hears it,
+  and `jr2 steer` prints `its next Turn hears it`.
+- When that Machine instance ends first, the message is not delivered.
+
+## Read what became of the message
+
+[`jr2 status`](../reference/cli.md#status) prints the record of the messages of the run in its `steering` field. Each
+entry has the slot, the author, the text, the time, and the `outcome`: `held` while it waits, `heard` when a Turn heard
+it, or `not-delivered` when its Machine instance ended first.
+
+```sh
+jr2 status 7058
+```
+
+```text
+→ context <context> / namespace <namespace>
+{"runId":"7058fde8-4c32-4513-82f0-e6c095d8707b","workflow":"notes",…,"steering":[{"id":"c46a31f0-db82-4d80-b7f1-8908c2d9b121","agent":"root/writer","author":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"text":"Put the breaking change first.","at":"2026-11-06T20:56:33.005Z","outcome":"heard"},{"id":"f788b1f6-2b93-44be-a54e-e91f83685493","agent":"root/writer","author":{"kind":"machine","from":{"party":"agent","id":"reviewer"}},"text":"The release notes are well-structured, but I suggest a change for clarity in the **Notifications** section:\n\n\"Real-time notifications are now **persisted** across device logins.\"\n\n\"Persisted\" is technical jargon referring to data storage. If the intended meaning is that notifications appear on different devices, \"**synchronized**\" (or \"synced\") is the standard and clearer term for users.\n\nSuggested edit: \"Real-time notifications are now **synchronized** across devices.\"","at":"2026-11-06T20:57:35.442Z","outcome":"heard"}],…}
+started by: token/instance on behalf of kubernetes-admin
+```
+
+The model reads the message after the notices of the Turn and before its Allowed picks. The Harness tells the model that
+the message is an instruction from outside the run, and gives your name as a [Caller](../reference/glossary.md#caller).
+
+## Send the message from the Console
+
+With a credential that has the `steer` scope for the Workflow, the [Console](../reference/glossary.md#console) shows a
+box beside the conversation in the bottom drawer. Select the run, and click the tab of the Agent slot. Type the message
+in the box under `steer <slot>`, and click `send`. The box shows `<slot> cannot be steered now` when the definition of
+the Agent says `steerable: false`, or when the Machine instance of the slot ended. The conversation shows the message
+where the model read it. [Open the Console](open-the-console.md#read-a-conversation) tells how to open the drawer.
+
+## Send the message from HTTP
+
+A client that is not the CLI sends the message to
+[`POST /runs/:runId/steering`](../reference/http-api.md#post-runs-runid-steering), with the credential of a Caller that
+has the `steer` scope for the Workflow of the run. [Give a Caller a scope](give-a-caller-a-scope.md) makes such a token.
+The path takes the full run id, not a prefix.
+[`GET /runs/:runId/agents`](../reference/http-api.md#get-runs-runid-agents) lists the slots. This example reaches the
+Orchestrator through the port forward in [Open the Console](open-the-console.md):
+
+```sh
+curl -X POST http://localhost:4000/runs/<run id>/steering \
+  -H "authorization: Bearer <token>" \
+  -d '{"agent":"root/writer","text":"Put the breaking change first."}'
+```
+
+```text
+{"id":"29e54d63-e858-4249-a789-f7e5506f433a","agent":"root/writer","open":true}
+```
+
+The status is 202.
+
+## Steer from the Machine
+
+The Machine sends a Steering message with the [`steer`](../reference/authoring-surface/steer.md) action, in a
+transition. In `notes.ts`, the `note` pick of the reviewer sends the writer back to `writing`, and `steer` gives the
+reviewer's text to the writer's next Turn.
+
+`from` names the [Sender](../reference/glossary.md#sender) of the event: here, the reviewer. Then the writer reads the
+text as information from a peer, not as an instruction. When `from` is a Gate, the writer reads the text as what the
+Gate received, not as an order: the workflow did not write it. A `steer` with no `from` is the text of the workflow
+itself. Agents tell each other things only in this way: jr2 gives an Agent no tool to message another Agent.
+
+The Machine can steer an Agent whose definition says `steerable: false`. That refuses Callers only.
+
+## Rules
+
+- A message is at most 16 KiB of UTF-8. `POST /runs/:runId/steering` refuses a longer text with the status 413:
+  `the text is longer than 16384 bytes (16 KiB)`. The `steer` action cuts a longer text and adds
+  `[jr2 cut this message at 16 KiB]`.
+- A body with no `agent`, or no `text`, gets the status 400.
+- A slot that no live Machine instance of the run holds gets the status 409, with the slots of the run in `agents`:
+  `no live Machine instance of run "<run id>" holds the Agent slot "<agent>" (its slots: <slots>)`. A run that has ended
+  gets 409 too: `run "<run id>" is not live: no Agent of it can hear a message`.
+- A slot whose Agent says `steerable: false` gets the status 403:
+  `the Agent slot "<agent>" is not steerable: its definition says steerable: false`.
+- A Caller with no `steer` scope for the Workflow of the run gets the status 403:
+  `the Caller <via>/<name> needs the "steer" scope for Workflow "<workflow>" (ADR-0078)`.
+- An unknown run gets the status 404: `no run "<run id>"`.
+- The record keeps the newest 100 messages of a run, and each message that waits.
+
+## Read next
+
+- [Agents and Turns](../concepts/agents-and-turns.md#steering-messages)
+- [`jr2 steer`](../reference/cli.md#steer) and [`steer`](../reference/authoring-surface/steer.md)
+- [ADR-0002](../reference/decisions/0002-duplex-streaming-actor.md#steering-messages): Steering messages
+- [ADR-0062](../reference/decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md): one ledger for notices
+  and Steering messages

package/docs/guides/use-a-hosted-provider.md

@@ -186,10 +186,16 @@ custom provider, with `harness.provider` and `apiKey`. The guide
 - `jr2 up` refuses a gateway address that is not `https://`:
   `harness.catalog.<id>.baseUrl must be an https:// URL — the Custodian carries TLS only (ADR-0059). Read it from .env: catalog: { anthropic: { baseUrl: process.env.LITELLM_URL ?? "" } }`.
 - `jr2 up` warns about a key that no pod gets:
-  `warning: secrets[<i>] (<NAME>) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect names it (ADR-0059, ADR-0068)`.
+  `warning: secrets[<i>] (<NAME>) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect or Hook names it (ADR-0059, ADR-0068)`.
 - A credential that signs each request, such as `AWS_ACCESS_KEY_ID`, cannot be a Held secret. `jr2 up` warns when
   `harness.env` sets one. Send the calls through a gateway that holds the credential, and hold the key of the gateway:
   `warning: harness.env sets <NAME>: a signing credential cannot be held (a Stand-in cannot be swapped into a signature), so the Agent can read it — route the provider through a gateway that holds it, and hold the gateway's key instead (ADR-0059)`.
+- The Harness process reads the file that a credential-file name in `harness.env` names, such as `AWS_CONFIG_FILE` or
+  `GOOGLE_APPLICATION_CREDENTIALS`. `jr2 up` refuses a path in a folder that the Agent's code writes, or a path that is
+  not absolute:
+  `harness.env[<i>] sets <NAME> to "<path>", which is in <folder>, a folder the Agent's code writes: the Harness process reads that file, and code that writes it acts outside the Agent's confinement (ADR-0076). Point it at a file of the image that the Sandbox's user cannot write.`
+  For another path, it warns:
+  `warning: harness.env sets <NAME>: the Harness process reads "<path>", so the Sandbox's user must not be able to write it — a folder of the image that the user owns is one the Agent's code writes (ADR-0076)`.
 - The Harness refuses a model that is not in the catalog when it admits the Turn:
   `harness admission failed (400): agent "<agent>": model "<provider>/<modelId>" resolves to nothing — not in pi's catalog, and no custom provider "<provider>" is configured (ADR-0018)`.