@jr2/orchestrator 0.5.1 → 0.6.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,13 +575,13 @@ 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
 Lost Sandbox has lost all of its work, because no commit was pushed.
@@ -593,8 +664,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 +713,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/an-agent-in-a-sandbox.md

@@ -161,7 +161,7 @@ jr2 run task --input '{"prompt":"In docs/site/tutorial/greet, one test fails. Fi
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run a7a8fc26-851f-4459-9efb-845389acfda9 (task) — attached
+run 290b4be9-1e24-46a2-8cb5-27fabb3bbd3c (task) — attached
   → active "placing"
   → active "provisioning"
   → active "attaching"
@@ -183,10 +183,12 @@ jr2 status <run id>
 ```
 
 The status is one line of JSON. While the coder works, `gates` is `[]`. When the run waits at `review`, `gates` holds
-the Gate. Its `gate` is `body.review`, and the line ends with its `meta`:
+the Gate. Its `gate` is `body.review`, and the line ends with its `meta`. After the JSON, `jr2 status` prints one line
+for each Worktree that the run cut:
 
 ```text
-…"gate":"body.review",…,"meta":{"summary":"Fixed the \"trims the name\" test failure in docs/site/tutorial/greet. The bug was that the name wasn't being trimmed before constructing the greeting output. Added `.trim()` to the name extraction in src/greet.js, changing `args.find(...) ?? \"world\"` to `(args.find(...) ?? \"world\").trim()`. All 6 tests now pass.","branch":"jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16","worktree":"/work/target/jr2-task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16"}}]}
+…"gate":"body.review",…,"meta":{"summary":"Fixed a bug in docs/site/tutorial/greet/src/greet.js where the name argument wasn't being trimmed. The test \"trims the name\" failed because input like \" ada \" produced \"hello,  ada \" instead of \"hello, ada\". Added `.trim()` to the name extraction so whitespace is stripped before constructing the greeting. All 6 tests now pass.","branch":"jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd","worktree":"/work/target/task"}}]}
+worktree: /work/target/task (target), branch jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd
 ```
 
 Run the command again until `gates` holds the Gate.
@@ -196,7 +198,7 @@ Run the command again until `gates` holds the Gate.
 - `worktree` is the folder in the Sandbox that holds the branch. It is
   [the Worktree](../reference/glossary.md#worktree).
 
-Copy `branch` and `worktree` from your output. The part after `jr2/task-`, here `d8f59a0c-9ea1-43fc-8d0c-b153caf70f16`,
+Copy `branch` and `worktree` from your output. The part after `jr2/task-`, here `1f34eef3-5749-4d7c-a16b-488c56ec88cd`,
 is the [Instance ID](../reference/glossary.md#instance-id) of the run. `jr2 status` prints it as `instanceId`. It is not
 the run id. Do not make the branch name from the run id. With the Instance token, the drawer of the
 [Console](../reference/glossary.md#console) shows the same `meta`.
@@ -215,10 +217,10 @@ kubectl -n my-instance get sandboxes -l jr2.dev/run=<run id>
 
 ```text
 NAME                      PHASE   ENDPOINT                                              AGE
