@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/concepts/workspaces.md

@@ -8,10 +8,10 @@ description: How a Workflow gets a Sandbox with a git Worktree or a shared folde
 A [Workspace](../reference/glossary.md#workspace) is a [Machine](../reference/glossary.md#machine) that runs a body
 Machine in a [Sandbox](../reference/glossary.md#sandbox). The Sandbox is a pod of its own, with a folder, `/work`, that
 the Agents and Effects of the body share. When the Workspace names [Repos](../reference/glossary.md#repo), `/work` holds
-a git [Worktree](../reference/glossary.md#worktree) of each Repo on one branch. A Workspace that names no Repo has only
-the folder (see [A Workspace with no Repo](#a-workspace-with-no-repo)). You make a Workspace with
-[`workspace()`](../reference/authoring-surface/workspace.md). The Workspace makes the Sandbox when the run enters it,
-and deletes the Sandbox when the body reaches a final state.
+a clone of each Repo. The body cuts each git [Worktree](../reference/glossary.md#worktree) that it needs. A Workspace
+that names no Repo has only the folder (see [A Workspace with no Repo](#a-workspace-with-no-repo)). You make a Workspace
+with [`workspace()`](../reference/authoring-surface/workspace.md). The Workspace makes the Sandbox when the run enters
+it, and deletes the Sandbox when the body reaches a final state.
 
 ## Why Workspaces exist
 
@@ -27,14 +27,24 @@ Agent.
 ## A Workspace and its body
 
 This example is a [Workflow](../reference/glossary.md#workflow). A coder changes the `app` Repo, and reads the
-`handbook` Repo beside it. Then a person approves the change at a [Gate](../reference/glossary.md#gate), and the Machine
-pushes the branch:
+`handbook` Repo beside it. The Machine first cuts the coder's Worktree. Then a person approves the change at a
+[Gate](../reference/glossary.md#gate), and the Machine pushes the branch:
 
 **Anthropic**
 
 ```ts
 import { z } from "zod";
-import { agent, defineEvent, fail, jr2Setup, push, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  agent,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 const finished = defineEvent({
   name: "finished",
@@ -51,6 +61,10 @@ const approve = defineEvent({
 const runInput = z.object({ ticket: z.string(), prompt: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app" | "handbook">;
 
+// The folder of the Worktree, and its branch. The Machine knows both before the cut.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const branchOf = (context: BodyInput) => `docs/${context.ticket}`;
+
 const body = jr2Setup({
   types: {} as { context: BodyInput; input: BodyInput },
   events: [finished, approve],
@@ -59,6 +73,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer. You commit your work on the branch.",
     }),
+    cut: worktree(),
     // Two Repo Slots, so the push names the slot that it pushes.
     publish: push({ slot: "app" }),
     fail: fail(),
@@ -66,17 +81,25 @@ const body = jr2Setup({
 }).createMachine({
   id: "docs-fix",
   context: ({ input }) => input,
-  initial: "working",
+  initial: "cutting",
   // The Sandbox is gone, and its unpushed commits with it. This body fails the run.
   on: { "agent.fault": ".failed", "workspace.lost": ".lost" },
   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: branchOf(context) }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "working" }, { target: "notCut" }],
+      },
+    },
     working: {
       invoke: {
         src: "coder",
         input: ({ context }) => ({
-          prompt: `${context.prompt}\nRead the style rules in ${context.workspace.repos.handbook}.`,
-          // The Agent works in the Worktree of the app slot.
-          cwd: context.workspace.repos.app,
+          // A slot that is only read needs no cut: its `default` folder is on the Binding's base.
+          prompt: `${context.prompt}\nRead the style rules in ${context.workspace.repos.handbook}/default.`,
+          cwd: fixTree(context),
         }),
       },
       on: { finished: "review" },
@@ -86,7 +109,7 @@ const body = jr2Setup({
       invoke: {
         src: "gate",
         input: ({ context }) => ({
-          meta: { branch: context.workspace.branch, worktree: context.workspace.repos.app },
+          meta: { branch: branchOf(context), worktree: fixTree(context) },
         }),
       },
       on: { approve: "publishing" },
@@ -96,11 +119,14 @@ const body = jr2Setup({
     publishing: {
       invoke: {
         src: "publish",
+        // The Worktree names what to push: jr2 reads its branch from the cut.
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "review" }],
       },
     },
     done: { type: "final" },
     // Not final states: a final state means `done`. Each one fails the run, and the run ends `failed`.
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
   },
@@ -115,7 +141,6 @@ export const machine = workspace(body, {
     app: { url: "https://github.com/you/app.git", ref: "main" },
     handbook: "https://github.com/you/handbook.git",
   },
-  spec: ({ input }) => ({ branch: `docs/${input.ticket}` }),
 });
 ```
 
@@ -123,7 +148,17 @@ export const machine = workspace(body, {
 
 ```ts
 import { z } from "zod";
-import { agent, defineEvent, fail, jr2Setup, push, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  agent,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 const finished = defineEvent({
   name: "finished",
@@ -140,6 +175,10 @@ const approve = defineEvent({
 const runInput = z.object({ ticket: z.string(), prompt: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app" | "handbook">;
 
+// The folder of the Worktree, and its branch. The Machine knows both before the cut.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const branchOf = (context: BodyInput) => `docs/${context.ticket}`;
+
 const body = jr2Setup({
   types: {} as { context: BodyInput; input: BodyInput },
   events: [finished, approve],
@@ -148,6 +187,7 @@ const body = jr2Setup({
       model: "local/qwen3.6-35b-a3b",
       instructions: "You are a careful engineer. You commit your work on the branch.",
     }),
+    cut: worktree(),
     // Two Repo Slots, so the push names the slot that it pushes.
     publish: push({ slot: "app" }),
     fail: fail(),
@@ -155,17 +195,25 @@ const body = jr2Setup({
 }).createMachine({
   id: "docs-fix",
   context: ({ input }) => input,
-  initial: "working",
+  initial: "cutting",
   // The Sandbox is gone, and its unpushed commits with it. This body fails the run.
   on: { "agent.fault": ".failed", "workspace.lost": ".lost" },
   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: branchOf(context) }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "working" }, { target: "notCut" }],
+      },
+    },
     working: {
       invoke: {
         src: "coder",
         input: ({ context }) => ({
-          prompt: `${context.prompt}\nRead the style rules in ${context.workspace.repos.handbook}.`,
-          // The Agent works in the Worktree of the app slot.
-          cwd: context.workspace.repos.app,
+          // A slot that is only read needs no cut: its `default` folder is on the Binding's base.
+          prompt: `${context.prompt}\nRead the style rules in ${context.workspace.repos.handbook}/default.`,
+          cwd: fixTree(context),
         }),
       },
       on: { finished: "review" },
@@ -175,7 +223,7 @@ const body = jr2Setup({
       invoke: {
         src: "gate",
         input: ({ context }) => ({
-          meta: { branch: context.workspace.branch, worktree: context.workspace.repos.app },
+          meta: { branch: branchOf(context), worktree: fixTree(context) },
         }),
       },
       on: { approve: "publishing" },
@@ -185,11 +233,14 @@ const body = jr2Setup({
     publishing: {
       invoke: {
         src: "publish",
+        // The Worktree names what to push: jr2 reads its branch from the cut.
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "review" }],
       },
     },
     done: { type: "final" },
     // Not final states: a final state means `done`. Each one fails the run, and the run ends `failed`.
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
   },
@@ -204,28 +255,26 @@ export const machine = workspace(body, {
     app: { url: "https://github.com/you/app.git", ref: "main" },
     handbook: "https://github.com/you/handbook.git",
   },
-  spec: ({ input }) => ({ branch: `docs/${input.ticket}` }),
 });
 ```
 
 [Agents and Turns](agents-and-turns.md) tells how to define an Agent.
 
 The options of `workspace()` say what the Sandbox is. [`jr2 up`](../reference/cli.md#up) reads them before a run starts.
-Only `spec` and a per-run [Repo Slot](../reference/glossary.md#repo-slot) read the run input:
+Only a per-run [Repo Slot](../reference/glossary.md#repo-slot) reads the run input:
 
 - `input` is the schema of the run input: what [`jr2 run`](../reference/cli.md#run) gives with `--input`. Put it on the
   `workspace()`, not on the body.
 - `repos` gives the Repo Slots that the Sandbox clones. Leave it out for a Workspace with no Repo.
-- `spec` is a function from the run input to the branch. Its input also holds `instanceId` (see
-  [`HostInjectedInput`](../reference/authoring-surface/type-hostinjectedinput.md)).
 - `resources` is the [Size](../reference/glossary.md#size). `image`, `user` and `effector` name the images of the pod's
   containers.
 - `secrets` names the [Held secrets](../reference/glossary.md#held-secret) that the Sandbox can use (see
   [Secrets and trust](secrets-and-trust.md)).
+- `workGroup` is the group id that owns the files in `/work`. The default is 2000.
 
 The body gets the run input, plus `workspace`: the handles of the Workspace (see
-[`WorkspaceHandles`](../reference/authoring-surface/type-workspacehandles.md)). `workspace.repos` gives the absolute
-path of each Worktree, and `workspace.branch` gives the branch. Give a path to an Agent's
+[`WorkspaceHandles`](../reference/authoring-surface/type-workspacehandles.md)). `workspace.repos` gives the folder of
+each Repo Slot, `/work/<slot>`. This folder is not a Worktree. Give the path of a Worktree to an Agent's
 [Turn](../reference/glossary.md#turn) as its `cwd`, as the example does. Type the body's input with
 [`Workspaced`](../reference/authoring-surface/type-workspaced.md), also when the run input is `z.object({})`.
 
@@ -243,7 +292,8 @@ A Repo Slot is a key of the `repos` option. The key is your Machine's name for t
 Repo under `/work`. Each slot is one of three kinds:
 
 - **Bound**: the Machine gives the url, or a [Binding](../reference/glossary.md#binding) `{ url, ref }`. `ref` is the
-  branch or the commit that the Worktree starts from. Without `ref`, the Worktree starts from the Repo's default branch.
+  branch, the tag or the commit that the clone stays on, and a new branch starts from it. Without `ref`, it is the
+  Repo's default branch.
 - **[Open](../reference/glossary.md#open)**: the Machine gives [`open`](../reference/authoring-surface/open.md). The
   [Instance](../reference/glossary.md#instance) that registers the Machine binds the slot with
   [`customize()`](../reference/authoring-surface/customize.md) (see [Composition](composition.md)).
@@ -251,7 +301,7 @@ Repo under `/work`. Each slot is one of three kinds:
 
 A Machine that names no slot writes `repos: open` for the whole map. Then the composer names each slot.
 `workspace.repos` keeps the slots in the order that `repos` declares them. jr2 gives no slot a special meaning. Your
-Machine says which Worktree each Agent works in.
+Machine says where each Agent works.
 
 The cluster keeps one read-only cache of each Repo on each node. A Sandbox clones from that cache, and a fetch in the
 pod goes through it. [Architecture](architecture.md) tells about the Repo cache. Run
@@ -259,23 +309,44 @@ pod goes through it. [Architecture](architecture.md) tells about the Repo cache.
 
 ## The folders in the Sandbox
 
-Each Repo Slot gets a folder under `/work`. The clone of the Repo is `/work/<slot>/default/`. The Worktree of the branch
-is beside it, at `/work/<slot>/<branch>`. In the folder name, each `/` of the branch becomes `-`. For example, the
-branch `docs/T-12` of the slot `app` is at `/work/app/docs-T-12`. This is the
-[Project layout](../reference/glossary.md#project-layout).
+Each Repo Slot gets a folder under `/work`. The clone of the Repo is `/work/<slot>/default/`. It stays on the base of
+the Binding: a branch is attached, and a tag or a commit is detached. No work happens in `default/`. A slot that an
+Agent only reads needs nothing more: the Agent reads `/work/<slot>/default`. This is the
+[Project layout](../reference/glossary.md#project-layout). `/work/.jr2/` is reserved for jr2.
+
+The Workspace only clones. Your Machine cuts each Worktree with the
+[`worktree()`](../reference/authoring-surface/worktree.md) Effect, in a state of the body. You give the path, and the
+branch or the commit:
+
+- `{ path: "/work/app/fix", branch: "docs/123" }` cuts a branch Worktree. The cut finds a local branch, then
+  `origin/<branch>`, tracked, after a fetch. With neither, it makes a new branch from `from` or the base of the Binding.
+- `{ path: "/work/app/review", detach: sha }` cuts a detached Worktree for a reviewer. Each cut forces it to the commit
+  and cleans it. Ignored files stay, so that the reviewer can run the tests.
+
+The path is exactly `/work/<slot>/<name>`. The name is one segment that is not `default` and starts with neither `.` nor
+`-`. So your Machine knows the path before the cut, and the folder name does not change with the branch name.
+
+The output of a cut is `ready`, `refused` or `unknown`. A later outcome can come, so route the last arm of `onDone` with
+no guard. A bad path or a bad branch name is `refused`, and nothing changes. A cut is idempotent: the same cut again
+reads the same Worktree, and its `head` is the tip of the branch.
+
+`worktree({ expect: "new" })` refuses a branch that exists. `worktree({ expect: "existing" })` refuses a branch that
+does not exist, and makes nothing.
+
+The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as people in one checkout do.
+Each coder that needs its own branch gets its own Worktree of the one clone.
 
-`spec` returns a [`WorkspaceSpec`](../reference/authoring-surface/type-workspacespec.md). It gives the branch, and two
-optional fields:
+Your Machine chooses the branch name. Give each run a different branch, so that two runs do not push to one branch. Make
+it from a field of the run input, or from `instanceId` when the run input has no field that is different for each run.
+Only a root `workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets it only when
+its parent gives it.
 
-- `reviewSha`: a commit for a reviewer. jr2 checks it out in a second Worktree, at `/work/<slot>/<branch>-review`. The
-  body gets its paths as `workspace.review`.
-- `workGroup`: the group id that owns the files in `/work`. The default is 2000.
+An Agent, a `command`, a `push`, and an `http` Effect with a file body each name their Worktree by its path: `cwd` for a
+Turn, `worktree` for an Effect. A `push` has no branch in its input. jr2 reads the branch from the cut of that path. So
+an Agent that moves `HEAD` does not change what is pushed.
 
-Your Machine chooses the branch name. jr2 makes the branch in each Repo Slot. Give each run a different branch, so that
-two runs do not push to one branch. Make it from a field of the run input, or from `instanceId` when the run input has
-no field that is different for each run: ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. Only a root
-`workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets it only when its parent
-gives it.
+jr2 has no Effect that removes a Worktree. To remove one, run `git worktree remove` in a `command`.
+[Cut a Worktree](../guides/cut-a-worktree.md) gives the procedure.
 
 ## A Workspace with no Repo
 
@@ -504,15 +575,16 @@ export const machine = workspace(body, { input: runInput });
 
 In a Workspace with no Repo:
 
-- Type the body's input as `Workspaced<RunInput, never>`. The handles are `{ repos: {} }`, with no branch.
+- Type the body's input as `Workspaced<RunInput, never>`. The handles are `{ repos: {} }`.
 - An Agent's Turn that gives no `cwd` works in `/work`. The Agent's `workspace` access is the same as in each Workspace:
   `"write"` gives it `write`, `edit` and `bash`, and `"read"` gives it `bash` only.
 - A `command` with no Effect secret runs in `/work`.
 - An `http` Effect sends a file of `/work` with `file(path)`. The path is relative to `/work`.
-- `spec` is optional, and gives only `workGroup`.
-- A `push` needs a branch, and a `command` with an Effect secret runs on a commit. Thus `jr2 up` refuses both.
+- A `worktree()` needs a Repo Slot, a `push` needs a branch, and a `command` with an Effect secret runs on a commit.
+  Thus `jr2 up` refuses all three.
 
-jr2 deletes `/work` with the Sandbox. Send what must stay before the body ends, as the example does with `upload`. A
+jr2 deletes `/work` with the Sandbox. Send what must stay before the body ends, as the example does with `upload`. The
+secret `files` that `upload` names is an entry of the `secrets` list of `jr2.config.ts`, as each Effect secret is. A
 Lost Sandbox has lost all of its work, because no commit was pushed.
 
 ## The pod
@@ -529,10 +601,10 @@ A Sandbox pod has two containers, and two more when the Machine needs them:
 ### The Sandbox Image
 
 The [Sandbox Image](../reference/glossary.md#sandbox-image) is the image of the Harness container. It holds the tools
-that an Agent's Working tools can use, and the shell that you get when you run `kubectl exec` into the pod. The image is
-yours. Its floor is glibc, git and a writable `HOME`. [Add tools to the Sandbox](../guides/add-tools-to-the-sandbox.md)
-gives the full list. jr2 adds nothing to the image. It mounts its own runtime into the pod at `/opt/jr2`, and starts the
-Harness from there. Thus the `ENTRYPOINT` and the `CMD` of the image do not run.
+that an Agent's Working tools can use, and the shell that you get with `jr2 workspace shell`. The image is yours. Its
+floor is glibc, git and a writable `HOME`. [Add tools to the Sandbox](../guides/add-tools-to-the-sandbox.md) gives the
+full list. jr2 adds nothing to the image. It mounts its own runtime into the pod at `/opt/jr2`, and starts the Harness
+from there. Thus the `ENTRYPOINT` and the `CMD` of the image do not run.
 
 `image` names it in one of two forms:
 
@@ -593,8 +665,7 @@ A Workspace goes through these states:
 
 1. `placing`: jr2 writes the Sandbox, and waits for a node.
 2. `provisioning`: the pod starts.
-3. `attaching`: the Harness clones each Repo Slot and makes its Worktree. With no Repo Slot, this state has nothing to
-   do.
+3. `attaching`: the Harness clones each Repo Slot. With no Repo Slot, this state has nothing to do.
 4. `running`: the body runs.
 5. `teardown`: the body is in a final state, and jr2 deletes the Sandbox.
 6. `failing`: the body invoked [`fail`](../reference/authoring-surface/fail.md), and jr2 deletes the Sandbox. Then the
@@ -643,29 +714,37 @@ the Harness container does not lose the Workspace: the pod and `/work` stay.
 - A per-run url must match an entry of [`git.credentials`](../reference/config.md#git-credentials). jr2 refuses the url
   before it makes the Sandbox when no entry matches it. Thus a run cannot send the cluster's credentials to a host that
   it chooses.
-- `spec` returns a `branch`. When a run enters the Workspace, it faults if `spec` gives no `branch`, or the branch
-  `default`, because `default` is the folder of the clone. With no Repo Slot, it faults if `spec` gives a `branch` or a
-  `reviewSha`.
-- With no Repo Slot, `jr2 up` refuses a `push`, and a `command` that names an Effect secret.
+- `jr2 up` refuses a Repo Slot name that starts with `.`, because `/work/.jr2/` is reserved for jr2.
+- A cut of the branch that `default/` holds is `refused`, and the reason names `/work/<slot>/default`.
+- With no Repo Slot, `jr2 up` refuses a `worktree()`, a `push`, and a `command` that names an Effect secret.
 - A Size has only `limits.memory` and `limits.cpu`. jr2 refuses `requests` and each other key.
 - `jr2 up` refuses a Size that leaves the Harness container less than 256Mi of memory, or no cpu.
-- Under a Workspace with more than one Repo Slot, a Turn states its `cwd`, and a `command` and a `push` name their slot.
+- Under a Workspace with Repo Slots, a Turn states its `cwd`, and a `command`, a `push` and an `http` Effect with a file
+  body state their `worktree`. A Turn that wants `/work` states `cwd: "/work"`. An Agent with `workspace: "none"` needs
+  no `cwd`.
+- A `push`, a `command` that names an Effect secret, and an `http` Effect with a file body need a Worktree that a cut of
+  this run made.
+- Under a Workspace with more than one Repo Slot, a `push` names its `slot`.
 
 The guides and the Reference give the refusal text of each rule.
 
 ## Read next
 
+- [Cut a Worktree](../guides/cut-a-worktree.md)
 - [Look inside a Sandbox](../guides/look-inside-a-sandbox.md)
 - [Add tools to the Sandbox](../guides/add-tools-to-the-sandbox.md)
 - [Size a Workspace](../guides/size-a-workspace.md)
 - [Give the cluster git credentials](../guides/give-the-cluster-git-credentials.md)
 - [Effects](effects.md), [Composition](composition.md), [Architecture](architecture.md)
 - Reference: [`workspace`](../reference/authoring-surface/workspace.md),
+  [`worktree`](../reference/authoring-surface/worktree.md),
   [`RepoSlot`](../reference/authoring-surface/type-reposlot.md), [`Size`](../reference/authoring-surface/type-size.md),
   [`UserContainer`](../reference/authoring-surface/type-usercontainer.md),
   [`workspace.lost`](../reference/mechanism-events.md#workspace-lost), [`sandbox`](../reference/config.md#sandbox)
 - [ADR-0012](../reference/decisions/0012-workspace-wrapper-machine.md): `workspace()` wraps a body Machine and owns only
   Sandbox lifecycle
+- [ADR-0075](../reference/decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md): a Machine cuts a
+  Worktree, and the Workspace only clones
 - [ADR-0051](../reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md): a Repo is a slot
   on the `workspace()` and a cache on the node
 - [ADR-0060](../reference/decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md): a Workspace states

package/docs/get-started/a-model-decides.md

@@ -406,8 +406,7 @@ there:
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run 8fecb896-2100-4ee6-88d6-788eaf0d7244 (triage) — attached
-  → active "triaging"
+run f40a189e-b554-4310-b6e5-3b92c74e414e (triage) — attached
   → active "triaging"
   → active "clarify"
 ```
@@ -427,10 +426,10 @@ can show the same state. `jr2 run` does not return while the run waits. Keep it
 > ```text
 > …
 > → context kind-jr2 / namespace my-instance
-> run 89cc6ea5-9e2d-4f8a-8d02-18a6e47f2a5c (triage) — attached
+> run 4eafe1a5-b45d-4613-8ae3-4c85b26eeb0c (triage) — attached
 >   → active "triaging"
 >   → done "accepted"
-> {"runId":"89cc6ea5-9e2d-4f8a-8d02-18a6e47f2a5c","workflow":"triage","instanceId":"fac049b9-9dd2-4ba5-aca8-0b3ebe619701","status":"done","value":"accepted","context":{"request":"Add a --version flag to the CLI. It prints the installed version and exits.","exchange":[],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"assembly":"3eb6cd4d61bf","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
+> {"runId":"4eafe1a5-b45d-4613-8ae3-4c85b26eeb0c","workflow":"triage","instanceId":"d4daa575-f8ac-4ba9-af2e-406084adbd89","startedAt":"2026-11-06T19:24:22.161Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"done","value":"accepted","context":{"request":"Add a --version flag to the CLI. It prints the installed version and exits.","exchange":[],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"assembly":"9ff0a4d3c5da","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
 > ```
 >
 > Your run id and your [Instance ID](../reference/glossary.md#instance-id) are different, and so is the `summary`, the
@@ -444,14 +443,15 @@ The Gate holds the question of the Agent in its `meta`. In the send terminal, ru
 jr2 status <run id>
 ```
 
-`<run id>` is the run id that `jr2 run` printed. You can give its first 4 characters or more, such as `8fecb896`.
+`<run id>` is the run id that `jr2 run` printed. You can give its first 4 characters or more, such as `f40a189e`.
 [`jr2 status`](../reference/cli.md#status) prints the status of the run as one line of JSON. The Gate is in `gates`, at
 the end:
 
 ```text
 …
 → context kind-jr2 / namespace my-instance
-{"runId":"8fecb896-2100-4ee6-88d6-788eaf0d7244","workflow":"triage","instanceId":"a814d943-9b27-410c-a790-2c4225aa05ba","status":"active","value":"clarify","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where specifically should the version number be displayed (e.g., CLI flag, About screen, or help output), and what exact user action should trigger it?"}]},"children":[],"waiting":[],"held":[],"assembly":"3eb6cd4d61bf","gates":[{"gate":"clarify","path":["clarify"],"accepts":[{"name":"answer","description":"Answer the triager's question. It triages the request again with the answer in hand.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"info":{"type":"string","description":"The answer, in prose."}},"required":["info"],"additionalProperties":false}}],"acceptsNow":["answer"],"meta":{"question":"Where specifically should the version number be displayed (e.g., CLI flag, About screen, or help output), and what exact user action should trigger it?"}}]}
+{"runId":"f40a189e-b554-4310-b6e5-3b92c74e414e","workflow":"triage","instanceId":"6a6fb1c4-d6d8-4867-a51b-693c0772cc7b","startedAt":"2026-11-06T19:23:30.814Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"active","value":"clarify","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where should the version number be displayed to users (e.g., a specific command like `--version`, an 'About' screen, or a startup log message)?"}]},"children":[],"waiting":[],"held":[],"assembly":"9ff0a4d3c5da","gates":[{"gate":"clarify","path":["clarify"],"accepts":[{"name":"answer","description":"Answer the triager's question. It triages the request again with the answer in hand.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"info":{"type":"string","description":"The answer, in prose."}},"required":["info"],"additionalProperties":false}}],"acceptsNow":["answer"],"meta":{"question":"Where should the version number be displayed to users (e.g., a specific command like `--version`, an 'About' screen, or a startup log message)?"}}]}
+started by: token/instance on behalf of kubernetes-admin
 ```
 
 The `question` is in the words of the model, so your question is different. Your instance id is different too. The Gate
@@ -470,7 +470,7 @@ jr2 send <run id> --gate clarify --event answer --input '{"info":"Add a --versio
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered answer to gate "clarify" on 8fecb896-2100-4ee6-88d6-788eaf0d7244
+delivered answer to gate "clarify" on f40a189e-b554-4310-b6e5-3b92c74e414e
 ```
 
 The run goes back to `triaging`, and the Agent reads your answer. Look at the first terminal. When the Agent picks
@@ -481,7 +481,7 @@ The run goes back to `triaging`, and the Agent reads your answer. Look at the fi
   → active "triaging"
   → active "triaging"
   → done "accepted"
-{"runId":"8fecb896-2100-4ee6-88d6-788eaf0d7244","workflow":"triage","instanceId":"a814d943-9b27-410c-a790-2c4225aa05ba","status":"done","value":"accepted","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where specifically should the version number be displayed (e.g., CLI flag, About screen, or help output), and what exact user action should trigger it?","info":"Add a --version flag to the CLI. It prints the installed version and exits."}],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"assembly":"3eb6cd4d61bf","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
+{"runId":"f40a189e-b554-4310-b6e5-3b92c74e414e","workflow":"triage","instanceId":"6a6fb1c4-d6d8-4867-a51b-693c0772cc7b","startedAt":"2026-11-06T19:23:30.814Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"done","value":"accepted","context":{"request":"People keep asking what version they are running.","exchange":[{"question":"Where should the version number be displayed to users (e.g., a specific command like `--version`, an 'About' screen, or a startup log message)?","info":"Add a --version flag to the CLI. It prints the installed version and exits."}],"summary":"Add a --version flag to the CLI that prints the installed version and exits."},"children":[],"waiting":[],"held":[],"answers":[{"gate":"clarify","type":"answer","at":"2026-11-06T19:24:02.957Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}],"assembly":"9ff0a4d3c5da","output":{"outcome":"accepted","summary":"Add a --version flag to the CLI that prints the installed version and exits."}}
 ```
 
 `summary` is the request as the model wrote it again, in one sentence. Your summary is different. The `output` of the
@@ -502,24 +502,25 @@ This request does not say what is wrong. The run goes to `clarify` and waits, as
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run 84079cb2-3cdd-4b9a-ae39-51ab873c5f3c (triage) — attached
+run 7e6c9deb-ca65-4103-b517-abf6b0028aff (triage) — attached
   → active "triaging"
   → active "clarify"
 ```
 
-`84079cb2-3cdd-4b9a-ae39-51ab873c5f3c` is the id of the second run. Your run id is different. If the Agent picks
+`7e6c9deb-ca65-4103-b517-abf6b0028aff` is the id of the second run. Your run id is different. If the Agent picks
 `accept` or `reject`, start the run again.
 
 ## Answer from the Console
 
-Open `http://localhost:4000` in your browser. If the badge after the `instance token` box shows `live`, go to the next
-step. If the box is empty, get the token. In the send terminal, run:
+Open `http://localhost:4000` in your browser. If the nav shows `as token/instance` and the badge `live`, go to the next
+step. If the nav shows the `Caller token` box, get the token. In the send terminal, run:
 
 ```sh
 kubectl -n my-instance get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d
 ```
 
-Type the token in the `instance token` box. Push Enter. The badge after the box shows `live`.
+Type the token in the `Caller token` box. Push Enter. The badge after the box shows `live`, and the nav shows
+`as token/instance`.
 
 Click `triage` in the Fleet rail on the left. The center shows the Machine of `triage`, with its states and transitions.
 Click the run in the rail. The Console lights the state of the run, `clarify`.