@jr2/orchestrator 0.5.1 → 0.7.0

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

@@ -5,10 +5,12 @@ description: "Declare a Source: where a `pool()` gets its work items, one at a t
 
 # `source`
 
-Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+## Overload 1
 
 ```ts
-function source<T>(spec: SourceSpec<T>): SourceSpec<T>
+function source<T, TInput = unknown>(spec: SourceSpec<T, TInput>): SourceSpec<T, TInput>
 ```
 
 Declare a Source: where a `pool()` gets its work items, one at a time. It gives back the spec
@@ -25,7 +27,7 @@ that you pass. The item type `T` types what `next` gives. `pool()` does not carr
 
 ```ts
 import { fromPromise } from "xstate";
-import { source } from "@jr2/orchestrator";
+import { source, type PoolNextInput } from "@jr2/orchestrator";
 
 type Issue = { id: string; title: string };
 
@@ -35,7 +37,7 @@ const backlog: Issue[] = [
 ];
 
 export const issues = source<Issue>({
-  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
+  next: fromPromise(async ({ input }: { input: PoolNextInput }) => {
     const issue = backlog.find((i) => !input.active.includes(i.id)) ?? null;
     if (issue) backlog.splice(backlog.indexOf(issue), 1);
     return issue;
@@ -49,3 +51,56 @@ export const issues = source<Issue>({
 - [Run one worker per item](../../guides/run-one-worker-per-item.md)
 - [Pools and Sources](../../concepts/pools-and-sources.md)
 - [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)
+
+## Overload 2
+
+```ts
+function source<const S extends z.ZodType>(spec: {
+  item: S;
+  hooks: SourceHooks<Carry<z.output<NoInfer<S>>>, {}>;
+  hold?: number;
+  reply?: SourceReply<z.output<NoInfer<S>>>;
+}): PushSourceSpec<z.output<S>>
+```
+
+Declare a PUSH Source: the schema of an item, and the handlers that carry it. Only a standing
+Pool of runs takes it.
+
+**Parameters**
+
+- `spec`: `item`, `hooks`, `hold` and `reply`. See [`PushSourceSpec`](type-pushsourcespec.md).
+
+  - `item`: `S`
+  - `hooks`: `SourceHooks<Carry<z.output<NoInfer<S>>>, {}>`
+  - `hold` (optional): `number`
+  - `reply` (optional): `SourceReply<z.output<NoInfer<S>>>`
+
+**Returns**: The same spec.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+
+## Overload 3
+
+```ts
+function source<
+  T,
+  TInput = unknown,
+  R extends AnyActorLogic = AnyActorLogic,
+>(
+  spec: ReadSourceSpec<T, TInput, R>,
+): ReadSourceSpec<T, TInput, R>
+```
+
+Declare a READ Source: a read of the whole set, and the items in its answer.
+
+**Parameters**
+
+- `spec`: `read`, `items`, `wake`, `pollEvery`, `hooks` and `reply`. See [`ReadSourceSpec`](type-readsourcespec.md).
+
+**Returns**: The same spec.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

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

@@ -0,0 +1,93 @@
+---
+title: steer
+description: "Send a Steering message to one Agent of this Machine: an action for a transition."
+---
+
+# `steer`
+
+Function, in `@jr2/orchestrator/src/steer.ts`. It is an export of `@jr2/orchestrator`, in the [Steering](group-steering.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function steer<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject["params"] | undefined,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+>(
+  agent: string,
+  text: string | ((args: SteerArgs<TContext, TExpressionEvent>) => string),
+  opts: { from?: Sender | ((args: SteerArgs<TContext, TExpressionEvent>) => Sender | undefined) } = {},
+): ActionFunction<TContext, TExpressionEvent, TEvent, TParams, TActor, never, never, never, never>
+```
+
+Send a Steering message to one Agent of this Machine: an action for a transition. The Agent hears
+the text once, without an interrupt. When a Turn of the Agent is open, its Harness adds the text
+at the Turn's next step boundary. Otherwise the text waits for the Agent's next Turn in this
+Machine instance. When this Machine instance ends first, the message is not delivered.
+
+A Steering message is not an event: no guard reads it, and no Gate takes it. The Agent decides
+what to do with it, and acts on the workflow only by its picks.
+
+Use it to relay what one Agent says to another. Give `from` the Sender of the event (the
+`sender` field that the Orchestrator writes on it): the Agent then reads the text as the word of
+a peer, not as an order. When the Sender is a Gate, the Agent reads the text as what the Gate
+received, not as an order. With no `from`, the Agent reads the text as the workflow's own.
+
+`agent` is the name of an Agent in this Machine's `actors`. A text longer than 16 KiB is cut.
+The Machine can steer an Agent whose definition says `steerable: false`: that refuses Callers
+only.
+
+**Parameters**
+
+- `agent`
+- `text`
+- `opts`
+
+  - `from` (optional): `Sender | ((args: SteerArgs<TContext, TExpressionEvent>) => Sender | undefined)`
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, jr2Setup, steer } from "@jr2/orchestrator";
+
+const done = defineEvent({ name: "done", description: "The draft is ready.", input: z.object({}) });
+const note = defineEvent({
+  name: "note",
+  description: "Send the draft back to the writer, with what to change.",
+  input: z.object({ text: z.string().min(1) }),
+});
+
+export const machine = jr2Setup({
+  events: [done, note],
+  actors: {
+    writer: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You write.", workspace: "none" }),
+    reviewer: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You review.", workspace: "none" }),
+  },
+}).createMachine({
+  initial: "writing",
+  states: {
+    writing: {
+      invoke: { src: "writer", input: { prompt: "Write the notes.", continue: true } },
+      on: { done: "reviewing" },
+    },
+    reviewing: {
+      invoke: { src: "reviewer", input: { prompt: "Review the notes." } },
+      on: {
+        // The writer's next Turn hears the note as the reviewer's word, not as an order.
+        note: {
+          target: "writing",
+          actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+        },
+      },
+    },
+  },
+});
+```
+
+**See also**
+
+- [Steer an Agent](../../guides/steer-an-agent.md)
+- [Agents and Turns](../../concepts/agents-and-turns.md)
+- [ADR-0002: The agent actor is a duplex channel; its control plane is Menu tool calls](../decisions/0002-duplex-streaming-actor.md)

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

@@ -5,7 +5,7 @@ description: "Make a string from literal text and Effect secrets, as a tagged te
 
 # `text`
 
-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 text<

package/docs/reference/authoring-surface/type-agentdefinition.md

@@ -5,7 +5,7 @@ description: "An Agent's definition: which model it runs, its instructions, and
 
 # `AgentDefinition`
 
-Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type AgentDefinition = {
@@ -14,6 +14,8 @@ type AgentDefinition = {
   description?: string;
   thinkingLevel?: ThinkingLevel;
   workspace?: WorkspaceAccess;
+  mcp?: readonly AgentMcpServer[];
+  steerable?: boolean;
 };
 ```
 
