@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/decisions/0005-sandbox-pod-composition.md

@@ -6,14 +6,21 @@ A Sandbox pod composes up to four containers around one shared worktree volume (
   [ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)) with jr2's runtime mounted at
   `/opt/jr2` and the command overridden to start the Harness. The Agent's toolchain lives here because the Working tools
   (read/write/edit/bash) execute here — the tools the Agent can reach are this image's. It is also where a human
-  `kubectl exec`s to inspect a run with the agent's exact tools, worktrees, and filesystem.
+  inspects a run with the agent's exact tools, worktrees, and filesystem: `jr2 workspace shell` starts its shell through
+  the spawner, as an Agent's `bash` starts ([ADR-0009](0009-cli-and-instance-interface.md)), so the shell does not reach
+  the control Stand-in. One Harness container serves every workspace-ful Agent of the Sandbox. Each process that the
+  Harness starts in `/work` — a Working tool's shell, a test, git, a `command` Effect — runs as a confined child of the
+  Harness process, so no code from `/work` reaches the control credential that the Harness process holds
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
 - **Custodian container** — jr2-composed sidecar, upstream Envoy configured at provision by the Orchestrator
   ([ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md),
   [ADR-0059](0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)): the pod's credential holder. It holds
   the Sandbox token and the held secrets its pod names — model API keys above all — as files, and carries the Harness's
   traffic out: its Menu and the ask to the Orchestrator, and its outbound HTTPS. It exists as a separate container
   precisely _because_ the Working tools give the Agent code execution in the Harness container — the credentials live
-  where the Agent cannot read them, and the Harness container's env holds only their Stand-ins.
+  where the Agent cannot read them, and the Harness container holds only their Stand-ins, which are secret: only the
+  Harness process holds them, as files, and a process it confines gets only those that its `workspace()` grants
+  (ADR-0059, ADR-0076).
 - **User Container** — opt-in third seat, composed only when the `workspace()` names its image (a `file:` docker context
   the Machine ships or a registry ref, the same resolution as the Sandbox Image, no default —
   [ADR-0049](0049-a-machine-carries-its-parts-and-composes-by-invoke.md)). The authoring surface is that string —
@@ -22,10 +29,11 @@ A Sandbox pod composes up to four containers around one shared worktree volume (
   Size ([ADR-0060](0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)): a budget is the pod's business, not
   the process's, so it puts nothing in the container. Env and ports are not forwarded, because every key jr2 forwarded
   into the process would be a crack in "jr2 puts nothing in it"; a routable port (the follow-up below) is the known
-  candidate for the next key. In the pod it is the container named `user` (`kubectl exec -c user`). It runs its **own
-  entrypoint, untouched**: jr2 injects nothing into its process — no env, no command, no probe — and overrides nothing;
-  it mounts only what the checkouts need to be checkouts (below). The zero-contract seat, which is exactly why it
-  exists. Two jobs no other seat can do:
+  candidate for the next key. In the pod it is the container named `user`: `jr2 workspace shell <ws> --user` is
+  `kubectl exec -c user`, and `jr2 workspace forward <ws> <port> [--stdio]` reaches its sshd or any of its listeners by
+  port-forward ([ADR-0009](0009-cli-and-instance-interface.md)). It runs its **own entrypoint, untouched**: jr2 injects
+  nothing into its process — no env, no command, no probe — and overrides nothing; it mounts only what the checkouts
+  need to be checkouts (below). The zero-contract seat, which is exactly why it exists. Two jobs no other seat can do:
   - **Unattended services.** A container's one command belongs to the Harness in the primary seat (ADR-0037), so an
     image's own services — an sshd for managed access, an IDE server, a metrics agent — need a container whose command
     jr2 deliberately does not own. A system built _on_ jr2 that hands people access to their Sandboxes automates through
@@ -63,8 +71,8 @@ What each container mounts of the credentials, stated once:
 
 | Container   | Mounts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `harness`   | `jr2-ca` at `/etc/jr2/ca` (the trust bundles). None of the Custodian's volumes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `custodian` | its values (the Sandbox token, its pod's `jr2-held-secrets-<pod>`, each user `secretKeyRef` its pod names) at `/etc/jr2/custodian/values`; its leaves (`jr2-held-tls`); its pod's config (its own `<sandbox>-custodian`, and `program.lua` from `jr2-held`); `upstream.crt`.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `harness`   | `jr2-ca` at `/etc/jr2/ca` (the trust bundles); the Stand-ins — the control one and each held secret's — as files under `/run/jr2/` that only the Harness process reads and no process it confines can (ADR-0059, ADR-0076); no Stand-in is in its env. None of the Custodian's volumes.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `custodian` | its values (the Sandbox's control token and fetch token, its pod's `jr2-held-secrets-<pod>`, each user `secretKeyRef` its pod names) at `/etc/jr2/custodian/values`; its leaves (`jr2-held-tls`); its pod's config (its own `<sandbox>-custodian`, and `program.lua` from `jr2-held`); `upstream.crt`.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `user`      | the checkouts' three volumes, and nothing else.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `effector`  | `/work`, `/repos/<key>` and `/opt/jr2` read-only; at `/run/jr2/secrets` (0400) the secrets its Effects name — its pod's `jr2-effector-<pod>` literals, each user `secretKeyRef` by reference — and at `@git/<name>/` each `git.credentials` entry's push Secret the Sandbox CR names (`gitCredentials`), which the operator projects from that entry's Secret by reference into this container alone (`@` is no character of a secret's name, so no secret's file takes that directory); at `/run/jr2/effector` its key (its own `<sandbox>-effector`) and `effector.json`; an emptyDir at `/run/jr2/scratch` as `$HOME`; at `/etc/jr2/effector-ca`, read-only, the instance's caBundle ConfigMap when the instance ships one (ADR-0020). |
 
