@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/iterate-on-a-machine-on-kind.md

@@ -49,21 +49,21 @@ jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
 typecheck: tsc --noEmit (the instance's own compiler)
 agents: (none) (carried by 1 workflow machine(s))
 assembly: staging
-assembly: 0adf5bff234d (kit v<version>; 1 workflow(s): ping)
+assembly: 0756fbb530cb (kit v<version>; 1 workflow(s): ping)
 …
 sandbox images: skipped (no registered Machine composes a Sandbox)
 …
 orchestrator: applying (image ghcr.io/snapwich/jr2-orchestrator:<version>)
 orchestrator: waiting for rollout
 orchestrator: verified — 1 pod(s) running ghcr.io/snapwich/jr2-orchestrator:<version>
-instance effector: none (no Effect is placed there)
-assembly: publishing 0adf5bff234d (current is ba71fa27f37f)
-assembly: 0adf5bff234d is current — workflows: ping
-swept nothing — every labeled image is named by a live root
+instance effector: none (no Effect is placed there, and no Hook needs it)
+assembly: publishing 0756fbb530cb (current is 50e6f81e3bfb)
+assembly: 0756fbb530cb is current — workflows: ping
+…
 converged — `jr2 run <workflow>` when ready
 ```
 
-`0adf5bff234d` is the hash of the new [Assembly](../reference/glossary.md#assembly), and `ba71fa27f37f` is the hash of
+`0756fbb530cb` is the hash of the new [Assembly](../reference/glossary.md#assembly), and `50e6f81e3bfb` is the hash of
 the Assembly that was current. Your hashes can be different. `<version>` is the
 [Kit version](../reference/glossary.md#kit-version). The hash changed, because the Workflow changed. Thus `jr2 up`
 published the new Assembly to the [Orchestrator](../reference/glossary.md#orchestrator). The image of the Orchestrator
@@ -84,9 +84,9 @@ jr2 run ping --input '{"message":"hi"}'
 
 ```text
 → context kind-jr2 / namespace my-instance
-run 7df09f94-d26d-44c3-ba1e-0279f16ccacb (ping) — attached
+run 8b6c68a2-2ab6-498b-9cc5-bb722d71140f (ping) — attached
   → done "done"
-{"runId":"7df09f94-d26d-44c3-ba1e-0279f16ccacb","workflow":"ping","instanceId":"b2ec6504-553e-495a-a8be-62715c6d8595","status":"done","value":"done","context":{"message":"hi","reply":"pong, again: hi"},"children":[],"waiting":[],"held":[],"assembly":"0adf5bff234d"}
+{"runId":"8b6c68a2-2ab6-498b-9cc5-bb722d71140f","workflow":"ping","instanceId":"919c7165-d20e-472b-b889-1ba4209a488b","startedAt":"2026-11-06T19:17:06.158Z","status":"done","value":"done","context":{"message":"hi","reply":"pong, again: hi"},"children":[],"waiting":[],"held":[],"assembly":"0756fbb530cb","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}
 ```
 
 Your run id and your instance id are different. The `reply` comes from the new Machine, and `assembly` is the hash of
@@ -112,8 +112,9 @@ A second `jr2 up` with no change builds nothing and publishes nothing:
 
 ```text
 …
-assembly: 0adf5bff234d (current — publish skipped)
+assembly: 0756fbb530cb (current — publish skipped)
 swept nothing — every labeled image is named by a live root
+…
 converged — `jr2 run <workflow>` when ready
 ```
 

package/docs/guides/let-an-agent-write-a-chart.md

@@ -158,15 +158,18 @@ jr2 run plan --input '{"task":"Write the release notes for the greet CLI, and as
 Open the run in the [Console](../reference/glossary.md#console). After the planner picks `run_chart`, the Console draws
 the Chart inside `running`. The Chart of each run is different, because the planner writes it.
 
-When the door refuses a Chart, the answer to the pick holds the report. The log of the
-[Instance Harness](../reference/glossary.md#instance-harness) shows each answer. Replace `<namespace>` with the
-namespace of your Instance, and `<run id>` with the full run id. The log holds the lines of each run of a Menu-only
-Agent, and the first `grep` keeps the lines of your run:
+When the door refuses a Chart, the answer to the pick holds the report. The conversation of the planner shows each
+answer. [`jr2 logs`](../reference/cli.md#logs) prints it. Replace `<run id>` with the run id, or its first 4 characters
+or more:
 
 ```sh
-kubectl -n <namespace> logs statefulset/jr2-instance-harness -c harness | grep -F '[<run id>/' | grep -F '[run_chart answer]'
+jr2 logs <run id> planner | grep -F '[run_chart answer]'
 ```
 
+[Read a conversation](read-a-conversation.md) tells more. The log of the Instance Harness has the same lines, for each
+run of a Menu-only Agent:
+`kubectl -n <namespace> logs statefulset/jr2-instance-harness -c harness | grep -F '[<run id>/'`, with the full run id.
+
 For example, in one run with the model of each tab, the first Chart of the planner gave a prompt to the Gate. The door
 refused it:
 
@@ -185,7 +188,7 @@ it. Then the Chart ends, and the run ends with the status `done`.
 
 - [`openBody()`](../reference/authoring-surface/openbody.md) refuses a declaration that is not correct, with one line
   for each problem. The refusal starts with `openBody: `, then each problem, separated by `; `. For example:
-  - `lends.<kind>: an Open body lends agents, effects, machines, guards, actions, delays, gate and fail only`
+  - `lends.<kind>: an Open body lends agents, effects, machines, gates, guards, actions, delays, gate and fail only`
   - `allows.workspace: "<value>" is not a Workspace access (write, read, none)`
   - `ceilings.<ceiling>: missing; an Open body states every ceiling`
   - `ceilings.<ceiling>: <value> is not a positive integer`
@@ -200,11 +203,15 @@ it. Then the Chart ends, and the run ends with the status `done`.
 - The door refuses a Chart, and gives one line for each problem. Each line starts with the path in the Chart. For
   example:
   - `<path>: "<name>" is not a lent actor or an Agent of this Chart; lent: <names>; kit: <gate, fail or none>; minted: <names>`
-  - `<path>: "<name>" is not a lent guard; lent guards: <names> (and jr2.sentBy with params { id }, and jr2.failure)`
+  - `<path>: "<name>" is not a lent guard; lent guards: <names> (and jr2.sentBy with params { id }, jr2.failure and jr2.ready)`
   - `<path>.type: "<name>" is not a generic or a lent action; generic: set, append, increment, clear; lent: <names>`
   - ``<path>: <reference> is supplied by nothing: it is not in the initial `context`, and no `set`, `append` or `increment` writes it``,
     then what a write supplies
   - `<path>: "<reference>" is not a reference: it starts at context, event or input (a reference is a path, never an expression)`
+  - ``<path>: the lent cut "<slot>" does not state `expect`, so a Chart cannot use it; <fix>``
+  - ``<path>: the lent cut "<slot>" states `expect: "existing"` beside the lent force push "<slot>", and together they can force-push any existing branch; <fix>``
+  - ``<path>.cwd: "<cwd>" is a Repo Slot's folder, not a Worktree; `cwd` is a Worktree that a cut made, "/work/<slot>/<name>", or "/work/<slot>/default" to read, or "/work"``
+  - ``<path>: <agent> works under a Workspace with Repo Slots, and a Turn there says where: `cwd` is a Worktree, or "/work"``
 - The door then compiles the Chart as the Open body does. A line of this last check starts with `(chart):`, and names a
   state by its [xstate](https://xstate.js.org) id (for example `body.writing`), not by its path in the Chart.
 - A refusal is output, not an error: the Open body ends with `{ outcome: "refused", report }`. A Chart wrapper that

package/docs/guides/look-inside-a-sandbox.md

@@ -11,61 +11,89 @@ Open a shell in the [Sandbox](../reference/glossary.md#sandbox) of a run, and re
 A [Workspace](../reference/glossary.md#workspace) of the run makes the Sandbox, and deletes it when the body of the
 Workspace gets to its final state or fails. The [Rules](#rules) give the cases in which the Sandbox stays. The Sandbox
 is a pod. Its `harness` container runs the [Harness](../reference/glossary.md#harness), and the Agent's
-[Working tools](../reference/glossary.md#working-tools) run in it. When you use `kubectl exec`, you get a shell in the
-same container. An Agent that has only the [Menu](../reference/glossary.md#menu) has no Sandbox. To read its
-conversation, see [Watch a run](watch-a-run.md).
+[Working tools](../reference/glossary.md#working-tools) run in it. `jr2 workspace shell` gives you a shell in the same
+container, as the Agent's tools run. An Agent that has only the [Menu](../reference/glossary.md#menu) has no Sandbox. To
+read what an Agent said and did, see [Read a conversation](read-a-conversation.md).
 
-In the commands on this page, replace these values:
+In the commands on this page, replace `<run id>` with the run id, or its first 4 characters or more.
+[`jr2 run`](../reference/cli.md#run) prints it in the line `run <run id> (<workflow>) — attached`.
+[`jr2 runs`](../reference/cli.md#runs) prints the `runId` of each live run.
 
-- `<namespace>`: the namespace of your [Instance](../reference/glossary.md#instance). It is the
-  [`name`](../reference/config.md#name) in `jr2.config.ts`. When `jr2.config.ts` sets no `name`, it is the name of the
-  Instance folder.
-- `<run id>`: the full run id. [`jr2 run`](../reference/cli.md#run) prints it in the line
-  `run <run id> (<workflow>) — attached`. [`jr2 runs`](../reference/cli.md#runs) prints the `runId` of each live run. A
-  prefix does not work here, because `kubectl` does not know the run ids.
-
-Give each `jr2` command in the Instance folder.
+Give each `jr2` command in the [Instance](../reference/glossary.md#instance) folder. The `jr2 workspace` commands read
+the Sandbox resources from the cluster with your kubectl credentials. They do not use the
+[Orchestrator](../reference/glossary.md#orchestrator), so they also work when the Orchestrator is down.
 
 ## Find the Sandbox
 
-The label `jr2.dev/run` on each Sandbox holds the full id of its run:
+Run [`jr2 workspace ls`](../reference/cli.md#workspace-ls) with the run id. Without a run id, it lists each Workspace of
+the Instance:
 
 ```sh
-kubectl -n <namespace> get sandboxes -l jr2.dev/run=<run id>
+jr2 workspace ls <run id>
 ```
 
 ```text
-NAME                     PHASE   ENDPOINT                                             AGE
-ws-a1322024-x-2-h8pgwk   Ready   http://ws-a1322024-x-2-h8pgwk.my-instance.svc:8080   16s
+→ context <context> / namespace <namespace>
+WORKSPACE     SANDBOX                  WORKFLOW  PHASE  AGE  RUN
+7a0e8b50/x:0  ws-7a0e8b50-x-0-1eolpdi  task      Ready  32s  held
 ```
 
-- `NAME` is the name of the Sandbox, here `ws-a1322024-x-2-h8pgwk`. Your name is different. It starts with `ws-`, then
-  the first 8 characters of the run id. The pod has the same name. In the commands below, write it in place of
-  `<sandbox>`.
+- `WORKSPACE` is the handle of the Workspace: the first 8 characters of the run id, then the path of the Workspace in
+  the run. In the commands below, write it in place of `<workspace>`. You can also give the name of the Sandbox, or the
+  first characters of the run id, then `/` and the path.
+- `SANDBOX` is the name of the Sandbox, here `ws-7a0e8b50-x-0-1eolpdi`. Your name is different. The pod has the same
+  name.
 - A run that has two Workspaces at the same time has two rows.
-- `PHASE` is `Pending` until the pod is ready and its node has a fresh cache of each Repo. Then it is `Ready`. It is
-  `Lost` when the pod is gone, and a `Lost` Sandbox does not get a new pod. A delete removes the Sandbox at once, so you
-  seldom see the phase `Terminating`.
-- When the run has no Sandbox now, `kubectl` prints `No resources found in <namespace> namespace.`
+- `PHASE` is `Pending` until the pod is ready and its node has a fresh cache of each
+  [Repo](../reference/glossary.md#repo). Then it is `Ready`. It is `Lost` when the pod is gone, and a `Lost` Sandbox
+  does not get a new pod. A delete removes the Sandbox at once, so you seldom see the phase `Terminating`.
+- `RUN` tells if a run holds the Sandbox. `held`: a run holds it, or an Orchestrator that stopped held it. `released`:
+  its run does not hold it now. `idle`: nothing renewed its [Lease](../reference/glossary.md#lease) for its idle time.
+  `unknown`: the Sandbox has no mark.
+- When the run has no Sandbox now, the table has only its header.
+- `--json` prints the list as one JSON object.
+- [`jr2 status <run id>`](../reference/cli.md#status) prints each [Worktree](../reference/glossary.md#worktree) that the
+  run cut, with its path and its branch, in `worktrees` and in one `worktree:` line for each cut. Give this command on
+  your computer, not in the Sandbox.
 - When a [Workflow](../reference/glossary.md#workflow) puts `branch` and `worktree` in the `meta` of a
   [Gate](../reference/glossary.md#gate), as the `review` Gate of [`task`](../reference/machines.md#task) does,
-  [`jr2 status <run id>`](../reference/cli.md#status) prints them in `gates`. Give this command on your computer, not in
-  the Sandbox. Then you can copy the Worktree from the status.
+  `jr2 status <run id>` prints them in `gates` too.
 
 ## Open a shell
 
+Run [`jr2 workspace shell`](../reference/cli.md#workspace-shell) with the handle:
+
 ```sh
-kubectl -n <namespace> exec -it <sandbox> -c harness -- bash
+jr2 workspace shell <workspace>
 ```
 
-The default [Sandbox Image](../reference/glossary.md#sandbox-image) that [`jr2 init`](../reference/cli.md#init) writes
-starts from `node:24-slim`, which has `bash`. If your Sandbox Image has no `bash`, use `sh`.
+`jr2 completion bash|zsh|fish` completes the handles; see [`jr2 completion`](../reference/cli.md#completion).
+
+The shell runs as the Agent's tools run. The Harness starts it in the same Landlock domain as the Agents, in `/work`.
+Thus it has the same files, the same limits and the same [Stand-ins](../reference/glossary.md#stand-in) as an Agent's
+`bash`, and it cannot read the credential with which the Harness speaks for the Agents. It can see and stop a process
+that an Agent started, such as a dev server. The shell is `bash`, or `sh` when the image has no `bash`. The default
+[Sandbox Image](../reference/glossary.md#sandbox-image) that [`jr2 init`](../reference/cli.md#init) writes starts from
+`node:24-slim`, which has `bash`.
+
+To run one command and not a shell, give it after `--`:
+
+```sh
+jr2 workspace shell <workspace> -- git -C /work status
+```
+
+A command after `--` has no terminal. Ctrl-C stops `jr2`, and the command gets the end of its input but no signal. Thus
+a command that does not stop at the end of its input, such as a dev server, can continue to run.
+
+When the Workspace has a [User Container](../reference/glossary.md#user-container), add `--user` to open a shell in it.
+[Add tools to the Sandbox](add-tools-to-the-sandbox.md#run-a-service-beside-the-agent) tells how to reach a service in
+it.
 
 ## Find the Worktree
 
 Each [Repo Slot](../reference/glossary.md#repo-slot) of the Workspace has a folder in `/work`. In it, `default` is a
-clone of the [Repo](../reference/glossary.md#repo), and the [Worktree](../reference/glossary.md#worktree) of the branch
-is beside it. To show the folders of the Repo Slots, use this command:
+clone of the Repo, and each [Worktree](../reference/glossary.md#worktree) that the Machine cut is beside it. To show the
+folders of the Repo Slots, use this command:
 
 ```sh
 ls /work
@@ -80,20 +108,20 @@ git -C /work/<Repo Slot>/default worktree list
 For the slot `target` of a run of `task`, the output is:
 
 ```text
-/work/target/default                                        1e40403 [main]
-/work/target/jr2-task-0cbdb607-48dc-4eab-9469-f8e41f2b0025  1e40403 [jr2/task-0cbdb607-48dc-4eab-9469-f8e41f2b0025]
+/work/target/default  9f67321f (detached HEAD)
+/work/target/task     9f67321f [jr2/task-48ebf9ad-1e5d-4997-a330-d91ec762f83c]
 ```
 
-The first line is the clone, on the default branch of the Repo. The second line is the Worktree of the branch. Your
-commits and your instance id are different.
+The first line is the clone, on the base of the Repo Slot. Here the base is a tag, so the clone is detached. On a
+branch, the line shows the branch. The second line is the Worktree that `task` cut. Your commits and your instance id
+are different.
 
-- In the commands below, `<branch>` is the name of the branch, and `<worktree>` is the folder of its Worktree. The
-  folder is the name of the branch, with each `/` changed to `-`. For example, the branch `jr2/task-<instance id>` has
-  the Worktree `/work/target/jr2-task-<instance id>`.
-- A Workspace that has a commit to review has one more Worktree, `/work/<Repo Slot>/<worktree>-review`. It holds that
-  commit, with no branch.
-- The attach makes the folders and the Worktrees after the Sandbox is `Ready`. Until then, `/work` has no folder for the
-  Repo Slot.
+- In the commands below, `<branch>` is the name of the branch, and `<worktree>` is the name of the folder of its
+  Worktree. Your Machine chooses each one. The name of the folder does not come from the branch. `task` names the folder
+  `task`.
+- A detached Worktree, such as the Worktree of a reviewer, shows `(detached HEAD)` in place of a branch.
+- The attach makes the folders and the clones after the Sandbox is `Ready`. Until then, `/work` has no folder for the
+  Repo Slot. The Machine cuts each Worktree in a state of its body. See [Cut a Worktree](cut-a-worktree.md).
 
 ## Read the branch
 
@@ -124,7 +152,7 @@ git show --stat HEAD
 You can also give one command, with no shell:
 
 ```sh
-kubectl -n <namespace> exec <sandbox> -c harness -- git -C /work/<Repo Slot>/<worktree> log --oneline
+jr2 workspace shell <workspace> -- git -C /work/<Repo Slot>/<worktree> log --oneline
 ```
 
 ## Push the branch
@@ -148,6 +176,23 @@ A [Machine](../reference/glossary.md#machine) can also push the branch with an
 > The Agent works in the same files as your shell, so it sees each change that you make there. When the Sandbox goes, a
 > commit that you did not push goes with it.
 
+## Remove a Sandbox that no run holds
+
+A Sandbox that a cancel with `--keep` or a fault left stays until the operator deletes it. To delete it before then, run
+[`jr2 workspace rm`](../reference/cli.md#workspace-rm):
+
+```sh
+jr2 workspace rm <workspace>
+```
+
+```text
+→ context <context> / namespace <namespace>
+removed Workspace 7a0e8b50/x:0 (ws-7a0e8b50-x-0-1eolpdi)
+```
+
+`jr2 workspace rm` removes only a Sandbox that `jr2 workspace ls` shows as `released` or `idle`. To remove the Sandbox
+of a live run, cancel the run. See [Cancel a run](cancel-a-run.md).
+
 ## Rules
 
 - The Workspace deletes its Sandbox when its body gets to its final state. When the body of each Workspace of the run
@@ -164,11 +209,39 @@ A [Machine](../reference/glossary.md#machine) can also push the branch with an
   its Workspace. The operator deletes the Sandbox 30 minutes after the last renewal.
 - A Workspace in [Placing](../reference/glossary.md#placing) deletes its Sandbox at once, also after a fault and after a
   CANCEL with `--keep`. Its Sandbox has no node yet, so it has nothing to look inside.
+- The `jr2 workspace` commands need your kubectl credentials to list the Sandbox resources. Without them, the command
+  says: `cannot list the Sandboxes in namespace <namespace>: <message>`
+- With no kube context, the `jr2 workspace` commands say:
+  ``no kube context — `kind create cluster` (or point kubectl at one), then `jr2 up` ``
+- A handle that names no Workspace is an error. The command exits with `1`:
+  ``no Workspace "<handle>" — `jr2 workspace ls` lists them``
+- A handle that names more than one Workspace is an error. The command lists each Workspace that it names, and exits
+  with `1`: `"<handle>" names <n> Workspaces — give more of the run id:`
+- `jr2 workspace rm` refuses the Sandbox of a live run, and exits with `1`. There is no option to force it:
+  ``Workspace <handle> (<sandbox>) is not removed: run <run id> holds it — cancel the run first (`jr2 send <run id> --event CANCEL`)``
+- `jr2 workspace rm` refuses a Sandbox with no hold mark (`RUN` is `unknown`), and exits with `1`:
+  ``Workspace <handle> (<sandbox>) is not removed: it has no hold mark, so it may be held by run <run id> — cancel the run first (`jr2 send <run id> --event CANCEL`)``
+- `jr2 workspace rm` refuses a Sandbox that a run started to hold again after `jr2 workspace rm` read it:
+  ``Workspace <handle> (<sandbox>) is not removed: it changed after it was read, so a run may hold it again — run `jr2 workspace ls` and try again``
+- `jr2 workspace shell --user` refuses a Workspace with no User Container, and exits with `1`:
+  ``Workspace <handle> has no User Container: its workspace() names no `user` image``
+- A refusal of the Harness starts with `jr2 workspace shell: `.
+- `jr2 workspace shell` needs `bash` or `sh` on the `PATH` of the Sandbox Image. When it has neither, the command says:
+  `jr2 workspace shell: the Sandbox Image has no bash and no sh on its PATH`
+- `jr2 workspace shell --user` with no command needs `sh` in the image of the User Container. When it has none, the
+  command says: `the User Container's image has no sh: give it a shell, or name a command after --`
+- `jr2 workspace shell --user -- <command>` says this when the User Container cannot run the command (exit `126` or
+  `127`): `the User Container could not run <command> (exit <code>)`
 
 ## Read next
 
 - [Workspaces](../concepts/workspaces.md)
+- [Cut a Worktree](cut-a-worktree.md)
 - [ADR-0004](../reference/decisions/0004-worktree-provisioning-model.md): the clone and the Worktree.
 - [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of a Sandbox.
 - [ADR-0012](../reference/decisions/0012-workspace-wrapper-machine.md): when a Workspace deletes its Sandbox.
+- [ADR-0021](../reference/decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md): the Lease, and when a
+  run holds its Sandbox.
+- [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md): why
+  your shell runs in the domain of the Agents.
 - [Watch a run](watch-a-run.md)

package/docs/guides/move-from-kind-to-a-shared-cluster.md

@@ -54,6 +54,22 @@ below explains one field. Set only the fields that your cluster needs.
   API server and in the kubelets.
 - A container runtime that mounts image volumes, such as containerd 2.1 or later, or CRI-O 1.31 or later. `jr2 up` does
   not check the runtime. With an older runtime, the first Sandbox fails, and its pod events give the cause.
+- Landlock ABI 3 or later in the kernel of each [Sandbox node](../reference/glossary.md#sandbox-node): Linux 6.2 or
+  later, with `landlock` in its list of security modules. A distribution kernel can have it at an older version: the
+  check, not the version, decides. The Harness confines each program of an Agent with it. The Repo cache agent on each
+  Sandbox node checks it, and `jr2 up` refuses to converge while a Sandbox node has no Landlock. It names each such
+  node. To keep a node out, use `sandbox.nodeSelector` or a taint (see
+  [Choose the Sandbox nodes](#choose-the-sandbox-nodes)). A node that joins later and has no Landlock gets no working
+  Sandbox: its Harness does not start.
+- A CNI that enforces NetworkPolicy, and no node credential that a pod can get. `jr2 up` applies a NetworkPolicy that
+  stops each Harness pod at the cloud metadata addresses: `169.254.169.254`, `fd00:ec2::254`, `169.254.170.2`,
+  `169.254.170.23` and `100.100.100.200`. There, the metadata service of a node can give the node's cloud credential to
+  a pod. `jr2 up` does not check these. Do these checks:
+  - Find the metadata address of your cloud provider. If it is not in the list, block it with a NetworkPolicy of your
+    own.
+  - Make sure that the CNI enforces NetworkPolicy. Without it, the policy stops nothing.
+  - Give pods no node credential. On GKE, use Workload Identity. On AWS, use IMDSv2 with a hop limit of 1. Then a pod
+    gets no node credential from the metadata service, also where the policy does not apply.
 - Your kubectl user can apply objects outside the namespace of the Instance. `jr2 up` applies the operator in the
   `jr2-system` namespace, with its CustomResourceDefinitions, ClusterRoles and ClusterRoleBindings. It also applies two
   PriorityClasses, unless you name your own.

package/docs/guides/open-the-console.md

@@ -1,12 +1,13 @@
 ---
 title: Open the Console
-description: Forward the port of the Orchestrator, open the Console, and unlock it with the Instance token.
+description: Forward the port of the Orchestrator, open the Console, and unlock it with a token or a login.
 ---
 
 # Open the Console
 
-Open the [Console](../reference/glossary.md#console) in a browser, and paste the Instance token to start runs and answer
-[Gates](../reference/glossary.md#gate).
+Open the [Console](../reference/glossary.md#console) in a browser. Paste a token, or log in, to start runs and answer
+[Gates](../reference/glossary.md#gate). The Console shows only what the [Caller](../reference/glossary.md#caller) of the
+token may do.
 
 The [Orchestrator](../reference/glossary.md#orchestrator) serves the Console on port 4000, in the cluster. To reach it
 from your computer, forward the port with `kubectl`. In the commands on this page, replace `<namespace>` with the
@@ -39,6 +40,8 @@ Without the token, the Console shows the runs, and you cannot change them:
   Click the caret of a Workflow to list its runs.
 - The center shows the [Machine](../reference/glossary.md#machine) of the Workflow that you select. When you select a
   run, the Console shows the states that the run is in.
+- A run on an [Assembly](../reference/glossary.md#assembly) that is not the current one shows the mark
+  `older Assembly · <hash>`. The center then shows the Machine of that run, not the current Machine.
 - The Activity tab of the right drawer lists the type of each [Emit](../reference/glossary.md#emit) of the runs of the
   Workflow, the newest first.
 
@@ -62,29 +65,75 @@ The command prints the token, with no line break after it.
 
 ## Paste the token
 
-Paste the token into the box `instance token` in the nav of the Console. Push Enter. The badge after the box shows `…`
-while the Console checks the token, then `live`. With a live token, the Console shows more:
+Paste the token into the box `Caller token` in the nav of the Console. Push Enter. The badge after the box shows `…`
+while the Console checks the token, then `live`. The nav then shows who the Console acts as, such as
+`as token/instance`. Put the pointer on the name to see its scopes.
 
-- A `start` button for each Workflow in the Fleet rail. It opens a form for the run input of the Workflow. A Workflow
-  that declares no run input gets a box for JSON.
-- The Attention tab of the right drawer. It shows a card for each open Gate of the selected Workflow, with a form to
-  send each event that the Gate takes. Select `all workflows` to see the Gates of each Workflow.
+The Console asks the Orchestrator what the token may do ([`GET /whoami`](../reference/http-api.md#get-whoami)). Then it
+shows each control that a scope of the token opens:
 
-The Console keeps the token in the browser tab. A reload keeps it. When you close the tab, the token is gone.
+| Scope    | What the Console shows                                                                                                                                                                    |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start`  | A `start` button for the Workflow in the Fleet rail. It opens a form for the run input of the Workflow.                                                                                   |
+| `answer` | The Attention tab of the right drawer, with a card for each open Gate and a form for each event it takes.                                                                                 |
+| `read`   | The full state of the selected run: why it waits, why it failed, and who started it. The ended runs of the Workflow in the Fleet rail. The conversations of the run in the bottom drawer. |
+| `cancel` | A `cancel run` button on the selected run, while the run is live.                                                                                                                         |
+| `steer`  | A box in the bottom drawer, beside the [Agent](../reference/glossary.md#agent) slot, to send a [Steering message](../reference/glossary.md#steering-message) while the run is live.       |
+
+The Instance token has each scope for each Workflow, so it shows each control. A named Caller token shows the controls
+of its scopes, for its Workflows ([Give a Caller a scope](give-a-caller-a-scope.md)). A Workflow that declares no run
+input gets a box for JSON in its start form. In the Attention tab, select `all workflows` to see the Gates of each
+Workflow.
+
+The Console keeps the token in the browser tab. A reload keeps it. When you close the tab, the token is gone. Click
+`sign out` to forget it before then.
+
+## Read a conversation
+
+With `read`, the Fleet rail lists the ended runs of the selected Workflow under its live runs, each with its status. A
+`drifted` run shows its reason. Click an ended run to see its Machine, the state where it ended, and its conversations,
+for as long as jr2 keeps the run ([`runs.retain`](../reference/config.md#runs)).
+
+The bottom drawer shows the [Conversations](../reference/glossary.md#conversation) of the selected run. Closed, it is a
+bar with one tab for each Agent slot of the run. A dot shows a slot whose [Turn](../reference/glossary.md#turn) is open.
+Click a tab to open the drawer on that slot. The drawer shows what the model wrote, each tool call with the answer of
+its pick, the refusals, the Steering messages and the notices. While the Turn is open, the drawer adds each new entry.
+Drag the top edge of the drawer to change its height. The browser keeps the height for you.
+
+## Log in
+
+When the Instance declares an issuer with [`login: true`](../reference/config.md#callers), the nav shows a `log in`
+button. Click it. The browser goes to the login page of the issuer, and then comes back to the Console. The Console then
+acts as you, with the scopes that your groups give. The nav shows the name that jr2 shows for you, such as your email.
+
+To make the login work, register a client at the issuer:
+
+- A public client, with no secret. Its client id is the `audience` of the issuer entry.
+- The redirect URI is the root of the Console, such as `http://localhost:4000/`.
+- The issuer must let the origin of the Console call its discovery document and its token endpoint (CORS).
+
+The login needs the Console on `https`, or on `localhost`, because the browser makes its code challenge only there.
 
 ## Rules
 
 - A token that the Orchestrator does not accept reads `invalid`. The Console then shows no `start` button and no
   Attention tab.
-- When the Orchestrator refuses the token later, with the status 401, the Console goes back to view only.
-- Only the Instance token unlocks the Console. A [Sandbox](../reference/glossary.md#sandbox) token reads `invalid`.
+- When the Orchestrator refuses the token later, with the status 401, the Console goes back to view only. An expired
+  login and a rotated token do this.
+- A login whose groups give no scope reads `live` and shows no control. The nav shows who you are, so that you can see
+  why.
+- A [Sandbox](../reference/glossary.md#sandbox) token is not a Caller. It reads `invalid`.
+- The Console hides a control that the scopes do not open, so that you do not get a 403. The Orchestrator still checks
+  each request.
 - The port forward stops when you stop its command, or when the Orchestrator pod restarts. Then run the command again.
 
 ## Read next
 
 - [Architecture](../concepts/architecture.md)
-- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md): why the token unlocks the
-  Console.
+- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md): why a Caller's credential
+  unlocks the Console, and how the login works.
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): the
+  Callers and their scopes.
 - [ADR-0014](../reference/decisions/0014-observation-is-open-run-state-is-not.md): what the Console shows with no token.
 - [`GET /`](../reference/http-api.md#get) and the [open band](../reference/http-api.md#band-open)
 - [Answer a Gate](answer-a-gate.md)