@jr2/orchestrator 0.5.1 → 0.6.0

package/docs/llms.txt

@@ -1,6 +1,6 @@
 # jr2
 
-> A kit for agentic workflows as xstate Machines, run on Kubernetes. These are the docs of Kit version 0.5.1, as plain Markdown.
+> A kit for agentic workflows as xstate Machines, run on Kubernetes. These are the docs of Kit version 0.6.0, as plain Markdown.
 
 ## Home
 
@@ -55,8 +55,9 @@
 - [Write a Workflow](guides/write-a-workflow.md): Write a module in workflows/ that exports a Machine, with the input that starts a run and its Vocabulary.
 - [Bind a shipped Machine's Open parts](guides/bind-open-parts.md): Register a Machine from a package as a Workflow, and bind the parts that it leaves Open with customize().
 - [Set an Agent's access and Dials](guides/set-an-agents-access-and-dials.md): Choose what an Agent can do to the Workspace, and set the Dials and continue of one Turn.
+- [Cut a Worktree](guides/cut-a-worktree.md): Make a Worktree with worktree(), choose what a cut refuses, and remove a Worktree.
 - [Run a command or call a URL with an Effect](guides/run-a-command-or-call-a-url.md): Run a program or call a URL as an Effect, give it input from a pick, and route on its output.
-- [Push and sign a branch](guides/push-and-sign-a-branch.md): Push the branch of a Workspace, and sign its commits with a key that the Agent never reads.
+- [Push and sign a branch](guides/push-and-sign-a-branch.md): Push the branch of a Worktree, and sign its commits with a key that the Agent never reads.
 - [Start a run from a run](guides/start-a-run-from-a-run.md): Use a dispatch Effect to start a run of a Workflow from a Machine, in this Instance or in a different one.
 - [Add tools to the Sandbox](guides/add-tools-to-the-sandbox.md): Put the programs that your Agents use into the Sandbox Image, or run a service in a User Container.
 - [Size a Workspace](guides/size-a-workspace.md): Give a Workspace the memory and cpu that its Sandbox needs, and see how jr2 divides them in the pod.
@@ -77,12 +78,13 @@
   - [`agent`](reference/authoring-surface/agent.md): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
   - [`AgentDefinition`](reference/authoring-surface/type-agentdefinition.md): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
   - [`ThinkingLevel`](reference/authoring-surface/type-thinkinglevel.md): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.
-  - [`workspace`](reference/authoring-surface/workspace.md): Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch.
-  - [`Workspaced`](reference/authoring-surface/type-workspaced.md): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`).
+  - [`workspace`](reference/authoring-surface/workspace.md): Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot.
+  - [`Workspaced`](reference/authoring-surface/type-workspaced.md): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, the folder of each Repo Slot).
   - [`Binding`](reference/authoring-surface/type-binding.md): The repository of a Repo Slot: `{ url, ref }`.
   - [`RepoSlot`](reference/authoring-surface/type-reposlot.md): The value of one Repo Slot in `workspace({ repos })`.
   - [`arg`](reference/authoring-surface/arg.md): Mark one argv entry of a `command` that the input of the Effect fills.
   - [`CommandOutput`](reference/authoring-surface/type-commandoutput.md): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`LaterOutcome`](reference/authoring-surface/type-lateroutcome.md): A value of `outcome` that this kit does not give.
   - [`command`](reference/authoring-surface/command.md): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
   - [`basic`](reference/authoring-surface/basic.md): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
   - [`bearer`](reference/authoring-surface/bearer.md): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
@@ -91,8 +93,22 @@
   - [`secret`](reference/authoring-surface/secret.md): Name an Effect secret: `secret("jira")`.
   - [`text`](reference/authoring-surface/text.md): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
   - [`HttpOutput`](reference/authoring-surface/type-httpoutput.md): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
-  - [`push`](reference/authoring-surface/push.md): Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+  - [`push`](reference/authoring-surface/push.md): Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot.
   - [`PushOutput`](reference/authoring-surface/type-pushoutput.md): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`branchName`](reference/authoring-surface/branchname.md): A kit schema for a pick param that names a branch.
+  - [`isReady`](reference/authoring-surface/isready.md): Is it `ready`?
+  - [`readyOf`](reference/authoring-surface/readyof.md): The `ready` output of an `onDone` arm that `isReady` guards.
+  - [`worktree`](reference/authoring-surface/worktree.md): Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there.
+  - [`AnyFramePath`](reference/authoring-surface/type-anyframepath.md): A Turn's Frame: a Worktree, or `/work`, stated.
+  - [`AnyWorktreePath`](reference/authoring-surface/type-anyworktreepath.md): A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body.
+  - [`FramePath`](reference/authoring-surface/type-framepath.md): A Turn's Frame in a Workspace with the Repo Slots `S`.
+  - [`WorktreeFound`](reference/authoring-surface/type-worktreefound.md): What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work; `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no upstream; `commit`, a detached cut.
+  - [`WorktreeInput`](reference/authoring-surface/type-worktreeinput.md): The input of a `worktree()`: a branch Worktree, or a detached one.
+  - [`WorktreeOptions`](reference/authoring-surface/type-worktreeoptions.md): The options of `worktree()`.
+  - [`WorktreeOutput`](reference/authoring-surface/type-worktreeoutput.md): The output of a `worktree()`.
+  - [`WorktreePath`](reference/authoring-surface/type-worktreepath.md): A Worktree of the Repo Slots `S`.
+  - [`WorktreeReady`](reference/authoring-surface/type-worktreeready.md): Type, an export of @jr2/orchestrator.
+  - [`WorktreeRefused`](reference/authoring-surface/type-worktreerefused.md): No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a name that the remote cannot confirm.
   - [`dispatch`](reference/authoring-surface/dispatch.md): Make a `dispatch` Effect: it starts a run of a Workflow.
   - [`DispatchOutput`](reference/authoring-surface/type-dispatchoutput.md): The output of a `dispatch` Effect.
   - [`answer`](reference/authoring-surface/answer.md): Set what the Agent reads when jr2 answers its pick.
@@ -106,6 +122,7 @@
   - [`UserContainer`](reference/authoring-surface/type-usercontainer.md): The User Container in its object form: its image, and its part of the Workspace's Size.
   - [`pool`](reference/authoring-surface/pool.md): Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once.
   - [`source`](reference/authoring-surface/source.md): Declare a Source: where a `pool()` gets its work items, one at a time.
+  - [`PoolNextInput`](reference/authoring-surface/type-poolnextinput.md): The input of a Source's `next`: the ids of the items that workers have now, the ids of the items that settled, and the Pool's input.
   - [`openBody`](reference/authoring-surface/openbody.md): Make an Open body: the actor slot that a Chart binds.
   - [`OpenBodyDeclaration`](reference/authoring-surface/type-openbodydeclaration.md): What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can have, and the limits of a Chart.
   - [`OpenBodyOutput`](reference/authoring-surface/type-openbodyoutput.md): The output of an Open body.
@@ -126,7 +143,7 @@
   - [`WithoutEmptyIndex`](reference/authoring-surface/type-withoutemptyindex.md): The fields of the run input `T`.
   - [`PermissiveWorkspaceOptions`](reference/authoring-surface/type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
   - [`PermissiveNoSlotWorkspaceOptions`](reference/authoring-surface/type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
-  - [`WorkspaceHandles`](reference/authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch.
+  - [`WorkspaceHandles`](reference/authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot.
   - [`ExecOutcome`](reference/authoring-surface/type-execoutcome.md): How an exec ended.
   - [`Unknown`](reference/authoring-surface/type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
   - [`Arg`](reference/authoring-surface/type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
@@ -136,11 +153,14 @@
   - [`Secret`](reference/authoring-surface/type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
   - [`Text`](reference/authoring-surface/type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
   - [`FromInput`](reference/authoring-surface/type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
-  - [`FileBody`](reference/authoring-surface/type-filebody.md): `file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
+  - [`FileBody`](reference/authoring-surface/type-filebody.md): `file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
   - [`HttpDefinition`](reference/authoring-surface/type-httpdefinition.md): An `http` Effect's definition.
+  - [`HttpFileInput`](reference/authoring-surface/type-httpfileinput.md): The input of an `http` Effect with a Worktree file as its body.
   - [`OpenSecret`](reference/authoring-surface/type-opensecret.md): `secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054).
   - [`PushOptions`](reference/authoring-surface/type-pushoptions.md): The options of `push()`.
-  - [`PushInput`](reference/authoring-surface/type-pushinput.md): The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.
+  - [`PushInput`](reference/authoring-surface/type-pushinput.md): The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`.
+  - [`Duration`](reference/authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+  - [`NameStart`](reference/authoring-surface/type-namestart.md): What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.
   - [`DispatchDefinition`](reference/authoring-surface/type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
   - [`DispatchInput`](reference/authoring-surface/type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
   - [`DispatchOpenParts`](reference/authoring-surface/type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
@@ -155,10 +175,7 @@
   - [`Sender`](reference/authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
   - [`FailureInput`](reference/authoring-surface/type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
   - [`SandboxOptions`](reference/authoring-surface/type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
-  - [`WorkspaceSpec`](reference/authoring-surface/type-workspacespec.md): What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields.
-  - [`NoSlotSpec`](reference/authoring-surface/type-noslotspec.md): What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`.
   - [`SlotHandles`](reference/authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
-  - [`Duration`](reference/authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
   - [`CommandEnv`](reference/authoring-surface/type-commandenv.md): The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a file that holds it.
   - [`TextPart`](reference/authoring-surface/type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
   - [`HttpMethod`](reference/authoring-surface/type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
@@ -179,18 +196,20 @@
   - [`ToProvidedActor`](reference/authoring-surface/type-toprovidedactor.md): A type that the Authoring surface names.
   - [`MergedActors`](reference/authoring-surface/type-mergedactors.md): A type that the Authoring surface names.
   - [`ToParameterizedObject`](reference/authoring-surface/type-toparameterizedobject.md): A type that the Authoring surface names.
+  - [`BindActors`](reference/authoring-surface/type-bindactors.md): A type that the Authoring surface names.
   - [`SentByGuards`](reference/authoring-surface/type-sentbyguards.md): A type that the Authoring surface names.
   - [`AgentLogic`](reference/authoring-surface/type-agentlogic.md): A type that the Authoring surface names.
   - [`BodyAcceptsDoor`](reference/authoring-surface/type-bodyacceptsdoor.md): A type that the Authoring surface names.
   - [`WorkspaceMachine`](reference/authoring-surface/type-workspacemachine.md): A type that the Authoring surface names.
+  - [`DoorlessInput`](reference/authoring-surface/type-doorlessinput.md): A type that the Authoring surface names.
   - [`BodyAcceptsSlots`](reference/authoring-surface/type-bodyacceptsslots.md): A type that the Authoring surface names.
   - [`EffectLogic`](reference/authoring-surface/type-effectlogic.md): A type that the Authoring surface names.
   - [`OpenOf`](reference/authoring-surface/type-openof.md): A type that the Authoring surface names.
   - [`EnvOpenParts`](reference/authoring-surface/type-envopenparts.md): A type that the Authoring surface names.
   - [`OpenEffect`](reference/authoring-surface/type-openeffect.md): A type that the Authoring surface names.
   - [`MarkedIf`](reference/authoring-surface/type-markedif.md): A type that the Authoring surface names.
-  - [`HttpInput`](reference/authoring-surface/type-httpinput.md): A type that the Authoring surface names.
   - [`HttpOpenParts`](reference/authoring-surface/type-httpopenparts.md): A type that the Authoring surface names.
+  - [`HttpInput`](reference/authoring-surface/type-httpinput.md): A type that the Authoring surface names.
   - [`PushWireOutput`](reference/authoring-surface/type-pushwireoutput.md): A type that the Authoring surface names.
   - [`SyncState`](reference/authoring-surface/type-syncstate.md): A type that the Authoring surface names.
   - [`AnswerAction`](reference/authoring-surface/type-answeraction.md): A type that the Authoring surface names.
@@ -206,6 +225,8 @@
   - [`PoolMachine`](reference/authoring-surface/type-poolmachine.md): A type that the Authoring surface names.
   - [`EventFrom`](reference/authoring-surface/type-eventfrom.md): A type that the Authoring surface names.
   - [`ArgNames`](reference/authoring-surface/type-argnames.md): A type that the Authoring surface names.
+  - [`WorktreeKey`](reference/authoring-surface/type-worktreekey.md): A type that the Authoring surface names.
+  - [`NotWorktreeKeys`](reference/authoring-surface/type-notworktreekeys.md): A type that the Authoring surface names.
   - [`OpenSecretMark`](reference/authoring-surface/type-opensecretmark.md): A type that the Authoring surface names.
 - [@jr2/machines](reference/machines.md): The Machines that @jr2/machines ships: their input, their output, and their Open parts.
 - [jr2.config.ts](reference/config.md): Every field of jr2.config.ts: its type, whether it is required, its default, and what it does.

package/docs/reference/authoring-surface/agent.md

@@ -8,7 +8,11 @@ description: "Make an Agent: an actor slot that runs one Turn of a model each ti
 Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
 
 ```ts
-function agent(declaration: AgentDeclaration): AgentLogic
+function agent<
+  const D extends AgentDeclaration,
+>(
+  declaration: D,
+): AgentLogic & (D extends { workspace: "none" } ? { readonly definition: { readonly workspace: "none" } } : unknown)
 ```
 
 Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it. Put it
@@ -16,8 +20,9 @@ under `actors` in `jr2Setup`, and invoke it by its key: `actors: { coder: agent(
 `invoke: { src: "coder", input: { prompt } }`. The key is the Agent's name.
 
 The invoke's `input` is the Turn: `prompt` (required), `cwd`, `model`, `thinkingLevel` and
-`continue`. `cwd` is the absolute directory where the Working tools work. Absent, it is the
-Worktree of the Workspace's one Repo Slot. `continue: true` continues the Agent's conversation
+`continue`. `cwd` is the absolute directory where the Working tools work. Under Repo Slots it
+is required: a Worktree that a cut made, `<slot>/default` to read, or `/work`. An Agent with
+`workspace: "none"`, and a Workspace with no Repo Slot, need no `cwd`. `continue: true` continues the Agent's conversation
 in this Machine. Absent, each Turn starts a new conversation. `continue` is the literal `true`,
 not a `boolean`. A Turn can join only a conversation that an earlier Turn started with
 `continue: true`. Thus in a retry loop, put `continue: true` on each Turn, also on the first, so
@@ -43,10 +48,9 @@ When a Turn starts, it refuses:
 - a key in `input` that a Turn does not have: ``agent "<slot>": the Turn's input carries
   `<key>`, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials
   (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
-- no `cwd` under a Workspace with more than one Repo Slot: ``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)``
+- no `cwd` under Repo Slots: ``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)``
 - a `cwd` that is not an absolute path: ``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 makes this refusal
@@ -70,7 +74,16 @@ When a Turn starts, it refuses:
 
 ```ts
 import { z } from "zod";
-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 finish = defineEvent({
   name: "finish",
@@ -80,6 +93,8 @@ const finish = defineEvent({
 const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: BodyInput },
   events: [finish],
@@ -88,26 +103,35 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You fix failing tests. You change no test.",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "fix",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    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: "Make `node --test` pass, then commit.",
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           thinkingLevel: "high",
         }),
       },
       on: { finish: "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" } } },
   },
@@ -116,7 +140,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 

package/docs/reference/authoring-surface/answer.md

@@ -61,8 +61,10 @@ import {
   command,
   defineEvent,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -80,6 +82,8 @@ const finished = defineEvent({
 
 type Input = Workspaced<{}, "app">;
 
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
   events: [runTests, finished],
@@ -88,6 +92,7 @@ const body = jr2Setup({
       model: "anthropic/claude-haiku-5-5",
       instructions: "You are a careful engineer.",
     }),
+    cut: worktree(),
     tests: command(["npm", "test"]),
     fail: fail(),
   },
@@ -95,10 +100,20 @@ const body = jr2Setup({
   id: "fix-tests",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "fix-tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
-      invoke: { src: "coder", input: { prompt: "Make the tests pass." } },
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: "Make the tests pass.", cwd: fixTree(context) }),
+      },
       on: { finished: "done" },
       initial: "ready",
       states: {
@@ -106,6 +121,7 @@ const body = jr2Setup({
         testing: {
           invoke: {
             src: "tests",
+            input: ({ context }) => ({ worktree: fixTree(context) }),
             onDone: {
               target: "ready",
               // The Agent reads this string, not the whole output of the command.
@@ -120,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" } } },
   },
@@ -127,7 +144,6 @@ const body = jr2Setup({
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "fix-tests" }),
 });
 ```
 

package/docs/reference/authoring-surface/arg.md

@@ -26,30 +26,52 @@ map it in the invoke's input`. The angle brackets around the name are in the tex
 **Example**
 
 ```ts
-import { arg, command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  arg,
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
 
 type Input = Workspaced<{ file: string }, "app">;
 
+const lintTree = (context: Input) => `${context.workspace.repos.app}/lint` as const;
+
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
-  actors: { lint: command(["npx", "eslint", arg("file")]), fail: fail() },
+  actors: { cut: worktree(), lint: command(["npx", "eslint", arg("file")]), fail: fail() },
 }).createMachine({
   id: "lint",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "lint",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: lintTree(context), branch: "lint" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "lint" }, { target: "notCut" }],
+      },
+    },
     lint: {
-      invoke: { src: "lint", input: ({ context }) => ({ file: context.file }), onDone: "done" },
+      invoke: {
+        src: "lint",
+        input: ({ context }) => ({ file: context.file, worktree: lintTree(context) }),
+        onDone: "done",
+      },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "lint" }),
 });
 ```
 

package/docs/reference/authoring-surface/branchname.md

@@ -0,0 +1,15 @@
+---
+title: branchName
+description: A kit schema for a pick param that names a branch.
+---
+
+# `branchName`
+
+Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+const branchName: ZodString
+```
+
+A kit schema for a pick param that names a branch. For example:
+`input: z.object({ branch: branchName })`.

package/docs/reference/authoring-surface/command.md

@@ -16,7 +16,7 @@ function command<
 >(
   argv: A,
   options?: Opt,
-): EffectLogic<CommandInput<A, Opt["pin"]>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>
+): EffectLogic<CommandInput<A, Opt["pin"], Opt>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>
 ```
 
 Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a
@@ -29,8 +29,8 @@ shell, write it: `["sh", "-c", "…"]`.
 
 Where it runs:
 - With no Effect secret in `env`, in the Harness container of the enclosing Workspace's Sandbox.
-  It runs in the Worktree of a Repo Slot, or in `/work` in a Workspace with no Repo Slot. The
-  Agent's Working tools also run in this container.
+  It runs in the Worktree that `worktree` of the invoke's input names, or in `/work` in a
+  Workspace with no Repo Slot. The Agent's Working tools also run in this container.
 - With an Effect secret in `env`, in the Sandbox Effector, against a commit of the branch. This
   is the branch tip when it starts, or with `pin: true` the commit that the invoke's `input.sha`
   names. The output then says `dirty: true` when the Worktree held edits that the command did
@@ -67,11 +67,9 @@ It refuses, when you call it:
 And when it starts, with no Effect secret in `env`:
 - outside a `workspace()`: `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)`
-- 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)`
-- a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
-  its Workspace does not carry (<slots>)`
+- no `worktree` under Repo Slots: `` 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` ``
 - an `arg()` with no string in `input`: `command "<slot>": argv slot <<name>> has no string
   value in its input (got <type>) — map it in the invoke's input`. The angle brackets around the
   arg's name are in the text: `argv slot <file>`. `<type>` is `nothing` when `input` has no such
@@ -80,15 +78,13 @@ And when it starts, with no Effect secret in `env`:
 And when it starts, with an Effect secret in `env`:
 - outside a `workspace()`: `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>) — say which: { slot: "<slot>" }
-  (ADR-0051)`
 - 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)`. `jr2 up` refuses it first, with the same reason
-- a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
-  its Workspace does not carry (<slots>)`
+- a `worktree` that no cut made in this Sandbox: the output is `exited` 127, with `no cut made
+  <path> in this Sandbox: cut it with worktree()` in its tail. A detached Worktree gets the same
+  form
 - `pin: true` and an `input.sha` that is not a full commit id: `command "<slot>" (pin): its
   input's sha is not a full commit id`
 - an `arg()` with no string in `input`: the same text as above.
@@ -98,8 +94,7 @@ And when it starts, with an Effect secret in `env`:
 - `argv`: The program and its arguments: strings and `arg("name")` entries. Or `open`, in a
   Machine that you publish as a package, for the Instance that registers it to bind with
   `customize()`.
-- `options` ([`CommandOptions`](type-commandoptions.md)): Optional. `slot`: the Repo Slot whose Worktree the command runs in; needed only
-  where the Workspace has more than one. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
+- `options` ([`CommandOptions`](type-commandoptions.md)): Optional. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
   `"10m"`; when it expires, the output is `timeout`. `tail`: how many characters of the end of
   the output stream to keep, default 4096. `env`: environment variables. Each value is
   `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a
@@ -112,26 +107,46 @@ And when it starts, with an Effect secret in `env`:
 
 ```ts
 import { z } from "zod";
-import { arg, command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import {
+  arg,
+  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">;
 
+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(),
     tests: command(["node", "--test", arg("file")], { timeout: "5m" }),
     fail: fail(),
   },
 }).createMachine({
   id: "check",
+  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: { file: "test/greet.test.js" },
+        input: ({ context }) => ({ file: "test/greet.test.js", worktree: testTree(context) }),
         onDone: [
           {
             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -144,6 +159,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 test did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
@@ -151,7 +167,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -170,7 +185,7 @@ function command<
 >(
   argv: typeof open,
   options?: Opt,
-): EffectLogic<OpenCommandInput<Opt["pin"]>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<Opt>>
+): EffectLogic<OpenCommandInput<Opt["pin"], Opt>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<Opt>>
 ```
 
 Make a `command` Effect whose argv is Open: `command(open, options)`, in a Machine that you

package/docs/reference/authoring-surface/fail.md

@@ -37,24 +37,37 @@ It refuses an input that is not a Failure's, and the run ends `error`: ``fail: t
 
 ```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">;
+
+const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
 
 const body = jr2Setup({
-  types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
+  types: {} as { input: BodyInput; context: BodyInput },
   actors: {
+    cut: worktree(),
     tests: command(["npm", "test"], { timeout: "15m" }),
     fail: fail(),
   },
 }).createMachine({
   id: "check",
+  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,
@@ -67,6 +80,7 @@ const body = jr2Setup({
     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
     failing: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
     passed: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
@@ -74,7 +88,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```