@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -11,42 +11,47 @@ 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.
@@ -56,18 +61,39 @@ ws-a1322024-x-2-h8pgwk   Ready   http://ws-a1322024-x-2-h8pgwk.my-instance.svc:8
 
 ## 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 each [Worktree](../reference/glossary.md#worktree) that the
-Machine cut 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
@@ -82,8 +108,8 @@ git -C /work/<Repo Slot>/default worktree list
 For the slot `target` of a run of `task`, the output is:
 
 ```text
-/work/target/default  7f258f6 (detached HEAD)
-/work/target/task     e467788 [jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd]
+/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 base of the Repo Slot. Here the base is a tag, so the clone is detached. On a
@@ -126,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
@@ -150,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
@@ -166,6 +209,29 @@ 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
 
@@ -174,4 +240,8 @@ A [Machine](../reference/glossary.md#machine) can also push the branch with an
 - [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/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)

package/docs/guides/read-a-conversation.md

@@ -0,0 +1,225 @@
+---
+title: Read a conversation
+description: Read what an Agent said and did in a run, live or after the run ended, with jr2 logs or the Console.
+---
+
+# Read a conversation
+
+Read the [Conversation](../reference/glossary.md#conversation) of each [Agent](../reference/glossary.md#agent) of a run,
+while the run continues or after it ended.
+
+The [Harness](../reference/glossary.md#harness) of each Agent sends the entries of its conversation to the
+[Orchestrator](../reference/glossary.md#orchestrator) during the [Turn](../reference/glossary.md#turn). The Orchestrator
+keeps them for as long as it keeps the run. Thus you can read a conversation after its
+[Sandbox](../reference/glossary.md#sandbox) is gone. A [Menu](../reference/glossary.md#menu)-only Agent sends its
+conversation in the same way.
+
+The examples on this page use a run of the `task` [Workflow](../reference/glossary.md#workflow) of
+[An Agent in a Sandbox](../get-started/an-agent-in-a-sandbox.md), with the prompt
+``In docs/intro/repo, run `node bin/greet.js`. Then finish, with what it printed.``. In the commands, replace `<run id>`
+with the run id, or its first 4 characters or more. `jr2 run` prints the run id in the line
+`run <run id> (<workflow>) — attached`.
+
+Give each `jr2` command in the [Instance](../reference/glossary.md#instance) folder.
+
+## Print the conversations of a run
+
+Run [`jr2 logs`](../reference/cli.md#logs) with the run id. It prints the conversation of each Agent of the run, in the
+order of the time of each entry:
+
+```sh
+jr2 logs <run id>
+```
+
+```text
+→ context <context> / namespace <namespace>
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [prompt] In docs/intro/repo, run `node bin/greet.js`. Then finish, with what it printed.
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] Work in /work/target/task, on branch jr2/task-48ebf9ad-1e5d-4997-a330-d91ec762f83c — your tools are rooted there, so a relative path lands inside it. Commit what you do there, then call finish.
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] <jr2-turn>
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] Working directory: /work/target/task
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] Allowed now: `mcp__jr2__finish`.
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] </jr2-turn>
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [thinking] The user wants me to:
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] 1. Run `node bin/greet.js` in the directory `docs/intro/repo`
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] 2. Finish with what it printed
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] Let me first check if this file exists and what it contains, then run it.
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [text]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [bash] node docs/intro/repo/bin/greet.js
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [thinking] The command printed "hello, world". Now I need to finish with that.
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [text]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder]
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [finish] {"summary":"Ran `node bin/greet.js` in docs/intro/repo. It printed: hello, world"}
+[coder] [7a0e8b50-7b3e-4d83-837c-d07857d81868/body/coder] [finish answer] Delivered "finish" to the workflow (delivery a86c2340-377a-4c4d-a138-2872c38c1219). The workflow consumed it and moved on: your turn is over.
+```
+
+The thinking, the calls and the text are the words of the model, so your conversation is different. Your ids are
+different too.
+
+`jr2 logs` prints the conversation lines of the pod log of the Harness. It does not print the lines of the story of the
+run: `[run] …`, and `[<agent>] [admitted] …` and `[<agent>] [pick] …`, which have no Instance ID.
+[Watch a run](watch-a-run.md#read-the-pod-log) tells how to read the pod log.
+
+## Print the conversation of one Agent
+
+Give an Agent slot, or the name of an Agent, after the run id. An Agent slot is the path of the
+[Machine](../reference/glossary.md#machine) of the Agent, then its name, such as `body/coder`.
+[`jr2 steer`](../reference/cli.md#steer) `<run id>` lists the Agent slots of a live run. A name, such as `coder`, prints
+each conversation of the Agents of that name:
+
+```sh
+jr2 logs <run id> coder
+```
+
+When the run keeps no conversation of that Agent, `jr2 logs` lists the Agents that it keeps. Without `-f`, it then exits
+with `1`. With `-f`, it waits for the conversation of that Agent.
+
+## Follow a conversation
+
+Add `-f` to print each new entry when the Orchestrator keeps it:
+
+```sh
+jr2 logs <run id> -f
+```
+
+`jr2 logs -f` first prints what the Orchestrator keeps. Then it follows each conversation that has an open Turn, and it
+finds each new conversation of the run. It stops when the run ended and no Turn is open. The Harness sends its entries
+when the model's answer ends, at the end of the Turn, and about one time each second. Thus a line comes a short time
+after the model wrote it.
+
+## Read the lines
+
+Each line starts with the name of the Agent in brackets, then the [Instance ID](../reference/glossary.md#instance-id) of
+the conversation in brackets. The Instance ID starts with the run id. The first line of each entry then has a label in
+brackets. The next lines of the same entry have no label:
+
+| Line                                          | What it shows                                                                                                                                                                        |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `[<agent>] [<iid>] [prompt] <text>`           | A message that the model reads: the prompt of the Turn, or a message that jr2 adds to the Turn, such as a [Steering message](../reference/glossary.md#steering-message) or a notice. |
+| `[<agent>] [<iid>] [thinking] <text>`         | The thinking of the model.                                                                                                                                                           |
+| `[<agent>] [<iid>] [text] <text>`             | The text of the model.                                                                                                                                                               |
+| `[<agent>] [<iid>] [<call>] <input>`          | A call of a [Working tool](../reference/glossary.md#working-tools), or a pick from the Menu. `<input>` is a path for read, write and edit, the command for `bash`, or else JSON.     |
+| `[<agent>] [<iid>] [<server>/<tool>] <input>` | A call of an [MCP tool](../reference/glossary.md#mcp-tools): the server's name in `jr2.config.ts`, then the tool. `<input>` is JSON. A pick never prints with a `/`.                 |
+| `[<agent>] [<iid>] [<pick> answer] <text>`    | The answer that the model got for a pick from its Menu.                                                                                                                              |
+| `[<agent>] [<iid>] [<pick> error] <text>`     | An answer to a pick that the model reads as an error, such as a refusal.                                                                                                             |
+| `[<agent>] [<iid>] [compacted] <text>`        | The Harness made the context of the conversation smaller: `context <before> → ~<after> tokens (window <window>)`.                                                                    |
+| `[<agent>] [<iid>] [thinking level] <text>`   | The model has no thinking level of the name that the Turn asked for, and the line names the level that the model ran at. The Harness prints it one time for each Turn.               |
+| `[<agent>] [<iid>] [cut] <text>`              | The Orchestrator keeps no more entries of this conversation. See [Rules](#rules).                                                                                                    |
+
+The conversation does not hold the result of a Working tool or of an MCP tool. For example, it does not hold the text of
+a file that the Agent read, or the output of a command that the Agent ran. The Harness cuts an input that is longer than
+2000 characters at its end, and marks the cut with `…`. It cuts a long answer to a pick in its middle, and marks the cut
+with `… [<n> characters cut] …`. The model reads the full text.
+
+## Read a conversation in the Console
+
+With a [Caller](../reference/glossary.md#caller) token that has the `read` scope for the Workflow, the
+[Console](../reference/glossary.md#console) shows the conversations of the run that you select:
+
+- The bottom drawer has one tab for each Agent slot of the run. A dot on a tab shows a slot whose Turn is open.
+- Click a tab. The drawer opens on the conversation of that slot. While the Turn is open, the drawer adds each new
+  entry.
+- The drawer folds each pick with its answer. A Working tool's call shows no result. It shows the Steering messages, the
+  notices and each [Compaction](../reference/glossary.md#compaction).
+- The Fleet rail lists the ended runs of the Workflow under its live runs. Click an ended run to read its conversations.
+
+[Open the Console](open-the-console.md#read-a-conversation) tells more.
+
+## Keep conversations for a different time
+
+The Orchestrator keeps an ended run, with its conversations, for 30 days. To change the time, set
+[`runs.retain`](../reference/config.md#runs) in `jr2.config.ts`. The conversations are on the state volume of the
+Orchestrator. A new volume claim is `5Gi` by default. To make it larger, set `runs.volume`:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  runs: {
+    // Keep each ended run, its conversations and the hook log for 90 days.
+    retain: "90d",
+    // The size of the Orchestrator's state volume. A larger size needs a StorageClass that allows expansion.
+    volume: "20Gi",
+  },
+});
+```
+
+Then run [`jr2 up`](../reference/cli.md#up). The Orchestrator uses the new `retain` at its next sweep, one time each
+hour. When `runs.volume` is larger than the volume claim, `jr2 up` makes the claim larger, but only when its
+StorageClass allows expansion. The `standard` class of kind does not. Thus on kind, with the claim of `5Gi` that the
+first `jr2 up` made, `jr2 up` refuses, and applies nothing:
+
+```text
+…
+refusing: runs.volume is 20Gi, larger than the state volume claim jr2-state (5Gi), and its StorageClass "standard" does not allow expansion (allowVolumeExpansion is not true). Keep runs.volume at 5Gi, or use a StorageClass that allows expansion (ADR-0065). Nothing was applied.
+```
+
+On kind, set `runs.volume` before the first `jr2 up` of the Instance. A new claim takes that size, and `jr2 up` prints
+no line about it. A live run and its conversations stay, whatever their age.
+
+## Rules
+
+- The Orchestrator keeps at most 8 MiB of one conversation. It keeps the start of the conversation. In place of the
+  entry that goes above the limit, it keeps one entry `[cut]`, and it keeps no entry after it:
+  `the Orchestrator keeps no more of this conversation: it is at its cap of 8 MiB (ADR-0023)`
+- When the state volume is more than 80% full, the Orchestrator deletes the conversations of the runs that ended, the
+  oldest run first, until the volume is less than 80% full. It does not delete the row of the run. It never deletes a
+  conversation of a live run for space. `jr2 logs` prints `<agent slot> [<iid>]: no space` in place of a conversation
+  that it deleted, and `jr2 status` and `jr2 runs` give the run `swept: "conversation swept: no space"`.
+- When the volume is more than 95% full and no ended run has a conversation to delete, the Orchestrator keeps no more
+  entries of each open conversation:
+  `the Orchestrator keeps no more of this conversation: its state volume is full (ADR-0065)`
+- `jr2 logs` with an Agent that the run keeps no conversation of prints a line on stderr. Without `-f`, it then exits
+  with `1`; with `-f`, it waits: `run <run id> keeps no conversation of "<agent>" — its Agents: <slots>`
+- When the run keeps no conversation at all, the line ends differently:
+  `run <run id> keeps no conversation of "<agent>" — it keeps no conversation yet`
+- The routes of the conversations refuse a Caller without the `read` scope for the Workflow of the run, with the status
+  code `403`: `the Caller <via>/<name> needs the "read" scope for Workflow "<workflow>" (ADR-0078)`. A Caller with the
+  `read` scope for no Workflow gets this refusal first:
+  `the Caller <via>/<name> has no "read" scope for any Workflow (ADR-0078)`
+- `GET /runs/:runId/conversations/:instanceId` refuses an Instance ID that the run does not keep, with the status code
+  `404`: `run "<run id>" keeps no conversation "<iid>"`
+- `runs.retain` is a number and `m`, `h`, `d` or `w`. The config load refuses another value:
+  `<file> at runs.retain: "<value>" is not a duration — a number and m, h, d or w, such as "30d" (ADR-0065)`
+- The config load refuses a `runs.retain` that is shorter than one hour:
+  `<file> at runs.retain: "<value>" is shorter than 1h — jr2 keeps an ended run for at least 1h (ADR-0065)`
+- The config load refuses a `runs.volume` with no unit:
+  `<file> at runs.volume: "<value>" is not a storage quantity — a number and a unit, such as "5Gi" or "500Mi" (ADR-0065)`
+- `jr2 up` grows the claim when `runs.volume` is larger and the StorageClass allows expansion:
+  `state volume: growing the claim jr2-state from <claim size> to <size>`
+- `jr2 up` keeps the size of a claim that exists when `runs.volume` is not set, and the claim is not `5Gi`:
+  `state volume: keeping the claim jr2-state at <claim size> — runs.volume is not set, and the default 5Gi is for a new claim`
+- `jr2 up` refuses, and applies nothing, when it cannot read the claim:
+  `refusing: cannot read the state volume claim jr2-state in namespace "<namespace>" (<error>). Nothing was applied.`
+- `jr2 up` refuses, and applies nothing, when `runs.volume` is larger and it cannot read the StorageClass:
+  `refusing: runs.volume is <size>, larger than the state volume claim jr2-state (<claim size>), and jr2 cannot read StorageClass "<class>" to see if it allows expansion (<error>). Nothing was applied.`
+- `jr2 up` refuses a `runs.volume` that is smaller than the claim, and applies nothing:
+  `refusing: runs.volume is <size>, smaller than the state volume claim jr2-state (<claim size>) — Kubernetes never makes a claim smaller. Set runs.volume to <claim size> or more (ADR-0065). Nothing was applied.`
+- `jr2 up` refuses a larger `runs.volume` on a StorageClass that does not allow expansion, and applies nothing:
+  `refusing: runs.volume is <size>, larger than the state volume claim jr2-state (<claim size>), and its StorageClass "<class>" does not allow expansion (allowVolumeExpansion is not true). Keep runs.volume at <claim size>, or use a StorageClass that allows expansion (ADR-0065). Nothing was applied.`
+
+> **Caution**
+>
+> A Caller with `read` can read each conversation of the Workflow, and the answers that jr2 gives to the picks. An answer
+> can hold the output of a [`command`](../reference/authoring-surface/command.md)
+> [Effect](../reference/glossary.md#effect). Give `read` only to the Callers that can see that output.
+> [Secrets and trust](../concepts/secrets-and-trust.md) tells what a conversation can hold.
+
+## Read next
+
+- [Agents and Turns](../concepts/agents-and-turns.md)
+- [Durable runs](../concepts/durable-runs.md): how long jr2 keeps a run.
+- [ADR-0023](../reference/decisions/0023-the-harness-prints-the-conversation.md): the Harness prints the conversation,
+  and the Orchestrator keeps it.
+- [ADR-0065](../reference/decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md):
+  `runs.retain`, `runs.volume` and the space guard.
+- Reference: [`jr2 logs`](../reference/cli.md#logs), [`runs`](../reference/config.md#runs),
+  [`GET /runs/:runId/conversations`](../reference/http-api.md#get-runs-runid-conversations)
+- [Watch a run](watch-a-run.md)

package/docs/guides/run-a-chart-by-name.md

@@ -141,26 +141,24 @@ Put the Chart file in a folder that has the name of its wrapper: `workflows/<wra
 lower-case letters, digits and `-`. Then run [`jr2 up`](../reference/cli.md#up). It checks each Chart file at the door
 before it changes the cluster, and publishes it in the [Assembly](../reference/glossary.md#assembly).
 
-[`jr2 runs`](../reference/cli.md#runs) lists the Chart under its wrapper, on stderr:
+[`jr2 workflows`](../reference/cli.md#workflows) lists the Chart under its wrapper:
 
 ```sh
-jr2 runs
+jr2 workflows
 ```
 
 ```text
 …
 → context kind-jr2 / namespace my-instance
-workflows:
-  notes (machine, Chart wrapper: body "body", one-shot)
-    notes/summary (chart file)
-  ping (machine)
-[]
+notes (machine, Chart wrapper: body "body", one-shot)
+  notes/summary (chart file)
+ping (machine)
 ```
 
 The first line, `…`, is the line `→ .env:`, with the keys that the CLI took from `.env`.
 
-`one-shot` means that the wrapper also takes a Chart in its run input. `jr2 runs --workflows` prints the same list as
-JSON on stdout.
+`one-shot` means that the wrapper also takes a Chart in its run input. `jr2 workflows --json` prints the same list as
+JSON.
 
 ## Run the Chart
 
@@ -173,7 +171,7 @@ jr2 run notes/summary --input '{"topic":"the greet CLI"}'
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run 08a1a07b-b5d8-4e8b-aec5-811eab9289ec (notes/summary) — attached
+run ff5db853-9afc-4563-9db4-e5c2a49b15a2 (notes/summary) — attached
   → active "running"
   → active "running"
   → done "done"
@@ -203,12 +201,12 @@ curl -X PUT -H "Authorization: Bearer $TOKEN" -H "content-type: application/json
 ```
 
 ```text
-{"name":"notes/brief","origin":"runtime","hash":"4685124c248a"}
+{"name":"notes/brief","origin":"runtime","hash":"4f2fb0e7474c"}
 ```
 
 `hash` is the hash of the Chart text. The status code is `201` for a new name, and `200` when the Chart replaced a
-runtime Chart with the same name. `jr2 runs` then lists `notes/brief (chart)`, and `jr2 run notes/brief` starts it. A
-run of the old text keeps its own text.
+runtime Chart with the same name. `jr2 workflows` then lists `notes/brief (chart)`, and `jr2 run notes/brief` starts it.
+A run of the old text keeps its own text.
 
 To remove the Chart:
 
@@ -217,7 +215,7 @@ curl -X DELETE -H "Authorization: Bearer $TOKEN" http://localhost:4000/workflows
 ```
 
 The Orchestrator keeps a runtime Chart on its volume, so it stays after a restart. When a publish removes a part that it
-uses, it stays, and `jr2 runs` marks it `unrunnable` with the reason.
+uses, it stays, and `jr2 workflows` marks it `unrunnable` with the reason.
 
 ## Run a Chart one time
 
@@ -254,7 +252,9 @@ write.
 - The `PUT` refuses a Chart that the door refuses, with the status `422`: `{"error":"refused","report":[<problems>]}`
 - The `DELETE` refuses a Chart file, with the status `409`:
   ``a Chart file is the Instance's own: remove workflows/<wrapper>/<name>.chart.json and `jr2 up` (ADR-0070)``
-- `PUT` and `DELETE` need the Instance token. Without it, the status is `401`.
+- `PUT` and `DELETE` need the Instance token. No scope opens them. Without a token, the status is `401`. With the token
+  of a named Caller or a JWT, the status is `403`:
+  `this route needs the Instance token: no scope opens it, so the Caller <via>/<name> cannot`
 - An unrunnable named Chart does not start. The status is `409`: `named Chart "<wrapper>/<name>" cannot run: <reason>`
 - `jr2 run` prints the report of a Chart that the door refuses in the run input, and exits with `1`:
   `error: the door refused the Chart for "<workflow>"`, then one line for each problem.
@@ -264,7 +264,8 @@ write.
 - [Charts](../concepts/charts.md)
 - [Start a run](start-a-run.md)
 - [Let an Agent write a Chart](let-an-agent-write-a-chart.md)
-- Reference: [`chartSchema`](../reference/authoring-surface/chartschema.md), [`jr2 runs`](../reference/cli.md#runs),
+- Reference: [`chartSchema`](../reference/authoring-surface/chartschema.md),
+  [`jr2 workflows`](../reference/cli.md#workflows),
   [`PUT /workflows/:wrapper/charts/:name`](../reference/http-api.md#put-workflows-wrapper-charts-name),
   [`GET /workflows/:wrapper/chart-schema`](../reference/http-api.md#get-workflows-wrapper-chart-schema)
 - [ADR-0070](../reference/decisions/0070-a-machine-lends-its-parts-to-a-chart.md): a Machine lends its parts to a Chart.