-ws-a7a8fc26-x-38-oakg23   Ready   http://ws-a7a8fc26-x-38-oakg23.my-instance.svc:8080   5m10s
+ws-290b4be9-x-0-19gh8ze   Ready   http://ws-290b4be9-x-0-19gh8ze.my-instance.svc:8080   5m25s
 ```
 
-`ws-a7a8fc26-x-38-oakg23` is the name of the Sandbox. Your Sandbox has a different name. It starts with `ws-` and the
+`ws-290b4be9-x-0-19gh8ze` is the name of the Sandbox. Your Sandbox has a different name. It starts with `ws-` and the
 first 8 characters of the run id. The pod of the Sandbox has the same name. The commands below write it as `<sandbox>`.
 
 ## Look inside the Sandbox
@@ -237,12 +239,12 @@ node --test
 ```
 
 ```text
-✔ greets the world by default (1.172165ms)
-✔ greets a name (0.138615ms)
-✔ shouts (0.117168ms)
-✔ trims the name (0.067037ms)
-✔ prints help (0.642445ms)
-✔ refuses an unknown flag (0.281559ms)
+✔ greets the world by default (1.0597ms)
+✔ greets a name (0.162102ms)
+✔ shouts (0.08266ms)
+✔ trims the name (0.057171ms)
+✔ prints help (3.806196ms)
+✔ refuses an unknown flag (0.222015ms)
 ℹ tests 6
 ℹ suites 0
 ℹ pass 6
@@ -250,7 +252,7 @@ node --test
 ℹ cancelled 0
 ℹ skipped 0
 ℹ todo 0
-ℹ duration_ms 55.318206
+ℹ duration_ms 53.312932
 ```
 
 Your times are different. Read the commits of the coder. The branch starts at the release tag, so the commits after the
@@ -261,7 +263,7 @@ git log --oneline v<version>..HEAD
 ```
 
 ```text
-1a84393 Fix: trim the name before using it in greet output
+e467788 fix: trim name in greet.js to handle leading/trailing whitespace
 ```
 
 Each line is one commit. The commit ids and the messages come from the model. The author of each commit is
@@ -283,7 +285,7 @@ jr2 send <run id> --gate body.review --event request_changes --input '{"notes":"
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered request_changes to gate "body.review" on a7a8fc26-851f-4459-9efb-845389acfda9
+delivered request_changes to gate "body.review" on 290b4be9-1e24-46a2-8cb5-27fabb3bbd3c
 ```
 
 The coder continues the same conversation, with your notes as its next prompt. The Sandbox and the branch stay. Run
@@ -312,7 +314,7 @@ Username for 'https://github.com': <you>
 Password for 'https://<you>@github.com':
 …
 To https://github.com/<you>/jr2.git
- * [new branch]      jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16 -> jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16
+ * [new branch]      jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd -> jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd
 ```
 
 `origin` fetches through the Repo cache of the node, and pushes to your fork. Open your fork on GitHub to see the
@@ -337,7 +339,7 @@ jr2 send <run id> --gate body.review --event approve
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered approve to gate "body.review" on a7a8fc26-851f-4459-9efb-845389acfda9
+delivered approve to gate "body.review" on 290b4be9-1e24-46a2-8cb5-27fabb3bbd3c
 ```
 
 In the first terminal, `jr2 run` prints the end of the run, then the final status as one line of JSON, and stops:
@@ -346,7 +348,7 @@ In the first terminal, `jr2 run` prints the end of the run, then the final statu
 …
   → active "teardown"
   → done "done"
-{"runId":"a7a8fc26-851f-4459-9efb-845389acfda9","workflow":"task",…,"output":{"branch":"jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16"}}
+{"runId":"290b4be9-1e24-46a2-8cb5-27fabb3bbd3c","workflow":"task",…,"output":{"branch":"jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd"},"worktrees":[{"slot":"target","path":"/work/target/task","branch":"jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd"}]}
 ```
 
 ## Make sure that the Sandbox is gone
@@ -364,7 +366,7 @@ No resources found in my-instance namespace.
 ## What happened
 
 - `task` is a Machine in a Workspace. The run made a Sandbox for the Workspace and cloned your fork into it. It cut the
-  branch from the release tag, in a Worktree in `/work/target/`. See [Workspaces](../concepts/workspaces.md).
+  branch from the release tag, in the Worktree `/work/target/task`. See [Workspaces](../concepts/workspaces.md).
 - `task` left its Repo Slots and the model of its coder Open. `customize()` bound them where you registered the
   Workflow, and `jr2 up` refuses a Workflow with an Open part. See [Composition](../concepts/composition.md) and
   [ADR-0054](../reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md).