@@ -51,10 +53,21 @@ cannot change `instructions` or `workspace`.
   What the Agent may do to the Workspace. Default: `"write"`.
   - `"write"`: all the Working tools (read, write, edit, bash, grep, glob).
   - `"read"`: no write or edit tool. The Agent keeps bash, so `"read"` does not stop a command
-    that writes. To keep the Agent from changing the branch, frame its Turn in the review
-    Worktree: `reviewSha` in the spec, then `cwd: context.workspace.review?.<slot>`.
+    that writes. To keep the Agent from changing the branch, frame its Turn in a detached
+    Worktree: cut it with `{ path, detach: sha }`, then give that `path` as `cwd`.
   - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
     runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it.
+- `mcp` (optional): `readonly AgentMcpServer[]`
+
+  The MCP servers whose tools the Agent gets, each with its allowlist: see
+  [`AgentMcpServer`](type-agentmcpserver.md). The tools join the Agent's tools, after its Working tools and before
+  its Menu. A call to one is not a pick, and the Turn goes on after it. Default: none. A composer
+  replaces the whole list with `customize(machine, { agents: { <slot>: { mcp: [...] } } })`.
+- `steerable` (optional): `boolean`
+
+  May a Caller send this Agent a Steering message? Default: `true`. With `false`,
+  `POST /runs/:runId/steering` and `jr2 steer` refuse it, and `GET /runs/:runId/agents` says
+  `steerable: false`. The Machine can still steer the Agent with the `steer` action.
 
 **Example**
 

