@jr2/orchestrator 0.5.1 → 0.7.0

package/src/parts.ts

@@ -48,15 +48,18 @@
 import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AnyActorRef, AnyStateMachine, StateNode, UnknownActorLogic } from "xstate";
-import { isAgent, isOpenAgent, type AgentDeclaration } from "./agent.ts";
-import { argvText, isEffect, placementOf, type EffectParts, type Placement } from "./effect.ts";
+import { isAgent, isOpenAgent, type AgentDeclaration, type AgentMcpServer, type WorkspaceAccess } from "./agent.ts";
+import { argvText, isEffect, placementOf, type EffectParts, type EffectSlot, type Placement } from "./effect.ts";
+import { isGateSlot } from "./gate.ts";
 import { effectBindingLine, openPartsOf, type OpenEffectPart } from "./open-effect.ts";
 import { isFailSlot } from "./fail.ts";
 import { isImageContext } from "./images.ts";
 import { isOpenBody, openBodyDeclarationOf, type OpenBodyDeclaration } from "./open-body.ts";
 import { open } from "./open.ts";
 import { repoIdentity } from "./repo-identity.ts";
+import { refuseUnroutedOutcome } from "./effect-checks.ts";
 import { refuseUnroutedAgentFault } from "./mechanism-routes.ts";
+import { refuseSlotActiveTwice } from "./party.ts";
 import { refuseLostOutput } from "./run-output.ts";
 import { userSeatOf, type Size, type UserContainer } from "./size.ts";
 
@@ -75,9 +78,9 @@ import { userSeatOf, type Size, type UserContainer } from "./size.ts";
 export { open } from "./open.ts";
 
 /**
- * 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
@@ -102,7 +105,6 @@ export { open } from "./open.ts";
  *
  * export const machine = workspace(body, {
  *   repos: { app },
- *   spec: () => ({ branch: "jr2/hotfix" }),
  * });
  * ```
  *
@@ -113,8 +115,8 @@ export { open } from "./open.ts";
 export type Binding = {
   /** The Repo's git url. */
   url: 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. */
   ref?: string;
 };
 
@@ -130,10 +132,11 @@ export type Binding = {
  * - a function of the run input, `({ input }) => url` or a {@link Binding}: each run chooses. The
  *   url must match an entry of `git.credentials` in `jr2.config.ts`, or the run cannot use it.
  *
- * The key of the slot is a directory name under `/work`. It starts with a letter, and
- * `workspace()` and `customize()` refuse a key that does not: ``<where>: Repo Slot key "<key>" is
- * not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a
- * letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).`` They refuse a value of another
+ * The key of the slot is a directory name under `/work`. It starts with a letter, so never with
+ * `.`: `/work/.jr2/` is reserved for jr2. `workspace()` and `customize()` refuse a key that does
+ * not: ``<where>: Repo Slot key "<key>" is not a directory name — a slot becomes `/work/<slot>`,
+ * `/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter and matches
+ * /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).`` They refuse a value of another
  * shape: ``<where>: Repo Slot "<slot>" is <what> — a slot is `open`, a url, `{ url, ref? }`, or a
  * mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
  *
@@ -163,7 +166,6 @@ export type Binding = {
  *     docs: "https://github.com/you/docs.git",
  *     config: open,
  *   },
- *   spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
  * });
  * ```
  *
