@jr2/orchestrator 0.6.0 → 0.7.0

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