@@ -98,12 +106,13 @@ jr2 sets `runAsUser` nowhere — each image's own `USER` decides its seat's uid
 and plain POSIX modes would then make the other seat's files read-only. jr2 closes that with two mechanisms it happens
 to own, unconditionally (both are inert when the uids already match):
 
-- **The pod carries `fsGroup` — the work group, default `2000`.** The default is convention; the one override lives on
-  the `WorkspaceSpec` (`workGroup?: number`, beside `image` and `user` — pod composition is the spec's business,
-  ADR-0037), for the image whose session users already hold a gid of their own. Never a config key. Any value is safe
-  for the jr2 seats: Kubernetes grants the fsGroup as a supplemental group to every container process, so the Harness
-  writes `/work` whatever the number, and no image's `/etc/group` needs to know it. fsGroup puts a setgid group on
-  `/work`'s root, and setgid propagates down, so everything either seat creates is group-_owned_ by the work group.
+- **The pod carries `fsGroup` — the work group, default `2000`.** The default is convention; the one override is an
+  option of `workspace()` (`workspace(body, { workGroup: 2000 })`, beside `image` and `user` — pod composition is the
+  wrapper's business, ADR-0037), for the image whose session users already hold a gid of their own. Never a config key.
+  Any value is safe for the jr2 seats: Kubernetes grants the fsGroup as a supplemental group to every container process,
+  so the Harness writes `/work` whatever the number, and no image's `/etc/group` needs to know it. fsGroup puts a setgid
+  group on `/work`'s root, and setgid propagates down, so everything either seat creates is group-_owned_ by the work
+  group.
 - **The attach stamps a default ACL on every repo root it creates** — `u::rwx,g::rwx,o::r-x`, set by `work-acl`, a
   static helper on the runtime volume (part of ADR-0037's published `/opt/jr2` surface, static for the same reason `rg`
   is: it executes on a libc jr2 does not control). A default ACL is inherited by everything created beneath it, and
@@ -116,16 +125,16 @@ to own, unconditionally (both are inert when the uids already match):
 Group _membership_ is the one thing an image can still owe. `kubectl exec` sessions and a non-root sshd's logins hold
 the work group automatically — both inherit the container's supplemental groups, where Kubernetes put the fsGroup. A
 **root** sshd is the exception: the logins it setuids rebuild their groups from `/etc/group`, so that image puts its
-session user in the work group itself (`groupadd -g 2000 work && usermod -aG work <user>`) — or the spec points
+session user in the work group itself (`groupadd -g 2000 work && usermod -aG work <user>`) — or the `workspace()` points
 `workGroup` at a gid its users already hold.
 
 **The promise is scoped to repo trees.** An ad-hoc path at `/work`'s top level — either seat's `mkdir /work/scratch` —
 carries no default ACL, so files there fall back to the writer's umask. The Harness runs at `umask 002` (itself and
 every tool child) and the attach script opens with the same line, so jr2's own writes are group-writable even there;
 what a User Container session writes outside a repo tree is its own business. A Workspace with no Repo Slot (ADR-0051)
-has no repo tree: its steps share `/work` itself, every Agent and `command` of it in the one Harness container as one
-uid, so they need no ACL; a User Container's writes there have this paragraph's limit, until a user of that seat needs
-more.
+has no repo tree: its steps share `/work` itself, every Agent and `command` of it at the one uid in the one Harness
+container, so they need no ACL; a User Container's writes there have this paragraph's limit, until a user of that seat
+needs more.
 
 ## Constraints on the seat
 
@@ -134,8 +143,8 @@ The seat is zero-_contract_, not zero-_physics_. What an image brought here must
 - **The entrypoint must block.** The pod's restart policy restarts an exited container, so a `CMD` that finishes
   crash-loops. Run a long-lived process — an sshd, an IDE server, `sleep infinity` at minimum.
 - **The ports of jr2's seats are taken** — one network namespace: `:8080` (the Harness), the Custodian's
-  `127.0.0.1:8081` (control), `127.0.0.1:15001` (egress) and `:15021` (health), and `:8082` (the Sandbox Effector, in a
-  pod that has one). Everything else is the image's. A process that binds `:8082` while the Sandbox Effector is down
+  `127.0.0.1:8081` (the fetch), `127.0.0.1:15001` (egress) and `:15021` (health), and `:8082` (the Sandbox Effector, in
+  a pod that has one). Everything else is the image's. A process that binds `:8082` while the Sandbox Effector is down
   gets signed requests it can neither forge nor answer (ADR-0068): the Effect fails closed.
 - **Root is allowed.** The hardened security context (non-root, all capabilities dropped, no escalation) applies to the
   seats jr2 owns — Harness, Custodian and Sandbox Effector, per container — and deliberately not here: the seat's