@@ -195,12 +197,13 @@ export function repoSlotState(value: RepoSlot<any>): RepoSlotState {
  * carry — and to what a prompt can name without quoting. It starts with a LETTER: the handles
  * keep declaration order, which a Machine may give a meaning to (`task`: the first slot is the
  * one the coder edits), and JS puts an integer-like key such as `"1"` ahead of every other key in
- * `Object.keys`, wherever the author wrote it. */
+ * `Object.keys`, wherever the author wrote it. So a key never starts with `.`, and `/work/.jr2/`
+ * stays jr2's (ADR-0075). */
 export const REPO_SLOT_KEY = /^[A-Za-z][A-Za-z0-9._-]*$/;
 
 /**
- * Refuse a malformed slot value BY NAME, at build time — the same derives-from-a-typo class the
- * spec guard catches for the branch, one build earlier. A bound url is also parsed here: an
+ * Refuse a malformed slot value BY NAME, at build time — a derives-from-a-typo fault, one build
+ * earlier. A bound url is also parsed here: an
  * identity the walk cannot derive (a relative path, an unknown scheme) is refused where the
  * author wrote it rather than at the converge that walks it. `where` names the caller
  * (`workspace()`, `customize()`).
@@ -209,8 +212,8 @@ export function assertRepoSlot(where: string, slot: string, value: unknown): ass
   if (!REPO_SLOT_KEY.test(slot)) {
     throw new Error(
       `${where}: Repo Slot key ${JSON.stringify(slot)} is not a directory name — a slot becomes ` +
-        "`/work/<slot>` and its order matters, so it starts with a letter and matches " +
-        "/^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).",
+        "`/work/<slot>`, `/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter " +
+        "and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).",
     );
   }
   if (value === open || typeof value === "function") return;
@@ -242,9 +245,8 @@ export function assertRepoSlot(where: string, slot: string, value: unknown): ass
  * to a concrete ref on the port's side, which is what keeps the Machine cluster-agnostic. The
  * Repos are Slots, each bound, open, or per-run.
  *
- * They are options rather than `WorkspaceSpec` fields because they are STATIC: `jr2 up` must find
- * them by walking the Machine, and a per-run spec is a function of run input that no walk can
- * evaluate.
+ * They are static options because `jr2 up` must find them by walking the Machine, and no walk can
+ * evaluate a function of run input.
  */
 export type SandboxParts = {
   /** The Sandbox Image. Absent → the Instance's `images/default`, then the stock Harness. */
@@ -258,6 +260,8 @@ export type SandboxParts = {
   /** The Size the Machine states (ADR-0060) — the `workspace()`'s, with any `customize()` layered
    * over it. Absent → the Instance's `sandbox.resources`, then the kit default. */
   resources?: Size;
+  /** The pod's work group (ADR-0005). Absent: the port's default. */
+  workGroup?: number;
   /** The Held secrets this Workspace's pod gets beside its Agents' model keys (ADR-0059): names of
    * the `secrets` list. Naming is placement — no other pod gets a name for being listed here. */
   secrets?: string[];
@@ -561,14 +565,15 @@ export type CarriedEffect = {
   (| {
         kind: "command";
         argv: string[];
-        slot?: string;
         secrets?: string[];
         pin?: true;
         open?: Array<"argv" | "secret">;
+        /** A `worktree()`: its `expect`. A report prints it in place of the kit program's argv. */
+        cut?: { expect?: "new" | "existing" };
       }
     /** An http Effect (ADR-0068): its method, its fixed target, and the secrets it names — what
      * places each secret, and what its Effector's config allows. `file`: its body is a Worktree
-     * file (ADR-0067), so it runs in its Workspace's Sandbox Effector, on Repo Slot `slot` when named.
+     * file (ADR-0067), so it runs in its Workspace's Sandbox Effector.
      * An Open url has no target, and names only the secrets its headers and auth name. */
     | {
         kind: "http";
@@ -577,10 +582,9 @@ export type CarriedEffect = {
         secrets: string[];
         idempotent: boolean;
         file?: true;
-        slot?: string;
         open?: Array<"url" | "secret">;
       }
-    /** A push (ADR-0067, ADR-0051): the Workspace's branch to its Repo Slot's Binding. It names no
+    /** A push (ADR-0067, ADR-0075): a cut Worktree's branch to its Repo Slot's Binding. It names no
      * secret: `jr2 up` resolves its credential through `git.credentials`. */
     | { kind: "push"; slot?: string; sign: boolean; squash: boolean; force: boolean; pin: boolean; secrets: string[] }
     /** A dispatch (ADR-0071): the Workflow it starts a run of, as `jr2 run` names it, whether it
@@ -598,6 +602,20 @@ export type CarriedEffect = {
         input?: Record<string, unknown>;
         open?: Array<"target">;
       }
+    /** An mcp Effect (ADR-0079): what it asks of which server, by the server's name in the `mcp`
+     * block of `jr2.config.ts`. It names no secret of its own: `jr2 up` reads the server's url and
+     * secret from the config and places them in the Instance Effector. An Open server or tool is
+     * absent until bound. `timeoutMs` is the author's; 0 when the author set none, and the server's
+     * `timeout` then applies. */
+    | {
+        kind: "mcp";
+        op: "call" | "read" | "prompt";
+        server?: string;
+        tool?: string;
+        secrets: string[];
+        idempotent: boolean;
+        open?: Array<"server" | "tool">;
+      }
   );
 
 /** One state that can fail the run (ADR-0073): it invokes a `fail()` slot. `state` is the state's
@@ -646,9 +664,22 @@ export type CarriedParts = {
   /**
    * The Instance Harness is needed (ADR-0031): an Agent declares `workspace: "none"`, or an Open
    * body allows it. `models` are the models its Turns may run: those Agents', and those Open bodies'
-   * allowed ones. Absent when nothing needs it.
+   * allowed ones. `servers` are the MCP servers those Agents name (ADR-0079), sorted, deduped.
+   * Absent when nothing needs it.
    */
-  instanceHarness?: { models: string[] };
+  instanceHarness?: { models: string[]; servers: string[] };
+  /** Every Agent slot whose definition names an MCP server (ADR-0079), at each `customize()` route
+   * the walk reached it by, in walk order: what `jr2 up` checks against the config's `mcp` block. */
+  mcpAgents: CarriedMcpAgent[];
+};
+
+/** An Agent that names MCP servers (ADR-0079): its slot, the `customize()` route to its Machine,
+ * where its Turns run, and its `mcp` list as written. */
+export type CarriedMcpAgent = {
+  slot: string;
+  path: OpenSlot["path"];
+  workspace: WorkspaceAccess;
+  mcp: readonly AgentMcpServer[];
 };
 
 /** A machine actor, told apart from a promise/callback/observable one by having a state tree.
@@ -739,6 +770,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const openEffects: CarriedParts["openEffects"] = [];
   const sizes: CarriedSize[] = [];
   const openBodies: CarriedParts["openBodies"] = [];
+  const mcpAgents: CarriedMcpAgent[] = [];
   // The Machine that declares each Open body: where its lent Agents are read (not carried data).
   const bodyWrappers = new Map<CarriedParts["openBodies"][number], AnyStateMachine>();
   let sandboxed = false;
@@ -808,6 +840,9 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     refuseInlineParts(machine);
     refuseLostOutput(machine);
     refuseUnroutedAgentFault(machine);
+    refuseUnroutedOutcome(machine);
+    // Here too, for a Machine built with xstate's own setup: the Turns' identity is the runtime's.
+    refuseSlotActiveTwice(machine);
     const parts = sandboxPartsOf(machine);
     const user = userSeatOf(parts.user);
     collectImage(parts.image);
@@ -826,8 +861,11 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     const body = wrapperBodyOf(machine);
     for (const { state, slot } of failingStatesOf(machine)) failures.push({ machine: machine.id, state, slot, path });
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
-      if (isAgent(logic)) collectAgent(path, name, logic.definition);
-      else if (isOpenBody(logic)) {
+      if (isAgent(logic)) {
+        collectAgent(path, name, logic.definition);
+        const { mcp, workspace } = logic.definition;
+        if (mcp?.length) mcpAgents.push({ slot: name, path, workspace: workspace ?? "write", mcp });
+      } else if (isOpenBody(logic)) {
         const body = { slot: name, declaration: openBodyDeclarationOf(logic), path };
         openBodies.push(body);
         bodyWrappers.set(body, machine);
@@ -836,6 +874,10 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
         effects.push(effect);
         if (effect.kind !== "push" && effect.open !== undefined)
           openEffects.push({ slot: name, path, parts: [...effect.open] });
+      } else if (lookReadOf(logic)) {
+        // A Gate slot's look reads with an http Effect (ADR-0011): the Instance Effector runs it, so
+        // `jr2 up` converges the Effector and places its secrets as for any Effect slot.
+        effects.push(carriedEffectOf(`${name}.look`, path, route, lookReadOf(logic)!.effect));
       } else {
         const child = asMachine(logic);
         if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name]);
@@ -852,6 +894,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const noneBodies = openBodies.filter((b) => bodyTurnsRunIn(bodyWrappers.get(b)!, b.declaration, "instance"));
   const harnessModels = new Set<string>(menuOnly.map((a) => a.definition.model).filter(bound));
   for (const body of noneBodies) for (const m of body.declaration.allows.models) harnessModels.add(m);
+  const harnessServers = new Set(menuOnly.flatMap((a) => (a.definition.mcp ?? []).map((e) => e.server)));
   return {
     agents,
     failures,
@@ -865,7 +908,10 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     composesSandbox: sandboxed,
     openBodies,
     models: [...models].sort(),
-    ...(menuOnly.length || noneBodies.length ? { instanceHarness: { models: [...harnessModels].sort() } } : {}),
+    ...(menuOnly.length || noneBodies.length
+      ? { instanceHarness: { models: [...harnessModels].sort(), servers: [...harnessServers].sort() } }
+      : {}),
+    mcpAgents,
   };
 }
 
@@ -918,6 +964,11 @@ export function placedEffectsOf(root: AnyStateMachine): CarriedEffect[] {
         effects.push(carriedEffectOf(name, path, route, logic.effect));
         continue;
       }
+      const look = lookReadOf(logic);
+      if (look) {
+        effects.push(carriedEffectOf(`${name}.look`, path, route, look.effect));
+        continue;
+      }
       const child = asMachine(logic);
       if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name], on);
     }
@@ -968,7 +1019,22 @@ export function carriedEffectOf(
       idempotent: parts.idempotent,
       timeoutMs: parts.timeoutMs,
       ...(parts.file ? { file: true as const } : {}),
-      ...(parts.file?.slot !== undefined ? { slot: parts.file.slot } : {}),
+    };
+  }
+  if (parts.kind === "mcp") {
+    return {
+      name,
+      path,
+      route,
+      kind: "mcp",
+      placement,
+      op: parts.op,
+      ...(parts.server === open ? {} : { server: parts.server }),
+      ...(parts.tool === undefined || parts.tool === open ? {} : { tool: parts.tool }),
+      secrets: [],
+      idempotent: parts.idempotent,
+      timeoutMs: parts.timeoutMs ?? 0,
+      ...(openParts.length ? { open: openParts as Array<"server" | "tool"> } : {}),
     };
   }
   if (parts.kind === "push") {
@@ -988,7 +1054,7 @@ export function carriedEffectOf(
       ...(slot !== undefined ? { slot } : {}),
     };
   }
-  const { argv, timeoutMs, slot, secrets, pin } = parts;
+  const { argv, timeoutMs, secrets, pin } = parts;
   return {
     name,
     path,
@@ -997,10 +1063,10 @@ export function carriedEffectOf(
     placement,
     argv: argvText(argv),
     timeoutMs,
-    ...(slot !== undefined ? { slot } : {}),
     ...(secrets?.length ? { secrets: [...secrets] } : {}),
     ...(pin ? { pin } : {}),
     ...(openParts.length ? { open: openParts as Array<"argv" | "secret"> } : {}),
+    ...(parts.cut ? { cut: { ...parts.cut } } : {}),
   };
 }
 
@@ -1035,10 +1101,17 @@ export type WorkspacePod = {
    * down to the next `workspace()`, which is a pod of its own, and every model an Open body below
    * it allows a Chart's own Agents when it allows "write" or "read" (ADR-0070). Sorted, deduped. */
   models: string[];
+  /** The MCP servers that the Agents whose Turns run in this pod name (ADR-0079), with the Agent
+   * that names each and its allowlist: what places each server's secret in this pod, and what the
+   * allowlist rule reads. Absent when none names one. */
+  mcp?: Array<{ slot: string; path: OpenSlot["path"]; entry: AgentMcpServer }>;
   /** The Effects placed in this pod's Sandbox Effector (ADR-0068): every `push`, file-body `http` and
    * credentialed `command` slot below the `workspace()`, down to the next `workspace()` — read off
    * their plain data, statically. Empty → the pod gets no Sandbox Effector and no Secret. */
   effects: CarriedEffect[];
+  /** The slot of each `worktree()` below the `workspace()`, down to the next `workspace()`. A cut runs
+   * in the Harness container, so `effects` does not hold it. Absent when there is none. */
+  cuts?: string[];
   /** The `workspace()`'s `effector: { image }`, as written. Absent → the Sandbox Image. */
   effector?: { image: string };
   /** The `workspace()`'s own `image`, as written — its Sandbox Image. Absent → `images/default`,
@@ -1067,6 +1140,8 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
     models: Set<string>,
     on: Set<AnyStateMachine>,
     effects: Map<string, CarriedEffect>,
+    cuts: Set<string>,
+    mcp: NonNullable<WorkspacePod["mcp"]>,
     path: OpenSlot["path"],
     route: PlacementRoute,
   ): void => {
@@ -1074,12 +1149,14 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
     on.add(machine);
     const body = wrapperBodyOf(machine);
     const visit = (child: AnyStateMachine, at: OpenSlot["path"], to: PlacementRoute) => {
-      if (!composesSandbox(child)) modelsIn(child, models, on, effects, at, to);
+      if (!composesSandbox(child)) modelsIn(child, models, on, effects, cuts, mcp, at, to);
     };
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
       if (isAgent(logic)) {
         const { model, workspace } = logic.definition;
         if (workspace !== "none" && typeof model === "string") models.add(model);
+        // A "none" Agent's servers are the Instance Harness's (ADR-0079), never this pod's.
+        if (workspace !== "none") for (const entry of logic.definition.mcp ?? []) mcp.push({ slot: name, path, entry });
         continue;
       }
       // A Turn under an Open body may run in this pod with any model the body allows (ADR-0070):
@@ -1093,6 +1170,7 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
       if (isEffect(logic)) {
         const effect = carriedEffectOf(name, path, route, logic.effect);
         if (effect.placement === "sandbox") effects.set(JSON.stringify([route, name]), effect);
+        if (logic.effect.kind === "command" && logic.effect.cut) cuts.add(name);
         continue;
       }
       const child = asMachine(logic);
@@ -1112,7 +1190,9 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
     if (composesSandbox(machine)) {
       const models = new Set<string>();
       const effects = new Map<string, CarriedEffect>();
-      modelsIn(machine, models, new Set(), effects, path, route);
+      const cuts = new Set<string>();
+      const mcp: NonNullable<WorkspacePod["mcp"]> = [];
+      modelsIn(machine, models, new Set(), effects, cuts, mcp, path, route);
       const parts = sandboxPartsOf(machine);
       const bindings: Record<string, string | undefined> = {};
       if (parts.repos !== open) {
@@ -1127,6 +1207,8 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
         secrets: [...(parts.secrets ?? [])],
         models: [...models].sort(),
         effects: [...effects.values()],
+        ...(cuts.size ? { cuts: [...cuts] } : {}),
+        ...(mcp.length ? { mcp } : {}),
         ...(parts.effector ? { effector: { ...parts.effector } } : {}),
         ...(parts.image !== undefined ? { image: parts.image } : {}),
         bindings,
@@ -1145,6 +1227,14 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
   return pods;
 }
 
+/** The read of a Gate slot's bound look, when it is an Effect (ADR-0011); undefined otherwise. */
+function lookReadOf(logic: unknown): EffectSlot | undefined {
+  if (!isGateSlot(logic)) return undefined;
+  const look = logic.gateSlot.look;
+  if (typeof look !== "object" || look === null) return undefined;
+  return isEffect(look.read) ? look.read : undefined;
+}
+
 /** Every state of `machine`'s own tree that invokes a `fail()` slot (ADR-0073), in document order,
  * with the slot key: a state that can fail the run. A child Machine's states are its own walk's. */
 export function failingStatesOf(machine: AnyStateMachine): Array<{ state: string; slot: string }> {

package/src/party.ts

@@ -19,6 +19,7 @@
 import type { AnyActorRef, AnyEventObject, AnyMachineSnapshot, AnyStateMachine } from "xstate";
 import { SENDER_KEY, type Sender } from "@jr2/agent-protocol";
 import { isAgent } from "./agent.ts";
+import { isGateInvoke } from "./gate-brand.ts";
 import { vocabularyOf } from "./vocabulary.ts";
 
 /** The guard type `sentBy` names: dotted, so no author guard can take the name. */
@@ -138,7 +139,7 @@ export function partiesAt(node: Node, machine: AnyStateMachine): Sender[] {
   const out: Sender[] = [];
   for (const inv of node.invoke) {
     if (typeof inv.src !== "string") continue;
-    if (inv.src === "gate") out.push({ party: "gate", id: inv.id });
+    if (isGateInvoke(inv, actors)) out.push({ party: "gate", id: inv.id });
     else if (isAgent(actors[inv.src])) out.push({ party: "agent", id: inv.src });
   }
   return out;
@@ -422,6 +423,39 @@ function orthogonal(a: Node, b: Node): boolean {
 /** Can the two states be active at the same time? */
 const together = (a: Node, b: Node): boolean => isAncestorOrSelf(a, b) || isAncestorOrSelf(b, a) || orthogonal(a, b);
 
+/**
+ * Refuse one Agent slot invoked by two states that can be active together (ADR-0015): in two
+ * parallel regions, one state inside the other, or twice by one state. A slot is one Agent of this
+ * Machine: its Turns share one sender, so `sentBy` cannot tell them apart and one pick matches both
+ * writings, and they share one conversation, so `continue` cannot hold two. Two Agents at once are
+ * two slots (one definition can fill both), a child Machine in each region, or a Pool (ADR-0075).
+ */
+export function refuseSlotActiveTwice(machine: AnyStateMachine): void {
+  const bySlot = new Map<string, Node[]>();
+  for (const node of allNodes(machine))
+    for (const p of partiesAt(node, machine))
+      if (p.party === "agent") bySlot.set(p.id, [...(bySlot.get(p.id) ?? []), node]);
+  for (const [slot, nodes] of bySlot) {
+    for (let i = 0; i < nodes.length; i++) {
+      for (let j = i + 1; j < nodes.length; j++) {
+        const [a, b] = [nodes[i]!, nodes[j]!];
+        if (!together(a, b)) continue;
+        const how =
+          a === b
+            ? `state "${a.id}" invokes it twice`
+            : `"${a.id}" and "${b.id}" invoke it and can be active together ` +
+              (orthogonal(a, b) ? "(parallel regions)" : "(one inside the other)");
+        throw new Error(
+          `machine "${machine.id}": Agent "${slot}" would run two Turns at once: ${how}. A slot is one Agent, with ` +
+            "one sender and one conversation, so `sentBy` cannot tell its two Turns apart and `continue` cannot " +
+            "hold both. For two Agents at once, use two slots (one definition can fill both), a child Machine in " +
+            "each region, or a Pool (ADR-0075)",
+        );
+      }
+    }
+  }
+}
+
 /** One writing: one `on` key on one state, with its candidates (an array writing has several). */
 type Writing = { node: Node; name: string; candidates: Transition[] };
 

package/src/pick.ts

@@ -63,9 +63,11 @@ import type { PickAnswer } from "./wire.ts";
  *   command,
  *   defineEvent,
  *   fail,
+ *   isReady,
  *   jr2Setup,
  *   paramsOf,
  *   workspace,
+ *   worktree,
  *   type Workspaced,
  * } from "@jr2/orchestrator";
  *
@@ -83,6 +85,8 @@ import type { PickAnswer } from "./wire.ts";
  *
  * 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: [runTest, finished],
@@ -91,6 +95,7 @@ import type { PickAnswer } from "./wire.ts";
  *       model: "anthropic/claude-haiku-5-5",
  *       instructions: "You are a careful engineer.",
  *     }),
+ *     cut: worktree(),
  *     test: command(["node", "--test", arg("file")]),
  *     fail: fail(),
  *   },
@@ -98,12 +103,22 @@ import type { PickAnswer } from "./wire.ts";
  *   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. Run the tests of one module at a time." },
+ *         input: ({ context }) => ({
+ *           prompt: "Make the tests pass. Run the tests of one module at a time.",
+ *           cwd: fixTree(context),
+ *         }),
  *       },
  *       on: { finished: "done" },
  *       initial: "ready",
@@ -113,13 +128,17 @@ import type { PickAnswer } from "./wire.ts";
  *           invoke: {
  *             src: "test",
  *             // A plain mapper: the Machine makes the file name from the pick's `module`.
- *             input: ({ event }) => ({ file: `test/${paramsOf(event, runTest).module}.test.js` }),
+ *             input: ({ context, event }) => ({
+ *               file: `test/${paramsOf(event, runTest).module}.test.js`,
+ *               worktree: fixTree(context),
+ *             }),
  *             onDone: "ready",
  *           },
  *         },
  *       },
  *     },
  *     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 +146,6 @@ import type { PickAnswer } from "./wire.ts";
  *
  * export const machine = workspace(body, {
  *   repos: { app: { url: "https://github.com/you/app.git" } },
- *   spec: () => ({ branch: "fix-tests" }),
  * });
  * ```
  *
@@ -406,8 +424,8 @@ export function fromPick<N extends string, I extends z.ZodObject, C, E extends E
 }
 
 /**
- * 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.
  */
@@ -640,8 +658,10 @@ export const isAnswer = (action: unknown): boolean =>
  *   command,
  *   defineEvent,
  *   fail,
+ *   isReady,
  *   jr2Setup,
  *   workspace,
+ *   worktree,
  *   type Workspaced,
  * } from "@jr2/orchestrator";
  *
@@ -659,6 +679,8 @@ export const isAnswer = (action: unknown): boolean =>
  *
  * 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],
@@ -667,6 +689,7 @@ export const isAnswer = (action: unknown): boolean =>
  *       model: "anthropic/claude-haiku-5-5",
  *       instructions: "You are a careful engineer.",
  *     }),
+ *     cut: worktree(),
  *     tests: command(["npm", "test"]),
  *     fail: fail(),
  *   },
@@ -674,10 +697,20 @@ export const isAnswer = (action: unknown): boolean =>
  *   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: {
@@ -685,6 +718,7 @@ export const isAnswer = (action: unknown): boolean =>
  *         testing: {
  *           invoke: {
  *             src: "tests",
+ *             input: ({ context }) => ({ worktree: fixTree(context) }),
  *             onDone: {
  *               target: "ready",
  *               // The Agent reads this string, not the whole output of the command.
@@ -699,6 +733,7 @@ export const isAnswer = (action: unknown): boolean =>
  *       },
  *     },
  *     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" } } },
  *   },
@@ -706,7 +741,6 @@ export const isAnswer = (action: unknown): boolean =>
  *
  * export const machine = workspace(body, {
  *   repos: { app: { url: "https://github.com/you/app.git" } },
- *   spec: () => ({ branch: "fix-tests" }),
  * });
  * ```
  *