@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/get-started/have-your-assistant-write-a-machine.md

@@ -111,8 +111,14 @@ can differ when your Assistant used other names. Other Workflows of the Instance
 …
 typecheck: tsc --noEmit (the instance's own compiler)
 effects: workflow "fix" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
   tests: command ["node","--test","docs/site/tutorial/greet/test/*.test.js"] — 300s, in the Harness
   publish: push — 300s, in the Sandbox Effector
+…
+failures: workflow "fix" — the states that fail the run (ADR-0073)
+  fix.notCut: invokes fail
+  fix.lost: invokes fail
+…
 seats: workflow "fix" — who may send what, per state (ADR-0015)
   fix.working agent:coder: [finish]
   fix.review gate: [approve, request_changes]
@@ -126,8 +132,9 @@ git.credentials "*": push Secret jr2-git-push-684888c0 — pushes over https
 
 Read these lines as a first check:
 
-- `effects` shows two Effects: a command and a push. A Workflow that pushes with no
+- `effects` shows three Effects: the cut, a command and a push. A Workflow that pushes with no
   [Gate](../reference/glossary.md#gate) before the push shows the same lines. The graph shows where the push is.
+- `failures` shows the two states that end the run as `failed`.
 - `seats` shows that the coder can send only `finish`. Only the Gate in `review` can send `approve` and
   `request_changes`.
 - The `warning` line is about git over ssh. The `jr2-git-ssh` Secret is for an ssh key, and it does not exist. Your fork
@@ -199,7 +206,7 @@ jr2 run fix --input '{"prompt":"In docs/site/tutorial/greet, one test fails. Fix
 ```text
 …
 → context kind-jr2 / namespace my-instance
-run b22cef63-1523-45f3-9c51-36c54b79ce36 (fix) — attached
+run 790ad78a-db4e-4b09-a248-ab62da088cde (fix) — attached
   → active "placing"
   → active "provisioning"
   → active "attaching"
@@ -221,12 +228,14 @@ jr2 status <run id>
 
 [`jr2 status`](../reference/cli.md#status) prints the status of the run as one line of JSON. Its `gates` list holds the
 Gate of `review`. Its `gate` is `body.review`. Give that value to `--gate`. The `meta` of the Gate gives the coder's
-`summary`, the `branch` and the `worktree`:
+`summary`, the `branch` and the `worktree`. After the JSON, `jr2 status` prints one line for each Worktree that the run
+cut:
 
 ```text
 …
 → context kind-jr2 / namespace my-instance
-{…,"gates":[{"gate":"body.review",…,"meta":{"summary":"Fixed the \"trims the name\" test failure in docs/site/tutorial/greet/src/greet.js by adding .trim() to the name parsing. The name \" ada \" was not being trimmed, causing the greeting to include extra whitespace. Changed `args.find((a) => !a.startsWith(\"-\")) ?? \"world\"` to `(args.find((a) => !a.startsWith(\"-\")) ?? \"world\").trim()`.","branch":"jr2/fix-336ae477-2a46-49c2-b142-b81e705bb3f8","worktree":"/work/target/jr2-fix-336ae477-2a46-49c2-b142-b81e705bb3f8"}}]}
+{…,"gates":[{"gate":"body.review",…,"meta":{"summary":"Fixed the \"trims the name\" test failure in docs/site/tutorial/greet. The bug was that the `greet` function didn't trim whitespace from the name argument. Added `.trim()` to the name extraction so that `greet([\" ada \"])` correctly returns `\"hello, ada\"` instead of `\"hello,  ada \"`.","branch":"jr2/fix-a78c793e-607a-4b33-9784-ccf2cfb6f395","worktree":"/work/target/fix"}}]}
+worktree: /work/target/fix (target), branch jr2/fix-a78c793e-607a-4b33-9784-ccf2cfb6f395
 ```
 
 The `summary` is in the words of the model, so your summary is different.
@@ -242,7 +251,7 @@ jr2 send <run id> --gate body.review --event approve
 ```text
 …
 → context kind-jr2 / namespace my-instance
-delivered approve to gate "body.review" on b22cef63-1523-45f3-9c51-36c54b79ce36
+delivered approve to gate "body.review" on 790ad78a-db4e-4b09-a248-ab62da088cde
 ```
 
 The run goes to `pushing`, and the push Effect pushes the branch. Then the run ends, and jr2 removes the
@@ -253,7 +262,7 @@ status as one line of JSON:
 …
   → active "teardown"
   → done "done"
-{"runId":"b22cef63-1523-45f3-9c51-36c54b79ce36","workflow":"fix",…,"output":{"outcome":"pushed","branch":"jr2/fix-336ae477-2a46-49c2-b142-b81e705bb3f8","commit":"03f8800ec105c98f612bd2c55687bb92db80357a"}}
+{"runId":"790ad78a-db4e-4b09-a248-ab62da088cde","workflow":"fix",…,"output":{"outcome":"pushed","branch":"jr2/fix-a78c793e-607a-4b33-9784-ccf2cfb6f395","commit":"ee7f5d8084db32c3610efb5c9b889a710ef30f70"},"worktrees":[{"slot":"target","path":"/work/target/fix","branch":"jr2/fix-a78c793e-607a-4b33-9784-ccf2cfb6f395"}]}
 ```
 
 In that JSON, `context.output` and `output` are the output of `fix`. In this result, it is
@@ -289,9 +298,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type CommandOutput,
   type HostInjectedInput,
   type PushOutput,
@@ -339,6 +350,15 @@ type Context = BodyInput & {
 // The output of a run that ends `done`. A lost Sandbox fails the run, with no output of this type.
 type Output = { outcome: "pushed"; branch: string; commit: string };
 
+// The Worktree of the coder. The Machine names the folder, and each Effect that works there names it.
+function fixTree(context: BodyInput) {
+  return `${context.workspace.repos.target}/fix` as const;
+}
+// One branch for each run, from its seed Instance ID.
+function branchOf(context: BodyInput): string {
+  return `jr2/fix-${context.instanceId}`;
+}
+
 // Two guards. A guard with a name shows that name on its arrow in the Console's graph.
 function testsPassed({ event }: { event: { output: CommandOutput } }): boolean {
   return event.output.outcome === "exited" && event.output.code === 0;
@@ -362,7 +382,9 @@ const body = jr2Setup({
 - Make the smallest change that fixes the bug.
 - End your turn with exactly one call to \`finish\`.`,
     }),
-    // A program in the Harness container of the Sandbox, in the Worktree of `target`. Node expands the glob itself.
+    // Cut a Worktree of `target`: the Workspace only clones.
+    cut: worktree(),
+    // A program in the Harness container of the Sandbox, in the Worktree that its input names. Node expands the glob itself.
     tests: command(["node", "--test", "docs/site/tutorial/greet/test/*.test.js"], { timeout: "5m" }),
     // Push the tip of the coder's branch to the Repo of `target`, with the token of `git.credentials`.
     publish: push(),
@@ -372,16 +394,24 @@ const body = jr2Setup({
 }).createMachine({
   id: "fix",
   context: ({ input }) => ({ ...input, fresh: true }),
-  initial: "working",
+  initial: "cutting",
   // The Sandbox is gone, and every commit that was not pushed went with it.
   on: { "workspace.lost": { target: ".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: promptOf(context),
-          cwd: context.workspace.repos.target,
+          cwd: fixTree(context),
           // Each Turn continues the coder's one conversation, so the coder remembers its work.
           continue: true,
         }),
@@ -406,6 +436,7 @@ const body = jr2Setup({
     testing: {
       invoke: {
         src: "tests",
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           { guard: testsPassed, target: "review" },
           {
@@ -423,8 +454,8 @@ const body = jr2Setup({
           meta: {
             ...(context.summary !== undefined ? { summary: context.summary } : {}),
             ...(context.reason !== undefined ? { reason: context.reason } : {}),
-            branch: context.workspace.branch,
-            worktree: context.workspace.repos.target,
+            branch: branchOf(context),
+            worktree: fixTree(context),
           },
         }),
       },
@@ -442,6 +473,7 @@ const body = jr2Setup({
     pushing: {
       invoke: {
         src: "publish",
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           {
             guard: pushed,
@@ -457,11 +489,12 @@ const body = jr2Setup({
       type: "final",
       output: ({ context }): Output => ({
         outcome: "pushed",
-        branch: context.workspace.branch,
+        branch: branchOf(context),
         commit: context.commit ?? "",
       }),
     },
-    // Not a final state: the run ends `failed`, and jr2 deletes the Sandbox.
+    // Not final states: the run ends `failed`, and jr2 deletes the Sandbox.
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost, with every commit that was not pushed" } } },
   },
   // The output of the run. xstate reads only this root `output` as the output of the Machine. It
@@ -476,14 +509,14 @@ function promptOf(context: Context): string {
   const reason = context.reason ? `\n\nThe last attempt ended: ${context.reason}` : "";
   return (
     `${context.prompt}${reason}${feedback ? `\n\n${feedback}` : ""}\n\n` +
-    `Work in ${context.workspace.repos.target}, on the branch ${context.workspace.branch}. ` +
+    `Work in ${fixTree(context)}, on the branch ${branchOf(context)}. ` +
     "Commit your fix there, then call finish."
   );
 }
 
 // What the coder reads when the tests fail: the end of the output of `node --test`.
 function testFeedback(output: CommandOutput): string {
-  const text = output.outcome === "unknown" ? output.reason : output.tail;
+  const text = "tail" in output ? output.tail : output.reason;
   return (
     `The tests do not pass (${output.outcome}). The end of their output:\n${text}\n\n` +
     "Fix the code, commit, then call finish."
@@ -503,8 +536,6 @@ function pushFailure(output: PushOutput): string {
 export const machine = workspace(body, {
   input: door,
   repos: { target: { url: "https://github.com/<you>/jr2.git", ref: "v<version>" } },
-  // One branch for each run, from its seed Instance ID: `input.instanceId`.
-  spec: ({ input }) => ({ branch: `jr2/fix-${input.instanceId}` }),
 });
 ```
 
@@ -518,9 +549,11 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   push,
   workspace,
+  worktree,
   type CommandOutput,
   type HostInjectedInput,
   type PushOutput,
@@ -568,6 +601,15 @@ type Context = BodyInput & {
 // The output of a run that ends `done`. A lost Sandbox fails the run, with no output of this type.
 type Output = { outcome: "pushed"; branch: string; commit: string };
 
+// The Worktree of the coder. The Machine names the folder, and each Effect that works there names it.
+function fixTree(context: BodyInput) {
+  return `${context.workspace.repos.target}/fix` as const;
+}
+// One branch for each run, from its seed Instance ID.
+function branchOf(context: BodyInput): string {
+  return `jr2/fix-${context.instanceId}`;
+}
+
 // Two guards. A guard with a name shows that name on its arrow in the Console's graph.
 function testsPassed({ event }: { event: { output: CommandOutput } }): boolean {
   return event.output.outcome === "exited" && event.output.code === 0;
@@ -591,7 +633,9 @@ const body = jr2Setup({
 - Make the smallest change that fixes the bug.
 - End your turn with exactly one call to \`finish\`.`,
     }),
-    // A program in the Harness container of the Sandbox, in the Worktree of `target`. Node expands the glob itself.
+    // Cut a Worktree of `target`: the Workspace only clones.
+    cut: worktree(),
+    // A program in the Harness container of the Sandbox, in the Worktree that its input names. Node expands the glob itself.
     tests: command(["node", "--test", "docs/site/tutorial/greet/test/*.test.js"], { timeout: "5m" }),
     // Push the tip of the coder's branch to the Repo of `target`, with the token of `git.credentials`.
     publish: push(),
@@ -601,16 +645,24 @@ const body = jr2Setup({
 }).createMachine({
   id: "fix",
   context: ({ input }) => ({ ...input, fresh: true }),
-  initial: "working",
+  initial: "cutting",
   // The Sandbox is gone, and every commit that was not pushed went with it.
   on: { "workspace.lost": { target: ".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: promptOf(context),
-          cwd: context.workspace.repos.target,
+          cwd: fixTree(context),
           // Each Turn continues the coder's one conversation, so the coder remembers its work.
           continue: true,
         }),
@@ -635,6 +687,7 @@ const body = jr2Setup({
     testing: {
       invoke: {
         src: "tests",
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           { guard: testsPassed, target: "review" },
           {
@@ -652,8 +705,8 @@ const body = jr2Setup({
           meta: {
             ...(context.summary !== undefined ? { summary: context.summary } : {}),
             ...(context.reason !== undefined ? { reason: context.reason } : {}),
-            branch: context.workspace.branch,
-            worktree: context.workspace.repos.target,
+            branch: branchOf(context),
+            worktree: fixTree(context),
           },
         }),
       },
@@ -671,6 +724,7 @@ const body = jr2Setup({
     pushing: {
       invoke: {
         src: "publish",
+        input: ({ context }) => ({ worktree: fixTree(context) }),
         onDone: [
           {
             guard: pushed,
@@ -686,11 +740,12 @@ const body = jr2Setup({
       type: "final",
       output: ({ context }): Output => ({
         outcome: "pushed",
-        branch: context.workspace.branch,
+        branch: branchOf(context),
         commit: context.commit ?? "",
       }),
     },
-    // Not a final state: the run ends `failed`, and jr2 deletes the Sandbox.
+    // Not final states: the run ends `failed`, and jr2 deletes the Sandbox.
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost, with every commit that was not pushed" } } },
   },
   // The output of the run. xstate reads only this root `output` as the output of the Machine. It
@@ -705,14 +760,14 @@ function promptOf(context: Context): string {
   const reason = context.reason ? `\n\nThe last attempt ended: ${context.reason}` : "";
   return (
     `${context.prompt}${reason}${feedback ? `\n\n${feedback}` : ""}\n\n` +
-    `Work in ${context.workspace.repos.target}, on the branch ${context.workspace.branch}. ` +
+    `Work in ${fixTree(context)}, on the branch ${branchOf(context)}. ` +
     "Commit your fix there, then call finish."
   );
 }
 
 // What the coder reads when the tests fail: the end of the output of `node --test`.
 function testFeedback(output: CommandOutput): string {
-  const text = output.outcome === "unknown" ? output.reason : output.tail;
+  const text = "tail" in output ? output.tail : output.reason;
   return (
     `The tests do not pass (${output.outcome}). The end of their output:\n${text}\n\n` +
     "Fix the code, commit, then call finish."
@@ -732,8 +787,6 @@ function pushFailure(output: PushOutput): string {
 export const machine = workspace(body, {
   input: door,
   repos: { target: { url: "https://github.com/<you>/jr2.git", ref: "v<version>" } },
-  // One branch for each run, from its seed Instance ID: `input.instanceId`.
-  spec: ({ input }) => ({ branch: `jr2/fix-${input.instanceId}` }),
 });
 ```
 
@@ -765,16 +818,19 @@ const requestChanges = defineEvent({
 });
 ```
 
-**The Effects.** `tests` and `publish` are actor slots, as the coder is. A state runs one when it invokes it.
-[`command()`](../reference/authoring-surface/command.md) takes a list of arguments, not a line of shell text. It runs in
-the [Worktree](../reference/glossary.md#worktree) of the one [Repo Slot](../reference/glossary.md#repo-slot). A command
-runs in the root of the Worktree, so `tests` names the test files by their path from that root.
-[`push()`](../reference/authoring-surface/push.md) pushes the tip of the coder's branch.
+**The Effects.** `cut`, `tests` and `publish` are actor slots, as the coder is. A state runs one when it invokes it.
+[`worktree()`](../reference/authoring-surface/worktree.md) cuts a [Worktree](../reference/glossary.md#worktree) of the
+[Repo Slot](../reference/glossary.md#repo-slot). [`command()`](../reference/authoring-surface/command.md) takes a list
+of arguments, not a line of shell text. Its input names the Worktree. A command runs in the root of the Worktree, so
+`tests` names the test files by their path from that root. [`push()`](../reference/authoring-surface/push.md) pushes the
+tip of the coder's branch. Its input names the Worktree too, and jr2 reads the branch from the cut.
 [`fail()`](../reference/authoring-surface/fail.md) is a Part, not an Effect. The `lost` state invokes it to end the run
 `failed`, because a final state means `done`.
 
 ```ts
-// A program in the Harness container of the Sandbox, in the Worktree of `target`. Node expands the glob itself.
+// Cut a Worktree of `target`: the Workspace only clones.
+cut: worktree(),
+// A program in the Harness container of the Sandbox, in the Worktree that its input names. Node expands the glob itself.
 tests: command(["node", "--test", "docs/site/tutorial/greet/test/*.test.js"], { timeout: "5m" }),
 // Push the tip of the coder's branch to the Repo of `target`, with the token of `git.credentials`.
 publish: push(),
@@ -782,6 +838,21 @@ publish: push(),
 fail: fail(),
 ```
 
+**The cut.** The Workspace only clones. `cutting` is the first state, and it makes the coder's Worktree. The path is
+`/work/target/fix`, and the branch has the Instance ID of the run in it. See
+[Cut a Worktree](../guides/cut-a-worktree.md).
+
+```ts
+// 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" }],
+  },
+},
+```
+
 **The coder's state.** `working` invokes the coder. Each [Turn](../reference/glossary.md#turn) gets a prompt and the
 folder to work in. `continue: true` keeps one conversation, so the coder remembers its last Turn. `finish` is the
 coder's pick: the run goes to `testing`. [`agent.fault`](../reference/mechanism-events.md#agent-fault) is an event from
@@ -793,7 +864,7 @@ working: {
     src: "coder",
     input: ({ context }) => ({
       prompt: promptOf(context),
-      cwd: context.workspace.repos.target,
+      cwd: fixTree(context),
       // Each Turn continues the coder's one conversation, so the coder remembers its work.
       continue: true,
     }),
@@ -825,6 +896,7 @@ catches every other outcome. See [`CommandOutput`](../reference/authoring-surfac
 testing: {
   invoke: {
     src: "tests",
+    input: ({ context }) => ({ worktree: fixTree(context) }),
     onDone: [
       { guard: testsPassed, target: "review" },
       {
@@ -849,8 +921,8 @@ review: {
       meta: {
         ...(context.summary !== undefined ? { summary: context.summary } : {}),
         ...(context.reason !== undefined ? { reason: context.reason } : {}),
-        branch: context.workspace.branch,
-        worktree: context.workspace.repos.target,
+        branch: branchOf(context),
+        worktree: fixTree(context),
       },
     }),
   },
@@ -875,6 +947,7 @@ commits in it. See [`PushOutput`](../reference/authoring-surface/type-pushoutput
 pushing: {
   invoke: {
     src: "publish",
+    input: ({ context }) => ({ worktree: fixTree(context) }),
     onDone: [
       {
         guard: pushed,
@@ -890,15 +963,13 @@ pushing: {
 
 **The Workspace.** [`workspace()`](../reference/authoring-surface/workspace.md) runs the body in a Sandbox. `input` is
 the schema of the run input that `jr2 run --input` sends. `repos` binds the Repo Slot `target` to your fork, at the
-release tag. `spec` gives the branch. The input of `spec` also holds `instanceId`, an id that jr2 makes for each run, so
+release tag. A new branch starts from that tag. The body also gets `instanceId`, an id that jr2 makes for each run, so
 each run gets a branch of its own.
 
 ```ts
 export const machine = workspace(body, {
   input: door,
   repos: { target: { url: "https://github.com/<you>/jr2.git", ref: "v<version>" } },
-  // One branch for each run, from its seed Instance ID: `input.instanceId`.
-  spec: ({ input }) => ({ branch: `jr2/fix-${input.instanceId}` }),
 });
 ```
 

package/docs/get-started/install.md

@@ -20,6 +20,10 @@ This is the first page of the tutorial. You need a computer with these tools:
 kind makes the cluster from Docker containers. `jr2 up` builds an image with Docker and loads it into the kind cluster.
 kubectl is the tool that `jr2 up`, `jr2 run` and the other commands use to speak to the cluster.
 
+The kind cluster uses the Linux kernel of Docker: the kernel of your computer, or on macOS and Windows, the kernel of
+the virtual machine of Docker. jr2 needs Landlock in that kernel: Linux 6.2 or later, with `landlock` in its list of
+security modules. `jr2 up` refuses to converge without Landlock.
+
 ## Check Node.js
 
 Run:

package/docs/guides/add-tools-to-the-sandbox.md

@@ -12,16 +12,17 @@ Put the programs that your [Agents](../reference/glossary.md#agent) and
 A [Workspace](../reference/glossary.md#workspace) runs its body in a [Sandbox](../reference/glossary.md#sandbox): a pod
 of its own. The Sandbox Image is the image of the pod's `harness` container. The Agent's
 [Working tools](../reference/glossary.md#working-tools) run in that container, and so do the `command` Effects and the
-shell that you get with `kubectl exec`. Thus a program that is in the image is a program that they can run.
+shell that you get with `jr2 workspace shell`. Thus a program that is in the image is a program that they can run.
 
 Use this table to choose:
 
-| You want                                       | Do this                                                                                                        |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| The same tools for each Workspace              | Change `images/default/Dockerfile`.                                                                            |
-| Different tools for the Workspaces of one file | Put a docker context beside the workflow module, and name it in the `image` option.                            |
-| An image that you build and push yourself      | Write its registry ref in the `image` option.                                                                  |
-| A service that runs beside the Agent           | Name its image in the `user` option. It runs in the [User Container](../reference/glossary.md#user-container). |
+| You want                                       | Do this                                                                                                                                   |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| The same tools for each Workspace              | Change `images/default/Dockerfile`.                                                                                                       |
+| Different tools for the Workspaces of one file | Put a docker context beside the workflow module, and name it in the `image` option.                                                       |
+| An image that you build and push yourself      | Write its registry ref in the `image` option.                                                                                             |
+| A service that runs beside the Agent           | Name its image in the `user` option. It runs in the [User Container](../reference/glossary.md#user-container).                            |
+| A tool that the model calls by name            | Put an MCP server in the image, and declare it in `jr2.config.ts`. See [Write a tool as an MCP server](write-a-tool-as-an-mcp-server.md). |
 
 ## Add a tool to the default image
 
@@ -137,26 +138,39 @@ RUN pip install --no-cache-dir pytest ruff
 
 ```ts
 import { z } from "zod";
-import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { command, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+// The Worktree that the tests run in.
+const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
+
 const body = jr2Setup({
-  types: {} as { input: BodyInput },
+  types: {} as { input: BodyInput; context: BodyInput },
   actors: {
+    cut: worktree(),
     // python and pytest come from the Sandbox Image in ./python.
     tests: command(["python", "-m", "pytest"], { timeout: "15m" }),
     fail: fail(),
   },
 }).createMachine({
   id: "pytest",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "testing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
     testing: {
       invoke: {
         src: "tests",
+        input: ({ context }) => ({ worktree: testTree(context) }),
         onDone: [
           {
             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -169,6 +183,7 @@ const body = jr2Setup({
     passed: { type: "final" },
     // Not final states: each one fails the run, and the run ends `failed`.
     failed: { invoke: { src: "fail", input: { reason: "pytest did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
   },
 });
@@ -178,7 +193,6 @@ export const machine = workspace(body, {
   // The docker context in the folder beside this file. jr2 up builds it.
   image: import.meta.resolve("./python"),
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -226,17 +240,23 @@ RUN apk add --no-cache git
 # The Worktrees under /work belong to a different user. Tell git to trust them.
 RUN git config --system --add safe.directory '*'
 
-# jr2 does not replace this command. It must keep running: when it ends, the pod is not ready.
+# jr2 does not replace this command. It must keep running: when it ends, Kubernetes starts the container again.
 CMD ["sh", "-c", "while true; do sleep 3600; done"]
 ```
 
 Save it as `workflows/shell/Dockerfile`. Name it in the `workspace()` options with
 `user: import.meta.resolve("./shell")`. `user` takes the same two forms as `image`, and `jr2 up` builds a `file:`
-context in the same way. Open the shell with `kubectl -n <namespace> exec -it <sandbox> -c user -- sh`.
+context in the same way. Open the shell with [`jr2 workspace shell`](../reference/cli.md#workspace-shell) and `--user`.
+[Look inside a Sandbox](look-inside-a-sandbox.md#find-the-sandbox) tells how to find `<workspace>`:
+
+```sh
+jr2 workspace shell <workspace> --user
+```
 
 The User Container is not a second Sandbox Image:
 
-- Its own `ENTRYPOINT` and `CMD` run. Its process must keep running: when it ends, the pod is not ready.
+- Its own `ENTRYPOINT` and `CMD` run. Its process must keep running. When it ends, Kubernetes starts the container
+  again, so a `CMD` that ends at once restarts again and again.
 - jr2 gives it `/work`, which it can write, and `/repos` and `/opt/jr2`, which it can only read. jr2 gives it no other
   mount, no environment variable and no command.
 - It has no floor: an Alpine base is correct here. It runs as the `USER` of its image, and root is permitted.
@@ -253,6 +273,42 @@ container, the [Sandbox Effector](../reference/glossary.md#sandbox-effector). By
 [Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md) and
 [Push and sign a branch](push-and-sign-a-branch.md).
 
+### Reach a service in the User Container
+
+No Service of the cluster goes to the User Container. To reach a port in the Sandbox pod, run
+[`jr2 workspace forward`](../reference/cli.md#workspace-forward). It forwards a port on your computer to the port in the
+pod, through the API server of the cluster, until you push Ctrl-C:
+
+```sh
+jr2 workspace forward <workspace> 3000
+```
+
+```text
+→ context <context> / namespace <namespace>
+127.0.0.1:36779
+forwarding 127.0.0.1:36779 → 7a0e8b50/x:0:3000 — Ctrl-C ends it
+```
+
+The address on stdout is the local address. The port changes on each run.
+
+When the User Container runs an sshd on port `22`, `ssh` can go through `jr2 workspace forward --stdio`. Add this entry
+to `~/.ssh/config`. Replace `<namespace>` with the namespace of your Instance:
+
+```text
+Host *.jr2
+  ProxyCommand jr2 workspace forward %h 22 --stdio -n <namespace>
+```
+
+Then connect with the name of the Sandbox, which `jr2 workspace ls` prints, and `.jr2`:
+
+```sh
+ssh <sandbox>.jr2
+```
+
+With `-n`, `jr2 workspace forward` needs no Instance folder, so `ssh` can run it from each folder. The sshd and its keys
+are yours: jr2 gives the User Container no key. With `ssh -A`, your `ssh-agent` goes only to the User Container, and the
+Agent runs nothing there.
+
 ## Rules
 
 - `workspace()` refuses an `image` that is empty or not a string:
@@ -290,6 +346,7 @@ container, the [Sandbox Effector](../reference/glossary.md#sandbox-effector). By
   [`UserContainer`](../reference/authoring-surface/type-usercontainer.md), [`jr2 up`](../reference/cli.md#up)
 - [ADR-0037](../reference/decisions/0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md): the Instance
   builds its Sandbox Images, and jr2 injects the Harness.
-- [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of the Sandbox pod.
+- [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md): the containers of the Sandbox pod, and how you
+  reach the User Container.
 - [ADR-0049](../reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md): a Machine carries its
   images.