@@ -162,7 +171,10 @@ namespace, node, and the worktree volume, and are one trust domain in every isol
 container edge does provide is **credential visibility** — the asymmetry ADR-0013 builds on: the Agent executes code in
 the Harness container and none in the others, so a secret that exists only in another container's mount namespace is out
 of its reach. That is why the Custodian holds the Orchestrator credential and the model keys, and it is what the User
-Container offers a human session — with its edges stated plainly:
+Container offers a human session. Inside the Harness container, a second edge holds the one credential the Harness keeps
+itself, the control Stand-in: the Harness process is jr2's code, and each process it starts in `/work` is confined from
+that Stand-in by Landlock (ADR-0076, [ADR-0077](0077-jr2-requires-landlock-on-every-sandbox-node.md)). The edges, stated
+plainly:
 
 - It holds only for what stays in the private filesystem or session. Anything on `/work` or listening on `localhost` is
   shared with the Agent — the pod has one network namespace. The Custodian's listeners are on `localhost` too; what they
@@ -206,8 +218,8 @@ Container offers a human session — with its edges stated plainly:
 
 - The generic `Sandbox` CRD composes all of this as plain container specs
   ([ADR-0001](0001-operator-owned-generic-sandbox.md) holds — the operator stays agent-agnostic); the Orchestrator's
-  `kubectlSandbox` supplies the images. The pod runs two containers, plus `user` when the spec names one and `effector`
-  when an Effect is placed there.
+  `kubectlSandbox` supplies the images. The pod runs two containers, plus `user` when the `workspace()` names one and
+  `effector` when an Effect is placed there.
 - Every container but the Sandbox Effector carries a limit from the Workspace's Size (ADR-0060): the Custodian a fixed
   kit slice, the User Container its split if stated, the Harness the rest. The Sandbox Effector carries no limit of its
   own: like a User Container with no split, it shares the pod's Size ceiling — the whole Size, as pod-level resources —
@@ -225,6 +237,8 @@ Container offers a human session — with its edges stated plainly:
 - The Harness container's `/work` writes being group-writable widens nothing: every process that could abuse group
   access already runs in the same trust domain, and the work group exists only inside this pod.
 - **Routable access is a follow-up, deliberately untaken**: the operator's Service serves the Harness at `:8080`, and a
-  managed system wanting cluster-routed ssh to the User Container needs a declared port there. `kubectl port-forward`
-  reaches any listener in the pod without one, which covers the human case day one.
+  managed system wanting cluster-routed ssh to the User Container needs a declared port there. A person reaches the User
+  Container through the kube API: `jr2 workspace shell --user` by exec, and `jr2 workspace forward` by port-forward,
+  which reaches any listener in the pod with no Service. `forward --stdio` is an ssh `ProxyCommand`, so
+  `ssh <sandbox>.jr2` with agent forwarding reaches the User Container's sshd (ADR-0009).
 - **GLOSSARY.md**: **User Container** is a glossary term.

package/docs/reference/decisions/0006-agent-control-surface.md

@@ -42,6 +42,9 @@ is the only structured channel. Consequences:
 
 ## Residual
 
