@jr2/orchestrator 0.5.1 → 0.7.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.7.0, as plain Markdown.
 
 ## Home
 
@@ -24,14 +24,15 @@
 - [Machines and Workflows](concepts/machines-and-workflows.md): What a Machine and a Workflow are, the door of a run, the Vocabulary, and Emits.
 - [Agents and Turns](concepts/agents-and-turns.md): What an Agent is, what one Turn of an Agent holds, how a Turn ends, and what jr2 does when a Turn fails.
 - [The Menu](concepts/the-menu.md): How an Agent picks from the events that its Machine takes, and how the Machine decides what each pick does.
-- [Gates](concepts/gates.md): How a run waits for an event from a person, the CLI, the Console, a webhook or a CI job.
-- [Effects](concepts/effects.md): How a Machine runs a command, calls a URL, pushes a branch or starts a run, at most once.
+- [Gates](concepts/gates.md): How a run waits for an event from a person, the CLI, the Console, a Hook or a CI job.
+- [Effects](concepts/effects.md): How a Machine runs a command, calls a URL or an MCP tool, pushes a branch or starts a run.
 - [Workspaces](concepts/workspaces.md): How a Workflow gets a Sandbox with a git Worktree or a shared folder, and how long it keeps it.
 - [Composition](concepts/composition.md): How a Machine composes Machines that you import, and how you bind the parts that they leave Open.
 - [Charts](concepts/charts.md): How an Agent writes a Machine as data at run time, which cannot reach the process of the Orchestrator.
-- [Pools and Sources](concepts/pools-and-sources.md): How a Pool runs one worker Machine for each work item that a Source gives, and how its run ends.
+- [Pools and Sources](concepts/pools-and-sources.md): How a Pool runs one worker for each item of a Source, how a Hook brings items, and how its run ends.
 - [Architecture](concepts/architecture.md): What runs on your computer, in the cluster and in a Sandbox, and which part does what.
 - [Secrets and trust](concepts/secrets-and-trust.md): Where jr2 keeps each credential, which tokens it makes, and what a caller can see and do without one.
+- [Callers and Hooks](concepts/callers-and-hooks.md): Who acts on an Instance from outside its Machines, what each one may do, and what a Hook does.
 - [Converge](concepts/converge.md): What jr2 up makes in the cluster from your Instance folder, and the Assembly that it publishes.
 - [Durable runs](concepts/durable-runs.md): How a run survives a restart of the Orchestrator, what ends it, and how long jr2 keeps a run that ended.
 
@@ -39,13 +40,17 @@
 
 - [Start a run](guides/start-a-run.md): Start a run of a Workflow from the CLI, from the Console, or with a call to the HTTP API.
 - [Answer a Gate](guides/answer-a-gate.md): Send an event to an open Gate of a run, from the CLI, the Console, a webhook handler or a CI job.
+- [Answer a Gate from a forge](guides/answer-a-gate-from-a-forge.md): Make a Gate that a review on GitHub or GitLab answers, and that looks for the review it waits for.
+- [Steer an Agent](guides/steer-an-agent.md): Send free text to one Agent of a live run, from the CLI, from HTTP, or from the Machine itself.
 - [Watch a run](guides/watch-a-run.md): See where a run is and what its Agents do: in the CLI, in the Console, and in the pod log.
+- [Read a conversation](guides/read-a-conversation.md): Read what an Agent said and did in a run, live or after the run ended, with jr2 logs or the Console.
 - [Look inside a Sandbox](guides/look-inside-a-sandbox.md): Open a shell in the Sandbox of a run, and read the branch that its Agent works on.
 - [Cancel a run](guides/cancel-a-run.md): End a live run with CANCEL, and delete its Sandboxes or keep them to look inside.
-- [Open the Console](guides/open-the-console.md): Forward the port of the Orchestrator, open the Console, and unlock it with the Instance token.
+- [Open the Console](guides/open-the-console.md): Forward the port of the Orchestrator, open the Console, and unlock it with a token or a login.
 - [Use a local model](guides/use-a-local-model.md): Connect your Agents to a model on an OpenAI-compatible endpoint, with or without TLS and a key.
 - [Use a hosted provider or a gateway](guides/use-a-hosted-provider.md): Give your Agents a model from a hosted provider, directly or through a gateway.
 - [Give the cluster git credentials](guides/give-the-cluster-git-credentials.md): Give the cluster a token or an ssh key to clone and push your Repos, and choose which Repos a run can name.
