@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/guides/move-from-kind-to-a-shared-cluster.md

@@ -54,6 +54,22 @@ below explains one field. Set only the fields that your cluster needs.
   API server and in the kubelets.
 - A container runtime that mounts image volumes, such as containerd 2.1 or later, or CRI-O 1.31 or later. `jr2 up` does
   not check the runtime. With an older runtime, the first Sandbox fails, and its pod events give the cause.
+- Landlock ABI 3 or later in the kernel of each [Sandbox node](../reference/glossary.md#sandbox-node): Linux 6.2 or
+  later, with `landlock` in its list of security modules. A distribution kernel can have it at an older version: the
+  check, not the version, decides. The Harness confines each program of an Agent with it. The Repo cache agent on each
+  Sandbox node checks it, and `jr2 up` refuses to converge while a Sandbox node has no Landlock. It names each such
+  node. To keep a node out, use `sandbox.nodeSelector` or a taint (see
+  [Choose the Sandbox nodes](#choose-the-sandbox-nodes)). A node that joins later and has no Landlock gets no working
+  Sandbox: its Harness does not start.
+- A CNI that enforces NetworkPolicy, and no node credential that a pod can get. `jr2 up` applies a NetworkPolicy that
+  stops each Harness pod at the cloud metadata addresses: `169.254.169.254`, `fd00:ec2::254`, `169.254.170.2`,
+  `169.254.170.23` and `100.100.100.200`. There, the metadata service of a node can give the node's cloud credential to
+  a pod. `jr2 up` does not check these. Do these checks:
+  - Find the metadata address of your cloud provider. If it is not in the list, block it with a NetworkPolicy of your
+    own.
+  - Make sure that the CNI enforces NetworkPolicy. Without it, the policy stops nothing.
+  - Give pods no node credential. On GKE, use Workload Identity. On AWS, use IMDSv2 with a hop limit of 1. Then a pod
+    gets no node credential from the metadata service, also where the policy does not apply.
 - Your kubectl user can apply objects outside the namespace of the Instance. `jr2 up` applies the operator in the
   `jr2-system` namespace, with its CustomResourceDefinitions, ClusterRoles and ClusterRoleBindings. It also applies two
   PriorityClasses, unless you name your own.

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

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

package/docs/guides/run-a-command-or-call-a-url.md

@@ -10,8 +10,9 @@ Run a program in the [Workspace](../reference/glossary.md#workspace), or call a
 
 Put the Effect under `actors` in [`jr2Setup`](../reference/authoring-surface/jr2setup.md), beside the
 [Agents](../reference/glossary.md#agent). Then invoke it by its key from a state, and route on its output in `onDone`.
-In this [Workflow](../reference/glossary.md#workflow), a coder fixes the tests. It picks `run_test` to run one test file
-with a [`command`](../reference/authoring-surface/command.md) Effect. When it picks `finished`, an
+In this [Workflow](../reference/glossary.md#workflow), the Machine cuts a [Worktree](../reference/glossary.md#worktree),
+and a coder fixes the tests there. It picks `run_test` to run one test file with a
+[`command`](../reference/authoring-surface/command.md) Effect. When it picks `finished`, an
 [`http`](../reference/authoring-surface/http.md) Effect posts its summary to a URL. Save the file as
 `workflows/fix-and-report.ts` in your [Instance](../reference/glossary.md#instance):
 
@@ -29,9 +30,11 @@ import {
   fail,
   fromPick,
   http,
+  isReady,
   jr2Setup,
   secret,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -50,6 +53,9 @@ const finished = defineEvent({
 const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the coder and the command name.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
@@ -60,6 +66,8 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You fix failing tests. You change no test. You commit the fix.",
     }),
+    // Cut the Worktree: an Effect too.
+    cut: worktree(),
     // One program, with no shell. arg("file") is one argument, from the input of the Effect.
     test: command(["node", "--test", arg("file")], { timeout: "5m" }),
     // A call to a fixed URL. The Effector puts the value of the secret in the header.
@@ -77,12 +85,20 @@ const body = jr2Setup({
   id: "fix-and-report",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: ({ context }) => ({ prompt: context.prompt, cwd: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: fixTree(context) }),
       },
       on: {
         finished: "reporting",
@@ -95,8 +111,8 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "test",
-            // The `file` of the pick goes to the arg("file") of the command.
-            input: fromPick(runTest),
+            // The `file` of the pick goes to the arg("file") of the command. The Machine gives `worktree`.
+            input: fromPick(runTest, ({ context }) => ({ worktree: fixTree(context) })),
             onDone: {
               target: "ready",
               // The Agent reads this text as the answer to its run_test pick.
@@ -114,7 +130,7 @@ const body = jr2Setup({
       invoke: {
         src: "report",
         // The Agent gives `summary`. The Machine gives `branch`.
-        input: fromPick(finished, ({ context }) => ({ branch: context.workspace.branch })),
+        input: fromPick(finished, ({ context }) => ({ branch: context.branch })),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "response" && event.output.status < 300, target: "done" },
           { target: "notReported" },
@@ -123,6 +139,7 @@ const body = jr2Setup({
     },
     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" } } },
     notReported: { invoke: { src: "fail", input: { reason: "the report did not go out" } } },
     failed: { invoke: { src: "fail", input: { reason: "the coder could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
@@ -132,7 +149,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -150,9 +166,11 @@ import {
   fail,
   fromPick,
   http,
+  isReady,
   jr2Setup,
   secret,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -171,6 +189,9 @@ const finished = defineEvent({
 const runInput = z.object({ prompt: z.string(), branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the coder and the command name.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const passed = (output: CommandOutput): boolean => output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
@@ -181,6 +202,8 @@ const body = jr2Setup({
       model: "local/qwen3.6-35b-a3b",
       instructions: "You fix failing tests. You change no test. You commit the fix.",
     }),
+    // Cut the Worktree: an Effect too.
+    cut: worktree(),
     // One program, with no shell. arg("file") is one argument, from the input of the Effect.
     test: command(["node", "--test", arg("file")], { timeout: "5m" }),
     // A call to a fixed URL. The Effector puts the value of the secret in the header.
@@ -198,12 +221,20 @@ const body = jr2Setup({
   id: "fix-and-report",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
-        input: ({ context }) => ({ prompt: context.prompt, cwd: context.workspace.repos.app }),
+        input: ({ context }) => ({ prompt: context.prompt, cwd: fixTree(context) }),
       },
       on: {
         finished: "reporting",
@@ -216,8 +247,8 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "test",
-            // The `file` of the pick goes to the arg("file") of the command.
-            input: fromPick(runTest),
+            // The `file` of the pick goes to the arg("file") of the command. The Machine gives `worktree`.
+            input: fromPick(runTest, ({ context }) => ({ worktree: fixTree(context) })),
             onDone: {
               target: "ready",
               // The Agent reads this text as the answer to its run_test pick.
@@ -235,7 +266,7 @@ const body = jr2Setup({
       invoke: {
         src: "report",
         // The Agent gives `summary`. The Machine gives `branch`.
-        input: fromPick(finished, ({ context }) => ({ branch: context.workspace.branch })),
+        input: fromPick(finished, ({ context }) => ({ branch: context.branch })),
         onDone: [
           { guard: ({ event }) => event.output.outcome === "response" && event.output.status < 300, target: "done" },
           { target: "notReported" },
@@ -244,6 +275,7 @@ const body = jr2Setup({
     },
     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" } } },
     notReported: { invoke: { src: "fail", input: { reason: "the report did not go out" } } },
     failed: { invoke: { src: "fail", input: { reason: "the coder could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
@@ -253,7 +285,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -261,7 +292,7 @@ The `coding` state routes [`agent.fault`](../reference/mechanism-events.md#agent
 Turn of the coder fails with no pick. Each state that invokes an Agent has a route for it, on the state or on a state
 above it: `jr2 check` refuses a Machine without one. When no transition takes the event, the run ends `error`.
 
-`failed`, `notReported` and `lost` are not final states. Each one invokes
+`notCut`, `failed`, `notReported` and `lost` are not final states. Each one invokes
 [`fail`](../reference/authoring-surface/fail.md), and the run ends `failed` with its reason: a final state means `done`.
 Do not throw from a promise to fail, because a throw is a defect, and the run ends `error`.
 
@@ -301,25 +332,24 @@ The options:
 - `timeout`: how long the program can run, such as `"90s"`, `"10m"` or `"1h"`. The default is `"10m"`. After it, jr2
   kills the process group, and the outcome is `timeout`.
 - `tail`: how many characters of the end of the output the Machine gets. The default is 4096.
-- `slot`: the [Repo Slot](../reference/glossary.md#repo-slot) whose [Worktree](../reference/glossary.md#worktree) the
-  program runs in. Write it only when the Workspace has more than one Repo Slot.
 
-The program starts in the root of the Worktree. In a Workspace with no Repo Slot, it starts in `/work`, the folder that
-the steps of the Workspace share (see [Workspaces](../concepts/workspaces.md#a-workspace-with-no-repo)). To run it in a
-subfolder, give the path as an argument, such as `["node", "--test", "<dir>/test/*.test.js"]`, or write
-`["sh", "-c", "cd <dir> && <program>"]`.
+The input of the Effect says where the program runs. Under [Repo Slots](../reference/glossary.md#repo-slot), `worktree`
+is required: the path of a Worktree that a cut made, or `/work/<slot>/default`. The program starts in the root of that
+folder. In a Workspace with no Repo Slot, it starts in `/work`, the folder that the steps of the Workspace share (see
+[Workspaces](../concepts/workspaces.md#a-workspace-with-no-repo)). To run it in a subfolder, give the path as an
+argument, such as `["node", "--test", "<dir>/test/*.test.js"]`, or write `["sh", "-c", "cd <dir> && <program>"]`.
 
 A `command` with no Effect secret runs in the [Harness](../reference/glossary.md#harness) container of the
-[Sandbox](../reference/glossary.md#sandbox), in the Worktree, beside the
-[Working tools](../reference/glossary.md#working-tools) of the Agent. It uses the tools of the
-[Sandbox Image](../reference/glossary.md#sandbox-image). Thus invoke it in the body of a
+[Sandbox](../reference/glossary.md#sandbox), beside the [Working tools](../reference/glossary.md#working-tools) of the
+Agent. It uses the tools of the [Sandbox Image](../reference/glossary.md#sandbox-image). Thus invoke it in the body of a
 [`workspace()`](../reference/authoring-surface/workspace.md).
 
 Each outcome is output for `onDone`, also a failure. Route on `outcome`
 ([`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)):
 
 - `exited`, with `code` and `tail`. A test that fails is `exited` with a `code` that is not 0. A program that the
-  container does not have is `exited` with code 127.
+  container does not have is `exited` with code 127. A bad `worktree` is `exited` with code 127 too, and `tail` gives
+  the reason. A bad path does not add an outcome.
 - `timeout`, with `tail`.
 - `killed`, with `signal` and `tail`.
 - `unknown`, with `reason`: jr2 cannot tell what the program did. jr2 does not run it again.
@@ -332,13 +362,14 @@ the value. `secret("<name>").path` gives the path of a file that holds the value
 list of `jr2.config.ts`, as for `hook-token`.
 
 A `command` with an Effect secret in `env` does not run beside the Agent. It runs in the
-[Sandbox Effector](../reference/glossary.md#sandbox-effector), a container that the Agent cannot reach. It runs against
-one commit of the branch, not against the live Worktree:
+[Sandbox Effector](../reference/glossary.md#sandbox-effector), a container that the Agent cannot reach. Its `worktree`
+must be a branch Worktree that a cut made in this Sandbox, because a path alone does not name the target of a
+credential. It runs against one commit of that branch, not against the live Worktree:
 
 - By default, the commit is the tip of the branch when the Effect starts. When the Worktree holds changes that the
   program did not see, its output has `dirty: true`.
-- With `pin: true`, the commit is the `sha` of the input of the Effect: `{ sha: "<full commit id>" }`. Use it for a
-  commit that a [Gate](../reference/glossary.md#gate) approved.
+- With `pin: true`, the commit is the `sha` of the input of the Effect: `{ worktree, sha: "<full commit id>" }`. Use it
+  for a commit that a [Gate](../reference/glossary.md#gate) approved.
 
 The Sandbox Effector runs in the Sandbox Image, or in the image of the `effector` option of `workspace()`. Thus that
 image must hold the program.
@@ -362,8 +393,10 @@ image must hold the program.
 - `maxBody`: how many bytes of a text body the output keeps. The default is 65536.
 - `idempotent`: `true` when a second call is safe. The default is `false`. See [Effects](../concepts/effects.md).
 
-To send a file of the Worktree as the body, use [`file(path)`](../reference/authoring-surface/file.md) as `body`. In a
-Workspace with no Repo Slot, the path is relative to `/work`. jr2 sends a file body only with `PUT`, `POST` or `PATCH`.
+To send a file of a Worktree as the body, use [`file(path)`](../reference/authoring-surface/file.md) as `body`. The
+input of the Effect names the Worktree, `{ worktree }`, and a cut in this Sandbox must have made it. The path is
+relative to that Worktree. In a Workspace with no Repo Slot, the input has no `worktree`, and the path is relative to
+`/work`. jr2 sends a file body only with `PUT`, `POST` or `PATCH`.
 
 An `http` Effect runs in the [Instance Effector](../reference/glossary.md#instance-effector). The
 [Effector](../reference/glossary.md#effector) puts the value of each Effect secret into the call. The Agent never reads
@@ -414,9 +447,12 @@ jr2 up
 ```text
 …
 effects: workflow "fix-and-report" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
   test: command ["node","--test","<file>"] — 300s, in the Harness
   report: http POST https://hooks.example.com — 30s, in the Instance Effector, secrets "hook-token"
+…
 failures: workflow "fix-and-report" — the states that fail the run (ADR-0073)
+  fix-and-report.notCut: invokes fail
   fix-and-report.notReported: invokes fail
   fix-and-report.failed: invokes fail
   fix-and-report.lost: invokes fail
@@ -440,20 +476,19 @@ When you call `command()`, it refuses:
 - `pin: true` with no Effect secret in `env`:
   ``command(argv, { pin: true }) names no secret in its env: `pin` chooses the commit a credentialed command runs against in the Sandbox Effector, and a command that names no secret runs in the live Worktree (ADR-0067) — name its secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` ``
 
+`workspace()` refuses a body with an invoke that does not say where it works, when it can read the input:
+``workspace(): state "<state>": "<slot>" names no `<key>`, and a Workspace with Repo Slots says where each Turn and Effect works: a Worktree, or `cwd: "/work"` for a Turn (ADR-0057)``
+
 When a `command` starts, it refuses:
 
 - a state outside a `workspace()`. With no Effect secret in `env`:
   `command "<slot>" runs in the Harness container of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`.
   With one:
   `command "<slot>" runs in the Sandbox Effector of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
-- no `slot` under a Workspace with more than one Repo Slot:
-  `command "<slot>" runs under a Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`.
-  With an Effect secret in `env`, the text is
-  `command "<slot>" runs under a Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`
+- no `worktree` under Repo Slots, with no Effect secret in `env`:
+  ``command "<slot>" runs under a Workspace with Repo Slots (<slots>) and its input names no `worktree`: say which, a Worktree that a cut gave or `<slot>/default` ``
 - with an Effect secret in `env`, a Workspace with no Repo Slot:
   `command "<slot>" runs under a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and it runs in /work beside the Agent (ADR-0051)`
-- a `slot` that the Workspace does not have:
-  `command "<slot>" names Repo Slot "<name>", which its Workspace does not carry (<slots>)`
 - an `arg()` with no string in the input. The angle brackets around the name are in the text, and `<type>` is `nothing`
   when the input has no such key:
   `command "<slot>": argv slot <<name>> has no string value in its input (got <type>) — map it in the invoke's input`
@@ -477,7 +512,7 @@ When you call `http()`, it refuses:
 - a file body with a method other than `PUT`, `POST` or `PATCH`:
   `http({ method: "<method>", body: file(...) }): a file body is sent with PUT, POST, PATCH (ADR-0068)`
 - a `body` that is not `file()`:
-  ``http({ body }): a body is file(path, { slot?, segments?, contentType? }) — json and text come from `request` ``
+  ``http({ body }): a body is file(path, { segments?, contentType? }) — json and text come from `request` ``
 - a `content-type` header beside the `contentType` of `file()`:
   `http({ headers, body: file(path, { contentType }) }): "content-type" is set by file()'s contentType — write one of them (ADR-0067)`
 - a `request` with a file body:
@@ -489,9 +524,16 @@ When an `http` Effect starts, it refuses an input that its `input` schema does n
 `http "<slot>": its input does not match the definition's input schema — <path>: <message>`. With a file body, the text
 ends after `input schema`.
 
-An `http` Effect with a file body runs in the Sandbox Effector. When it starts, it refuses a state outside a
-`workspace()`:
-`http "<slot>" runs in the Sandbox Effector of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+An `http` Effect with a file body runs in the Sandbox Effector. When it starts, it refuses:
+
+- a state outside a `workspace()`:
+  `http "<slot>" runs in the Sandbox Effector of a Workspace, and its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+- no `worktree` under Repo Slots:
+  ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its input names no `worktree` ``
+
+A bad `worktree` is output, because a word of a run can cause it. An `http` Effect with a file body settles `refused`. A
+`command` settles `exited` with code 127, with the reason in `tail`. A credentialed `command` and a file body need a
+cut: `no cut made <path> in this Sandbox: cut it with worktree()`
 
 When you call `secret()`, `bearer()` or `text`, they refuse:
 
@@ -534,6 +576,7 @@ When you call `secret()`, `bearer()` or `text`, they refuse:
 - [Secrets and trust](../concepts/secrets-and-trust.md): who holds an Effect secret.
 - [The Menu](../concepts/the-menu.md): how a pick waits for its answer.
 - [Push and sign a branch](push-and-sign-a-branch.md): the `push` Effect.
+- [Cut a Worktree](cut-a-worktree.md): the Worktree that a `command` runs in, and the removal of a Worktree.
 - Reference: [`command`](../reference/authoring-surface/command.md),
   [`CommandOptions`](../reference/authoring-surface/type-commandoptions.md),
   [`http`](../reference/authoring-surface/http.md), [`secret`](../reference/authoring-surface/secret.md),