-Unsolicited mid-turn steering remains the hard case (ADR-0002): the menu only opens when the Agent reaches a checkpoint
-or a turn boundary. Evidence for the findings above: `poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md`
-(`poc/` is gitignored; conclusions live here).
+jr2's own typed notices now reach a running Agent through the step-boundary read (ADR-0002,
+[ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)); the Menu still opens only when the Agent
+reaches a checkpoint or a turn boundary. Free text from a Caller, or from the Machine, is a Steering message on the same
+channel (ADR-0002, [ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): the Agent
+hears it once, and it is never a pick or a workflow event. Evidence for the findings above:
+`poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md` (`poc/` is gitignored; conclusions live here).

package/docs/reference/decisions/0007-durable-machine-state.md

@@ -15,7 +15,7 @@ it from the start (the top Machine keeps only counts + ids, children report comp
 snapshot/restore possible.
 
 The store's own durability — what a persist survives, and how long a finished run's row lives — is
-[ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md).
+[ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md).
 
 Durable **agent handles** do not ride Machine context at all: the host persists an `iid → admission` ledger beside the
 snapshot in the same save (ADR-0016). Iids are globally unique, so restore needs no context-tree walking to find them.

package/docs/reference/decisions/0009-cli-and-instance-interface.md

@@ -63,12 +63,23 @@ export default defineConfig({
   ([ADR-0068](0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)): the credentials the Agents use — an
   Anthropic key, read from `process.env`/`.env`, held by the Custodian and never by the Harness (ADR-0059) — and the
   ones an Effect names, which only its Effector holds. Where each goes is read, never declared.
+- **`mcp` is the Instance's MCP servers**
+  ([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)): each
+  by a name that the author chooses, remote (`url`, an optional `secret`) or stdio (`command`, `args`), with a
+  `timeout`. An Agent and an `mcp` Effect name a server by that name.
+- **`callers`, `hooks` and `cors`** are the Instance's reach for Callers
+  ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): the named Caller tokens
+  and the JWT issuers with their scopes, the Hooks with their credentials and the Hook kinds that the config imports,
+  and the origins a browser app may call from.
 - **`registry`** (deployment-varying, resolve from env): absent → images are `kind load`-ed; present → pushed
   (ADR-0019). **`kitRegistry`** (also env) re-homes the published Kit image refs for self-hosted, air-gapped, or
   mirror-only clusters ([ADR-0044](0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md)).
 - **The snapshot store is sqlite** on a PVC in the instance's namespace (zero setup); no other store is owed
-  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md)) — the single-table, single-writer snapshot fits
-  sqlite, and `replicas: 1` keeps it single-writer.
+  ([ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)) — the single-table, single-writer
+  snapshot fits sqlite, and `replicas: 1` keeps it single-writer. The kept conversations are a second sqlite file on the
+  same volume ([ADR-0023](0023-the-harness-prints-the-conversation.md)).
+- **`runs`** sets how long jr2 keeps an ended run and the size of the state volume, `{ retain: "30d", volume: "5Gi" }`
+  by default (ADR-0065).
 - Git credentials for private repos: an HTTPS token from `.env`, or a `jr2-git-ssh` Secret holding the key `jr2 up`
   asked the user to choose — a generated in-cluster deploy keypair (the recommended default), a local key, or one pasted
   on stdin (ADR-0019, [ADR-0047](0047-the-git-ssh-key-source-is-the-users-choice.md)). Kube target: the current
@@ -79,28 +90,42 @@ export default defineConfig({
 The kit publishes to npm under `@jr2/*`; stock Agent definitions ship in **`@jr2/agents`** (coder, reviewer, …), and a
 package may ship whole Machines with their Agents and image inside (ADR-0049). Because a definition is plain data
 (ADR-0018), composition needs no API: a Machine carries `agent(coder)`, a workflows file exports a packaged Machine
-as-is or through `customize(machine, { agents: { coder: { model: "…" } } })`. Adding tools/skills waits on the
-definition contract growing that seat (ADR-0018).
+as-is or through `customize(machine, { agents: { coder: { model: "…" } } })`. An Agent's tools beyond its own come from
+the MCP servers that it names, and the same `customize()` rebinds them
+([ADR-0079](0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)). Adding
+skills waits on the definition contract growing that seat (ADR-0018).
 
 ## Orchestrator HTTP API (hono, run-addressed-by-id)
 
 Push + control + observe only — the **pull** path needs no HTTP (the Orchestrator's Source pulls, ADR-0017). Auth bands
 per ADR-0014: structure + observation open; the Agent surface takes the Sandbox token; run state, control, and gates
-take the Instance token.
+take a Caller with the scope in brackets (ADR-0078); `[instance]` is the Instance token alone.
 
 ```
 GET  /workflows                        # list registered workflows                       [open]
 GET  /workflows/:name/machine  /viz/*  # machine structure + visualizer                  [open]
 GET  /workflows/:name/runs[, /:runId/events]  # observation projection (ADR-0014)        [open]
+GET  /workflows/:name/runs/:runId/machine     # the run's own Machine, Charts compiled (ADR-0069) [open]
 GET  /workflows/:name/events           # SSE: the whole workflow, level-triggered (ADR-0022) [open]
-POST /workflows/:name/runs             # start a run (push work); body = input → { runId } [instance]
-GET  /runs   GET /runs/:runId          # live list; durable run status (read-through)    [instance]
-GET  /runs/resolve?prefix=<p>          # run ids sharing a prefix, live + settled        [instance]
-GET  /runs/:runId/events               # SSE: status replay + live deltas                [instance]
-POST /runs/:runId/events               # run-level infra interrupt: CANCEL               [instance]
-POST /runs/:runId/gates/:gate/events   # deliver a workflow event to an open gate        [instance]
+POST /workflows/:name/runs             # start a run (push work); body = input → { runId } [start]
+                                       # a standing Workflow: resume a paused one [?drop-held=true] (ADR-0017)
+GET  /runs                             # run summaries; ?status ?workflow ?since ?cursor  [read]
+GET  /runs/:runId                      # durable run status (read-through)               [read]
+GET  /runs/resolve?prefix=<p>          # run ids sharing a prefix, live + settled        [any scope]
+GET  /runs/:runId/events               # SSE: status replay + live deltas                [read]
+GET  /runs/:runId/conversations        # the run's kept conversations (ADR-0023)         [read]
+GET  /runs/:runId/conversations/:iid[?after=<seq>]  /events   # entries; SSE follow   [read]
+GET  /gates                            # open Gates the Caller may answer; ?workflow     [answer]
+POST /runs/:runId/events               # run-level infra interrupt: CANCEL               [cancel]
+POST /runs/:runId/gates/:gate/events   # deliver a workflow event to an open gate        [answer]
+POST /runs/:runId/steering             # a Steering message to an Agent slot (ADR-0002)  [steer]
+GET  /runs/:runId/agents               # the slot list, one row per Agent slot           [steer]
+GET  /whoami                           # the request's Caller record (ADR-0078)          [any Caller]
+POST /hooks/:name                      # a Hook's delivery (ADR-0011)                    [the Hook's verifier]
+GET  /hooks/:name                      # the Hook's log, newest first (ADR-0011)         [instance]
 GET  /repos                            # per-Repo node-cache sync state (ADR-0048)        [instance]
 GET  /agents/:iid/surface   POST /agents/:iid/events   # the Menu, via the Custodian    [sandbox]
+POST /agents/:iid/conversation         # a batch of the record's entries (ADR-0023)      [sandbox]
 POST /sandboxes/:name/fetch                            # the ask (ADR-0053)             [sandbox]
 GET  /healthz   GET /readyz
 ```
@@ -112,11 +137,11 @@ ADR-0047's "register the key, the cache agent retries" points at. Instance band,
 carries git's error text, exactly the class of author/deployment detail the open projections strip (ADR-0014).
 
 Gates are the human/webhook/CI seam (ADR-0011): a gated state registers `{ gate, accepts, meta }`; `GET /runs/:runId`
-lists the open gates (with schemas + `meta`), and the gate POST validates the body against the named event schema and
-delivers it into that state. Per-gate addressing exists because concurrent children park concurrently — a run-level
-events POST is ambiguous. `CANCEL` is the one reserved run-level event; everything else is workflow vocabulary. It
-**ends** the run — its Agents' turns end with it and it does not restore
-([ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)).
+lists the open gates (with schemas + `meta`), `GET /gates` lists the open Gates of every live run that the Caller may
+answer, and the gate POST validates the body against the named event schema and delivers it into that state. Per-gate
+addressing exists because concurrent children park concurrently — a run-level events POST is ambiguous. `CANCEL` is the
+one reserved run-level event; everything else is workflow vocabulary. It **ends** the run — its Agents' turns end with
+it and it does not restore ([ADR-0025](0025-cancel-ends-a-run-stop-parks-it.md)).
 
 ## The `jr2` CLI
 
@@ -137,25 +162,78 @@ jr2 version [--local] [--json]     # this jr2, the global that handed off, the I
 
 # runs / workflows (wrap the HTTP API)
 jr2 run <workflow> [--input <json>] [--detach]
-jr2 runs   jr2 status [runId|abbrev]   jr2 logs <runId|abbrev> [-f]   # bare `status` = the instance's repos (ADR-0048)
+jr2 run <workflow> [--drop-held]   # resume a paused standing Pool (ADR-0017)
+jr2 runs [--status <s>] [--workflow <w>] [--since <d>]   # live runs by default; `--status ended|all|<list>`
+jr2 workflows [--json]             # the Workflows a run can start, with their origins and Charts (ADR-0070)
+jr2 status [runId|abbrev]          # bare `status` = the instance's repos (ADR-0048)
+jr2 watch <runId|abbrev> [--json]  # the run's status feed, followed to its end
+jr2 logs <runId|abbrev> [agent] [-f]   # the run's conversations, printed as ADR-0023 prints them
+jr2 gates [--workflow <w>]         # the open Gates this Caller may answer, oldest first
 jr2 send <runId|abbrev> --event CANCEL
 jr2 send <runId|abbrev> --gate <gate> --event <name> [--input <json>]
-
-# workspaces (kubectl-style, over the operator's Sandbox CRs) — decided, not yet in the binary
-jr2 ls                             # list workspaces + run + status + endpoint
-jr2 ssh <workspace>                # exec into the Sandbox's harness container (ADR-0037)
-jr2 logs <workspace>   jr2 rm <workspace>
+jr2 steer <runId|abbrev> [<agent> "<text>"]   # a Steering message; the slots alone (ADR-0002)
+
+# Callers and Hooks (ADR-0078, ADR-0011)
+jr2 whoami                         # the Caller this credential is
+jr2 caller token <name>            # print a named Caller token's value
+jr2 caller rotate <name>           # make a new value; the old one stops working
+jr2 hooks <name>                   # the Hook's log of deliveries
+
+# workspaces (kubectl-style, over the operator's Sandbox CRs; kube credentials only)
+jr2 workspace ls [run]             # the Workspaces, with run, path, status and age
+jr2 workspace shell <ws> [--user] [-- <cmd>]   # a shell in the Workspace, as its Agents work (--user: the User Container)
+jr2 workspace forward <ws> <port> [--stdio]    # a local port to a port in the pod (--stdio: an ssh ProxyCommand)
+jr2 workspace rm <ws>              # remove a Sandbox that no live run holds
+
+# shell completion
+jr2 completion bash|zsh|fish       # the completion script, generated from the command table
 ```
 
-`jr2 ssh` is `kubectl exec -c harness` into the Sandbox Image
-([ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)) — the inspect seat: the agent's own
-tools, worktrees, and filesystem. The optional User Container ([ADR-0005](0005-sandbox-pod-composition.md)) is reached
-by its own front door (its sshd, or `kubectl exec -c user`), not by this verb — its point is sessions and services the
-agent's container must not host.
+**The workspace verbs read the cluster, not the Orchestrator.** They use the kube credentials of the current context and
+no Caller scope, so they work when the Orchestrator is down, and kube RBAC is the gate. A Workspace's handle is
+`<run-prefix>/<workspace path>`: a prefix of its run's id and its path in the run's Machine, read off the CR's label
+`jr2.dev/run` and its annotation `jr2.dev/workspace-path` ([ADR-0012](0012-workspace-wrapper-machine.md)). The CLI lists
+the instance's CRs and compares on the client, because a label selector cannot match a prefix. `workspace ls` prints the
+exact path. The CR's name is also a handle, and a handle that ends in `.jr2` is the CR's name with that suffix, for the
+ssh config below. A handle that matches more than one Workspace prints the candidates and fails, as a run prefix does.
+
+- **`workspace shell`** asks the Harness to start a shell through its spawner, so the shell is a process of the Agents'
+  Landlock domain, with its env, the Workspace's grants and its cwd
+  ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)). It can signal and trace
+  the Agents' processes, as a later `bash` call can. So the shell has the agent's own tools, worktrees and filesystem
+  ([ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)), and it never reaches the control
+  Stand-in or any Stand-in that the Workspace does not grant. `-- <cmd>` runs one command in place of a shell. `--user`
+  is `kubectl exec -c user` into the optional User Container ([ADR-0005](0005-sandbox-pod-composition.md)), where jr2
+  starts nothing of its own.
+- **`workspace forward`** is a port-forward to the Sandbox pod: a local port to `<port>` in the pod's network namespace,
+  which reaches a server the Agent started or the User Container's sshd. It prints `127.0.0.1:<local port>` and holds
+  the forward until Ctrl-C. With `--stdio` it carries the connection on its stdin and stdout, so it is an ssh
+  `ProxyCommand`: `Host *.jr2` with `ProxyCommand jr2 workspace forward %h 22 --stdio -n <namespace>`, where the host is
+  the CR's name with `.jr2` after it. ssh runs the command in any folder, and with `-n` the verb needs no instance
+  folder. There is no routable Service for the User Container; the forward reaches it through the kube API.
+- **`workspace rm`** deletes a Sandbox that no live run holds: an ended run's Sandbox that waits for its idle timeout,
+  or one that a fault left as evidence (ADR-0021). It refuses the Sandbox of a live run and says "cancel the run first".
+  It tells from the cluster alone, with no Orchestrator, by the hold mark that the Lease writes on the CR (ADR-0021):
+  `jr2.dev/hold` is `held` from the Lease's first write, and the Lease sets it to `released` when it stops for the
+  body's final state, a fault, a cancel or a parent that leaves the Workspace's state, but not while a live Workspace of
+  the run holds the same name (a parent that invokes the same Machine again after a defect). A restore that ends a run
+  `drifted` or `lost` without hosting it marks each of its CRs `released`. A park and a process shutdown write nothing,
+  so the CR of a run that an Orchestrator crash left stays `held`. `rm` removes a CR that is `released`, and a CR whose
+  `jr2.dev/keepalive` is older than the CR's idle timeout, which the operator reaps then in any case. It refuses every
+  other CR, a CR with no mark included. It measures the keepalive's age on the API server's clock (the `Date` header of
+  its answer), not on the local clock, so a fast laptop clock cannot make a live Sandbox look free. There is no
+  `--force`: the run owns its Workspace's life (ADR-0012).
+
+Pod logs stay `kubectl logs`. The conversations of a Workspace's Agents are `jr2 logs <run> [agent]`, which reads the
+Orchestrator's record and works after the Sandbox is gone (ADR-0023).
+
+**`jr2 completion`** prints the script for bash, zsh or fish, made from the command table, so a verb or a flag cannot
+complete that the CLI does not take. It completes dynamic values too: Workspace handles (from the CR labels and the
+`jr2.dev/workspace-path` annotation), live run ids, Workflow names, and the Agent slots of a run. A lookup that takes
+more than 2 s offers nothing, so a slow cluster never holds the shell.
 
 The CLI is the everyday surface; HTTP is the machine-to-machine one. The workspace verbs make the orchestrator feel like
-`kubectl` for agents: the run↔workspace link rides on the CR's labels (`jr2.dev/run`, `jr2.dev/workflow`), so `jr2 ls`
-can group without the orchestrator being reachable. CLI and hono app sit on one shared API client.
+`kubectl` for agents. CLI and hono app sit on one shared API client.
 
 A planned `jr2 build` (build + push + render manifests, no apply — the pure-GitOps CI verb) is deferred; `jr2 up` in CI
 covers the interim (ADR-0019).
@@ -165,9 +243,10 @@ covers the interim (ADR-0019).
 **Instance addressing.** The CLI finds its instance by walking up from cwd to the directory containing `jr2.config.ts` —
 the root marker. The _deployment_ is addressed by the current kube context + the instance's namespace: run-verbs
 port-forward the Orchestrator Service for the duration of the command and read the Instance token from its in-cluster
-Secret (kube RBAC is the gate). `--url` / `JR2_URL` (+ token env) overrides both — the ingress-exposed/remote-caller
-case — and skips the folder walk entirely. Every run-verb prints the context it targets on stderr, so ambient-context
-drift is visible (ADR-0019).
+Secret (kube RBAC is the gate); its Caller is `token/instance`, on behalf of the kube user (ADR-0078). `--url` /
+`JR2_URL` (+ `JR2_TOKEN`, any Caller's credential) overrides both — the ingress-exposed/remote-caller case — and skips
+the folder walk entirely. Every run-verb prints the context it targets on stderr, so ambient-context drift is visible
+(ADR-0019).
 
 **The command table.** Each verb is an entry in `packages/cli/src/command-table.ts`: its arguments, its flags, the env
 vars it reads, what it prints, and its ADRs, as data. The verb's `parseArgs` options come from its entry, and so does
@@ -178,12 +257,18 @@ usage line. The CLI Reference of the docs is generated from the same table
 
 **Two output classes (amended 2026-09-20).** The stream rule below — JSON result on stdout, activity on stderr — was
 written for `jr2 run`, whose reason is the pipe: `jr2 run … | jq` must yield the result alone. It generalises to every
-**result verb** — `run`, `runs`, `status <runId>`, `logs`, `kit push` — because their result is small and the stderr
-lines beside it are advisory. It does not generalise to a **report verb** — `version`, and `status` with no run id —
-whose output is a diagnosis a human reads whole: dual-printing there shows a JSON blob and a partial table, and the
-readable form exists nowhere. So a report verb prints its human table on **stdout**, and `--json` swaps the table for
-the one object. No `isatty` sniffing: output that changes with how it is invoked is a debugging trap of its own. `init`,
-`check`, `up`, `down`, `gc` and `send` are neither class — activity only, no result.
+**result verb** — `run`, `runs`, `status <runId>`, `gates`, `kit push` — because their result is small and the stderr
+lines beside it are advisory. It does not generalise to a **report verb** — `version`, `status` with no run id, `watch`,
+`logs` and `workspace ls` — whose output a human reads whole: dual-printing there shows a JSON blob and a partial table,
+and the readable form exists nowhere. So a report verb prints its human table or lines on **stdout**, and `--json` swaps
+them for the JSON (for `watch`, the feed's JSON frames; `logs` has no `--json`). No `isatty` sniffing: output that
+changes with how it is invoked is a debugging trap of its own. `init`, `check`, `up`, `down`, `gc`, `send`,
+`caller rotate` and `workspace rm` are neither class — activity only, no result. `workspace shell` and
+`workspace forward --stdio` give the terminal to the session or the connection. `whoami` is a result verb. A **value
+verb** — `caller token`, `completion`, `workspace forward` (its local address) — prints one value alone on stdout, not
+JSON, and activity on stderr, because its one use is `JR2_TOKEN=$(jr2 caller token ci)`, and a JSON string there needs
+`jq -r` for nothing. `caller rotate` prints no value: the new one is a `caller token` away, and a value is printed only
+when it is asked for.
 
 **`jr2 version` (amended 2026-09-20).** The report you paste into a bug: what is _here_ and what is _deployed_, side by
 side, so the gap between the halves is the answer ("you edited the pin and never ran `jr2 up`"). The local half: `cli`
@@ -225,13 +310,28 @@ orchestrator**, not a temporary per-invocation runtime — a jr2 run is durable
 outliving the CLI call. `--detach` starts the run, prints its `runId`, returns.
 
 **Attach / detach / re-attach.** A run lives server-side, so attaching = opening `GET /runs/:runId/events` and detaching
-= closing it (Ctrl-C); neither affects the run. `jr2 logs <runId> -f` re-attaches to any running run. On attach, the SSE
-**replays the run's current status immediately** (so a parked run shows where it is) before streaming live deltas; it
-carries `status` events (auto, per transition) and `emit` events (the workflow author's `emit({…})`).
+= closing it (Ctrl-C); neither affects the run. `jr2 watch <runId>` re-attaches to any run: it prints the lines that
+`jr2 run` prints while it is attached, follows the run to its end, and for an ended run prints its last status once. It
+exits 0 when it followed the feed to its end, for a failed or a parked run too: its exit code is the watch's, and
+`jr2 run`'s is the run's result. On attach, the SSE **replays the run's current status immediately** (so a parked run
+shows where it is) before streaming live deltas; it carries `status` events (auto, per transition) and `emit` events
+(the workflow author's `emit({…})`).
 
 **Terminal runs stay readable.** The final snapshot persists to the store before the run drops from the live registry,
 so `status` / `GET /runs/:runId` **read through to the store** — a completed run reports its terminal status/context
-instead of `404`. (`GET /runs` stays live-only; history via `?all` is deferred.)
+instead of `404`.
+
+**`GET /runs` lists history.** Its filters are `status` (`live` by default; `ended`, `all`, or a list of statuses),
+`workflow` and `since` (a duration back from now, such as `7d`, or an ISO-8601 time). It lists the newest start first, a
+page at a time: `limit` (50 by default, at most 500) and `cursor`, and the answer is `{ runs, next? }`. An item is a
+summary, not the whole `RunStatus`:
+`{ runId, workflow, status, reason?, startedBy?, startedAt, endedAt?, assembly?, openGates, placing?, dispatchedBy? }`,
+where `placing` names the child paths of the Workspaces that wait for capacity
+([ADR-0064](0064-a-workspace-waits-for-capacity.md)) and `dispatchedBy` names the run that started this one
+([ADR-0071](0071-a-run-starts-a-run-through-a-dispatch-effect.md)), because `jr2 runs` prints both. A `drifted` run is
+listed, with its reason (ADR-0030). A `live` row whose restore a boot deferred or that failed is listed as `active`,
+with the reason `waiting for restore`. A run is listed while its row is kept (`runs.retain`, ADR-0065). `jr2 runs` takes
+the same filters as `--status`, `--workflow` and `--since`.
 
 **Run ids abbreviate to a unique prefix.** A run id is a bare uuid, so every id-taking verb takes a git-style short
 form: `jr2 status 1a2b3c4d`. **Prefix only** — not fuzzy, not suffix — which keeps it an indexed range scan and keeps
@@ -250,10 +350,10 @@ returns silently for an unknown run, so an unresolved CANCEL used to report succ
 The candidate set is the ids that **exist**, not the ones that read: `lost` runs are included, because dropping them
 would let a prefix they share with a live run resolve silently to the live one. The set unions the live registry with
 the store — neither alone is complete, since `persist()` is microtask-scheduled (a just-started run is live before it is
-stored) and a settled run is stored but not live. Note the deliberate tension with `GET /runs`'s deferred `?all`: this
-route does reveal that settled run **ids** exist to an Instance-token holder. It answers ids only — no status, no
-context, no gates — to keep that widening as small as the feature allows, and it is Instance-only rather than open,
-since prefix probing on an open route would be a run-id enumeration oracle.
+stored) and a settled run is stored but not live. It answers ids only — no status, no context, no gates — to a Caller
+with any scope for their Workflow, where `GET /runs` needs `read`, and it is guarded rather than open, since prefix
+probing on an open route would be a run-id enumeration oracle. Any scope opens it, for the Workflows of that scope,
+because a Caller that may only cancel or steer also addresses a run by a prefix.
 
 **`jr2 init` (v1).** Scaffolds the minimum runnable instance: `jr2.config.ts` (root marker), `package.json` (deps on
 `@jr2/*` + xstate), one starter `workflows/<name>.ts`, `images/default/Dockerfile` (the Sandbox Image every Workspace
@@ -266,10 +366,11 @@ lockfile is what picks one ([ADR-0043](0043-the-kit-is-tested-as-installed-a-loc
 
 ## Consequences
 
-- The instance-facing packages (`@jr2/cli`, `@jr2/orchestrator`, `@jr2/agent-protocol`) publish to npm; `@jr2/harness`
-  ships inside a Kit image, never via npm
+- The instance-facing packages (`@jr2/cli`, `@jr2/orchestrator`, `@jr2/agent-protocol`, `@jr2/machines`) publish to npm;
+  `@jr2/harness` ships inside a Kit image, never via npm
   ([ADR-0043](0043-the-kit-is-tested-as-installed-a-local-registry-stands-in-for-npm.md)). The CLI ships as the `jr2`
   bin (`npx jr2`).
-- Workspaces are a first-class CLI resource backed by the operator's `Sandbox` CRs, label-linked to their runs.
+- Workspaces are a first-class CLI resource backed by the operator's `Sandbox` CRs, label-linked to their runs and their
+  paths, and reached with kube credentials alone.
 - Code is never loaded from a third party at run time (ADR-0008, ADR-0069): discovery is over the instance's own
   Assembly, which only `jr2 up` publishes. A run may bind a Machine's Open body with a Chart, which is data (ADR-0070).

package/docs/reference/decisions/0010-bdd-acceptance-tests.md

@@ -81,14 +81,16 @@ Cucumber.js**, living in a top-level `./features/` workspace package (`@jr2/e2e`
   one is the tier watching the fix rather than merely enjoying it: the retry is absorbed by design, so without it a
   cluster drifting toward the 90s window would keep passing — slightly slower, silently — until the day it did not.
 - **An opt-in `@console` tier for the Console's UX** (added with
-  [ADR-0032](0032-the-console-unlocks-with-the-instance-token.md)). The Console's risky behavior is interaction —
+  [ADR-0032](0032-the-console-unlocks-with-a-callers-credential.md)). The Console's risky behavior is interaction —
   token-mode switching, the frame-triggered gate inbox, selection vs. folding — which no reducer test sees and no CLI
   step drives. These scenarios hold a **Playwright page inside ordinary Cucumber steps** (Playwright the _library_, not
   the `@playwright/test` runner): the browser is a second driver of the same black box, reusing the per-scenario
   orchestrator fixture unchanged, and a scenario may drive both (the CLI starts a run; the browser sees it park). Tagged
   `@console` and **excluded from the default profile** exactly as `@kind` is — the everyday suite must not require a
-  Chromium install — but they need no docker: a host-booted orchestrator serves the Console fine. Scope discipline: they
-  assert what a user does and sees, never pixels or layout; what the page _believes_ stays in `console-store.test.ts`.
+  Chromium install — but they need no docker: a host-booted orchestrator serves the Console fine. The one exception is
+  the login, which needs an identity provider: its scenario runs Dex in a container and is also tagged `@dex`. The
+  `console` profile runs it; a host with no docker runs `--tags "@console and not @dex"`. Scope discipline: they assert
+  what a user does and sees, never pixels or layout; what the page _believes_ stays in `console-store.test.ts`.
 - **Harness conformance, in `@jr2/harness`, in the default gate**
   ([ADR-0027](0027-the-harness-is-jr2s-own-server-flue-retires-the-wire-stays.md)). The three tiers above all reach the
   Harness through the **stub Harness**, which is a hand-written model of the _wire_ — it holds no conversation, so it