+- [Give a Caller a scope](guides/give-a-caller-a-scope.md): Make a named token for a CI job or a bridge, give it only the scopes that it needs, and rotate it.
 - [Move from kind to a shared cluster](guides/move-from-kind-to-a-shared-cluster.md): Converge an Instance into a shared cluster, with a registry, Sandbox nodes, priority classes and a quota.
 - [Mirror the Kit images](guides/mirror-the-kit-images.md): Copy the Kit images and the Pinned image into your own registry, and make the cluster pull them from there.
 - [Upgrade the Kit version](guides/upgrade-the-kit-version.md): Move an Instance to a new Kit version. jr2 up converges it and updates the jr2 block in AGENTS.md.
@@ -55,12 +60,18 @@
 - [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.
+- [Give an Agent MCP tools](guides/give-an-agent-mcp-tools.md): Declare MCP servers in jr2.config.ts, and give an Agent the tools that it can call on each server.
+- [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.
+- [Call an MCP tool from a Machine](guides/call-an-mcp-tool-from-a-machine.md): Call a tool of an MCP server as an Effect, after the approval of a person, and route on its output.
+- [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.
+- [Write a tool as an MCP server](guides/write-a-tool-as-an-mcp-server.md): Write a small MCP server in TypeScript, put it in the Sandbox Image, and give its tool to an Agent.
 - [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.
 - [Run one worker per item](guides/run-one-worker-per-item.md): Make a Pool that runs one worker Machine for each item that a Source gives, and run it.
+- [Start a run for each alert](guides/start-a-run-for-each-alert.md): Make a standing Pool that starts one run for each alert that an outside service sends to a Hook.
+- [Write a Hook kind](guides/write-a-hook-kind.md): Write the kind of a service that jr2 ships no kind for, declare a Hook of it, and hear it at a Gate.
 - [Publish a Machine as an npm package](guides/publish-a-machine-as-an-npm-package.md): Ship a Machine in an npm package that names the Kit as a peer, and register it in an Instance.
 - [Let an Agent write a Chart](guides/let-an-agent-write-a-chart.md): Write a Chart wrapper whose planner Agent writes a Chart, runs it, and corrects it.
 - [Run a Chart by name](guides/run-a-chart-by-name.md): Keep a Chart under a name, as a Chart file or a runtime Chart, and run it with jr2 run.
@@ -68,21 +79,39 @@
 ## Reference
 
 - [Authoring surface](reference/authoring-surface.md): Every name that @jr2/orchestrator exports from its root, by group, with a link to its page: its signature, its TSDoc, and an example.
+  - [Authoring surface: Machine and events](reference/authoring-surface/group-machine-and-events.md): The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders (ADR-0011, ADR-0015).
+  - [Authoring surface: Gates](reference/authoring-surface/group-gates.md): A Gate slot hears a Hook (ADR-0011).
+  - [Authoring surface: Failure](reference/authoring-surface/group-failure.md): The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` (ADR-0073).
+  - [Authoring surface: Agents](reference/authoring-surface/group-agents.md): An Agent slot and the definition it carries (ADR-0028, ADR-0049).
+  - [Authoring surface: Workspaces and Repos](reference/authoring-surface/group-workspaces-and-repos.md): A Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
+  - [Authoring surface: Effects](reference/authoring-surface/group-effects.md): Work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071, ADR-0079), and what an author writes between a pick and that work.
+  - [Authoring surface: Steering](reference/authoring-surface/group-steering.md): The Machine's free text to one of its Agents, which the Agent hears once (ADR-0002).
+  - [Authoring surface: Composition](reference/authoring-surface/group-composition.md): A part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017, ADR-0049, ADR-0054, ADR-0060).
+  - [Authoring surface: Charts](reference/authoring-surface/group-charts.md): The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper (ADR-0070).
+  - [Authoring surface: Config](reference/authoring-surface/group-config.md): `jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050).
+  - [Authoring surface: Types these signatures name](reference/authoring-surface/group-types-these-signatures-name.md): The signature of an export, or a type here, names each of these types.
   - [`defineEvent`](reference/authoring-surface/defineevent.md): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
   - [`jr2Setup`](reference/authoring-surface/jr2setup.md): Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`.
   - [`sentBy`](reference/authoring-surface/sentby.md): A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy("coder")`.
   - [`HostInjectedInput`](reference/authoring-surface/type-hostinjectedinput.md): The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.
+  - [`gate`](reference/authoring-surface/gate.md): The Gate: an input that a run waits for from outside the run (ADR-0011).
+  - [`Delivered`](reference/authoring-surface/type-delivered.md): One plain event of a list of defs: `{ type: "approve", by }`.
+  - [`GateLook`](reference/authoring-surface/type-gatelook.md): A Gate's read of the fact that it waits for (ADR-0011).
+  - [`GateOutcome`](reference/authoring-surface/type-gateoutcome.md): What a delivery did at one open Gate.
+  - [`GateReply`](reference/authoring-surface/type-gatereply.md): The text that the person who acted reads.
   - [`fail`](reference/authoring-surface/fail.md): Fail the run: the Part a Machine invokes to end work that did not succeed.
   - [`isFailure`](reference/authoring-surface/isfailure.md): Is this error a Failure, which a state invoked `fail` to make?
   - [`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.
+  - [`AgentMcpServer`](reference/authoring-surface/type-agentmcpserver.md): One MCP server that an Agent uses, and the tools that it may call there.
   - [`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,21 +120,47 @@
   - [`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.
+  - [`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.
   - [`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.
+  - [`mcp`](reference/authoring-surface/mcp.md): The `mcp` Effects (ADR-0067, ADR-0079): `mcp.call(server, tool, { input })` calls a tool, `mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a prompt.
+  - [`McpOptions`](reference/authoring-surface/type-mcpoptions.md): The options of an `mcp` Effect.
+  - [`McpCallOutput`](reference/authoring-surface/type-mcpcalloutput.md): The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`McpOutput`](reference/authoring-surface/type-mcpoutput.md): The output of any `mcp` Effect: a call's, a read's or a prompt's.
+  - [`McpReadOutput`](reference/authoring-surface/type-mcpreadoutput.md): The output of an `mcp.read` or an `mcp.prompt` Effect.
   - [`answer`](reference/authoring-surface/answer.md): Set what the Agent reads when jr2 answers its pick.
   - [`fromPick`](reference/authoring-surface/frompick.md): Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name.
   - [`paramsOf`](reference/authoring-surface/paramsof.md): Read the params of a pick from the event that entered the state.
+  - [`steer`](reference/authoring-surface/steer.md): Send a Steering message to one Agent of this Machine: an action for a transition.
   - [`open`](reference/authoring-surface/open.md): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
   - [`customize`](reference/authoring-surface/customize.md): Retune the parts that a Machine carries, without a change to the module that exports it.
   - [`Customize`](reference/authoring-surface/type-customize.md): The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`.
   - [`EffectBinding`](reference/authoring-surface/type-effectbinding.md): The values that bind the Open parts of one Effect.
   - [`Size`](reference/authoring-surface/type-size.md): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
   - [`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.
+  - [`carry`](reference/authoring-surface/carry.md): Give the item itself.
+  - [`pool`](reference/authoring-surface/pool.md): Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most `cap` workers at once.
+  - [`reread`](reference/authoring-surface/reread.md): Read the Source again.
+  - [`skip`](reference/authoring-surface/skip.md): Bring nothing, and say why.
   - [`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.
+  - [`SourceReply`](reference/authoring-surface/type-sourcereply.md): The text that the person who acted reads, from this Source's verdict (ADR-0011, ADR-0017).
+  - [`SourceVerdict`](reference/authoring-surface/type-sourceverdict.md): A Source's verdict on one delivery, as its `reply` reads it (ADR-0017).
   - [`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.
@@ -113,10 +168,17 @@
   - [`chartSchemaFor`](reference/authoring-surface/chartschemafor.md): The Chart grammar for one Open body, as a zod schema.
   - [`defineConfig`](reference/authoring-surface/defineconfig.md): Declare the config of an Instance: the default export of `jr2.config.ts`.
   - [`JR2Config`](reference/authoring-surface/type-jr2config.md): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+  - [`McpRemoteServer`](reference/authoring-surface/type-mcpremoteserver.md): A remote MCP server, which the Harness reaches over Streamable HTTP.
+  - [`McpServer`](reference/authoring-surface/type-mcpserver.md): One MCP server of the Instance: a `McpRemoteServer` (`url`) or a `McpStdioServer` (`command`).
+  - [`McpStdioServer`](reference/authoring-surface/type-mcpstdioserver.md): A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent conversation, through jr2's spawner, inside the Agent's confinement.
+  - [`RunsConfig`](reference/authoring-surface/type-runsconfig.md): How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065).
   - [`EventSemantics`](reference/authoring-surface/type-eventsemantics.md): How the party that sends an event gets its answer.
   - [`EventAudience`](reference/authoring-surface/type-eventaudience.md): Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of a Gate), or `"any"` (both).
   - [`EventDef`](reference/authoring-surface/type-eventdef.md): A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere.
   - [`WorkflowEvent`](reference/authoring-surface/type-workflowevent.md): The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event.
+  - [`GateSlot`](reference/authoring-surface/type-gateslot.md): A Gate with parts that the Machine carries.
+  - [`Duration`](reference/authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+  - [`CallerRecord`](reference/authoring-surface/type-callerrecord.md): A Caller as a run records it (ADR-0078): who acted, and the party it says it acted for.
   - [`FailSlot`](reference/authoring-surface/type-failslot.md): The logic `fail()` returns: `failLogic` with the brand the walk reads.
   - [`Failure`](reference/authoring-surface/type-failure.md): A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
   - [`AgentDeclaration`](reference/authoring-surface/type-agentdeclaration.md): What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`.
@@ -126,7 +188,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,35 +198,47 @@
   - [`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`.
+  - [`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`.
-  - [`ChainLink`](reference/authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's pick — typed by the Machine's events.
+  - [`McpNotReturned`](reference/authoring-surface/type-mcpnotreturned.md): The outcomes that an `mcp` Effect gives besides `returned`.
+  - [`ChainLink`](reference/authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it.
+  - [`SteerArgs`](reference/authoring-surface/type-steerargs.md): The arguments a `steer` text or `from` function gets: the Machine's context and the event that the transition takes.
+  - [`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).
   - [`Quantity`](reference/authoring-surface/type-quantity.md): A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).
-  - [`PoolSpec`](reference/authoring-surface/type-poolspec.md): What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets.
-  - [`SourceSpec`](reference/authoring-surface/type-sourcespec.md): Where a Pool gets its work items: the Source.
+  - [`Carry`](reference/authoring-surface/type-carry.md): What `carry(item)` gives.
+  - [`PoolSpec`](reference/authoring-surface/type-poolspec.md): What you pass to `pool()` with a child Machine as its worker.
+  - [`StandingPoolSpec`](reference/authoring-surface/type-standingpoolspec.md): What you pass to `pool()` for a Pool of runs.
+  - [`Reread`](reference/authoring-surface/type-reread.md): What `reread()` gives.
+  - [`Skip`](reference/authoring-surface/type-skip.md): What `skip(reason)` gives: the delivery brings nothing, and the reason says why.
+  - [`SourceSpec`](reference/authoring-surface/type-sourcespec.md): A pull Source.
+  - [`SourceHooks`](reference/authoring-surface/type-sourcehooks.md): A Source's handlers, by Hook kind and event key.
+  - [`PushSourceSpec`](reference/authoring-surface/type-pushsourcespec.md): A push Source.
+  - [`ReadSourceSpec`](reference/authoring-surface/type-readsourcespec.md): A read Source.
   - [`OpenBodyLogic`](reference/authoring-surface/type-openbodylogic.md): The logic `openBody()` returns: actor logic that carries the brand.
   - [`Lends`](reference/authoring-surface/type-lends.md): The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
   - [`Ceilings`](reference/authoring-surface/type-ceilings.md): The limits that an Open body sets on its Chart.
   - [`ChartText`](reference/authoring-surface/type-charttext.md): The Chart text (ADR-0070).
-  - [`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).
+  - [`DeliveredEvent`](reference/authoring-surface/type-deliveredevent.md): A workflow event as delivered into a Machine: the def's name as `type`, plus its payload.
+  - [`Caller`](reference/authoring-surface/type-caller.md): A request's Caller (ADR-0078): who acts, through which authenticator, and what it may do.
   - [`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`.
   - [`HttpRequestParts`](reference/authoring-surface/type-httprequestparts.md): What the `request` of an `http` definition returns: the part of the request that changes for each run.
-  - [`NamedSecret`](reference/authoring-surface/type-namedsecret.md): A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present.
+  - [`NamedSecret`](reference/authoring-surface/type-namedsecret.md): A secret bound to a name, never `secret(open)`.
+  - [`SenderCallerField`](reference/authoring-surface/type-sendercallerfield.md): A field of a `Sender`'s Caller that jr2 can verify.
   - [`SourceNextResult`](reference/authoring-surface/type-sourcenextresult.md): What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
+  - [`SourceIn`](reference/authoring-surface/type-sourcein.md): What a Source's handler reads beside `payload`.
   - [`OpenBodySlot`](reference/authoring-surface/type-openbodyslot.md): The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
   - [`ChartJson`](reference/authoring-surface/type-chartjson.md): Plain JSON.
   - [`ChartEvent`](reference/authoring-surface/type-chartevent.md): An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
@@ -179,18 +253,23 @@
   - [`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.
+  - [`GateHooks`](reference/authoring-surface/type-gatehooks.md): A type that the Authoring surface names.
+  - [`EventFrom`](reference/authoring-surface/type-eventfrom.md): A type that the Authoring surface names.
+  - [`LookOutput`](reference/authoring-surface/type-lookoutput.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.
@@ -199,15 +278,23 @@
   - [`OpenEffectSlots`](reference/authoring-surface/type-openeffectslots.md): A type that the Authoring surface names.
   - [`BindingOf`](reference/authoring-surface/type-bindingof.md): A type that the Authoring surface names.
   - [`LogicAt`](reference/authoring-surface/type-logicat.md): A type that the Authoring surface names.
+  - [`GateSlots`](reference/authoring-surface/type-gateslots.md): A type that the Authoring surface names.
+  - [`GateBinding`](reference/authoring-surface/type-gatebinding.md): A type that the Authoring surface names.
+  - [`GateTypesAt`](reference/authoring-surface/type-gatetypesat.md): A type that the Authoring surface names.
   - [`ChildSlots`](reference/authoring-surface/type-childslots.md): A type that the Authoring surface names.
   - [`ChildAt`](reference/authoring-surface/type-childat.md): A type that the Authoring surface names.
   - [`RepoSlotsOf`](reference/authoring-surface/type-reposlotsof.md): A type that the Authoring surface names.
   - [`WorkspaceOf`](reference/authoring-surface/type-workspaceof.md): A type that the Authoring surface names.
   - [`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.
+  - [`StandingPoolMachine`](reference/authoring-surface/type-standingpoolmachine.md): A type that the Authoring surface names.
+  - [`GateSlotInput`](reference/authoring-surface/type-gateslotinput.md): A type that the Authoring surface names.
+  - [`GateSlotParts`](reference/authoring-surface/type-gateslotparts.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.
+- [Hook kinds](reference/hooks.md): Every name that @jr2/orchestrator/hooks exports: the interface of a Hook kind, the kinds that jr2 ships, and webhook().
 - [jr2.config.ts](reference/config.md): Every field of jr2.config.ts: its type, whether it is required, its default, and what it does.
 - [CLI](reference/cli.md): Every jr2 command: its synopsis, its arguments, flags and env vars, and what it prints.
 - [HTTP API](reference/http-api.md): Every route of the Orchestrator's HTTP API, by access band, and the types of its bodies and answers.

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

@@ -5,10 +5,14 @@ description: "Make an Agent: an actor slot that runs one Turn of a model each ti
 
 # `agent`
 
-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.
+Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```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

@@ -5,7 +5,7 @@ description: Set what the Agent reads when jr2 answers its pick.
 
 # `answer`
 
-Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function answer<
@@ -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

@@ -5,7 +5,7 @@ description: Mark one argv entry of a `command` that the input of the Effect fil
 
 # `arg`
 
-Constant, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Constant, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const arg: <const N extends string>(name: N) => Arg<N>
@@ -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/basic.md

@@ -5,7 +5,7 @@ description: "Make the `auth` of an `http` Effect that sends `Authorization: Bas
 
 # `basic`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function basic<

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

@@ -5,7 +5,7 @@ description: "Make the `auth` of an `http` Effect that sends `Authorization: Bea
 
 # `bearer`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function bearer<const S extends Secret>(s: S): MarkedIf<S, { readonly bearer: Secret }>

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`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+const branchName: ZodString
+```
+
+A kit schema for a pick param that names a branch. For example:
+`input: z.object({ branch: branchName })`.