@jr2/orchestrator 0.5.1 → 0.6.0

package/src/open-body.ts

@@ -24,6 +24,7 @@ import {
   type UnknownActorLogic,
 } from "xstate";
 import { isAgent, type AgentDefinition, type WorkspaceAccess } from "./agent.ts";
+import { ambientHandlesFor } from "./ambient.ts";
 import {
   admitChart,
   chartDigest,
@@ -31,8 +32,10 @@ import {
   ChartRefusal,
   GENERIC_ACTIONS,
   pathSegments,
+  READY_GUARD,
   resolveSource,
   resolveReferences,
+  slotFolderFault,
   type AdmittedChart,
   type ChartAction,
   type ChartGuard,
@@ -43,11 +46,12 @@ import {
   type ChartTransition,
   type ChartTransitions,
 } from "./chart.ts";
-import { inputKeysOf, isEffect, type Duration } from "./effect.ts";
+import { inputShapeOf, isEffect, type Duration, type InputShape } from "./effect.ts";
 import { fail, FAILURE_GUARD, failureGuard } from "./fail.ts";
 import { agent } from "./harness-client.ts";
 import { SENT_BY } from "./party.ts";
-import { wrapperBodyOf } from "./parts.ts";
+import { composesSandbox, sandboxPartsOf, wrapperBodyOf } from "./parts.ts";
+import { open } from "./open.ts";
 import { actorPath, boundRun } from "./registration.ts";
 import { COMPILED_CHART, jr2Setup } from "./setup.ts";
 import { attachBoundMachine, boundMachineFor } from "./vocabulary.ts";
@@ -573,9 +577,12 @@ export function admitBodyChart(
   text: unknown,
   decl: OpenBodyDeclaration,
   lent: LentParts,
-  options: { inputKeys?: readonly string[] } = {},
+  options: { inputKeys?: readonly string[]; repoSlots?: readonly string[] } = {},
 ): AdmittedChart {
-  const admitted = admitChart(text, decl, lent, options.inputKeys ? { inputKeys: options.inputKeys } : {});
+  const admitted = admitChart(text, decl, lent, {
+    ...(options.inputKeys ? { inputKeys: options.inputKeys } : {}),
+    ...(options.repoSlots ? { repoSlots: options.repoSlots } : {}),
+  });
   try {
     compileChart(admitted, lent, decl);
   } catch (err) {
@@ -627,11 +634,23 @@ export function admitOpenBodyChart(
   const logic = (inner.implementations.actors as Record<string, unknown>)[slot];
   if (!isOpenBody(logic)) throw new Error(`machine "${machine.id}" has no Open body "${slot}"`);
   const decl = openBodyDeclarationOf(logic);
+  const repoSlots = repoSlotsAround(machine);
   return admitBodyChart(text, decl, lentIn(inner.implementations as Implementations, decl), {
     ...(inputKeys ? { inputKeys } : {}),
+    ...(repoSlots ? { repoSlots } : {}),
   });
 }
 
+/** The Repo Slots of the `workspace()` around a Chart wrapper, where the door can see one: the
+ * wrapper IS the `workspace()`. Undefined: an Open map, or a Workspace that a parent state invokes,
+ * whose slots this door cannot read. Then the Open body's own door reads them off the running
+ * Workspace, and a Turn's or an Effect's start refuses what no door could see. */
+export function repoSlotsAround(machine: AnyStateMachine): readonly string[] | undefined {
+  if (!composesSandbox(machine)) return undefined;
+  const { repos } = sandboxPartsOf(machine);
+  return repos === open ? undefined : Object.keys(repos);
+}
+
 /**
  * Admit a Chart field of a Chart wrapper's door (ADR-0070), the door a run's start runs before the
  * run exists. The door cannot tell which Open body a field feeds, so the Chart is admitted against
@@ -648,7 +667,10 @@ export function admitWrapperChart(machine: AnyStateMachine, text: unknown): Admi
   for (const { slot, logic } of bodies) {
     const decl = openBodyDeclarationOf(logic);
     try {
-      return admitBodyChart(text, decl, lentIn(inner.implementations as Implementations, decl));
+      const repoSlots = repoSlotsAround(machine);
+      return admitBodyChart(text, decl, lentIn(inner.implementations as Implementations, decl), {
+        ...(repoSlots ? { repoSlots } : {}),
+      });
     } catch (err) {
       if (!(err instanceof ChartRefusal)) throw err;
       report.push(...err.report.map((line) => (bodies.length > 1 ? `body "${slot}": ${line}` : line)));
@@ -675,7 +697,7 @@ const scopeOf = (args: Args) => ({
   input: chartInputOf((args.context?.[CHART_INPUT_KEY] as Record<string, unknown> | undefined) ?? {}),
 });
 
-/** An invoke's error whose message jr2 wrote for a Chart to read: a lent Effect's input fault. */
+/** An invoke's error whose message jr2 wrote for a Chart to read: a fault in an input the door could not see. */
 class ChartInvokeFault extends Error {}
 
 /**
@@ -839,6 +861,10 @@ function transitionsOf(ts: ChartTransitions): unknown {
   return Array.isArray(ts) ? ts.map(transitionOf) : transitionOf(ts);
 }
 
+/** `jr2.ready`: is this cut's output `ready`? On an `onDone`. */
+const readyGuard = ({ event }: { event: unknown }): boolean =>
+  (event as { output?: { outcome?: unknown } } | undefined)?.output?.outcome === "ready";
+
 const mapValues = <T, U>(o: Record<string, T>, fn: (v: T) => U): Record<string, U> =>
   Object.fromEntries(Object.entries(o).map(([k, v]) => [k, fn(v)]));
 
@@ -847,15 +873,17 @@ const mapValues = <T, U>(o: Record<string, T>, fn: (v: T) => U): Record<string,
  * resolved object again at invoke time"), or undefined when it is. The door checked the literal
  * parts; a reference may still resolve to a value that is no string.
  */
-function effectInputFault(keys: readonly string[], value: unknown): string | undefined {
+function effectInputFault(shape: InputShape, value: unknown): string | undefined {
   const given = typeof value === "object" && value !== null && !Array.isArray(value) ? Object.keys(value) : undefined;
+  const known = [...shape.required, ...shape.optional, ...(shape.oneOf ?? [])];
   const ok =
     given !== undefined &&
-    given.length === keys.length &&
-    keys.every((k) => typeof (value as Record<string, unknown>)[k] === "string");
+    shape.required.every((k) => given.includes(k)) &&
+    given.every((k) => known.includes(k) && typeof (value as Record<string, unknown>)[k] === "string") &&
+    (shape.oneOf === undefined || shape.oneOf.filter((k) => given.includes(k)).length === 1);
   return ok
     ? undefined
-    : `its input resolved to ${JSON.stringify(value)}; it takes exactly ${keys.join(", ") || "nothing"}, each a string (ADR-0070)`;
+    : `its input resolved to ${JSON.stringify(value)}; it takes ${known.join(", ") || "nothing"}, each a string (ADR-0070)`;
 }
 
 const checkedEffects = new WeakMap<object, UnknownActorLogic>();
@@ -867,13 +895,15 @@ const checkedEffects = new WeakMap<object, UnknownActorLogic>();
  */
 function checkedEffect(slot: string, logic: UnknownActorLogic): UnknownActorLogic {
   if (!isEffect(logic)) return logic;
-  const keys = inputKeysOf(logic.effect);
-  if (keys === undefined) return logic;
+  const shape = inputShapeOf(logic.effect);
+  if (shape === undefined) return logic;
   const hit = checkedEffects.get(logic);
   if (hit) return hit;
   const checked = Object.create(logic) as UnknownActorLogic;
   checked.getInitialSnapshot = (scope, input) => {
-    const fault = effectInputFault(keys, input);
+    // An Effect that takes nothing, invoked with no input, is a whole input: the door let it through.
+    const fault =
+      input === undefined && shape.required.length === 0 && !shape.oneOf ? undefined : effectInputFault(shape, input);
     if (fault === undefined) return logic.getInitialSnapshot(scope, input);
     return {
       status: "error",
@@ -885,9 +915,38 @@ function checkedEffect(slot: string, logic: UnknownActorLogic): UnknownActorLogi
   return checked;
 }
 
-/** The lent actors as a Chart invokes them: each Effect checked at its start (see {@link checkedEffect}). */
+const checkedAgents = new WeakMap<object, UnknownActorLogic>();
+
+/**
+ * An Agent as a Chart invokes it: the Agent itself, whose start refuses a resolved `cwd` that is a
+ * Repo Slot's folder. A reference hides that value from the door. The check is in `start`, because
+ * the Workspace's handles are registered at a start, and a Chart's first invoke resolves before
+ * that. The refusal is THAT invoke's error, as in {@link checkedEffect}.
+ */
+function checkedAgent(slot: string, logic: UnknownActorLogic): UnknownActorLogic {
+  const hit = checkedAgents.get(logic);
+  if (hit) return hit;
+  const checked = Object.create(logic) as UnknownActorLogic;
+  checked.start = (snapshot, scope) => {
+    const cwd = ((snapshot as { input?: unknown }).input as { cwd?: unknown } | undefined)?.cwd;
+    const reads = (logic as { definition?: { workspace?: unknown } }).definition?.workspace !== "none";
+    const repos = reads && typeof cwd === "string" ? ambientHandlesFor(scope.self)?.repos : undefined;
+    const fault = repos ? slotFolderFault(cwd as string, Object.keys(repos)) : undefined;
+    if (fault !== undefined) throw new ChartInvokeFault(`the Agent "${slot}": ${fault}`);
+    logic.start?.(snapshot, scope);
+  };
+  checkedAgents.set(logic, checked);
+  return checked;
+}
+
+/** The lent actors as a Chart invokes them: each Effect and Agent checked at its start. */
 function chartActors(actors: Record<string, UnknownActorLogic>): Record<string, UnknownActorLogic> {
-  return Object.fromEntries(Object.entries(actors).map(([slot, logic]) => [slot, checkedEffect(slot, logic)]));
+  return Object.fromEntries(
+    Object.entries(actors).map(([slot, logic]) => [
+      slot,
+      isAgent(logic) ? checkedAgent(slot, logic) : checkedEffect(slot, logic),
+    ]),
+  );
 }
 
 /** An Agent Turn's input with `prompt` and `cwd` as strings: a whole placeholder may resolve to
@@ -964,7 +1023,7 @@ export type CompileOptions = OpenBodyOptions & {
 /**
  * Build the Machine a Chart describes (ADR-0070), with `jr2Setup` over: the lent actors by their
  * slot names, `agent(def)` for each Agent the Chart mints, the kit's `gate`, and `fail()` where the
- * body lends it; the lent guards, `jr2.sentBy` and `jr2.failure`; the lent actions and the four
+ * body lends it; the lent guards, `jr2.sentBy`, `jr2.failure` and `jr2.ready`; the lent actions and the four
  * generic ones; the lent delays. Every reference resolves at invoke time, so the Machine holds the
  * text's shape and no run's data. The Chart's
  * input is the context key {@link CHART_INPUT_KEY}; a done Chart outputs `{ outcome: "done",
@@ -984,7 +1043,7 @@ export function compileChart(
   const mint = options.mintAgent ?? ((_slot: string, definition: AgentDefinition) => agent(definition));
   const minted = mapValues(admitted.agents, (def) => def);
   const actors: Record<string, UnknownActorLogic> = chartActors(lent.actors);
-  for (const [slot, def] of Object.entries(minted)) actors[slot] = mint(slot, def);
+  for (const [slot, def] of Object.entries(minted)) actors[slot] = checkedAgent(slot, mint(slot, def));
   // The kit's Part that fails the run, where the body lends it (ADR-0073): no slot of the wrapper's.
   if (decl.lends.fail === true) actors.fail = fail();
   // The slots an invoke runs an Agent Turn in: the lent Agents and the Chart's own.
@@ -1018,7 +1077,11 @@ export function compileChart(
     events: admitted.events,
     actors,
     // `jr2.failure` is in every Chart, as `jr2.sentBy` is: a predicate, with no capability (ADR-0073).
-    guards: { ...(lent.guards as Record<string, unknown>), [FAILURE_GUARD]: failureGuard } as never,
+    guards: {
+      ...(lent.guards as Record<string, unknown>),
+      [FAILURE_GUARD]: failureGuard,
+      [READY_GUARD]: readyGuard,
+    } as never,
     actions: { ...(lent.actions as Record<string, unknown>), ...GENERIC } as never,
     delays: lent.delays as never,
   }).createMachine(config as never) as unknown as AnyStateMachine;
@@ -1382,7 +1445,10 @@ export function openBodyLogic(decl: OpenBodyDeclaration, options: OpenBodyOption
   /** Admit and compile a Chart text, and record the Machine the actor runs. Throws ChartRefusal. */
   const bind = (self: AnyActorRef, text: unknown, inputKeys: readonly string[]) => {
     const lent = liveLentOf(self, logic);
-    const admitted = admitChart(text, decl, lent, { inputKeys });
+    // A Chart that comes after the Workspace started finds its slots here. A Chart in the step that
+    // starts the Workspace comes before them, and the wrapper's door or the Turn's start saw it.
+    const repos = ambientHandlesFor(self)?.repos;
+    const admitted = admitChart(text, decl, lent, { inputKeys, ...(repos ? { repoSlots: Object.keys(repos) } : {}) });
     const src = (self as { src?: unknown }).src;
     const machine = compiledFor(admitted, lent, decl, {
       ...options,

package/src/open.ts

@@ -24,7 +24,18 @@
  * @example
  * ```ts
  * import { z } from "zod";
- * import { agent, customize, defineEvent, fail, jr2Setup, open, workspace } from "@jr2/orchestrator";
+ * import {
+ *   agent,
+ *   customize,
+ *   defineEvent,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   open,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
  *
  * const finish = defineEvent({
  *   name: "finish",
@@ -32,19 +43,40 @@
  *   input: z.object({}),
  * });
  *
+ * 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: [finish],
- *   actors: { coder: agent({ model: open, instructions: "You fix the failing test." }), fail: fail() },
+ *   actors: {
+ *     coder: agent({ model: open, instructions: "You fix the failing 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: "jr2/fix" }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+ *       },
+ *     },
  *     coding: {
- *       invoke: { src: "coder", input: { prompt: "Make `node --test` pass." } },
+ *       invoke: {
+ *         src: "coder",
+ *         input: ({ context }) => ({ prompt: "Make `node --test` pass.", cwd: fixTree(context) }),
+ *       },
  *       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" } } },
  *   },
@@ -53,7 +85,6 @@
  * // What a package exports: the repository and the model are Open.
  * export const fix = workspace(body, {
  *   repos: { app: open },
- *   spec: () => ({ branch: "jr2/fix" }),
  * });
  *
  * // What an Instance's `workflows/fix.ts` exports: the same Machine, its Open parts bound.

package/src/parts.ts

@@ -56,7 +56,9 @@ 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 +77,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 +104,6 @@ export { open } from "./open.ts";
  *
  * export const machine = workspace(body, {
  *   repos: { app },
- *   spec: () => ({ branch: "jr2/hotfix" }),
  * });
  * ```
  *
@@ -113,8 +114,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 +131,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 +165,6 @@ export type Binding = {
  *     docs: "https://github.com/you/docs.git",
  *     config: open,
  *   },
- *   spec: ({ input }) => ({ branch: `deploy/${input.service}` }),
  * });
  * ```
  *
@@ -195,12 +196,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 +211,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 +244,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 +259,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 +564,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 +581,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
@@ -808,6 +811,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);
@@ -968,7 +974,6 @@ 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 === "push") {
@@ -988,7 +993,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 +1002,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 } } : {}),
   };
 }
 
@@ -1039,6 +1044,9 @@ export type WorkspacePod = {
    * 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 +1075,7 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
     models: Set<string>,
     on: Set<AnyStateMachine>,
     effects: Map<string, CarriedEffect>,
+    cuts: Set<string>,
     path: OpenSlot["path"],
     route: PlacementRoute,
   ): void => {
@@ -1074,7 +1083,7 @@ 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, at, to);
     };
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
       if (isAgent(logic)) {
@@ -1093,6 +1102,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 +1122,8 @@ 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>();
+      modelsIn(machine, models, new Set(), effects, cuts, path, route);
       const parts = sandboxPartsOf(machine);
       const bindings: Record<string, string | undefined> = {};
       if (parts.repos !== open) {
@@ -1127,6 +1138,7 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
         secrets: [...(parts.secrets ?? [])],
         models: [...models].sort(),
         effects: [...effects.values()],
+        ...(cuts.size ? { cuts: [...cuts] } : {}),
         ...(parts.effector ? { effector: { ...parts.effector } } : {}),
         ...(parts.image !== undefined ? { image: parts.image } : {}),
         bindings,

package/src/party.ts

@@ -422,6 +422,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[] };