@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/guides/run-one-worker-per-item.md

@@ -31,7 +31,7 @@ The imports:
 ```ts
 import { fromPromise } from "xstate";
 import { z } from "zod";
-import { customize, defineEvent, pool, source } from "@jr2/orchestrator";
+import { customize, defineEvent, pool, source, type PoolNextInput } from "@jr2/orchestrator";
 import { task } from "@jr2/machines";
 ```
 
@@ -59,13 +59,9 @@ type Issue = { number: number; title: string; body: string };
 // because the request has no token.
 const ISSUES = "https://api.github.com/repos/you/app/issues?labels=jr2&state=open&per_page=100";
 
-// The issues that this Source gave to a worker. A worker has each one now, or it finished it.
-// The set is in the memory of the Orchestrator, and a restart empties it.
-const claimed = new Set<number>();
-
 // The Source: give the next open issue that no worker has had.
 const issues = source<Issue>({
-  next: fromPromise<Issue | null, { active: string[] }>(async ({ input }) => {
+  next: fromPromise<Issue | null, PoolNextInput>(async ({ input }) => {
     const res = await fetch(ISSUES, { headers: { accept: "application/vnd.github+json" } }).catch(() => undefined);
     if (!res?.ok) {
       // While workers run, look again later. With no worker, stop the run with the error.
@@ -78,12 +74,11 @@ const issues = source<Issue>({
       body: string | null;
       pull_request?: unknown;
     }>;
-    // The issues API also lists pull requests. Skip them, and skip each issue that a worker has now.
-    const issue = open.find(
-      (i) => i.pull_request === undefined && !claimed.has(i.number) && !input.active.includes(`issue-${i.number}`),
-    );
+    // The issues API also lists pull requests. Skip them, and skip each issue that a worker has now
+    // or that a worker finished.
+    const taken = [...input.active, ...input.settled];
+    const issue = open.find((i) => i.pull_request === undefined && !taken.includes(`issue-${i.number}`));
     if (!issue) return null;
-    claimed.add(issue.number);
     return { number: issue.number, title: issue.title, body: issue.body ?? "" };
   }),
   // Send this event to the `source` Gate when you add the label to an issue.
@@ -129,10 +124,10 @@ The file has five parts:
   When no issue is ready, it gives `null`. The request has no token, so the Repo must be public. Without a token, GitHub
   allows 60 requests in each hour. The example reads only the first page of issues: at most 100. When the request fails
   while workers run, `next` gives `null` in place of the error, so that the failure does not stop the run.
-- **The record of the Source.** `next` keeps each issue that it gives in the `Set` `claimed`, and skips the issues in
-  `active`. The `Set` is in the memory of the [Orchestrator](../reference/glossary.md#orchestrator), and each run of the
-  Workflow uses the same `Set`. A restart of the Orchestrator empties it. Then `next` can give a finished issue again,
-  but never an issue that a worker of this run has now.
+- **The record of the Source.** The Source keeps no record of its own. `next` skips each issue in `active` and in
+  `settled`. The Pool holds both, so they stay across a restart of the
+  [Orchestrator](../reference/glossary.md#orchestrator). Each run of the Workflow has its own lists, so a new run can
+  give an issue that is still open.
 - **The worker.** `fixer` is `task` with its two [Open](../reference/glossary.md#open) parts bound: the Repo and the
   model of the coder. [Bind a shipped Machine's Open parts](bind-open-parts.md) tells more.
 - **The run input.** `door` is the run input of the Pool. `cap` reads `workers` from it. A worker never gets it.
@@ -149,15 +144,21 @@ jr2 up
 …
 jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
 typecheck: tsc --noEmit (the instance's own compiler)
+…
+effects: workflow "issues" — what it runs outside itself (ADR-0067)
+  cut: worktree — 600s, in the Harness
+…
 failures: workflow "issues" — the states that fail the run (ADR-0073)
   issues.failing: invokes fail
+  task.noBranch: invokes fail
+  task.notCut: invokes fail
   task.lost: invokes fail
 …
 seats: workflow "issues" — who may send what, per state (ADR-0015)
   task.working agent:coder: [finish]
   task.review gate: [approve, request_changes]
 …
-agents: coder, triager (carried by 4 workflow machine(s))
+agents: coder, triager (carried by 5 workflow machine(s))
 …
 sandbox nodes: jr2-control-plane
 …
@@ -286,8 +287,8 @@ In the JSON, `context.items` holds the output of each worker that finished, by i
   workers register the same Gate or [Agent](../reference/glossary.md#agent), the run stops with the status `error`, and
   its `fault` is `registration address "<address>" is already live (two concurrent registrations share an id)`. For
   `task`, `<address>` is `gate/<run id>/<item id>.body.review` or `agent/<run id>/<item id>.body/coder`.
-- `next` gets only `active`: the ids of the items that workers have now. To not give a finished item again, the Source
-  must keep the items that it gave.
+- `next` gets `active`, the ids of the items that workers have now, and `settled`, the ids of the finished and failed
+  items. It also gets `input`, the input of the Pool. To not give a finished item again, skip each id in `settled`.
 - When a worker fails, for example when the Sandbox of a `task` is lost, the Pool keeps the Failure in `failures` and
   goes on. Only the Sandbox of that worker is deleted. The other workers, and the work in their Sandboxes, stay. A
   defect in a worker is different: the run stops with the status `error`.

package/docs/guides/set-an-agents-access-and-dials.md

@@ -19,7 +19,7 @@ the file as `workflows/review.ts` in your [Instance](../reference/glossary.md#in
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const approve = defineEvent({
   name: "approve",
@@ -42,6 +42,10 @@ const runInput = z.object({ branch: z.string(), sha: z.string(), model: z.string
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { notes: string; summary: string };
 
+// Two Worktrees of one clone: the coder's branch, and the commit that the reviewer reads.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/work` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [approve, requestChanges, finished],
@@ -64,21 +68,38 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "review",
   context: ({ input }) => ({ ...input, notes: "", summary: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "reviewing",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "detaching" }, { target: "notCut" }],
+      },
+    },
+    // The second cut has no branch: the Worktree holds the commit, detached.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
     reviewing: {
       invoke: {
         src: "reviewer",
         input: ({ context }) => ({
           prompt: `Review commit ${context.sha}.`,
-          // The review Worktree holds the commit of `reviewSha`, detached from the branch.
-          cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+          // The review Worktree holds the commit, detached from the branch.
+          cwd: reviewTree(context),
           // A Dial: this Turn thinks harder than the default of the model.
           thinkingLevel: "high",
         }),
@@ -93,7 +114,7 @@ const body = jr2Setup({
         src: "coder",
         input: ({ context }) => ({
           prompt: `Change the code on the branch as the review asks:\n\n${context.notes}`,
-          cwd: context.workspace.repos.app,
+          cwd: coderTree(context),
           // Each Turn of the coder continues the same conversation.
           continue: true,
           // A Dial: the model of this Turn, from the run input. Absent, the model of the definition.
@@ -115,6 +136,7 @@ const body = jr2Setup({
       },
     },
     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" } } },
   },
@@ -123,7 +145,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
 });
 ```
 
@@ -132,7 +153,7 @@ export const machine = workspace(body, {
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const approve = defineEvent({
   name: "approve",
@@ -155,6 +176,10 @@ const runInput = z.object({ branch: z.string(), sha: z.string(), model: z.string
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { notes: string; summary: string };
 
+// Two Worktrees of one clone: the coder's branch, and the commit that the reviewer reads.
+const coderTree = (context: BodyInput) => `${context.workspace.repos.app}/work` as const;
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [approve, requestChanges, finished],
@@ -177,21 +202,38 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "review",
   context: ({ input }) => ({ ...input, notes: "", summary: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "reviewing",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: coderTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "detaching" }, { target: "notCut" }],
+      },
+    },
+    // The second cut has no branch: the Worktree holds the commit, detached.
+    detaching: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
     reviewing: {
       invoke: {
         src: "reviewer",
         input: ({ context }) => ({
           prompt: `Review commit ${context.sha}.`,
-          // The review Worktree holds the commit of `reviewSha`, detached from the branch.
-          cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+          // The review Worktree holds the commit, detached from the branch.
+          cwd: reviewTree(context),
           // A Dial: this Turn thinks harder than the default of the model.
           thinkingLevel: "high",
         }),
@@ -206,7 +248,7 @@ const body = jr2Setup({
         src: "coder",
         input: ({ context }) => ({
           prompt: `Change the code on the branch as the review asks:\n\n${context.notes}`,
-          cwd: context.workspace.repos.app,
+          cwd: coderTree(context),
           // Each Turn of the coder continues the same conversation.
           continue: true,
           // A Dial: the model of this Turn, from the run input. Absent, the model of the definition.
@@ -228,6 +270,7 @@ const body = jr2Setup({
       },
     },
     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" } } },
   },
@@ -236,7 +279,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/<you>/app.git" },
-  spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
 });
 ```
 
@@ -259,13 +301,13 @@ prompt and picks from its [Menu](../reference/glossary.md#menu). You can invoke
 the example does, or in a [Machine](../reference/glossary.md#machine) with no Workspace.
 
 A `"read"` Agent keeps bash, so a command can still change a file or the branch. To keep a reviewer away from the
-branch, give its Turn the review [Worktree](../reference/glossary.md#worktree):
+branch, give its Turn a detached [Worktree](../reference/glossary.md#worktree):
 
-1. In the `spec` of the `workspace()`, set `reviewSha` to the commit to review.
-2. In the Turn, set `cwd` to `context.workspace.review?.<slot>`.
+1. Cut the Worktree with [`worktree()`](../reference/authoring-surface/worktree.md), with `{ path, detach }`.
+2. In the Turn, set `cwd` to that path.
 
-The review Worktree is `/work/<slot>/<branch>-review`, with each `/` in the branch changed to `-`. It holds the commit
-of `reviewSha`, detached from the branch. In the example, `<slot>` is `app`, and the commit comes from the run input.
+The Worktree holds the commit, with no branch. In the example, the path is `/work/app/review`, and the commit comes from
+the run input. [Cut a Worktree](cut-a-worktree.md) tells more.
 
 The access is a part of the identity of the Agent. Only the definition sets it. A Turn cannot change it.
 
@@ -290,7 +332,7 @@ Run [`jr2 up`](../reference/cli.md#up) to converge the new Workflow:
 jr2 up
 ```
 
-`jr2 up` prints no line that is special to this Workflow. The `seats:` lines show the picks of the three Agents.
+The `effects:` lines show the cut. The `seats:` lines show the picks of the three Agents.
 
 To give a model to the coder's Turns, add `model` to the run input:
 
@@ -337,9 +379,11 @@ task, also on a Turn that continues. In the example, each `fixing` prompt gives
 - jr2 refuses a Turn whose `input` has a key that a Turn does not have, such as `instructions` or `workspace`. Only the
   definition sets those two. `<keys>` is each key that is not correct, in backticks, with a comma between them:
   ``agent "<slot>": the Turn's input carries <keys>, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
-- Under a Workspace with more than one [Repo Slot](../reference/glossary.md#repo-slot), jr2 refuses a Turn of an Agent
-  with Working tools that sets no `cwd`:
-  ``turn <id>: agent "<slot>" works under a Workspace carrying more than one Repo Slot (<slots>) and its Turn framed no `cwd` — say which Worktree it works in (`cwd: context.workspace.repos.<slot>`, one of those), because the kit gives no slot a meaning (ADR-0051) and a Turn's Frame is where it works (ADR-0057)``
+- Under a Workspace with [Repo Slots](../reference/glossary.md#repo-slot), jr2 refuses a Turn of an Agent with Working
+  tools that sets no `cwd`:
+  ``turn <id>: agent "<slot>" works under a Workspace with Repo Slots (<slots>) and its Turn framed no `cwd`: say where it works, a Worktree, or `cwd: "/work"` above them (ADR-0057)``
+- `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)``
 - The Harness refuses a `cwd` that is not an absolute path. The run gets `agent.fault`, with this reason:
   ``harness admission failed (400): agent "<slot>": the Turn's Frame carries a `cwd` that is not an absolute path — the Frame says WHERE this Turn works (ADR-0057), and a Turn rooted anywhere else would work in the wrong directory silently``
 - The Harness refuses a model that is not in its catalog and not a model of the custom provider. The run gets
@@ -359,7 +403,8 @@ task, also on a Turn that continues. In the example, each `fixing` prompt gives
 ## Read next
 
 - [Agents and Turns](../concepts/agents-and-turns.md): the definition, the Frame, the Dials and `continue`.
-- [Workspaces](../concepts/workspaces.md): the Worktrees and the review Worktree.
+- [Workspaces](../concepts/workspaces.md): the Worktrees.
+- [Cut a Worktree](cut-a-worktree.md): a detached Worktree for a reviewer.
 - [The Menu](../concepts/the-menu.md): the picks of an Agent.
 - [Bind a shipped Machine's Open parts](bind-open-parts.md): bind an Open model.
 - Reference: [`agent`](../reference/authoring-surface/agent.md),

package/docs/guides/size-a-workspace.md

@@ -14,26 +14,39 @@ it on a node, so the Sandbox always has it. Write it in the `resources` option o
 
 ```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(),
     // JR2_CPUS holds the cpu limit of the container. Playwright does not read that limit.
     e2e: command(["sh", "-c", "npx playwright test --workers=$JR2_CPUS"], { timeout: "30m" }),
     fail: fail(),
   },
 }).createMachine({
   id: "e2e",
+  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: "e2e",
+        input: ({ context }) => ({ worktree: testTree(context) }),
         onDone: [
           {
             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -46,6 +59,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: "the Playwright tests did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox was lost" } } },
   },
 });
@@ -55,7 +69,6 @@ export const machine = workspace(body, {
   // The Size of the whole Sandbox: 4 GiB of memory and 2 cpus. jr2 reserves all of it on a node.
   resources: { limits: { memory: "4Gi", cpu: "2" } },
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -160,8 +173,8 @@ The Harness can miss a fast increase. Then the kernel stops the whole container,
 memory limit (OOMKilled, limit <memory>): the Workspace's processes passed the Harness container's memory limit and the kernel killed the container, the conversation with it. Use fewer workers, or give the Workspace a larger Size (ADR-0060, ADR-0061).
 ```
 
-The next Agent in the Workspace gets a notice of the kill. When you see either text again and again, state a larger
-Size.
+Each conversation that was in the Workspace at the kill gets a notice of it one time, and so does the next Turn of the
+Agent whose Turn the kill cut. When you see either text again and again, state a larger Size.
 
 ## Rules
 

package/docs/guides/use-a-hosted-provider.md

@@ -190,6 +190,12 @@ custom provider, with `harness.provider` and `apiKey`. The guide
 - A credential that signs each request, such as `AWS_ACCESS_KEY_ID`, cannot be a Held secret. `jr2 up` warns when
   `harness.env` sets one. Send the calls through a gateway that holds the credential, and hold the key of the gateway:
   `warning: harness.env sets <NAME>: a signing credential cannot be held (a Stand-in cannot be swapped into a signature), so the Agent can read it — route the provider through a gateway that holds it, and hold the gateway's key instead (ADR-0059)`.
+- The Harness process reads the file that a credential-file name in `harness.env` names, such as `AWS_CONFIG_FILE` or
+  `GOOGLE_APPLICATION_CREDENTIALS`. `jr2 up` refuses a path in a folder that the Agent's code writes, or a path that is
+  not absolute:
+  `harness.env[<i>] sets <NAME> to "<path>", which is in <folder>, a folder the Agent's code writes: the Harness process reads that file, and code that writes it acts outside the Agent's confinement (ADR-0076). Point it at a file of the image that the Sandbox's user cannot write.`
+  For another path, it warns:
+  `warning: harness.env sets <NAME>: the Harness process reads "<path>", so the Sandbox's user must not be able to write it — a folder of the image that the user owns is one the Agent's code writes (ADR-0076)`.
 - The Harness refuses a model that is not in the catalog when it admits the Turn:
   `harness admission failed (400): agent "<agent>": model "<provider>/<modelId>" resolves to nothing — not in pi's catalog, and no custom provider "<provider>" is configured (ADR-0018)`.
 

package/docs/guides/watch-a-run.md

@@ -79,19 +79,24 @@ jr2 status a2d8
 
 The status is a [`RunStatus`](../reference/http-api.md#type-runstatus), with the open Gates of the run:
 
-| Field      | What it holds                                                                                                                     |
-| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `status`   | `active` while the run continues. `done`, `failed`, `error` or `cancelled` when it ended. `drifted` when jr2 did not continue it. |
-| `value`    | The state of the root Machine.                                                                                                    |
-| `context`  | The context of the root Machine.                                                                                                  |
-| `children` | The Machines that the run invokes now, such as its Workspaces, each with its state.                                               |
-| `waiting`  | Each Workspace that waits for capacity: what it waits for, since when, and the words of the scheduler or the quota.               |
-| `held`     | Each [outstanding](../reference/glossary.md#outstanding) pick of an Agent: the Agent, the pick, and since when.                   |
-| `fault`    | The error, when the status is `error`.                                                                                            |
-| `output`   | The output of the Machine, when the run ended. For `failed`, the Failure: `{ reason, detail? }`.                                  |
-| `reason`   | Why jr2 set the status, when the Machine did not set it, such as `drifted`.                                                       |
-| `assembly` | The hash of the [Assembly](../reference/glossary.md#assembly) that the run started under, and holds.                              |
-| `gates`    | Each open Gate. [Answer a Gate](answer-a-gate.md) explains its fields.                                                            |
+| Field       | What it holds                                                                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status`    | `active` while the run continues. `done`, `failed`, `error` or `cancelled` when it ended. `drifted` when jr2 did not continue it.                             |
+| `value`     | The state of the root Machine.                                                                                                                                |
+| `context`   | The context of the root Machine.                                                                                                                              |
+| `children`  | The Machines that the run invokes now, such as its Workspaces, each with its state.                                                                           |
+| `waiting`   | Each Workspace that waits for capacity: what it waits for, since when, and the words of the scheduler or the quota.                                           |
+| `held`      | Each [outstanding](../reference/glossary.md#outstanding) pick of an Agent: the Agent, the pick, and since when.                                               |
+| `fault`     | The error, when the status is `error`.                                                                                                                        |
+| `output`    | The output of the Machine, when the run ended. For `failed`, the Failure: `{ reason, detail? }`.                                                              |
+| `reason`    | Why jr2 set the status, when the Machine did not set it, such as `drifted`.                                                                                   |
+| `assembly`  | The hash of the [Assembly](../reference/glossary.md#assembly) that the run started under, and holds.                                                          |
+| `gates`     | Each open Gate. [Answer a Gate](answer-a-gate.md) explains its fields.                                                                                        |
+| `worktrees` | Each [Worktree](../reference/glossary.md#worktree) that the run cut: its `slot`, its `path`, and its `branch`, which is `null` when the Worktree is detached. |
+
+For a run that cut a Worktree, `jr2 status` also prints one line on stderr for each cut:
+`worktree: <path> (<slot>), branch <branch>`, or `worktree: <path> (<slot>), detached`. jr2 reads each line from the
+record of the cut, so these lines do not change when an Agent changes the branch in the Worktree.
 
 [Durable runs](../concepts/durable-runs.md) tells how long jr2 keeps a run that ended.
 
@@ -241,19 +246,37 @@ For example, this is the log of a run of the `task` Workflow of
 
 ```text
 jr2 harness serving on :8080
+[run] [status] running · body: cutting
+[run] [status] running · body: cutting
 [run] [status] running · body: working
 [run] [status] running · body: working
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] [prompt] In docs/intro/repo, run `node bin/greet.js`. Then finish, with what it printed.
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder]
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] Work in /work/target/jr2-task-19b49b58-2ea4-4d79-b100-49aad6e12013, on branch jr2/task-19b49b58-2ea4-4d79-b100-49aad6e12013 — your tools are rooted there, so a relative path lands inside it. Commit what you do there, then call finish.
-…
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] [thinking] The user wants me to run `node bin/greet.js` inside `docs/intro/repo` directory. Let me navigate there and run it.
-…
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] [bash] cd docs/intro/repo && node bin/greet.js
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] [thinking] The script printed "hello, world". I should now finish with this summary.
-…
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] [finish] {"summary":"Ran `node bin/greet.js` in docs/intro/repo, which printed: hello, world"}
-[coder] [19b49b58-2ea4-4d79-b100-49aad6e12013/body/coder] [finish answer] Delivered "finish" to the workflow (delivery afe6340b-fe10-4819-b545-8ebd1b9a3964). The workflow consumed it and moved on: your turn is over.
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [prompt] In docs/intro/repo, run `node bin/greet.js`. Then finish, with what it printed.
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] Work in /work/target/task, on branch jr2/task-84f810c8-dda7-4577-a57e-4a09a4e7f507 — your tools are rooted there, so a relative path lands inside it. Commit what you do there, then call finish.
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] <jr2-turn>
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] Working directory: /work/target/task
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] Allowed now: `mcp__jr2__finish`.
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] </jr2-turn>
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [thinking] The user wants me to:
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] 1. Run `node bin/greet.js` from the `docs/intro/repo` directory within the worktree
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] 2. Report what it printed
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] 3. Commit my work and call finish
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] Let me first run the command.
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [text]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [bash] cd /work/target/task && node docs/intro/repo/bin/greet.js
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [thinking] The command printed "hello, world". Now I need to finish with that information.
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [text]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder]
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [finish] {"summary":"Ran `node bin/greet.js` from docs/intro/repo. It printed: hello, world"}
+[coder] [9501dd2f-95ba-479b-b384-307c736a8aad/body/coder] [finish answer] Delivered "finish" to the workflow (delivery 1b61fa16-50b7-4202-b7ed-b46a6ead5930). The workflow consumed it and moved on: your turn is over.
+[run] [status] running · body: review
 [run] [status] running · body: review
 ```
 

package/docs/guides/write-a-workflow.md

@@ -290,7 +290,7 @@ file whose name starts with `_`, or a `.d.ts` file. Thus put the code that two W
   not an empty one. The run ends `error`, and its fault is:
   `fail: the input must be { reason: string; detail?: unknown } with a reason that is not empty (got <value>) — invoke: { src: "fail", input: { reason: "the tests failed" } } (ADR-0073)`.
 - `workspace()` refuses a body that declares a door. Declare the door with the `input` option of `workspace()`:
-  ``workspace(): the body "<id>" declares its own run input, which nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected `workspace` handles, so the body's schema is not the door. Move it to the wrapper: workspace(body, { input, spec }) (ADR-0033).``
+  ``workspace(): the body "<id>" declares its own run input, which nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected `workspace` handles, so the body's schema is not the door. Move it to the wrapper: workspace(body, { input }) (ADR-0033).``
 - `jr2 up` prints each refusal of `defineEvent`, `createMachine` and `workspace()` as `error: <refusal>`, and exits with
   `1`. It changes nothing in the cluster.
 - The Orchestrator refuses a start whose input does not agree with the door, with the status code `400`: