@jr2/orchestrator 0.4.1 → 0.6.0

package/src/open.ts

@@ -5,13 +5,97 @@
 // and a `workspace()`'s Repo Slots (parts.ts, which already imports agent.ts). A module with
 // nothing but the sentinel in it is what lets both import it and neither import the other.
 
+// `Symbol.for`, so an Instance's own copy of this module and the CLI's walk agree on it — a
+// packaged Machine may be built against one and walked by the other.
 /**
- * Open (GLOSSARY.md, ADR-0054): this part is a composer's to bind, with `customize()` — a Repo
- * Slot with no url, an Agent with no model. The shape a packaged Machine ships in, because a
- * package cannot know the repository or pay for the model. `jr2 up` refuses an Open part nobody
- * bound and names the line that binds it; a run never sees one.
+ * Leave a part of a Machine Open: for the Instance that registers the Machine to bind with
+ * `customize()`. Write it where a value goes, in a Machine that you publish as a package, for a
+ * part that the package cannot know or pay for:
+ * - a Repo Slot: `repos: { app: open }`, or the whole map: `repos: open`;
+ * - an Agent's model: `agent({ model: open, … })`;
+ * - an Effect's url or argv: `http({ url: open, … })`, `command(open)`;
+ * - the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`.
  *
- * `Symbol.for`, so an Instance's own copy of this module and the CLI's walk agree on it — a
- * packaged Machine may be built against one and walked by the other.
+ * `jr2 up` refuses a Workflow with an Open part that nobody bound, and prints the `customize()`
+ * line that binds it: ``refusing: workflow "<name>" leaves <part> open — bind it where the Machine
+ * is registered: export const machine = customize(<import>, …)  (<adr>)``. A run never sees an
+ * Open part.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   agent,
+ *   customize,
+ *   defineEvent,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   open,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
+ *
+ * const finish = defineEvent({
+ *   name: "finish",
+ *   description: "Call this when `node --test` passes.",
+ *   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." }),
+ *     cut: worktree(),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "fix",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+ *   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: ({ 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" } } },
+ *   },
+ * });
+ *
+ * // What a package exports: the repository and the model are Open.
+ * export const fix = workspace(body, {
+ *   repos: { app: open },
+ * });
+ *
+ * // What an Instance's `workflows/fix.ts` exports: the same Machine, its Open parts bound.
+ * export const machine = customize(fix, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ * });
+ * ```
+ *
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/concepts/composition.md
+ * @see docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
  */
 export const open: unique symbol = Symbol.for("jr2.open");

package/src/parts.ts

@@ -51,10 +51,15 @@ import type { AnyActorRef, AnyStateMachine, StateNode, UnknownActorLogic } from
 import { isAgent, isOpenAgent, type AgentDeclaration } from "./agent.ts";
 import { argvText, isEffect, placementOf, type EffectParts, type Placement } from "./effect.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";
 
 // --- Repo Slots (ADR-0051) ---------------------------------------------------------------------
@@ -71,15 +76,102 @@ import { userSeatOf, type Size, type UserContainer } from "./size.ts";
 // meets it first, and `import { open } from "@jr2/orchestrator"` is the only spelling anyone writes.
 export { open } from "./open.ts";
 
