@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/http-api.md

@@ -5,9 +5,9 @@ description: "Every route of the Orchestrator's HTTP API, by access band, and th
 
 # HTTP API
 
-The Orchestrator's HTTP API: what the `jr2` CLI, the Console, a webhook and the Harness call. Each route is in one access band, by the credential it asks for ([ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md)). Send a token as `Authorization: Bearer <token>`. An error answer is `{ error }`, with the status the route gives. A path segment `:name` is a parameter; `:name{regex}` is a parameter that must match the regex.
+The Orchestrator's HTTP API: what the `jr2` CLI, the Console, a webhook and the Harness call. Each route is in one access band, by the credential it asks for ([ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Send a token as `Authorization: Bearer <token>`. An error answer is `{ error }`, with the status the route gives. A path segment `:name` is a parameter; `:name{regex}` is a parameter that must match the regex.
 
-Bands: [Open](#band-open), [Authenticated](#band-authenticated), [Instance token only](#band-instanceonly), [Publish token only](#band-publishonly). The types the bodies and answers name are in [Types](#types).
+Bands: [Open](#band-open), [Authenticated](#band-authenticated), [A Caller with a scope](#band-guarded), [Instance token only](#band-instanceonly), [Publish token only](#band-publishonly), [A Hook's verifier](#band-hook). The types the bodies and answers name are in [Types](#types).
 
 <a id="band-open"></a>
 
@@ -46,10 +46,10 @@ No token. Structure and observation: no run context, and no control.
 
 ### `GET /assembly`
 
-- Summary: The current Assembly and the Assemblies that live runs hold.
-- Response: [`AssemblyView`](#type-assemblyview)
+- Summary: The current Assembly, the Assemblies that live runs hold, and each standing Workflow: live, paused or waiting, its run, and how many items it holds.
+- Response: [`AssemblyView`](#type-assemblyview) & { standing?: [`StandingView`](#type-standingview)[] }
 - Stream: no
-- Decisions: [ADR-0069](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)
+- Decisions: [ADR-0017](decisions/0017-pool-over-a-source-port.md), [ADR-0069](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)
 
 <a id="get-workflows-wrapper-chart-schema"></a>
 
@@ -76,7 +76,16 @@ No token. Structure and observation: no run context, and no control.
 - Summary: The Console page to a browser; a 404 to a JSON caller.
 - Response: text/html (the Console shell)
 - Stream: no
-- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-the-instance-token.md)
+- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md)
+
+<a id="get-console-config"></a>
+
+### `GET /console/config`
+
+- Summary: What the Console needs before a login: each JWT issuer that offers a login, and its client id. Both are public values.
+- Response: { login: Array<{ issuer, clientId }> }
+- Stream: no
+- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="get-workflows-name"></a>
 
@@ -85,7 +94,7 @@ No token. Structure and observation: no run context, and no control.
 - Summary: The Console page to a browser; to a JSON caller, the workflow and its declared input schema.
 - Response: { name, machineId, input: JSON Schema | null }, or text/html
 - Stream: no
-- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-the-instance-token.md), [ADR-0033](decisions/0033-a-machine-declares-the-input-that-starts-it.md)
+- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md), [ADR-0033](decisions/0033-a-machine-declares-the-input-that-starts-it.md)
 
 <a id="get-workflows-name-machine"></a>
 
@@ -130,7 +139,7 @@ No token. Structure and observation: no run context, and no control.
 - Summary: The Console's stylesheet.
 - Response: text/css
 - Stream: no
-- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-the-instance-token.md)
+- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md)
 
 <a id="get-assets-elk-js"></a>
 
@@ -139,7 +148,7 @@ No token. Structure and observation: no run context, and no control.
 - Summary: The Console's graph layout library (the elkjs bundle).
 - Response: text/javascript
 - Stream: no
-- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-the-instance-token.md)
+- Decisions: [ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md)
 
 <a id="get-assets-file"></a>
 
@@ -178,8 +187,8 @@ Any token jr2 minted: the Instance token, or a Sandbox token. A Sandbox token re
 
 ### `GET /agents/:instanceId/surface`
 
