@jr2/orchestrator 0.5.1 → 0.6.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

@@ -137,26 +137,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 +182,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 +192,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 }),
 });
 ```
 

package/docs/guides/bind-open-parts.md

@@ -121,9 +121,10 @@ jr2 run fix-app --input '{"prompt":"Make the failing test in test/greet.test.ts
 The key of each Repo Slot is the name of the slot, and the directory `/work/<slot>` in the
 [Sandbox](../reference/glossary.md#sandbox). The value is one of these:
 
-- a url: `"https://github.com/<you>/handbook.git"`. The [Worktree](../reference/glossary.md#worktree) starts from the
-  default branch of the Repo.
-- a [Binding](../reference/glossary.md#binding): `{ url, ref }`. The Worktree starts from `ref`, a branch or a commit.
+- a url: `"https://github.com/<you>/handbook.git"`. The clone stays on the default branch of the Repo, and a new
+  [Worktree](../reference/glossary.md#worktree) branch starts from it.
+- a [Binding](../reference/glossary.md#binding): `{ url, ref }`. The clone stays on `ref`, a branch, a tag or a commit,
+  and a new branch starts from it.
 - a function of the run input: `({ input }) => url`, or `({ input }) => ({ url, ref })`. Each run chooses its Repo. The
   url must agree with an entry of [`git.credentials`](../reference/config.md#git-credentials) in `jr2.config.ts`.
 - `open`, to leave the slot Open for the Instance that registers your Machine.
@@ -191,7 +192,7 @@ gives the values, and [Run a command or call a URL with an Effect](run-a-command
 - `customize()` refuses an Open map that you bind with no slot:
   ``customize(): machine "<id>" declares its Repo Slots open as a map — name at least one: `repos: { app: "https://…" }` (ADR-0051).``
 - `customize()` refuses a Repo Slot key that is not a directory name. The key becomes `/work/<slot>`:
-  ``customize(): Repo Slot key "<slot>" is not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).``
+  ``customize(): Repo Slot key "<slot>" is not a directory name — a slot becomes `/work/<slot>`, `/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).``
 - `customize()` refuses an empty url:
   ``customize(): Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
   For an empty `ref`, the text says `bound with an empty ref`.