package/docs/reference/authoring-surface/type-agentmcpserver.md

@@ -0,0 +1,54 @@
+---
+title: AgentMcpServer
+description: One MCP server that an Agent uses, and the tools that it may call there.
+---
+
+# `AgentMcpServer`
+
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type AgentMcpServer = {
+  server: string;
+  tools?: readonly string[] | "*";
+};
+```
+
+One MCP server that an Agent uses, and the tools that it may call there.
+
+- `server` is a name of the `mcp` block of `jr2.config.ts`. `jr2 up` refuses a name that the
+  block does not declare, and prints the `customize()` line that binds the Agent to one it does.
+- `tools` is the allowlist. A remote server needs it: a list of tool names, or `"*"` for every
+  tool. The Harness offers and runs only those tools. When Workspace code in the Agent's Sandbox
+  can spend the server's secret, `jr2 up` takes only `"*"`, because a list would then not be a
+  limit. A stdio server takes no `tools`: the Agent gets every tool of the server.
+
+The model reads each tool as `mcp__<server>__<tool>`. A tool name in the list must keep that name
+within `[A-Za-z0-9_-]` and 128 characters.
+
+**Fields**
+
+- `server`: `string`
+
+  A server name of the `mcp` block of `jr2.config.ts`.
+- `tools` (optional): `readonly string[] | "*"`
+
+  The allowlist: tool names of the server, or `"*"` for every tool. Required for a remote
+  server; absent for a stdio server.
+
+**Example**
+
+```ts
+import { agent } from "@jr2/orchestrator";
+
+export const triage = agent({
+  model: "anthropic/claude-haiku-5-5",
+  instructions: "You read the ticket and post a summary to the channel.",
+  workspace: "none",
+  mcp: [{ server: "slack-acme", tools: ["post_message", "read_channel"] }],
+});
+```
+
+**See also**
+
+- [ADR-0079: An Agent holds MCP tools, a Machine calls them as an Effect, and the Machine is the approval](../decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)

package/docs/reference/authoring-surface/type-agentslots.md

@@ -8,5 +8,8 @@ description: A type that the Authoring surface names.
 Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
 
 ```ts
-type AgentSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AgentLogic }>["src"];
+type AgentSlots<M extends AnyStateMachine> = Extract<
+  SlotsOf<M>,
+  { logic: CallbackActorLogic<AgentRunReceiveEvent, any> }
+>["src"];
 ```

package/docs/reference/authoring-surface/type-anyframepath.md

@@ -0,0 +1,14 @@
+---
+title: AnyFramePath
+description: "A Turn's Frame: a Worktree, or `/work`, stated."
+---
+
+# `AnyFramePath`
+
+Type, 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
+type AnyFramePath = "/work" | `/work/${string}`;
+```
+
+A Turn's Frame: a Worktree, or `/work`, stated. `jr2Setup` narrows it to the body's slots.

package/docs/reference/authoring-surface/type-anyworktreepath.md

@@ -0,0 +1,15 @@
+---
+title: AnyWorktreePath
+description: "A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body."
+---
+
+# `AnyWorktreePath`
+
+Type, 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
+type AnyWorktreePath = `/work/${string}/${string}`;
+```
+
+A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the
+slots of the body.

package/docs/reference/authoring-surface/type-bindactors.md

@@ -0,0 +1,14 @@
+---
+title: BindActors
+description: A type that the Authoring surface names.
+---
+
+# `BindActors`
+
+Type, in `@jr2/orchestrator/src/setup.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type BindActors<A extends Record<string, UnknownActorLogic>, TInput, TContext> = {
+  [K in keyof A]: BindLogic<A[K], RepoSlotsOf<TInput, TContext>>;
+};
+```

package/docs/reference/authoring-surface/type-binding.md

@@ -5,7 +5,7 @@ description: "The repository of a Repo Slot: `{ url, ref }`."
 
 # `Binding`
 
-Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type Binding = {
@@ -14,9 +14,9 @@ type Binding = {
 };
 ```
 