-- Summary: An Agent's Menu and this Turn's Allowed picks. A Sandbox token reads only its own Sandbox's.
-- Response: [`AgentSurfaceView`](#type-agentsurfaceview)
+- Summary: An Agent's Menu, this Turn's Allowed picks, the conversation's pending notices and its slot's Steering messages. A control token reads only its own pod's, for the slot it states.
+- Response: [`AgentSurfaceView`](#type-agentsurfaceview) & { notices: Array<{ id, notice }>, steering?: Array<{ id, message }> }
 - Stream: no
 - Decisions: [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md), [ADR-0029](decisions/0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)
 
@@ -202,125 +211,239 @@ Any token jr2 minted: the Instance token, or a Sandbox token. A Sandbox token re
 - Stream: no
 - Decisions: [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md), [ADR-0024](decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)
 
+<a id="post-agents-instanceid-notices"></a>
+
+### `POST /agents/:instanceId/notices`
+
+- Summary: Acknowledge the notices and Steering messages a step boundary appended to the Turn: they are heard in its conversation.
+- Body: { heard: string[] }
+- Response: { heard: number }
+- Stream: no
+- Decisions: [ADR-0062](decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md), [ADR-0076](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)
+
+<a id="post-agents-instanceid-conversation"></a>
+
+### `POST /agents/:instanceId/conversation`
+
+- Summary: Keep a batch of a conversation's entries. Only the control token of the pod that the run's admission ledger names, for the ledger's slot; never the Instance token. An entry kept already adds nothing.
+- Body: { entries: Array<{ id, seq, at, kind, text }> }, at most 4 MiB
+- Response: { kept, cut }; 409 while the run's ledger does not name the conversation yet (send again); 404 for a run that is not known
+- Stream: no
+- Decisions: [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md), [ADR-0076](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)
+
 <a id="post-sandboxes-name-fetch"></a>
 
 ### `POST /sandboxes/:name/fetch`
 
-- Summary: Ask the node cache to fetch one Repo that this Sandbox mounts. A Sandbox token asks only for its own.
+- Summary: Ask the node cache to fetch one Repo that this Sandbox mounts. A fetch token asks only for its own.
 - Body: { identity }
 - Response: [`FetchAnswer`](#type-fetchanswer): { fetched } | { stale, asOf }
 - Stream: no
 - Decisions: [ADR-0053](decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md)
 
-<a id="band-instanceonly"></a>
+<a id="band-guarded"></a>
 
-## Instance token only
+## A Caller with a scope
 
-The Instance token alone: run control, starting a run, and full run state. A Sandbox token is refused.
+A Caller: the Instance token, a named Caller token, or a JWT. Each route needs one scope, for the Workflow of the run or the door that it addresses, and a 403 names the scope and the Workflow. The Instance token has every scope. A Sandbox token is not a Caller, and is refused. A Caller can state the party it acts for in the header `jr2-on-behalf-of`; jr2 records the claim and does not check it.
 
-<a id="put-workflows-wrapper-charts-name"></a>
+<a id="get-whoami"></a>
 
-### `PUT /workflows/:wrapper/charts/:name`
+### `GET /whoami`
 
-- Summary: Admit and keep a runtime Chart under a name. Its Workflow is `<wrapper>/<name>`.
-- Body: the Chart text alone
-- Response: 201 { name, origin, hash } when new, 200 when it replaced one; 422 { error, report } when refused
-- Stream: no
-- Decisions: [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)
-
-<a id="delete-workflows-wrapper-charts-name"></a>
-
-### `DELETE /workflows/:wrapper/charts/:name`
-
-- Summary: Remove a runtime Chart. A live run of it keeps its own text.
-- Response: 204
+- Summary: The request's Caller: how jr2 knows it, its name, what it may do, and the party it says it acts for.
+- Scope: any Caller
+- Response: [`Caller`](#type-caller)
 - Stream: no
-- Decisions: [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)
+- Decisions: [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="post-workflows-wrapper-charts-name-runs"></a>
 
 ### `POST /workflows/:wrapper/charts/:name/runs`
 
 - Summary: Start a run of a named Chart, as `POST /workflows/<wrapper>%2F<name>/runs` does.
+- Scope: `start`
 - Body: the Chart wrapper's input, without the Chart
 - Response: 201 { runId, instanceId }; 409 when the named Chart cannot run now
 - Stream: no
-- Decisions: [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)
+- Decisions: [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="post-workflows-name-runs"></a>
 
 ### `POST /workflows/:name/runs`
 
-- Summary: Start a run of a registered workflow. A `dispatch` from another Orchestrator sends the header `jr2-dispatched-by`, and a repeated start with its key answers the run that it started.
+- Summary: Start a run of a registered workflow. A `dispatch` from another Orchestrator sends the header `jr2-dispatched-by`, and a repeated start with its key answers the run that it started. With the header `jr2-key-only: true` too, the start is a key-only ask: it answers the run under the key, and starts nothing. For a standing Workflow, jr2 starts the run: the start only resumes a paused one, and `?drop-held=true` resumes it with no held item.
+- Scope: `start`
 - Body: the workflow's input, checked against its declared input schema
-- Response: 201 { runId, instanceId }; 200 { runId, instanceId, existing: true } for a repeated dispatch; 422 { error, report } when the door refuses a Chart in the input
+- Response: 201 { runId, instanceId }; 201 { runId, instanceId, resumed: true } for a resumed standing Workflow; 200 { runId, instanceId, existing: true } for a repeated dispatch; 200 { existing: false } for a key-only ask with no run under the key; 409 for a standing Workflow that is not paused, or a dispatch to one; 422 { error, report } when the door refuses a Chart in the input
 - Stream: no
-- Decisions: [ADR-0033](decisions/0033-a-machine-declares-the-input-that-starts-it.md), [ADR-0058](decisions/0058-a-harness-answers-the-orchestrator-alone.md), [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md), [ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)
+- Decisions: [ADR-0017](decisions/0017-pool-over-a-source-port.md), [ADR-0033](decisions/0033-a-machine-declares-the-input-that-starts-it.md), [ADR-0058](decisions/0058-a-harness-answers-the-orchestrator-alone.md), [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md), [ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="get-runs"></a>
 
 ### `GET /runs`
 
-- Summary: The live runs, with their full status.
-- Response: [`RunStatus`](#type-runstatus)[]
+- Summary: A page of the runs of the Workflows that the Caller may read, newest first: live runs by default; ?status=live|ended|all|<list> ?workflow ?since ?cursor ?limit.
+- Scope: `read`
+- Response: { runs: [`RunSummary`](#type-runsummary)[], next? }
 - Stream: no
-- Decisions: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md)
+- Decisions: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
-<a id="get-repos"></a>
+<a id="get-runs-resolve"></a>
 
-### `GET /repos`
+### `GET /runs/resolve`
 
-- Summary: The Repos as the cluster reports them.
-- Response: { dataPlane, repos: [`RepoStatus`](#type-repostatus)[] }
+- Summary: The run ids that start with a prefix (`?prefix=`, at least 4 characters), of the Workflows in any scope of the Caller.
+- Scope: any Caller
+- Response: { prefix, runIds: string[], truncated }
 - Stream: no
-- Decisions: [ADR-0048](decisions/0048-the-orchestrator-boots-without-its-repos.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)
+- Decisions: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
-<a id="get-runs-resolve"></a>
+<a id="get-gates"></a>
 
-### `GET /runs/resolve`
+### `GET /gates`
 
-- Summary: The run ids that start with a prefix (`?prefix=`, at least 4 characters).
-- Response: { prefix, runIds: string[], truncated }
+- Summary: The Gate inbox: every open Gate of every live run that the Caller may answer, oldest first, never a run's context; ?workflow.
+- Scope: `answer`
+- Response: { gates: [`GateInboxEntry`](#type-gateinboxentry)[] }
 - Stream: no
-- Decisions: [ADR-0009](decisions/0009-cli-and-instance-interface.md)
+- Decisions: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="get-runs-runid"></a>
 
 ### `GET /runs/:runId`
 
-- Summary: One run's status, live or settled, with its open Gates.
-- Response: [`RunStatus`](#type-runstatus) & { gates: [`GateView`](#type-gateview)[] }
+- Summary: One run's status, live or settled, with its open Gates. `read` opens the status, and `answer` opens the Gates that the Caller may answer: with `answer` alone the answer is the run's observation and those Gates, and never its context.
+- Scope: `read` or `answer`; each opens its own part of the answer
+- Response: [`RunStatus`](#type-runstatus) & { gates: [`GateView`](#type-gateview)[] }; [`RunStatus`](#type-runstatus) with `read` alone; [`RunObservation`](#type-runobservation) & { gates: [`GateView`](#type-gateview)[] } with `answer` alone
 - Stream: no
-- Decisions: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0011](decisions/0011-workflow-defined-events.md)
+- Decisions: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="post-runs-runid-gates-gate-events"></a>
 
 ### `POST /runs/:runId/gates/:gate/events`
 
-- Summary: Deliver an event to an open Gate of a run.
+- Summary: Deliver an event to an open Gate of a run. A Caller whose `answer` names single Gates of the Workflow is refused 403 for another Gate.
+- Scope: `answer`
 - Body: { type, ...payload }, checked against the Gate's schema for that event
 - Response: { ok: true }; 409 { error, acceptsNow } when the run does not take it now
 - Stream: no
-- Decisions: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md)
+- Decisions: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
 
 <a id="get-runs-runid-events"></a>
 
 ### `GET /runs/:runId/events`
 
 - Summary: One run's full activity until it settles; a settled run's final status, once.
-- Response: SSE: status, emit, retry, admission, pick, placing, placed, child-error, effect, gone
+- Scope: `read`
+- Response: SSE: status, emit, retry, admission, pick, placing, placed, child-error, looked, hook-refused, pool, effect, gone
+- Stream: yes: Server-Sent Events
+- Decisions: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0022](decisions/0022-observation-is-a-level-triggered-feed.md), [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md), [ADR-0064](decisions/0064-a-workspace-waits-for-capacity.md), [ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
+
+<a id="get-runs-runid-conversations"></a>
+
+### `GET /runs/:runId/conversations`
+
+- Summary: A run's kept conversations, the first first: one row for each conversation of each Agent, Menu-only Agents too, with its Agent slot.
+- Scope: `read`
+- Response: Array<{ agent, slot?, instanceId, open, bytes, cut, swept?: "no space" }>
+- Stream: no
+- Decisions: [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md), [ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)
+
+<a id="get-runs-runid-conversations-instanceid"></a>
+
+### `GET /runs/:runId/conversations/:instanceId`
+
+- Summary: The entries of one kept conversation after a sequence number (`?after=<seq>`, `?limit=`, 1000 by default). The Instance ID is URL-encoded.
+- Scope: `read`
+- Response: Array<{ id, seq, at, agent, kind, text }>
+- Stream: no
+- Decisions: [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md)
+
+<a id="get-runs-runid-conversations-instanceid-events"></a>
+
+### `GET /runs/:runId/conversations/:instanceId/events`
+
+- Summary: Follow one kept conversation: its entries after `?after=<seq>`, then each new one, until the conversation is not open.
+- Scope: `read`
+- Response: SSE: entry, end
 - Stream: yes: Server-Sent Events
-- Decisions: [ADR-0022](decisions/0022-observation-is-a-level-triggered-feed.md), [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md), [ADR-0064](decisions/0064-a-workspace-waits-for-capacity.md), [ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+- Decisions: [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md)
 
 <a id="post-runs-runid-events"></a>
 
 ### `POST /runs/:runId/events`
 
 - Summary: Cancel a run: it ends, and its Workspaces go unless `keep` is true.
+- Scope: `cancel`
 - Body: { type: "CANCEL", keep?: boolean }
 - Response: { ok: true }
 - Stream: no
-- Decisions: [ADR-0002](decisions/0002-duplex-streaming-actor.md), [ADR-0025](decisions/0025-cancel-ends-a-run-stop-parks-it.md)
+- Decisions: [ADR-0002](decisions/0002-duplex-streaming-actor.md), [ADR-0025](decisions/0025-cancel-ends-a-run-stop-parks-it.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
+
+<a id="get-runs-runid-agents"></a>
+
+### `GET /runs/:runId/agents`
+
+- Summary: The Agent slots of a run that a Steering message can go to: one row for each Agent of each live Machine instance.
+- Scope: `steer`
+- Response: Array<{ agent, open, steerable }>; [] for a run that is not live
+- Stream: no
+- Decisions: [ADR-0002](decisions/0002-duplex-streaming-actor.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
+
+<a id="post-runs-runid-steering"></a>
+
+### `POST /runs/:runId/steering`
+
+- Summary: Send a Steering message to one Agent slot of a live run: its open Turn hears it at a step boundary, or else its next Turn.
+- Scope: `steer`
+- Body: { agent, text }, `text` at most 16 KiB
+- Response: 202 { id, agent, open }; 413 for a longer text; 409 { error, agents? } when no live Machine instance holds the slot; 403 when the Agent is not steerable
+- Stream: no
+- Decisions: [ADR-0002](decisions/0002-duplex-streaming-actor.md), [ADR-0062](decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
+
+<a id="band-instanceonly"></a>
+
+## Instance token only
+
+The Instance token alone: the routes that no scope opens. A named Caller token is refused, whatever its scopes, and so is a Sandbox token.
+
+<a id="get-hooks-name"></a>
+
+### `GET /hooks/:name`
+
+- Summary: A Hook's log, newest first: each delivery that jr2 keeps (`runs.retain`, 30 days by default), with what the door did with it. `?limit=` (default 50, at most 1000).
+- Response: { hook, declared, lines: [`HookLogLine`](#type-hooklogline)[] }
+- Stream: no
+- Decisions: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)
+
+<a id="put-workflows-wrapper-charts-name"></a>
+
+### `PUT /workflows/:wrapper/charts/:name`
+
+- Summary: Admit and keep a runtime Chart under a name. Its Workflow is `<wrapper>/<name>`.
+- Body: the Chart text alone
+- Response: 201 { name, origin, hash } when new, 200 when it replaced one; 422 { error, report } when refused
+- Stream: no
+- Decisions: [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)
+
+<a id="delete-workflows-wrapper-charts-name"></a>
+
+### `DELETE /workflows/:wrapper/charts/:name`
+
+- Summary: Remove a runtime Chart. A live run of it keeps its own text.
+- Response: 204
+- Stream: no
+- Decisions: [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)
+
+<a id="get-repos"></a>
+
+### `GET /repos`
+
+- Summary: The Repos as the cluster reports them.
+- Response: { dataPlane, repos: [`RepoStatus`](#type-repostatus)[] }
+- Stream: no
+- Decisions: [ADR-0048](decisions/0048-the-orchestrator-boots-without-its-repos.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)
 
 <a id="band-publishonly"></a>
 
@@ -334,12 +457,154 @@ The publish token alone, which `jr2 up` reads from the instance Secret. The Inst
 
 - Summary: Publish the next Assembly. `jr2 up` calls it, and nothing else. A refused Assembly leaves the current one current.
 - Body: the Assembly as a tar stream, with the headers `jr2-kit-version` and `jr2-assembly-hash`
-- Response: 200 with the Assembly, its Workflows, the held Assemblies and the ones collected; 400, 409 or 422 with the reason
+- Response: 200 with the Assembly, its Workflows, the held Assemblies, the ones collected and each standing Workflow's state; 400, 409 or 422 with the reason
 - Stream: no
 - Decisions: [ADR-0069](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)
 
+<a id="band-hook"></a>
+
+## A Hook's verifier
+
+No bearer token: the Hook's own verifier checks each delivery, as its kind tells (a `token` header, an `ed25519` signature or a `mac`). A delivery that fails the verifier, or whose signed time is more than 300 seconds from the Orchestrator's clock, gets 401.
+
+<a id="post-hooks-name"></a>
+
+### `POST /hooks/:name`
+
+- Summary: A delivery of an outside service to the Hook that the current Assembly's config names. The Hook's verifier authenticates it, and it goes to the open Gates whose handlers hear its kind and event key. 413 for a body above 2 MiB, before the verifier and with no more of the body read than that; 401 for a delivery that fails the verifier, 404 for a name that no Hook has, 503 with no current Assembly, and 503 when a standing Pool that hears it has no live run and is not paused, or when the delivery followed the Pool's hand-overs 3 times and the Pool handed its run over again. A 503 claims no delivery id.
+- Body: the service's own request
+- Response: the kind's answer to a handshake, or [`HookOutcome`](#type-hookoutcome): { delivery, seen, delivered, refused, ignored, sources, payloadRefused? }
+- Stream: no
+- Decisions: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)
+
 ## Types
 
+<a id="type-caller"></a>
+
+### `Caller`
+
+```ts
+type Caller = {
+  via: "token" | "jwt" | "hook";
+  name: string;
+  shown?: string;
+  may: Scopes;
+  onBehalfOf?: string;
+};
+```
+
+A request's Caller ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): who acts, through which authenticator, and what it may do.
+
+**Fields**
+
+- `via`: `"token" | "jwt" | "hook"`
+
+  The authenticator that made the Caller: `token` (the Instance token or a named token), `jwt`
+  or `hook`.
+- `name`: `string`
+
+  The Caller's name for that authenticator: `instance`, a named token's name, a JWT's `sub`, a
+  Hook's name.
+- `shown` (optional): `string`
+
+  The name that jr2 shows, when it is not `name` (a JWT's `email`).
+- `may`: [`Scopes`](config.md#callers-tokens-name-may)
+
+  What the Caller may do.
+- `onBehalfOf` (optional): `string`
+
+  The Caller's claim about the party it acts for. jr2 records it and never checks it.
+
+<a id="type-hookoutcome"></a>
+
+### `HookOutcome`
+
+```ts
+type HookOutcome = {
+  delivery: string;
+  seen: boolean;
+  delivered: HookFanIn["delivered"];
+  refused: HookFanIn["refused"];
+  ignored: number;
+  sources: HookFanIn["sources"];
+  payloadRefused?: { kind: string; key: string; issues: unknown[] };
+};
+```
+
+The answer to one delivery ([ADR-0011](decisions/0011-workflow-defined-events.md)): `delivery` is its id, `seen` says it was a repeat,
+`delivered` the Gates that took it, `refused` the Gates that did not and why, `ignored` how many
+open Gates of its kind and key gave nothing, and `sources` each Source's verdict ([ADR-0017](decisions/0017-pool-over-a-source-port.md)).
+`payloadRefused` names the kind and the event key of a payload that the parse refused, with zod's
+issues.
+
+**Fields**
+
+- `delivery`: `string`
+- `seen`: `boolean`
+- `delivered`: `HookFanIn["delivered"]`
+- `refused`: `HookFanIn["refused"]`
+- `ignored`: `number`
+- `sources`: `HookFanIn["sources"]`
+- `payloadRefused` (optional): `object`
+
+  - `kind`: `string`
+  - `key`: `string`
+  - `issues`: `unknown[]`
+
+<a id="type-hooklogline"></a>
+
+### `HookLogLine`
+
+```ts
+type HookLogLine = {
+  hook: string;
+  at: string;
+  kind:
+    | "pending"
+    | "delivered"
+    | "seen"
+    | "hold-full"
+    | "no-live-run"
+    | "handshake"
+    | "payload-refused"
+    | "unreadable"
+    | "too-large"
+    | "follow-up";
+  status: number;
+  delivery?: string;
+  digest?: string;
+  key?: string;
+  detail?: unknown;
+};
+```
+
+One line of the hook log ([ADR-0011](decisions/0011-workflow-defined-events.md)): what the door did with one delivery of one Hook, and when.
+`kind` says which line it is: `delivered` (the fan-in ran; `outcome` holds what it did), `seen` (a
+repeat), `hold-full` (the fan-in ran and every Source was full, [ADR-0017](decisions/0017-pool-over-a-source-port.md): the line does not claim
+the id, so a send again is heard), `no-live-run` (the fan-in ran, and a standing Pool that hears the
+kind and key has no live run and is not paused: 503, and the line does not claim the id either),
+`handshake`, `payload-refused` (with zod's `issues`), `unreadable` (the kind could not
+read the request: `error`) or `follow-up` (the follow-up post of an answer that a person reads
+failed, or went to a url outside the kind's `posts`: `post` and `error`; its `status` is 0). A
+`reply` that threw is in the `replyErrors` of its delivery's `detail`. `status` is the status that
+the rules give, which is the status of the answer unless a person reads the answer: that answer is
+200 ([ADR-0011](decisions/0011-workflow-defined-events.md)).
+
+**Fields**
+
+- `hook`: `string`
+- `at`: `string`
+- `kind`: `"pending" | "delivered" | "seen" | "hold-full" | "no-live-run" | "handshake" | "payload-refused" | "unreadable" | "too-large" | "follow-up"`
+- `status`: `number`
+- `delivery` (optional): `string`
+- `digest` (optional): `string`
+- `key` (optional): `string`
+
+  The event key, when the kind read one.
+- `detail` (optional): `unknown`
+
+  What the line says: the outcome, zod's issues, the error.
+
 <a id="type-workflowlisting"></a>
 
 ### `WorkflowListing`
@@ -391,6 +656,40 @@ type AssemblyView = {
 - `current`: `{ hash: string; kitVersion: string; workflows: string[]; } | null`
 - `held`: `HeldAssembly[]`
 
+<a id="type-standingview"></a>
+
+### `StandingView`
+
+```ts
+type StandingView = {
+  workflow: string;
+  pool: string;
+  callee: string;
+  state: "live" | "paused" | "waiting";
+  run?: string;
+  held: number;
+  why?: "cancel" | "errors" | "bound";
+};
+```
+
+A standing Workflow as `jr2 up` and `jr2 status` print it ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): its Pool, its callee, its
+state, its run, and how many items it holds. `live`: a run is live. `paused`: a cancel (`why`:
+`cancel`), or a fourth run in a row in which no item that the run took started a run, after 3
+hand-overs: the last one ended `error` or `failed` (`errors`), or took its bound (`bound`). The
+held items are in the blob of `run`.
+`waiting`: no run is live, and jr2 starts one after the back-off. Structure and counts only: no
+key and no item, so it is on the open band with the Assembly.
+
+**Fields**
+
+- `workflow`: `string`
+- `pool`: `string`
+- `callee`: `string`
+- `state`: `"live" | "paused" | "waiting"`
+- `run` (optional): `string`
+- `held`: `number`
+- `why` (optional): `"cancel" | "errors" | "bound"`
+
 <a id="type-machinedoc"></a>
 
 ### `MachineDoc`
@@ -433,7 +732,7 @@ type RunObservation = {
   children: RunChild[];
   bound?: true;
   chartHashes?: string[];
-  dispatchedBy?: Omit<DispatchedBy, "effect">;
+  dispatchedBy?: Omit<DispatchedBy, "effect" | "key" | "hook">;
   dispatched?: Array<{ slot: string; run: string }>;
 };
 ```
@@ -469,7 +768,7 @@ parallel work (`"F-1"`) — the same class of thing as a state key.
 
   The hashes of the Charts it binds now (see `RunStatus.chartHashes`). Structure: a hash
   of a Chart's text, which `runMachine` already serves on the open band.
-- `dispatchedBy` (optional): `Omit<DispatchedBy, "effect">`
+- `dispatchedBy` (optional): `Omit<DispatchedBy, "effect" | "key" | "hook">`
 
   The run that dispatched this one, its slot, and the chain's depth ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)). Routing — two
   ids, a slot name and a number — the class of thing `runId` and `value` are, so [ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md)'s line
@@ -479,13 +778,116 @@ parallel work (`"F-1"`) — the same class of thing as a state key.
   The runs it dispatched, by slot ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)): the same routing as `dispatchedBy`, the other
   direction.
 
+<a id="type-runsummary"></a>
+
+### `RunSummary`
+
+```ts
+type RunSummary = {
+  runId: string;
+  workflow: string;
+  status: ShownStatus;
+  reason?: string;
+  startedBy?: RunStarter;
+  startedAt: string;
+  endedAt?: string;
+  assembly?: string;
+  openGates: number;
+  placing?: string[];
+  dispatchedBy?: DispatchedBy;
+  swept?: "conversation swept: no space";
+};
+```
+
+One run as `GET /runs` lists it ([ADR-0009](decisions/0009-cli-and-instance-interface.md)): a summary, not the whole `RunStatus`. `status` is
+`active` for a live run, else the store's word for how it ended. `reason` says why, where the
+Machine did not: the host's reason (`drifted`, `lost`, [ADR-0030](decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md)), the Failure's reason
+(`failed`, [ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)) or the fault (`error`). `endedAt` is the terminal write of an ended run.
+`openGates` counts the Gates open now, so it is 0 for an ended run. `placing` names the child
+paths of the Workspaces that wait for capacity ([ADR-0064](decisions/0064-a-workspace-waits-for-capacity.md)), and `dispatchedBy` the run that
+started this one ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)).
+
+**Fields**
+
+- `runId`: `string`
+- `workflow`: `string`
+- `status`: [`ShownStatus`](#type-shownstatus)
+- `reason` (optional): `string`
+- `startedBy` (optional): [`RunStarter`](#type-runstarter)
+- `startedAt`: `string`
+- `endedAt` (optional): `string`
+- `assembly` (optional): `string`
+- `openGates`: `number`
+- `placing` (optional): `string[]`
+- `dispatchedBy` (optional): [`DispatchedBy`](#type-dispatchedby)
+- `swept` (optional): `"conversation swept: no space"`
+
+  The space guard deleted the run's kept conversations ([ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)); the row stays.
+
+<a id="type-repostatus"></a>
+
+### `RepoStatus`
+
+```ts
+type RepoStatus = {
+  key: string;
+  url: string;
+  identity?: string;
+  bound: boolean;
+  lastAttached?: string;
+  nodes: RepoNodeState[];
+};
+```
+
+One `Repo` resource as the instance reports it (`GET /repos`).
+
+**Fields**
+
+- `key`: `string`
+
+  The cache key: the resource's name, the hostPath leaf, `/repos/<key>`.
+- `url`: `string`
+
+  The Binding's own spelling — what the cache clones.
+- `identity` (optional): `string`
+- `bound`: `boolean`
+
+  A registered Machine binds it — never evicted by `jr2 gc`.
+- `lastAttached` (optional): `string`
+
+  When a run last attached it — the eviction clock for a Repo nothing binds. Absent while only
+  the boot has stated it: a bound Repo no run has attached yet.
+- `nodes`: `RepoNodeState[]`
+
+<a id="type-gateinboxentry"></a>
+
+### `GateInboxEntry`
+
+```ts
+type GateInboxEntry = { runId: string; workflow: string } & GateView & {
+    openedAt: string;
+    hook?: string[];
+  };
+```
+
+One entry of the Gate inbox (`GET /gates` — [ADR-0011](decisions/0011-workflow-defined-events.md)): an open Gate as [`GateView`](#type-gateview) gives it,
+with its run, the run's Workflow, and when it opened, ISO-8601. `hook` names the Hook kinds that
+the Gate hears, when it hears one. Never the run's context ([ADR-0014](decisions/0014-observation-is-open-run-state-is-not.md)).
+
+**Fields**: each field of [`GateView`](#type-gateview), and these:
+
+- `runId`: `string`
+- `workflow`: `string`
+- `openedAt`: `string`
+- `hook` (optional): `string[]`
+
 <a id="type-runstatus"></a>
 
 ### `RunStatus`
 
 ```ts
 type RunStatus = RunRecord & {
-  status: string;
+  status: ShownStatus;
   value: unknown;
   context: unknown;
   children: RunChild[];
@@ -494,10 +896,16 @@ type RunStatus = RunRecord & {
   fault?: string;
   reason?: string;
   assembly?: string;
+  swept?: "conversation swept: no space";
   bound?: true;
   chartHashes?: string[];
   output?: unknown;
   dispatched?: Dispatched[];
+  cancelledBy?: CallerRecord;
+  handedOverTo?: string;
+  answers?: GateAnswer[];
+  steering?: SteeringRecord[];
+  worktrees?: RunWorktree[];
 };
 ```
 
@@ -507,7 +915,7 @@ A run's current observable state. `fault` carries the error message when status
 
 **Fields**: each field of [`RunRecord`](#type-runrecord), and these:
 
-- `status`: `string`
+- `status`: [`ShownStatus`](#type-shownstatus)
 - `value`: `unknown`
 - `context`: `unknown`
 - `children`: `RunChild[]`
@@ -521,7 +929,7 @@ A run's current observable state. `fault` carries the error message when status
 - `held`: `RunHeld[]`
 
   Every pick of this run that is outstanding ([ADR-0024](decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)): the Agent, its pick, and since when —
-  the Console's "held since". There is no default time bound on a held Turn; this is how a
+  the Console's "outstanding since". There is no default time bound on a held Turn; this is how a
   human sees one. Behind the token, like `context`: a pick names what the Agent did.
 - `fault` (optional): `string`
 - `reason` (optional): `string`
@@ -534,6 +942,10 @@ A run's current observable state. `fault` carries the error message when status
 
   The hash of the Assembly the run started under ([ADR-0069](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md)). Absent for a run no Assembly
   started.
+- `swept` (optional): `"conversation swept: no space"`
+
+  The space guard deleted the run's kept conversations ([ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md), [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md)): `jr2 logs` and
+  the Console show this in place of them. The run's row stays.
 - `bound` (optional): `true`
 
   The run binds at least one Chart ([ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)): its Machine is the bound one, `runMachine`.
@@ -554,41 +966,29 @@ A run's current observable state. `fault` carries the error message when status
   The runs this run's `dispatch` Effects started, oldest first ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)): the chain's other
   direction, read off the caller's own ledger rows. A foreign dispatch's run is a run of the
   Orchestrator its target names. Absent when it started none.
+- `cancelledBy` (optional): [`CallerRecord`](authoring-surface/type-callerrecord.md)
 
-<a id="type-repostatus"></a>
-
-### `RepoStatus`
-
-```ts
-type RepoStatus = {
-  key: string;
-  url: string;
-  identity?: string;
-  bound: boolean;
-  lastAttached?: string;
-  nodes: RepoNodeState[];
-};
-```
-
-One `Repo` resource as the instance reports it (`GET /repos`).
-
-**Fields**
-
-- `key`: `string`
-
-  The cache key: the resource's name, the hostPath leaf, `/repos/<key>`.
-- `url`: `string`
+  The Caller that cancelled the run ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). Behind the token: `observe` never
+  carries it.
+- `handedOverTo` (optional): `string`
 
-  The Binding's own spelling — what the cache clones.
-- `identity` (optional): `string`
-- `bound`: `boolean`
+  The run that took over from this standing run ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): a hand-over ends the run `done`.
+- `answers` (optional): `GateAnswer[]`
 
-  A registered Machine binds it — never evicted by `jr2 gc`.
-- `lastAttached` (optional): `string`
+  The answers to the run's Gates, oldest first, each with the Caller that gave it ([ADR-0011](decisions/0011-workflow-defined-events.md),
+  [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): the last `GATE_ANSWERS_KEPT`. An event that a Gate's `look` gives is not an
+  answer, and is not here. Behind the token. Absent when no Gate was answered.
+- `steering` (optional): `SteeringRecord[]`
 
-  When a run last attached it — the eviction clock for a Repo nothing binds. Absent while only
-  the boot has stated it: a bound Repo no run has attached yet.
-- `nodes`: `RepoNodeState[]`
+  The run's Steering messages, oldest first ([ADR-0002](decisions/0002-duplex-streaming-actor.md)): each one's Agent slot, author, text,
+  time and outcome — the newest 100, and each one still held. Behind the token, like `context`.
+  Absent when the run got none.
+- `worktrees` (optional): `RunWorktree[]`
+
+  The Worktrees this run's cuts made, oldest first ([ADR-0075](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)), read off its ledger's settled
+  `ready` rows, so an Agent's `git switch` does not change them. A re-cut of one path and branch
+  is one entry. Behind the token, like `context`: a branch name is the workflow's data. Absent
+  when the run cut none.
 
 <a id="type-gateview"></a>
 
@@ -632,6 +1032,7 @@ type AgentSurfaceView = {
   instanceId: string;
   runId: string;
   sandbox?: string;
+  slot?: string;
   menu: SurfaceEvent[];
   allowed: string[];
 };
@@ -655,6 +1056,10 @@ sandbox), and serving it lets a caller fail loudly on a surface that is not its
 - `instanceId`: `string`
 - `runId`: `string`
 - `sandbox` (optional): `string`
+- `slot` (optional): `string`
+
+  The slot this surface belongs to ([ADR-0076](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)): its Agent's actor path and agent name — the slot
+  the Harness must state to speak here. Absent on a registration no pod hosts.
 - `menu`: `SurfaceEvent[]`
 - `allowed`: `string[]`
 
@@ -763,6 +1168,81 @@ when nothing has ever fetched it, which the program prints as "an unknown time".
   - `stale`: `string`
   - `asOf`: `string | null`
 
+<a id="type-scopes"></a>
+
+### `Scopes`
+
+```ts
+type Scopes = {
+  start?: ScopeGrant;
+  answer?: AnswerGrant;
+  cancel?: ScopeGrant;
+  read?: ScopeGrant;
+  steer?: ScopeGrant;
+};
+```
+
+What a Caller may do: five scopes, each one for the Workflows that it names ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A scope
+that is absent opens nothing. Which scope opens which route is in the HTTP API Reference.
+
+A Caller's scope does not limit what its run dispatches: a Caller with `start` on `triage` starts
+a run whose Machine can dispatch `deploy`. The Machine is the author's, and it is the boundary of
+what its run does.
+
+**Fields**
+
+- `start` (optional): [`ScopeGrant`](config.md#callers-tokens-name-may-start)
+
+  Start a run.
+- `answer` (optional): [`AnswerGrant`](config.md#callers-tokens-name-may-answer)
+
+  Answer a Gate, and read a run's open Gates without its context. A list item
+  `{ workflow, gates }` opens only the Gates that it names, by invoke id (see [`GateGrant`](#type-gategrant)).
+- `cancel` (optional): [`ScopeGrant`](config.md#callers-tokens-name-may-start)
+
+  Cancel a run.
+- `read` (optional): [`ScopeGrant`](config.md#callers-tokens-name-may-start)
+
+  Read a run's state: its status, its context and its feed.
+- `steer` (optional): [`ScopeGrant`](config.md#callers-tokens-name-may-start)
+
+  Send a Steering message to an Agent of a run.
+
+<a id="type-hookfanin"></a>
+
+### `HookFanIn`
+
+```ts
+type HookFanIn = {
+  delivered: Array<{ run: string; workflow: string; gate: string; event: string }>;
+  refused: Array<{ run: string; gate: string; event?: string; reason: string }>;
+  ignored: number;
+  sources: SourceLine[];
+  waiting?: string[];
+  replies?: HookReply[];
+};
+```
+
+What a Hook's fan-in did ([ADR-0011](decisions/0011-workflow-defined-events.md)): the Gates that took the delivery, the ones that did not and
+why, and how many open Gates of its kind and key gave nothing.
+
+**Fields**
+
+- `delivered`: `Array<{ run: string; workflow: string; gate: string; event: string; }>`
+- `refused`: `Array<{ run: string; gate: string; event?: string; reason: string; }>`
+- `ignored`: `number`
+- `sources`: `SourceLine[]`
+
+  Each Source's verdict ([ADR-0017](decisions/0017-pool-over-a-source-port.md)), one line for each Pool whose Source hears the kind and key.
+- `waiting` (optional): `string[]`
+
+  The standing Workflows whose Source hears the kind and key, and that have no live run and are
+  not paused ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): a hand-over waits out its back-off. The door answers 503.
+- `replies` (optional): `HookReply[]`
+
+  For a delivery whose answer a person reads: the `reply` of each target that has one, in the
+  order of the fan-out ([ADR-0011](decisions/0011-workflow-defined-events.md)). The door joins them; it never puts them in the outcome.
+
 <a id="type-chartorigin"></a>
 
 ### `ChartOrigin`
@@ -858,7 +1338,15 @@ the same child machine are told apart.
 ### `DispatchedBy`
 
 ```ts
-type DispatchedBy = { run: string; slot: string; effect: string; depth: number; instance?: string };
+type DispatchedBy = {
+  run: string;
+  slot: string;
+  effect: string;
+  depth: number;
+  instance?: string;
+  key?: string;
+  hook?: { name: string; delivery: string; onBehalfOf?: string };
+};
 ```
 
 Which run dispatched a run ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)): the caller's run id, the slot of its `dispatch` Effect, and
@@ -875,25 +1363,145 @@ verify: opaque text, never resolved.
 - `effect`: `string`
 - `depth`: `number`
 - `instance` (optional): `string`
+- `key` (optional): `string`
+
+  The idempotency key when a Pool of runs started the run ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): the item's id. The store
+  scopes it to the callee Workflow, as it scopes `effect`. Absent: the key is `effect`.
+- `hook` (optional): `object`
+
+  The Hook delivery that carried the item to the Pool ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): the Hook's name, the delivery
+  id, and the party that the signed payload names. Absent for an item that a read or `next` gave.
+
+  - `name`: `string`
+  - `delivery`: `string`
+  - `onBehalfOf` (optional): `string`
+
+<a id="type-shownstatus"></a>
+
+### `ShownStatus`
+
+```ts
+type ShownStatus = typeof LIVE_STATUS | EndedStatus;
+```
+
+A run status as jr2 shows it, on every route and feed: `LIVE_STATUS` while the run is
+live, else how it ended. The store's own `live` and xstate's `stopped` are never shown.
+
+<a id="type-runstarter"></a>
+
+### `RunStarter`
+
+```ts
+type RunStarter =
+  | ({ kind: "caller" } & CallerRecord)
+  | { kind: "run"; run: string; slot: string }
+  | { kind: "jr2"; why: "boot" | "publish" | "hand-over" | "resume" };
+```
+
+Who started a run ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): a Caller on a guarded route; a run, through a local `dispatch`
+([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)); or jr2 itself, for a standing run ([ADR-0017](decisions/0017-pool-over-a-source-port.md)), at `boot`, at a `publish`, at a
+`hand-over`, or at a `resume`. A run that a foreign `dispatch` started records the Caller whose
+credential the other Instance sent.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `kind`, `via`, `name`, `shown`, `onBehalfOf`
+
+  - `kind`: `"caller"`
+  - `via`: `Caller["via"]`
+  - `name`: `string`
+  - `shown` (optional): `string`
+
+    The name that jr2 shows, when it is not `name` (a JWT's `email`).
+  - `onBehalfOf` (optional): `string`
+
+    The Caller's claim about the party it acts for. jr2 records it and never checks it, except for
+    a Hook, whose signature covers it.
+- Form 2: `kind`, `run`, `slot`
+
+  - `kind`: `"run"`
+  - `run`: `string`
+  - `slot`: `string`
+- Form 3: `kind`, `why`
+
+  - `kind`: `"jr2"`
+  - `why`: `"boot" | "publish" | "hand-over" | "resume"`
+
+<a id="type-reponodestate"></a>
+
+### `RepoNodeState`
+
+```ts
+type RepoNodeState = {
+  node: string;
+  present: boolean;
+  synced: boolean;
+  attempted?: "Probe" | "Clone" | "Fetch";
+  lastAttempt?: string;
+  lastFetched?: string;
+  lastError?: string;
+};
+```
+
+One node's view of a Repo, as the cache agent reports it on the resource's status.
+
+**Fields**
+
+- `node`: `string`
+- `present`: `boolean`
+
+  A clone exists on this node.
+- `synced`: `boolean`
+
+  The last attempt — a probe, a clone, or a fetch — succeeded.
+- `attempted` (optional): `"Probe" | "Clone" | "Fetch"`
+
+  Which of the three the last attempt was. A failed Probe is `jr2 status`'s signal for a Repo
+  no pod on the node mounts yet; only a failed Clone fails a Sandbox waiting on that node.
+- `lastAttempt` (optional): `string`
+- `lastFetched` (optional): `string`
+
+  The last successful clone or fetch.
+- `lastError` (optional): `string`
+
+  git's own words; absent when synced.
 
 <a id="type-runrecord"></a>
 
 ### `RunRecord`
 
 ```ts
-type RunRecord = { runId: string; workflow: string; instanceId: string; dispatchedBy?: DispatchedBy };
+type RunRecord = {
+  runId: string;
+  workflow: string;
+  instanceId: string;
+  startedAt: string;
+  dispatchedBy?: DispatchedBy;
+  startedBy?: RunStarter;
+  resumedBy?: CallerRecord;
+};
 ```
 
 The serializable identity of a run — what reconcile sees and what restore rebuilds from.
 `dispatchedBy` is the run that started it through a `dispatch` Effect, and this run's depth in
 that chain, as the caller sent it ([ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)); absent for a run a human or a client started.
+`startedBy` is who started it ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): a Caller, a run, or jr2. Behind the token, like
+`context`: `observe` never carries it. Absent for a run that a host started with no
+starter, as a test does.
 
 **Fields**
 
 - `runId`: `string`
 - `workflow`: `string`
 - `instanceId`: `string`
+- `startedAt`: `string`
+
+  When the run started, ISO-8601 ([ADR-0009](decisions/0009-cli-and-instance-interface.md)): the order of `GET /runs`.
 - `dispatchedBy` (optional): [`DispatchedBy`](#type-dispatchedby)
+- `startedBy` (optional): [`RunStarter`](#type-runstarter)
+- `resumedBy` (optional): [`CallerRecord`](authoring-surface/type-callerrecord.md)
+
+  The Caller whose `jr2 run` resumed this standing run ([ADR-0017](decisions/0017-pool-over-a-source-port.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)).
 
 <a id="type-runwaiting"></a>
 
@@ -951,44 +1559,97 @@ ledger row was written.
 - `run`: `string`
 - `at`: `string`
 
-<a id="type-reponodestate"></a>
+<a id="type-callerrecord"></a>
 
-### `RepoNodeState`
+### `CallerRecord`
 
 ```ts
-type RepoNodeState = {
-  node: string;
-  present: boolean;
-  synced: boolean;
-  attempted?: "Probe" | "Clone" | "Fetch";
-  lastAttempt?: string;
-  lastFetched?: string;
-  lastError?: string;
+type CallerRecord = {
+  via: Caller["via"];
+  name: string;
+  shown?: string;
+  onBehalfOf?: string;
 };
 ```
 
-One node's view of a Repo, as the cache agent reports it on the resource's status.
+A Caller as a run records it ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): who acted, and the party it says it acted for. Never its
+scopes.
 
 **Fields**
 
-- `node`: `string`
-- `present`: `boolean`
+- `via`: `Caller["via"]`
+- `name`: `string`
+- `shown` (optional): `string`
 
-  A clone exists on this node.
-- `synced`: `boolean`
+  The name that jr2 shows, when it is not `name` (a JWT's `email`).
+- `onBehalfOf` (optional): `string`
 
-  The last attempt — a probe, a clone, or a fetch — succeeded.
-- `attempted` (optional): `"Probe" | "Clone" | "Fetch"`
+  The Caller's claim about the party it acts for. jr2 records it and never checks it, except for
+  a Hook, whose signature covers it.
 
-  Which of the three the last attempt was. A failed Probe is `jr2 status`'s signal for a Repo
-  no pod on the node mounts yet; only a failed Clone fails a Sandbox waiting on that node.
-- `lastAttempt` (optional): `string`
-- `lastFetched` (optional): `string`
+<a id="type-gateanswer"></a>
 
-  The last successful clone or fetch.
-- `lastError` (optional): `string`
+### `GateAnswer`
 
-  git's own words; absent when synced.
+```ts
+type GateAnswer = { gate: string; type: string; at: string; answeredBy: CallerRecord; delivery?: string };
+```
+
+One answer to a Gate of a run, and the Caller that gave it ([ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). `delivery` is
+the Hook's delivery id when a Hook gave it: the run's `(delivery, gate)` pairs, so a restore never
+gives one delivery twice to one Gate.
+
+**Fields**
+
+- `gate`: `string`
+- `type`: `string`
+- `at`: `string`
+- `answeredBy`: [`CallerRecord`](authoring-surface/type-callerrecord.md)
+- `delivery` (optional): `string`
+
+<a id="type-steeringrecord"></a>
+
+### `SteeringRecord`
+
+```ts
+type SteeringRecord = {
+  id: string;
+  agent: string;
+  author: SteeringAuthor;
+  text: string;
+  at: string;
+  outcome: SteeringOutcome;
+};
+```
+
+The run's record of one Steering message: the slot it went to, its author, its text, when it was
+sent, and what became of it.
+
+**Fields**
+
+- `id`: `string`
+- `agent`: `string`
+- `author`: [`SteeringAuthor`](#type-steeringauthor)
+- `text`: `string`
+- `at`: `string`
+- `outcome`: [`SteeringOutcome`](#type-steeringoutcome)
+
+<a id="type-runworktree"></a>
+
+### `RunWorktree`
+
+```ts
+type RunWorktree = { slot: string; path: string; branch: string | null };
+```
+
+One Worktree a `worktree()` Effect of this run cut ([ADR-0075](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)): its Repo Slot, its path, and the
+branch of the cut. `branch` is `null` for a detached Worktree.
+
+**Fields**
+
+- `slot`: `string`
+- `path`: `string`
+- `branch`: `string | null`
 
 <a id="type-surfaceevent"></a>
 
@@ -1055,6 +1716,80 @@ whether work ran. Plain data; the Harness writes the words. `answer`: the value
   - `kind`: `"answer"`
   - `value`: `unknown`
 
+<a id="type-scopegrant"></a>
+
+### `ScopeGrant`
+
+```ts
+type ScopeGrant = "all" | readonly string[];
+```
+
+The Workflows that one scope of a Caller opens ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): `"all"` for every Workflow, or a list
+of Workflow names. A Chart wrapper's name in the list also opens each named Chart of that wrapper
+(`plan` opens `plan/weekly`), because a named Chart runs its wrapper's Machine. A named Chart's
+own name (`plan/weekly`) opens that Chart alone.
+
+<a id="type-answergrant"></a>
+
+### `AnswerGrant`
+
+```ts
+type AnswerGrant = "all" | readonly (string | GateGrant)[];
+```
+
+The Gates that the `answer` scope opens ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): `"all"`, or a list in which each item is a
+Workflow name, which opens every Gate of that Workflow, or a [`GateGrant`](#type-gategrant), which opens only
+the Gates that it names: `["triage", { workflow: "deploy", gates: ["approve"] }]`.
+
+<a id="type-sourceline"></a>
+
+### `SourceLine`
+
+```ts
+type SourceLine = { pool: string; workflow: string; source: string } & SourceVerdictLine;
+```
+
+One Source's verdict on one delivery ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): the Pool's run, its Workflow, the `source`
+Gate's id, and the verdict.
+
+**Fields**: each field of [`SourceVerdictLine`](#type-sourceverdictline), and these:
+
+- `pool`: `string`
+- `workflow`: `string`
+- `source`: `string`
+
+<a id="type-hookreply"></a>
+
+### `HookReply`
+
+```ts
+type HookReply = {
+  target: "source" | "gate";
+  workflow: string;
+  run: string;
+  gate: string;
+  text?: string;
+  skipped?: true;
+  error?: string;
+};
+```
+
+What one target's `reply` gave ([ADR-0011](decisions/0011-workflow-defined-events.md)): its place in the join (a Source or a Gate, its
+Workflow and its run), and its text, or the error of a `reply` that threw or gave no text. A
+`skipped` Source's text shows only when no other target gave one.
+
+**Fields**
+
+- `target`: `"source" | "gate"`
+- `workflow`: `string`
+- `run`: `string`
+- `gate`: `string`
+
+  The Gate's id, or the Pool's `source` Gate's id.
+- `text` (optional): `string`
+- `skipped` (optional): `true`
+- `error` (optional): `string`
+
 <a id="type-machinestatedoc"></a>
 
 ### `MachineStateDoc`
@@ -1201,6 +1936,57 @@ input names `accepts:` itself.
 - `agent` (optional): `string`
 - `names`: `string[]`
 
+<a id="type-endedstatus"></a>
+
+### `EndedStatus`
+
+```ts
+type EndedStatus = "done" | "failed" | "error" | "cancelled" | "lost" | "drifted";
+```
+
+How a run ended, as the store writes it ([ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md), [ADR-0025](decisions/0025-cancel-ends-a-run-stop-parks-it.md), [ADR-0030](decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md), [ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md), [ADR-0074](decisions/0074-an-unrouted-mechanism-event-is-refused-at-load-and-faults-the-run.md)).
+
+<a id="type-steeringauthor"></a>
+
+### `SteeringAuthor`
+
+```ts
+type SteeringAuthor =
+  | { kind: "caller"; via: "token" | "jwt" | "hook"; name: string; onBehalfOf?: string }
+  | { kind: "machine"; from?: { party: "agent" | "gate"; id: string } };
+```
+
+Who wrote a Steering message. `caller`: a Caller sent it from outside the run ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)), with
+the name jr2 shows and the party it says it acts for. `machine`: the Machine sent it with its
+`steer` action; `from` is the party whose words it relays, when it relays some.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `kind`, `via`, `name`, `onBehalfOf`
+
+  - `kind`: `"caller"`
+  - `via`: `"token" | "jwt" | "hook"`
+  - `name`: `string`
+  - `onBehalfOf` (optional): `string`
+- Form 2: `kind`, `from`
+
+  - `kind`: `"machine"`
+  - `from` (optional): `object`
+
+    - `party`: `"agent" | "gate"`
+    - `id`: `string`
+
+<a id="type-steeringoutcome"></a>
+
+### `SteeringOutcome`
+
+```ts
+type SteeringOutcome = "held" | "heard" | "not-delivered";
+```
+
+What became of one Steering message ([ADR-0002](decisions/0002-duplex-streaming-actor.md)): `held` until a Turn of its slot hears it,
+`heard` once one did, `not-delivered` when its Machine instance ended first.
+
 <a id="type-eventsemantics"></a>
 
 ### `EventSemantics`
@@ -1223,13 +2009,65 @@ How the party that sends an event gets its answer.
 - [The Menu](../concepts/the-menu.md)
 - [ADR-0006: The agent picks from a Machine-defined, schema-backed menu; it does not drive the workflow](decisions/0006-agent-control-surface.md)
 
+<a id="type-gategrant"></a>
+
+### `GateGrant`
+
+```ts
+type GateGrant = {
+  workflow: string;
+  gates: readonly string[];
+};
+```
+
+Some Gates of one Workflow, in the `answer` scope ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). A Gate's name is its invoke id: the
+static name that it has in the Machine that invokes it, and the id that its events carry as their
+sender ([ADR-0011](decisions/0011-workflow-defined-events.md)). That is the invoke `id` that the author wrote, or else the key path of its
+gated state below the root of that Machine (`body.humanReview`). One name opens every Gate of the
+Workflow with that id, in each child of a Pool too.
+
+`jr2 up` refuses an item for a Workflow that the Assembly does not have, a name that no Machine
+of the Workflow has, and a name that Gates in more than one Machine of the Workflow have. A Chart
+wrapper's item (`{ workflow: "plan", gates }`) opens those Gates in each Chart of `plan` too, and
+`jr2 up` checks its names against the wrapper's Machines and its Chart files. A runtime Chart is
+not in the Assembly, so `jr2 up` cannot check its Gates: a name that no Machine and no Chart file
+of the wrapper has, and an item for a runtime Chart (`plan/weekly` with no Chart file), are
+warnings, not refusals.
+
+**Fields**
+
+- `workflow`: `string`
+
+  The Workflow, as a bare name in the list names it.
+- `gates`: `readonly string[]`
+
+  The Gates' names.
+
+<a id="type-sourceverdictline"></a>
+
+### `SourceVerdictLine`
+
+```ts
+type SourceVerdictLine = { verdict: SourceVerdictName; key?: string; run?: string; reason?: string };
+```
+
+A Source's verdict on one delivery ([ADR-0017](decisions/0017-pool-over-a-source-port.md)): `key` for a carried item, `run` when a run holds
+that key, `reason` for a skip.
+
+**Fields**
+
+- `verdict`: [`SourceVerdictName`](#type-sourceverdictname)
+- `key` (optional): `string`
+- `run` (optional): `string`
+- `reason` (optional): `string`
+
 <a id="type-effectdoc"></a>
 
 ### `EffectDoc`
 
 ```ts
 type EffectDoc =
-  | { kind: "command"; argv: string[]; timeoutMs: number; slot?: string; secrets?: string[]; pin?: true }
+  | { kind: "command"; argv: string[]; timeoutMs: number; secrets?: string[]; pin?: true }
   | {
       kind: "http";
       method: string;
@@ -1240,20 +2078,29 @@ type EffectDoc =
       file?: true;
     }
   | { kind: "push"; sign: boolean; squash: boolean; force: boolean; pin: boolean; timeoutMs: number; slot?: string }
-  | { kind: "dispatch"; workflow: string; wait: boolean; target?: string; timeoutMs: number };
+  | { kind: "dispatch"; workflow: string; wait: boolean; target?: string; timeoutMs: number }
+  | {
+      kind: "mcp";
+      op: "call" | "read" | "prompt";
+      server: string;
+      tool?: string;
+      uri?: string;
+      prompt?: string;
+      timeoutMs?: number;
+      idempotent: boolean;
+    };
 ```
 
 An Effect slot's parts, as the doc carries them ([ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)): a command's argv (an argv slot reads
-`<name>`), its timeout, and the Repo Slot whose Worktree is its cwd, when it names one.
+`<name>`) and its timeout. Its input names its Worktree, so the doc does not ([ADR-0075](decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)).
 
 **Forms**: it is one of these objects.
 
-- Form 1: `kind`, `argv`, `timeoutMs`, `slot`, `secrets`, `pin`
+- Form 1: `kind`, `argv`, `timeoutMs`, `secrets`, `pin`
 
   - `kind`: `"command"`
   - `argv`: `string[]`
   - `timeoutMs`: `number`
-  - `slot` (optional): `string`
   - `secrets` (optional): `string[]`
   - `pin` (optional): `true`
 - Form 2: `kind`, `method`, `target`, `secrets`, `timeoutMs`, `idempotent`, `file`
@@ -1281,6 +2128,16 @@ An Effect slot's parts, as the doc carries them ([ADR-0067](decisions/0067-an-ef
   - `wait`: `boolean`
   - `target` (optional): `string`
   - `timeoutMs`: `number`
+- Form 5: `kind`, `op`, `server`, `tool`, `uri`, `prompt`, `timeoutMs`, `idempotent`
+
+  - `kind`: `"mcp"`
+  - `op`: `"call" | "read" | "prompt"`
+  - `server`: `string`
+  - `tool` (optional): `string`
+  - `uri` (optional): `string`
+  - `prompt` (optional): `string`
+  - `timeoutMs` (optional): `number`
+  - `idempotent`: `boolean`
 
 <a id="type-childmachinedoc"></a>
 
@@ -1346,3 +2203,11 @@ event to the other party too (`"any"`). Or set it to keep an event on the root f
 - [The Menu](../concepts/the-menu.md)
 - [Gates](../concepts/gates.md)
 - [ADR-0015: Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine](decisions/0015-authoring-surface-absorbs-the-mechanism.md)
+
+<a id="type-sourceverdictname"></a>
+
+### `SourceVerdictName`
+
+```ts
+type SourceVerdictName = (typeof SOURCE_VERDICTS)[number];
+```