@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/push-and-sign-a-branch.md

@@ -1,20 +1,22 @@
 ---
 title: Push and sign a branch
-description: Push the branch of a Workspace, and sign its commits with a key that the Agent never reads.
+description: Push the branch of a Worktree, and sign its commits with a key that the Agent never reads.
 ---
 
 # Push and sign a branch
 
-Push the branch of a [Workspace](../reference/glossary.md#workspace) with a `push`
+Push the branch of a [Worktree](../reference/glossary.md#worktree) with a `push`
 [Effect](../reference/glossary.md#effect), signed with a key that the [Agent](../reference/glossary.md#agent) never
 reads.
 
 [`push(options)`](../reference/authoring-surface/push.md) pushes the branch to the [Repo](../reference/glossary.md#repo)
-that the [Binding](../reference/glossary.md#binding) of its [Repo Slot](../reference/glossary.md#repo-slot) names. With
-`sign: true`, it pushes signed copies of the Agent's commits. In this [Workflow](../reference/glossary.md#workflow), a
-coder fixes the tests and commits. A person reads the branch at the [Gate](../reference/glossary.md#gate) of the state
-`review`, then sends `approve`. Then the [Machine](../reference/glossary.md#machine) pushes the branch, signed. Save the
-file as `workflows/publish.ts` in your [Instance](../reference/glossary.md#instance):
+that the [Binding](../reference/glossary.md#binding) of its [Repo Slot](../reference/glossary.md#repo-slot) names. Its
+input names the Worktree, `{ worktree }`, and has no branch. jr2 reads the branch from the cut of that path, so an Agent
+that moves `HEAD` does not change what jr2 pushes. With `sign: true`, it pushes signed copies of the Agent's commits. In
+this [Workflow](../reference/glossary.md#workflow), a coder fixes the tests and commits. A person reads the branch at
+the [Gate](../reference/glossary.md#gate) of the state `review`, then sends `approve`. Then the
+[Machine](../reference/glossary.md#machine) pushes the branch, signed. Save the file as `workflows/publish.ts` in your
+[Instance](../reference/glossary.md#instance):
 
 **Anthropic**
 
@@ -25,9 +27,11 @@ import {
   agent,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type PushOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -45,6 +49,9 @@ const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { pushed?: PushOutput };
 
+// The Worktree of the coder. The push names it, and jr2 reads its branch from the cut.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [finished, approve, stop],
@@ -53,6 +60,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You fix failing tests. You change no test. You commit the fix.",
     }),
+    cut: worktree(),
     // Push signed copies of the Agent's commits, with the key of the git.credentials entry.
     publish: push({ sign: true }),
     fail: fail(),
@@ -61,23 +69,32 @@ const body = jr2Setup({
   id: "publish",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: ({ context }) => ({ prompt: context.prompt, cwd: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: fixTree(context) }),
       },
       on: { finished: "review" },
     },
     // A person reads the branch, then answers.
     review: {
-      invoke: { src: "gate", input: ({ context }) => ({ meta: { branch: context.workspace.branch } }) },
+      invoke: { src: "gate", input: ({ context }) => ({ meta: { branch: context.branch } }) },
       on: { approve: "publishing", stop: "done" },
     },
     publishing: {
       invoke: {
         src: "publish",
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
           // rejected, diverged or unknown: the run waits, so that the Sandbox and its commits stay.
@@ -90,6 +107,7 @@ const body = jr2Setup({
       on: { approve: "publishing", stop: "done" },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -98,7 +116,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -111,9 +128,11 @@ import {
   agent,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type PushOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -131,6 +150,9 @@ const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { pushed?: PushOutput };
 
+// The Worktree of the coder. The push names it, and jr2 reads its branch from the cut.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [finished, approve, stop],
@@ -139,6 +161,7 @@ const body = jr2Setup({
       model: "local/qwen3.6-35b-a3b",
       instructions: "You fix failing tests. You change no test. You commit the fix.",
     }),
+    cut: worktree(),
     // Push signed copies of the Agent's commits, with the key of the git.credentials entry.
     publish: push({ sign: true }),
     fail: fail(),
@@ -147,23 +170,32 @@ const body = jr2Setup({
   id: "publish",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: ({ context }) => ({ prompt: context.prompt, cwd: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: fixTree(context) }),
       },
       on: { finished: "review" },
     },
     // A person reads the branch, then answers.
     review: {
-      invoke: { src: "gate", input: ({ context }) => ({ meta: { branch: context.workspace.branch } }) },
+      invoke: { src: "gate", input: ({ context }) => ({ meta: { branch: context.branch } }) },
       on: { approve: "publishing", stop: "done" },
     },
     publishing: {
       invoke: {
         src: "publish",
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
           // rejected, diverged or unknown: the run waits, so that the Sandbox and its commits stay.
@@ -176,6 +208,7 @@ const body = jr2Setup({
       on: { approve: "publishing", stop: "done" },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -184,7 +217,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -313,6 +345,7 @@ jr2 up
 ```text
 …
 effects: workflow "publish" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
   publish: push (sign) — 300s, in the Sandbox Effector
 …
 Workspace of workflow "publish": Sandbox Effector (image the Sandbox Image) holds no Effect secret; pushes Repo Slot "app" with git.credentials "github.com/<you>/"
@@ -372,7 +405,8 @@ Each outcome is output for `onDone`. Route on `outcome`
 ([`PushOutput`](../reference/authoring-surface/type-pushoutput.md)):
 
 - `pushed`: the remote has the commit. `published` is the commit on the remote, and `source` is the Agent's commit.
-- `rejected`: git, the remote or the Sandbox Effector refused the push. `stage` tells where, and `reason` tells why.
+- `rejected`: git, the remote or the Sandbox Effector refused the push. `stage` tells where, and `reason` tells why. A
+  `worktree` that jr2 cannot use is `rejected` at the `stage` `start`, and jr2 pushes nothing. See [Rules](#rules).
 - `diverged`: in a signed push, the commit on the remote is not in the history of the Agent's branch, and jr2 cannot
   pair it with an Agent commit. jr2 pushed nothing. An unsigned push to a remote branch that moved is `rejected`.
 - `unknown`: jr2 cannot tell what the push did.
@@ -394,12 +428,14 @@ jr2 send <run id> --gate body.notPushed --event approve
 
 ## Other options
 
-- `pin: true`: push the commit that the input of the Effect names, `{ sha: "<full commit id>" }`. Use it for a commit
-  that a Gate approved. Without `pin`, jr2 pushes the tip of the branch when the Effect starts.
-- `squash: true`: push one commit that holds all of the changes. The input gives its message, `{ message: "<text>" }`.
-  Without `sign`, the [`committer`](../reference/config.md#git-credentials-committer) of the entry commits it.
+- `pin: true`: push the commit that the input of the Effect names, `{ worktree, sha: "<full commit id>" }`. Use it for a
+  commit that a Gate approved. Without `pin`, jr2 pushes the tip of the branch when the Effect starts.
+- `squash: true`: push one commit that holds all of the changes. The input gives its message,
+  `{ worktree, message: "<text>" }`. Without `sign`, the [`committer`](../reference/config.md#git-credentials-committer)
+  of the entry commits it.
 - `force: true`: replace what the remote branch holds.
-- `slot`: the Repo Slot to push. Write it only when the Workspace has more than one Repo Slot.
+- `slot`: the Repo Slot to push. Write it only when the Workspace has more than one Repo Slot. It is static, because
+  `jr2 up` places the credential for each slot.
 - `timeout`: how long jr2 waits for the push. The default is `"5m"`. After it, the outcome is `unknown`.
 
 ## Rules
@@ -461,6 +497,15 @@ When a `push` starts, it refuses:
   `push({ pin: true }): its input's sha is not a full commit id (got <sha>)`
 - with `squash: true`, an input with no message: `push({ squash: true }): its input carries no message`
 
+A push settles `rejected`, with `stage` `start`, for each of these. Its `reason` ends `; nothing was pushed`:
+
+- a `worktree` that is not a Worktree path, or a slot that the Workspace does not have:
+  `"<path>" is not a Worktree path: /work/<slot>/<name>, with one segment in <name>`, or
+  `"<path>" names Repo Slot "<slot>", which its Workspace does not carry (<slots>)`
+- a `worktree` that no cut made in this Sandbox: `no cut made <path> in this Sandbox: cut it with worktree()`
+- a Worktree of a different Repo Slot: `<path> is a Worktree of Repo Slot "<slot>", not of "<slot>"`
+- a detached Worktree: `<path> is detached: a push publishes the branch of a Worktree, and it holds none`
+
 `push()` refuses a timeout that is not a positive duration:
 `timeout "<timeout>" is not a positive duration (like "30s", "5m")`
 
@@ -474,6 +519,7 @@ the push Secret of the entry, `jr2-git-push-<hash>`, as `jr2 up` shows it. It is
 - [Secrets and trust](../concepts/secrets-and-trust.md): who holds the push credential and the signing key.
 - [Give the cluster git credentials](give-the-cluster-git-credentials.md): the entries of `git.credentials`.
 - [Add tools to the Sandbox](add-tools-to-the-sandbox.md): the Sandbox Image.
+- [Cut a Worktree](cut-a-worktree.md): the Worktree that a `push` publishes.
 - Reference: [`push`](../reference/authoring-surface/push.md),
   [`PushOptions`](../reference/authoring-surface/type-pushoptions.md),
   [`PushOutput`](../reference/authoring-surface/type-pushoutput.md) and

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.