@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/guides/cut-a-worktree.md

@@ -0,0 +1,560 @@
+---
+title: Cut a Worktree
+description: Make a Worktree with worktree(), choose what a cut refuses, and remove a Worktree.
+---
+
+# Cut a Worktree
+
+Make each [Worktree](../reference/glossary.md#worktree) that your [Machine](../reference/glossary.md#machine) needs,
+with the [`worktree()`](../reference/authoring-surface/worktree.md) [Effect](../reference/glossary.md#effect).
+
+A [Workspace](../reference/glossary.md#workspace) only clones each [Repo](../reference/glossary.md#repo). The body of
+the Workspace does a [Cut](../reference/glossary.md#cut) of each Worktree in a state of its own. In this
+[Workflow](../reference/glossary.md#workflow), a coder [Agent](../reference/glossary.md#agent) works on a new branch. A
+reviewer reads the coder's commit in a second Worktree, with no branch. Then the Machine removes the review Worktree,
+and pushes the commit that the reviewer read. Save the file as `workflows/fix-a-bug.ts` in your
+[Instance](../reference/glossary.md#instance):
+
+**Anthropic**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import {
+  agent,
+  arg,
+  branchName,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  readyOf,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when you committed the fix.",
+  input: z.object({}),
+});
+const pass = defineEvent({ name: "pass", description: "Call this when the commit is correct.", input: z.object({}) });
+const revise = defineEvent({
+  name: "revise",
+  description: "Call this when the commit is not correct. Say what to change.",
+  input: z.object({ notes: z.string() }),
+});
+
+// The run input. `branchName` refuses a name that the cut and the push refuse.
+const runInput = z.object({ prompt: z.string(), branch: branchName });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+type Context = BodyInput & { reviewed?: string };
+
+// Your Machine names each folder. So it knows each path before the cut.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+const cloneTree = (context: BodyInput) => `${context.workspace.repos.app}/default` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: Context },
+  events: [finished, pass, revise],
+  actors: {
+    coder: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You fix the bug. You commit the fix." }),
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      workspace: "read",
+      instructions: "You review one commit. You change nothing.",
+    }),
+    // Each run gets a new branch: the cut refuses a branch that exists.
+    cut: worktree({ expect: "new" }),
+    // No `--force`: git refuses a Worktree with changes, and the output holds its exit code.
+    // The state below goes on with either result: a Worktree that stays does no harm here.
+    remove: command(["git", "worktree", "remove", arg("path")], { timeout: "1m" }),
+    publish: push({ pin: true }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-a-bug",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: coderTree(context), continue: true }),
+      },
+      on: { finished: "reading" },
+    },
+    // A cut of the same path reads the Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+    reading: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [
+          {
+            guard: ({ event }) => isReady(event.output),
+            target: "detaching",
+            actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+          },
+          { target: "notCut" },
+        ],
+      },
+    },
+    // Each round forces this folder to the commit, and cleans it.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review ${context.reviewed}.`, cwd: reviewTree(context) }),
+      },
+      on: {
+        pass: "removing",
+        revise: {
+          target: "coding",
+          actions: assign({ prompt: ({ event }) => `Change the fix as the review asks:\n\n${event.notes}` }),
+        },
+      },
+    },
+    // The clone is not the Worktree that goes, so the command runs there.
+    removing: {
+      invoke: {
+        src: "remove",
+        input: ({ context }) => ({ path: reviewTree(context), worktree: cloneTree(context) }),
+        onDone: "publishing",
+      },
+    },
+    // The input names the Worktree and the commit. jr2 reads the branch from the cut of that path.
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    notPushed: { invoke: { src: "fail", input: { reason: "the push did not succeed" } } },
+    failed: { invoke: { src: "fail", input: { reason: "an Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/<you>/app.git" },
+});
+```
+
+**Local**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import {
+  agent,
+  arg,
+  branchName,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  push,
+  readyOf,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const finished = defineEvent({
+  name: "finished",
+  description: "Call this when you committed the fix.",
+  input: z.object({}),
+});
+const pass = defineEvent({ name: "pass", description: "Call this when the commit is correct.", input: z.object({}) });
+const revise = defineEvent({
+  name: "revise",
+  description: "Call this when the commit is not correct. Say what to change.",
+  input: z.object({ notes: z.string() }),
+});
+
+// The run input. `branchName` refuses a name that the cut and the push refuse.
+const runInput = z.object({ prompt: z.string(), branch: branchName });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+type Context = BodyInput & { reviewed?: string };
+
+// Your Machine names each folder. So it knows each path before the cut.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+const cloneTree = (context: BodyInput) => `${context.workspace.repos.app}/default` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: Context },
+  events: [finished, pass, revise],
+  actors: {
+    coder: agent({ model: "local/qwen3.6-35b-a3b", instructions: "You fix the bug. You commit the fix." }),
+    reviewer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      workspace: "read",
+      instructions: "You review one commit. You change nothing.",
+    }),
+    // Each run gets a new branch: the cut refuses a branch that exists.
+    cut: worktree({ expect: "new" }),
+    // No `--force`: git refuses a Worktree with changes, and the output holds its exit code.
+    // The state below goes on with either result: a Worktree that stays does no harm here.
+    remove: command(["git", "worktree", "remove", arg("path")], { timeout: "1m" }),
+    publish: push({ pin: true }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-a-bug",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: context.prompt, cwd: coderTree(context), continue: true }),
+      },
+      on: { finished: "reading" },
+    },
+    // A cut of the same path reads the Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+    reading: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [
+          {
+            guard: ({ event }) => isReady(event.output),
+            target: "detaching",
+            actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+          },
+          { target: "notCut" },
+        ],
+      },
+    },
+    // Each round forces this folder to the commit, and cleans it.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review ${context.reviewed}.`, cwd: reviewTree(context) }),
+      },
+      on: {
+        pass: "removing",
+        revise: {
+          target: "coding",
+          actions: assign({ prompt: ({ event }) => `Change the fix as the review asks:\n\n${event.notes}` }),
+        },
+      },
+    },
+    // The clone is not the Worktree that goes, so the command runs there.
+    removing: {
+      invoke: {
+        src: "remove",
+        input: ({ context }) => ({ path: reviewTree(context), worktree: cloneTree(context) }),
+        onDone: "publishing",
+      },
+    },
+    // The input names the Worktree and the commit. jr2 reads the branch from the cut of that path.
+    publishing: {
+      invoke: {
+        src: "publish",
+        input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+        onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    notPushed: { invoke: { src: "fail", input: { reason: "the push did not succeed" } } },
+    failed: { invoke: { src: "fail", input: { reason: "an Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/<you>/app.git" },
+});
+```
+
+Write your GitHub user name in place of `<you>`. The Agents use the model of the tab.
+[Push and sign a branch](push-and-sign-a-branch.md) tells how to give the push a credential.
+
+## Name the path
+
+The path of a Worktree is exactly `/work/<slot>/<name>`. `<slot>` is a [Repo Slot](../reference/glossary.md#repo-slot).
+`<name>` is one folder name that you choose. It is not `default`, and it starts with neither `.` nor `-`. It does not
+change with the name of the branch.
+
+Make the path from `context.workspace.repos`, and add `as const`. Then the compiler can read the slot, and it refuses a
+slot that the Workspace does not have:
+
+```ts
+// Your Machine names each folder. So it knows each path before the cut.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+const cloneTree = (context: BodyInput) => `${context.workspace.repos.app}/default` as const;
+```
+
+The check of the compiler is a help. It sees only a literal path under `jr2Setup`. jr2 also checks each path when the
+run gets to it.
+
+## Cut a branch
+
+Invoke the Effect with `{ path, branch }`. `branch` is required, unless you give `detach`. The Machine names the branch,
+so jr2 never reads it from the folder or from `HEAD`.
+
+```ts
+cutting: {
+  invoke: {
+    src: "cut",
+    input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+    // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+    onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+  },
+},
+```
+
+The cut fetches, then finds the branch in this order:
+
+1. A local branch.
+2. `origin/<branch>`. The new local branch tracks it.
+3. A new branch, with no upstream. It starts from `from`, or from the base of the
+   [Binding](../reference/glossary.md#binding) when the input has no `from`.
+
+The output is `ready`, `refused` or `unknown`. Each Effect outcome is open, so give the last arm of `onDone` no guard.
+[`isReady`](../reference/authoring-surface/isready.md) is the guard for `ready`.
+
+| The field of `ready` | What it holds                                                                |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `slot`, `path`       | The Repo Slot and the path of the Worktree.                                  |
+| `branch`             | The branch of the cut, or `null` for a detached cut.                         |
+| `head`               | The tip of the branch, or the commit of a detached cut. It is never `HEAD`.  |
+| `found`              | How the cut found it: `local`, `remote`, `none`, `held` or `commit`.         |
+| `stale`              | The warning of git when the fetch failed. The cut used what the clone holds. |
+
+`held` means that a cut made this path before, so the Worktree holds earlier work. No fetch happens, and the cut does
+not check `expect` again. Thus a cut of the same path also reads a Worktree:
+
+```ts
+// A cut of the same path reads the Worktree. `head` is the tip of the branch, whatever HEAD the coder left.
+reading: {
+  invoke: {
+    src: "cut",
+    input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+    onDone: [
+      {
+        guard: ({ event }) => isReady(event.output),
+        target: "detaching",
+        actions: assign({ reviewed: ({ event }) => readyOf(event.output).head }),
+      },
+      { target: "notCut" },
+    ],
+  },
+},
+```
+
+[`readyOf`](../reference/authoring-surface/readyof.md) gives the `ready` output to an action, because xstate does not
+carry the guard to the action.
+
+## Choose what a cut refuses
+
+`expect` says if the branch can exist. It is an option of `worktree()`, so a run cannot change it:
+
+- `worktree()`: use a local branch, then a branch of the remote, then make a new branch.
+- `worktree({ expect: "new" })`: refuse a branch that exists, local or on the remote. Use it for a name that a planner
+  or a run input chooses for new work. A name that collides is then a refusal, and not the branch of a different person.
+- `worktree({ expect: "existing" })`: refuse a branch that does not exist, and make nothing. Use it when a run must
+  continue a branch that exists.
+
+The example gives the coder a new branch for each run:
+
+```ts
+// Each run gets a new branch: the cut refuses a branch that exists.
+cut: worktree({ expect: "new" }),
+```
+
+A pick param or a run input that names a branch can use the schema
+[`branchName`](../reference/authoring-surface/branchname.md). It is the rule of the cut and of the push. Thus jr2
+refuses a bad name at the [Menu](../reference/glossary.md#menu) or at the door, before the cut.
+
+## Read a commit with no branch
+
+Invoke the Effect with `{ path, detach }` to hold one commit, with no branch. The example gives this Worktree to a
+reviewer. Each cut forces the folder to the commit, and cleans it. Ignored files stay, so that a reviewer can run the
+tests:
+
+```ts
+// Each round forces this folder to the commit, and cleans it.
+detaching: {
+  invoke: {
+    src: "cut",
+    input: ({ context }) => ({ path: reviewTree(context), detach: context.reviewed! }),
+    onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+  },
+},
+```
+
+`expect` applies only to a branch. A slot with `expect` can thus also make a detached cut, as `cut` does here. A cut
+that you lend to a [Chart](../reference/glossary.md#chart) must state `expect`, so a Chart uses such a slot too.
+
+## Give the Worktree to each step
+
+Each step names its Worktree by its path:
+
+| The step                                | The key of its input |
+| --------------------------------------- | -------------------- |
+| A [Turn](../reference/glossary.md#turn) | `cwd`                |
+| A `command`                             | `worktree`           |
+| A `push`                                | `worktree`           |
+| An `http` Effect with a file            | `worktree`           |
+
+Each key is required under Repo Slots. A Turn that wants the folder above the Repo Slots states `cwd: "/work"`. To read
+a slot that has no Worktree, use `/work/<slot>/default`. A Workspace with no Repo Slot, and an Agent with
+`workspace: "none"`, need no `cwd`.
+
+A Turn of a Working Agent that names a path where no Worktree exists does not start. The
+[Harness](../reference/glossary.md#harness) refuses it, and the Machine gets `agent.fault` with
+``the Turn's `cwd` <path> does not exist: cut the Worktree first``.
+
+A `push` has no branch in its input. jr2 finds the cut of that path, and reads the branch there. An Agent can move
+`HEAD`, and it cannot change that record:
+
+```ts
+// The input names the Worktree and the commit. jr2 reads the branch from the cut of that path.
+publishing: {
+  invoke: {
+    src: "publish",
+    input: ({ context }) => ({ worktree: coderTree(context), sha: context.reviewed! }),
+    onDone: [{ guard: ({ event }) => event.output.outcome === "pushed", target: "done" }, { target: "notPushed" }],
+  },
+},
+```
+
+## Run more than one coder
+
+The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as people in one checkout do.
+Give each coder that needs its own branch a Worktree of its own, with its own path and its own branch. Each Worktree
+uses the one clone. To merge the branches, cut a Worktree for the merge target, and run `git merge` in a `command`
+there. No fetch is necessary, because each branch is in the clone. Then push once.
+
+Cuts of one clone wait for each other, so they do not collide.
+
+## Remove a Worktree
+
+jr2 has no Effect that removes a Worktree. To remove one, run `git worktree remove` in a `command`:
+
+```ts
+// No `--force`: git refuses a Worktree with changes, and the output holds its exit code.
+// The state below goes on with either result: a Worktree that stays does no harm here.
+remove: command(["git", "worktree", "remove", arg("path")], { timeout: "1m" }),
+```
+
+Invoke the `command` in a different Worktree. The clone is always there, so the example names it:
+
+```ts
+// The clone is not the Worktree that goes, so the command runs there.
+removing: {
+  invoke: {
+    src: "remove",
+    input: ({ context }) => ({ path: reviewTree(context), worktree: cloneTree(context) }),
+    onDone: "publishing",
+  },
+},
+```
+
+- The branch stays. Only the folder goes.
+- A Worktree with changes or with untracked files stays too, and git exits with a code that is not 0. Route on `exited`
+  to see it, or add `--force` to the argv to drop those changes. Ignored files do not stop the removal.
+- jr2 keeps its record of the cut. A cut of the same path and the same branch makes the folder again. Its `found` is
+  `local`. A detached cut makes the folder again too.
+- jr2 deletes each Worktree with the [Sandbox](../reference/glossary.md#sandbox). Thus a Machine needs this recipe only
+  to free the disk during a run.
+
+## Rules
+
+These settle as `refused`, and nothing changes. Route them to your last arm:
+
+- a path that is not a Worktree path: `"<path>" is not a Worktree path: /work/<slot>/<name>, with one segment in <name>`
+- the path of the clone: `"<path>" is the clone: it stays as the attach left it; cut a sibling`
+- a name that starts with `.` or `-`: `"<path>": a Worktree's name starts with neither . nor -`
+- a slot that the Workspace does not have:
+  `"<path>" names Repo Slot "<slot>", which its Workspace does not carry (<slots>)`
+- no branch and no commit, or both: ``a cut names a branch, or a commit in `detach` ``
+- `from` on a detached cut: ``a detached cut takes no `from` ``
+- `expect: "new"` on a branch that exists: `<branch> exists, and this cut makes only a new branch`
+- `expect: "existing"` on a branch that does not exist: `<branch> does not exist, and this cut makes nothing`
+- a re-cut that does not agree with the first cut: `<path> was cut for <branch>, not <other>`,
+  `<path> was cut detached, not for <branch>`, or `<path> was cut from <from>, not <other>`
+- a folder that no cut made: `<path> is a folder and no Worktree: a cut removes nothing it did not make`
+- a detached cut of a Worktree that no cut made:
+  `<path> is a Worktree no cut made, and a detached cut forces only its own`
+- a commit that the clone does not hold, also after a fetch: `no commit "<sha>" in this clone`
+- a branch that `default/` or a different Worktree holds: `<path> holds <branch>: read it there, or cut another branch`
+- a name that the clone does not hold, after a fetch that failed:
+  `<branch> is not in this clone, and the remote did not answer, so it may exist there: <warning>`
+- a `from` on a branch that exists:
+  ``<branch> exists, and it is not at `from` "<from>": `from` starts a new branch and moves no branch``
+
+A name that git or the push refuses also settles `refused`. The `reason` says why, for example
+`"<name>" is not a branch name`.
+
+These are not `refused`, because no word of a run can cause them:
+
+- `createMachine` refuses an Effect's `onDone` with a guard on its last arm:
+  `machine "<id>": state "<state>" (Effect "<slot>") has an onDone with no unguarded last arm — … (ADR-0075)`
+- `jr2 up` refuses a `worktree()` in a Workspace with no Repo Slot:
+  `workflow "<workflow>": worktree "<slot>" runs in Workspace of workflow "<workflow>", which has no Repo Slot: a cut makes a Worktree of a Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`
+- when a `worktree()` starts, it refuses the same Workspace:
+  `worktree "<slot>" runs under a Workspace with no Repo Slot: a cut makes a Worktree of a Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`
+- a Repo Slot name that starts with `.`, because `/work/.jr2/` is reserved for jr2. See
+  [Bind a shipped Machine's Open parts](bind-open-parts.md).
+
+## Read next
+
+- [Workspaces](../concepts/workspaces.md): the clone, the folders, and what names a Worktree.
+- [Effects](../concepts/effects.md): where a cut runs, and what a restart does to it.
+- [Push and sign a branch](push-and-sign-a-branch.md): the `push` Effect.
+- [Set an Agent's access and Dials](set-an-agents-access-and-dials.md): a reviewer in a detached Worktree.
+- [Let an Agent write a Chart](let-an-agent-write-a-chart.md): a cut that you lend to a Chart.
+- Reference: [`worktree`](../reference/authoring-surface/worktree.md),
+  [`WorktreeOptions`](../reference/authoring-surface/type-worktreeoptions.md),
+  [`WorktreeInput`](../reference/authoring-surface/type-worktreeinput.md),
+  [`WorktreeOutput`](../reference/authoring-surface/type-worktreeoutput.md) and
+  [`branchName`](../reference/authoring-surface/branchname.md).
+- [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.

package/docs/guides/fix-a-failed-converge.md

@@ -308,7 +308,7 @@ refusals of a push and of the [Effector](../reference/glossary.md#effector) imag
 
   The check has a limit. The check pod has labels of its own, so a NetworkPolicy that selects the Harness pods by label
   does not select the check pod. When such a policy closes the egress of the Harness pods, the check can pass while a
-  Turn fails.
+  Turn fails. The egress policy of jr2, which closes the cloud metadata addresses, selects the check pod too.
 
   A check can fail when the model works, for example a model that loads for longer than the check waits. When you know
   that the models work, run `jr2 up --skip-provider-preflight`. No check pod runs, and the converge goes on. `jr2 up`

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

@@ -200,11 +200,15 @@ it. Then the Chart ends, and the run ends with the status `done`.
 - The door refuses a Chart, and gives one line for each problem. Each line starts with the path in the Chart. For
   example:
   - `<path>: "<name>" is not a lent actor or an Agent of this Chart; lent: <names>; kit: <gate, fail or none>; minted: <names>`
-  - `<path>: "<name>" is not a lent guard; lent guards: <names> (and jr2.sentBy with params { id }, and jr2.failure)`
+  - `<path>: "<name>" is not a lent guard; lent guards: <names> (and jr2.sentBy with params { id }, jr2.failure and jr2.ready)`
   - `<path>.type: "<name>" is not a generic or a lent action; generic: set, append, increment, clear; lent: <names>`
   - ``<path>: <reference> is supplied by nothing: it is not in the initial `context`, and no `set`, `append` or `increment` writes it``,
     then what a write supplies
   - `<path>: "<reference>" is not a reference: it starts at context, event or input (a reference is a path, never an expression)`
+  - ``<path>: the lent cut "<slot>" does not state `expect`, so a Chart cannot use it; <fix>``
+  - ``<path>: the lent cut "<slot>" states `expect: "existing"` beside the lent force push "<slot>", and together they can force-push any existing branch; <fix>``
+  - ``<path>.cwd: "<cwd>" is a Repo Slot's folder, not a Worktree; `cwd` is a Worktree that a cut made, "/work/<slot>/<name>", or "/work/<slot>/default" to read, or "/work"``
+  - ``<path>: <agent> works under a Workspace with Repo Slots, and a Turn there says where: `cwd` is a Worktree, or "/work"``
 - The door then compiles the Chart as the Open body does. A line of this last check starts with `(chart):`, and names a
   state by its [xstate](https://xstate.js.org) id (for example `body.writing`), not by its path in the Chart.
 - A refusal is output, not an error: the Open body ends with `{ outcome: "refused", report }`. A Chart wrapper that

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

@@ -47,10 +47,12 @@ ws-a1322024-x-2-h8pgwk   Ready   http://ws-a1322024-x-2-h8pgwk.my-instance.svc:8
   `Lost` when the pod is gone, and a `Lost` Sandbox does not get a new pod. A delete removes the Sandbox at once, so you
   seldom see the phase `Terminating`.
 - When the run has no Sandbox now, `kubectl` prints `No resources found in <namespace> namespace.`
+- [`jr2 status <run id>`](../reference/cli.md#status) prints each [Worktree](../reference/glossary.md#worktree) that the
+  run cut, with its path and its branch, in `worktrees` and in one `worktree:` line for each cut. Give this command on
+  your computer, not in the Sandbox.
 - When a [Workflow](../reference/glossary.md#workflow) puts `branch` and `worktree` in the `meta` of a
   [Gate](../reference/glossary.md#gate), as the `review` Gate of [`task`](../reference/machines.md#task) does,
-  [`jr2 status <run id>`](../reference/cli.md#status) prints them in `gates`. Give this command on your computer, not in
-  the Sandbox. Then you can copy the Worktree from the status.
+  `jr2 status <run id>` prints them in `gates` too.
 
 ## Open a shell
 
@@ -64,8 +66,8 @@ starts from `node:24-slim`, which has `bash`. If your Sandbox Image has no `bash
 ## Find the Worktree
 
 Each [Repo Slot](../reference/glossary.md#repo-slot) of the Workspace has a folder in `/work`. In it, `default` is a
-clone of the [Repo](../reference/glossary.md#repo), and the [Worktree](../reference/glossary.md#worktree) of the branch
-is beside it. To show the folders of the Repo Slots, use this command:
+clone of the [Repo](../reference/glossary.md#repo), and each [Worktree](../reference/glossary.md#worktree) that the
+Machine cut is beside it. To show the folders of the Repo Slots, use this command:
 
 ```sh
 ls /work
@@ -80,20 +82,20 @@ git -C /work/<Repo Slot>/default worktree list
 For the slot `target` of a run of `task`, the output is:
 
 ```text
-/work/target/default                                        1e40403 [main]
-/work/target/jr2-task-0cbdb607-48dc-4eab-9469-f8e41f2b0025  1e40403 [jr2/task-0cbdb607-48dc-4eab-9469-f8e41f2b0025]
+/work/target/default  7f258f6 (detached HEAD)
+/work/target/task     e467788 [jr2/task-1f34eef3-5749-4d7c-a16b-488c56ec88cd]
 ```
 
-The first line is the clone, on the default branch of the Repo. The second line is the Worktree of the branch. Your
-commits and your instance id are different.
+The first line is the clone, on the base of the Repo Slot. Here the base is a tag, so the clone is detached. On a
+branch, the line shows the branch. The second line is the Worktree that `task` cut. Your commits and your instance id
+are different.
 
-- In the commands below, `<branch>` is the name of the branch, and `<worktree>` is the folder of its Worktree. The
-  folder is the name of the branch, with each `/` changed to `-`. For example, the branch `jr2/task-<instance id>` has
-  the Worktree `/work/target/jr2-task-<instance id>`.
-- A Workspace that has a commit to review has one more Worktree, `/work/<Repo Slot>/<worktree>-review`. It holds that
-  commit, with no branch.
-- The attach makes the folders and the Worktrees after the Sandbox is `Ready`. Until then, `/work` has no folder for the
-  Repo Slot.
+- In the commands below, `<branch>` is the name of the branch, and `<worktree>` is the name of the folder of its
+  Worktree. Your Machine chooses each one. The name of the folder does not come from the branch. `task` names the folder
+  `task`.
+- A detached Worktree, such as the Worktree of a reviewer, shows `(detached HEAD)` in place of a branch.
+- The attach makes the folders and the clones after the Sandbox is `Ready`. Until then, `/work` has no folder for the
+  Repo Slot. The Machine cuts each Worktree in a state of its body. See [Cut a Worktree](cut-a-worktree.md).
 
 ## Read the branch
 
@@ -168,6 +170,7 @@ A [Machine](../reference/glossary.md#machine) can also push the branch with an
 ## Read next
 
 - [Workspaces](../concepts/workspaces.md)
+- [Cut a Worktree](cut-a-worktree.md)
 - [ADR-0004](../reference/decisions/0004-worktree-provisioning-model.md): the clone and the Worktree.
 - [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of a Sandbox.
 - [ADR-0012](../reference/decisions/0012-workspace-wrapper-machine.md): when a Workspace deletes its Sandbox.