-/** What a Repo Slot resolves to (GLOSSARY.md "Binding"): the url, and the base the branch
- * Worktree is cut from — absent, the Repo's own default branch. */
-export type Binding = { url: string; ref?: string };
+/**
+ * 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
+ *   is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the
+ *   door (ADR-0051).``
+ * - an empty `ref`: the same text, with `bound with an empty ref` in place of `bound to an empty
+ *   url`.
+ * - a url that names no Repo, such as a relative path: ``<where>: Repo Slot "<slot>" binds
+ *   "<url>", which names no Repo — <reason> (ADR-0051).``
+ *
+ * @example
+ * ```ts
+ * import { jr2Setup, workspace, type Binding } from "@jr2/orchestrator";
+ *
+ * const app: Binding = { url: "https://github.com/you/app.git", ref: "release-2" };
+ *
+ * const body = jr2Setup().createMachine({
+ *   id: "body",
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   repos: { app },
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
+ */
+// What a Repo Slot resolves to (GLOSSARY.md "Binding").
+export type Binding = {
+  /** The Repo's git url. */
+  url: string;
+  /** 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;
+};
 
+// Bound and open are what `jr2 up` can see; per-run is the run's business, fenced at attach by
+// `git.credentials` (ADR-0051).
 /**
- * One Repo Slot's value: BOUND (a url, or `{ url, ref? }`), OPEN (the {@link open} sentinel —
- * someone downstream binds it), or PER-RUN (a mapper over the wrapper's door, so a run input — a
- * ticket field — decides). Bound and open are what `jr2 up` can see; per-run is the run's business,
- * fenced at attach by `git.credentials` (ADR-0051).
+ * The value of one Repo Slot in `workspace({ repos })`. One of:
+ * - a url, or a {@link Binding} `{ url, ref }`: the Machine names the Repo.
+ * - {@link open}: the Instance that registers the Machine binds it with `customize()`. `jr2 up`
+ *   refuses a Workflow that leaves it open: ``refusing: workflow "<name>" leaves Repo Slot
+ *   "<slot>" open — bind it where the Machine is registered: export const machine =
+ *   customize(<import>, …)  (ADR-0051)``, with the whole `customize` line to paste.
+ * - 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, 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).``
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { jr2Setup, open, workspace, type RepoSlot, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ service: z.string() });
+ * type RunInput = z.infer<typeof runInput>;
+ *
+ * const service: RepoSlot<RunInput> = ({ input }) => `https://github.com/you/${input.service}.git`;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: Workspaced<RunInput, "service" | "docs" | "config"> },
+ * }).createMachine({
+ *   id: "body",
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ * });
+ *
+ * // A Machine for a package: the Instance that registers it binds `config`.
+ * export const deploy = workspace(body, {
+ *   input: runInput,
+ *   repos: {
+ *     service,
+ *     docs: "https://github.com/you/docs.git",
+ *     config: open,
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/guides/give-the-cluster-git-credentials.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
  */
 export type RepoSlot<TInput = unknown> =
   | typeof open
@@ -104,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()`).
@@ -118,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;
@@ -151,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. */
@@ -167,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[];
@@ -199,8 +293,8 @@ export function sandboxPartsOf(machine: AnyStateMachine | undefined): SandboxPar
 
 /** Does this Machine COMPOSE a Sandbox — i.e. is it a `workspace()` wrapper? Distinct from
  * `sandboxPartsOf(m)` naming no image: a wrapper that names neither image still owns the two
- * seats, which is what `customize({ image })` retunes (ADR-0049) — and it always carries at least
- * one Repo Slot (ADR-0051). Also the data-plane switch, read off the walk: an Instance needs
+ * seats, which is what `customize({ image })` retunes (ADR-0049) — and it may carry no Repo Slot
+ * at all (ADR-0051). Also the data-plane switch, read off the walk: an Instance needs
  * Sandboxes exactly when a registered Machine composes one. A logic with no `config` (an Effect's,
  * ADR-0067) composes none. */
 export function composesSandbox(machine: AnyStateMachine): boolean {
@@ -470,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";
@@ -486,17 +581,39 @@ 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
+     * waits, and — toward another Orchestrator — the target's origin as an http target and its
+     * token as the one secret (placed in the Instance Effector beside the http Effects). No target:
+     * it runs in the Orchestrator's own process and names no secret. `input`: the slot's input
+     * schema as JSON Schema, what the walk compares with the callee's door; absent, the door alone
+     * checks. An Open target has no target and no secret yet. */
+    | {
+        kind: "dispatch";
+        workflow: string;
+        wait: boolean;
+        target?: { scheme: "http" | "https"; host: string; port: number };
+        secrets: string[];
+        input?: Record<string, unknown>;
+        open?: Array<"target">;
+      }
   );
 
+/** One state that can fail the run (ADR-0073): it invokes a `fail()` slot. `state` is the state's
+ * id, `machine` the id of its Machine, `slot` the slot key it invokes, and `path` the `customize()`
+ * route to its Machine, as an {@link OpenSlot}'s. Static, as a Gate or an Effect is: the walk reads
+ * it, and `jr2 up`, `jr2 check` and the Machine doc list it. */
+export type CarriedFailure = { machine: string; state: string; slot: string; path: OpenSlot["path"] };
+
 /** Everything the registered Machines carry that a converge or a boot must act on. */
 export type CarriedParts = {
   agents: CarriedAgent[];
+  /** Every state that invokes a `fail()` slot (ADR-0073), in walk order, nested Machines too. */
+  failures: CarriedFailure[];
   /** Every Effect slot, in walk order — one per Machine and slot key, at the first route the walk
    * reached its Machine by. The placement reads {@link placedEffectsOf}: one per route. */
   effects: CarriedEffect[];
@@ -556,17 +673,18 @@ function inlineMachines(node: StateNode<any, any>): Array<{ machine: AnyStateMac
 }
 
 /**
- * Refuse a Part written inline on an `invoke.src` — an `agent()`, an Effect or a `workspace()` that
+ * Refuse a Part written inline on an `invoke.src` — an `agent()`, an Effect, a `fail()` or a `workspace()` that
  * is no key of the Machine's `actors` (see the module comment). Thrown at build by
  * `jr2Setup.createMachine` and at load by {@link partsOf}, so a Machine built with xstate's own
- * `createMachine` is refused where `jr2 up` and the Orchestrator read it. A plain child Machine
- * written inline is not a Part: it stays walked, with no `customize()` route (its `path` is
- * `undefined`).
+ * `createMachine` is refused where `jr2 check`, `jr2 up` and the Orchestrator read it. A plain
+ * child Machine written inline is not a Part: it stays walked, with no `customize()` route (its
+ * `path` is `undefined`).
  */
 export function refuseInlineParts(machine: AnyStateMachine): void {
   const partOf = (src: unknown): { part: string; written: string } | undefined => {
     if (isAgent(src)) return { part: "an Agent", written: "agent(...)" };
     if (isEffect(src)) return { part: "an Effect", written: `${src.effect.kind}(...)` };
+    if (isFailSlot(src)) return { part: "a fail() Part", written: "fail()" };
     const child = asMachine(src);
     if (child && composesSandbox(child)) return { part: "a Workspace", written: "workspace(...)" };
     return undefined;
@@ -615,6 +733,7 @@ function canonical(value: unknown): string {
  */
 export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const agents: CarriedAgent[] = [];
+  const failures: CarriedFailure[] = [];
   const effects: CarriedEffect[] = [];
   const images: CarriedImage[] = [];
   const repos: CarriedRepo[] = [];
@@ -690,6 +809,11 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     if (walked.has(machine)) return;
     walked.add(machine);
     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);
@@ -706,6 +830,7 @@ 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)) {
@@ -735,6 +860,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   for (const body of noneBodies) for (const m of body.declaration.allows.models) harnessModels.add(m);
   return {
     agents,
+    failures,
     effects,
     images,
     repos,
@@ -817,6 +943,23 @@ export function carriedEffectOf(
 ): CarriedEffect {
   const placement = placementOf(parts);
   const openParts = openPartsOf(parts);
+  if (parts.kind === "dispatch") {
+    const input = (parts as { [DISPATCH_INPUT]?: Record<string, unknown> })[DISPATCH_INPUT];
+    return {
+      name,
+      path,
+      route,
+      kind: "dispatch",
+      placement,
+      workflow: parts.workflow,
+      wait: parts.wait,
+      timeoutMs: parts.timeoutMs,
+      ...(parts.target === undefined || parts.target === open ? {} : { target: originTarget(parts.target.url) }),
+      secrets: [...parts.secrets],
+      ...(input !== undefined ? { input } : {}),
+      ...(openParts.length ? { open: openParts as Array<"target"> } : {}),
+    };
+  }
   if (parts.kind === "http") {
     return {
       name,
@@ -831,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") {
@@ -851,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,
@@ -860,13 +1002,27 @@ 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 } } : {}),
   };
 }
 
+/** The key a dispatch's slot schema rides its parts under (dispatch-effect.ts): `Symbol.for`, so this
+ * walk reads it off a Machine built by another copy of the module (ADR-0071). */
+const DISPATCH_INPUT = Symbol.for("jr2.dispatch.input");
+
+/** A dispatch target's origin as the Effector's fence reads an http target: scheme, host, port. The
+ * origin was checked when the slot was built, so it parses. */
+function originTarget(url: string): { scheme: "http" | "https"; host: string; port: number } {
+  const u = new URL(url);
+  const scheme = u.protocol === "http:" ? "http" : "https";
+  // As an http target's: brackets off an IPv6 literal, lower case (http-effect.ts `targetOf`).
+  const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  return { scheme, host, port: u.port ? Number(u.port) : scheme === "http" ? 80 : 443 };
+}
+
 /**
  * One Workspace a Machine composes, as its pod's Held secrets are placed (ADR-0059): what the pod
  * names. Located like a {@link CarriedSize} — `path` is the `customize()` route to its
@@ -888,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`,
@@ -896,6 +1055,9 @@ export type WorkspacePod = {
   /** Each Repo Slot's Binding url as the Machine binds it, by slot, in order; undefined for an open
    * or per-run slot, whose url `jr2 up` cannot read. A push resolves its credential through it. */
   bindings: Record<string, string | undefined>;
+  /** The `workspace()` declares no Repo Slot (ADR-0051): it has only `/work`, which its steps
+   * share. Absent for one with slots, and for an Open map, whose slots the composer names. */
+  noSlot?: true;
 };
 
 /**
@@ -913,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 => {
@@ -920,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)) {
@@ -939,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);
@@ -958,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) {
@@ -973,9 +1138,11 @@ 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,
+        ...(parts.repos !== open && Object.keys(parts.repos).length === 0 ? { noSlot: true as const } : {}),
       });
     }
     const body = wrapperBodyOf(machine);
@@ -990,6 +1157,22 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
   return pods;
 }
 
+/** 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 }> {
+  const actors = machine.implementations.actors as Record<string, unknown>;
+  const out: Array<{ state: string; slot: string }> = [];
+  const visit = (node: StateNode<any, any>): void => {
+    for (const inv of node.invoke) {
+      if (typeof inv.src === "string" && isFailSlot(actors[inv.src])) out.push({ state: node.id, slot: inv.src });
+    }
+    const children = Object.values(node.states as Record<string, StateNode<any, any>>);
+    for (const child of children.sort((a, b) => a.order - b.order)) visit(child);
+  };
+  visit(machine.root);
+  return out;
+}
+
 /** Every machine object written inline below `node`, at any depth of its state tree, with its hop. */
 function walkStates(node: StateNode<any, any>, visit: (machine: AnyStateMachine, hop: RouteHop) => void): void {
   for (const { machine, hop } of inlineMachines(node)) visit(machine, hop);