-The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch
-or commit that the branch Worktree starts from; absent, the Repo's default branch. Where only a
-url is needed, a string is enough.
+The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch,
+the tag or the commit that the clone stays on, and that a new branch starts from; absent, the
+Repo's default branch. Where only a url is needed, a string is enough.
 
 `workspace()` and `customize()` refuse:
 - an empty `url`: ``<where>: Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot
@@ -34,8 +34,8 @@ url is needed, a string is enough.
   The Repo's git url.
 - `ref` (optional): `string`
 
-  The branch or commit that the branch Worktree starts from. Default: the Repo's default
-  branch.
+  The branch, tag or commit that the clone stays on, and that a new branch starts from. Default:
+  the Repo's default branch.
 
 **Example**
 
@@ -52,7 +52,6 @@ const body = jr2Setup().createMachine({
 
 export const machine = workspace(body, {
   repos: { app },
-  spec: () => ({ branch: "jr2/hotfix" }),
 });
 ```
 

package/docs/reference/authoring-surface/type-caller.md

@@ -0,0 +1,40 @@
+---
+title: Caller
+description: "A request's Caller (ADR-0078): who acts, through which authenticator, and what it may do."
+---
+
+# `Caller`
+
+Type, in `@jr2/orchestrator/src/tokens.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Caller = {
+  via: "token" | "jwt" | "hook";
+  name: string;
+  shown?: string;
+  may: Scopes;
+  onBehalfOf?: string;
+};
+```
+
+A request's Caller ([ADR-0078](../decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): who acts, through which authenticator, and what it may do.
+
+**Fields**
+
+- `via`: `"token" | "jwt" | "hook"`
+
+  The authenticator that made the Caller: `token` (the Instance token or a named token), `jwt`
+  or `hook`.
+- `name`: `string`
+
+  The Caller's name for that authenticator: `instance`, a named token's name, a JWT's `sub`, a
+  Hook's name.
+- `shown` (optional): `string`
+
+  The name that jr2 shows, when it is not `name` (a JWT's `email`).
+- `may`: [`Scopes`](../config.md#callers-tokens-name-may)
+
+  What the Caller may do.
+- `onBehalfOf` (optional): `string`
+
+  The Caller's claim about the party it acts for. jr2 records it and never checks it.

package/docs/reference/authoring-surface/type-callerrecord.md

@@ -0,0 +1,32 @@
+---
+title: CallerRecord
+description: "A Caller as a run records it (ADR-0078): who acted, and the party it says it acted for."
+---
+
+# `CallerRecord`
+
+Type, in `@jr2/orchestrator/src/callers.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type CallerRecord = {
+  via: Caller["via"];
+  name: string;
+  shown?: string;
+  onBehalfOf?: string;
+};
+```
+
+A Caller as a run records it ([ADR-0078](../decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): who acted, and the party it says it acted for. Never its
+scopes.
+
+**Fields**
+
+- `via`: `Caller["via"]`
+- `name`: `string`
+- `shown` (optional): `string`
+
+  The name that jr2 shows, when it is not `name` (a JWT's `email`).
+- `onBehalfOf` (optional): `string`
+
+  The Caller's claim about the party it acts for. jr2 records it and never checks it, except for
+  a Hook, whose signature covers it.

package/docs/reference/authoring-surface/type-carry.md

@@ -0,0 +1,19 @@
+---
+title: Carry
+description: What `carry(item)` gives.
+---
+
+# `Carry`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Carry<T> = { readonly [VERDICT]: "carry"; readonly item: T };
+```
+
+What `carry(item)` gives. Only a push Source (one with an `item` schema) gives it.
+
+**Fields**
+
+- `[VERDICT]`: `"carry"`
+- `item`: `T`

package/docs/reference/authoring-surface/type-chainlink.md

@@ -1,6 +1,6 @@
 ---
 title: ChainLink
-description: "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."
+description: One reply since the pick, as the author reads it.
 ---
 
 # `ChainLink`
@@ -13,7 +13,7 @@ type ChainLink<TActor extends ProvidedActor, TEvent extends EventObject> =
   | { kind: "event"; event: Exclude<TEvent, { type: `${string}.${string}` }> };
 ```
 
-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
+One reply since the pick, as the author reads it. It is 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. A reply is from outside the Machine: the events it sends
 itself are not links.

package/docs/reference/authoring-surface/type-commandinput.md

@@ -8,11 +8,12 @@ description: "A command's input: one string per argv slot, and with `pin` the ap
 Type, in `@jr2/orchestrator/src/effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
 
 ```ts
-type CommandInput<A extends readonly unknown[], P = false> = [
+type CommandInput<A extends readonly unknown[], P = false, Opt = unknown> = [
   ArgNames<A> | ([P] extends [true] ? "sha" : never),
 ] extends [never]
-  ? void
-  : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string };
+  ? (WorktreeKey<Opt> & NotWorktreeKeys) | ([Opt] extends [{ readonly env: object }] ? never : void)
+  : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string } & WorktreeKey<Opt> &
+      Omit<NotWorktreeKeys, ArgNames<A>>;
 ```
 
 A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`);

package/docs/reference/authoring-surface/type-commandoptions.md

@@ -9,7 +9,6 @@ Type, in `@jr2/orchestrator/src/effect.ts`. The signature of an export, or a typ
 
 ```ts
 type CommandOptions = {
-  slot?: string;
   timeout?: Duration;
   tail?: number;
   env?: CommandEnv;
@@ -22,27 +21,6 @@ output it keeps, its Effect secrets, and the commit it runs against.
 
 **Fields**
 
-- `slot` (optional): `string`
-
-  The Repo Slot whose Worktree is the working directory of the command. Write it only when the
-  Workspace has more than one Repo Slot. In a Workspace with no Repo Slot, the command starts in
-  `/work`, the folder that the steps of the Workspace share.
-
-  The command starts in the root of that Worktree. To run it in a subfolder, give the path as an
-  argument, or write `["sh", "-c", "cd <dir> && <program>"]`.
-
-  When it starts, it refuses:
-  - 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)`. When `env` names an Effect secret,
-    the text is `command "<slot>" runs under a Workspace carrying more than one Repo Slot
-    (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`.
-  - with an Effect secret in `env`, 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)`.
-  - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
-    its Workspace does not carry (<slots>)`.
 - `timeout` (optional): [`Duration`](type-duration.md)
 
   How long the command can run: a number and a unit, such as `"90s"`, `"10m"` or `"1h"`.

package/docs/reference/authoring-surface/type-commandoutput.md

@@ -5,10 +5,10 @@ description: "The output of a `command` Effect: what the `onDone` of its state g
 
 # `CommandOutput`
 
-Type, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, 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
-type CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown;
+type CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown | LaterOutcome;
 ```
 
 The output of a `command` Effect: what the `onDone` of its state gets as `event.output`. Every
@@ -25,6 +25,8 @@ outcome is output. A failed program is output too. Route on `outcome`:
 characters. `dirty` is `true` when a command that names an Effect secret ran against a commit,
 and the Worktree held changes that it did not see.
 
+The union is open ([`LaterOutcome`](type-lateroutcome.md)): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `code`, `tail`, `dirty`
@@ -48,6 +50,10 @@ and the Worktree held changes that it did not see.
 
   - `outcome`: `"unknown"`
   - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **Example**
 
@@ -56,28 +62,40 @@ import {
   command,
   type CommandOutput,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type Workspaced,
 } from "@jr2/orchestrator";
 
 type Input = Workspaced<{}, "app">;
 
+const testTree = (context: Input) => `${context.workspace.repos.app}/test` as const;
+
 const passed = (output: CommandOutput): boolean =>
   output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
   types: {} as { context: Input; input: Input },
-  actors: { tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
+  actors: { cut: worktree(), tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
 }).createMachine({
   id: "tests",
   context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "testing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: testTree(context), branch: "tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
     testing: {
       invoke: {
         src: "tests",
+        input: ({ context }) => ({ worktree: testTree(context) }),
         onDone: [
           { guard: ({ event }) => passed(event.output), target: "green" },
           { target: "red" },
@@ -87,13 +105,13 @@ const body = jr2Setup({
     green: { type: "final" },
     // Not a final state: a final state means `done`, and the run ends `failed` here.
     red: { invoke: { src: "fail", input: { reason: "npm 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" } } },
   },
 });
 
 export const machine = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: () => ({ branch: "tests" }),
 });
 ```