@jr2/orchestrator 0.4.1 → 0.6.0

package/src/workspace.ts

@@ -1,9 +1,10 @@
-// `workspace(body, { input, image, user, repos, resources, spec })` (ADR-0012, ADR-0049, ADR-0051,
-// ADR-0060): the jr2-owned wrapper Machine that owns ONLY Sandbox lifecycle — provision the Sandbox
-// (out of the STATIC `image`/`user`/`repos`/`resources` options it carries) + attach one worktree per Repo Slot, run the
-// author's body Machine inside it as the named slot `body`, with `{ workspace: { repos, branch } }`
-// appended to its input (the mechanism-facing endpoint/sandbox are published ambiently
-// — ADR-0016, ambient.ts), and destroy the Sandbox when the body reaches a final state. Teardown lives INSIDE the
+// `workspace(body, { input, image, user, repos, resources, workGroup })` (ADR-0012, ADR-0049, ADR-0051,
+// ADR-0060, ADR-0075): the jr2-owned wrapper Machine that owns ONLY Sandbox lifecycle — provision the Sandbox
+// (out of the STATIC `image`/`user`/`repos`/`resources` options it carries) + clone each Repo
+// Slot, run the author's body Machine inside it as the named slot `body`, with
+// `{ workspace: { repos } }` appended to its input (the mechanism-facing endpoint/sandbox
+// are published ambiently — ADR-0016, ambient.ts), and destroy the Sandbox when the body reaches a
+// final state or fails (ADR-0073). Teardown lives INSIDE the
 // wrapper's own states because an xstate stop is synchronous — multi-step async cleanup must be
 // states the machine transitions through itself, which forces the thing that provisions to also
 // observe the body's completion (the ADR's load-bearing argument). There is no retain policy: a
@@ -18,7 +19,9 @@
 //
 // The lifecycle (ADR-0012, ADR-0064): `placing` writes the Sandbox and waits, with no deadline,
 // for its pod to be scheduled; `provisioning` waits for Ready under a budget that starts there;
-// `attaching` runs the Harness's attach; `running` runs the body; `teardown` destroys.
+// `attaching` runs the Harness's attach; `running` runs the body; `teardown` destroys. A Failure from
+// the body (ADR-0073) goes to `failing`, which destroys as `teardown` does and then sends the same
+// Failure up; a defect has no `onError` here, so it goes up at once and its Sandbox stays as evidence.
 //
 // Restore-reconcile (ADR-0012, ADR-0021): every state from `placing` to `running` co-invokes the
 // lease, and in `running` the lease judges Continuity from the Orchestrator's watch for its
@@ -41,16 +44,22 @@ import {
 } from "xstate";
 import type { z } from "zod";
 import { registerAmbientHandles, type AmbientHandles } from "./ambient.ts";
+import { isAgent } from "./agent.ts";
+import { isEffect } from "./effect.ts";
+import { failLogic, failurePayload, isFailure, type Failure, type FailureInput } from "./fail.ts";
+import { refuseUnroutedLost } from "./mechanism-routes.ts";
 import {
   actorRoute,
   actorSlotPath,
   assertRepoSlot,
   attachSandboxParts,
   attachWrapperBody,
+  composesSandbox,
   customizeLine,
   open,
   repoSlotState,
   sandboxPartsOf,
+  wrapperBodyOf,
   type Binding,
   type JR2Repos,
   type JR2Wrapper,
@@ -61,7 +70,14 @@ import {
 } from "./parts.ts";
 import { actorPath, runBindingOf, type AnyActorSystem } from "./registration.ts";
 import { assertSize, assertUserSeat, userSeatOf, type Size, type UserContainer } from "./size.ts";
-import { attachInputSchema, inputSchemaOf, invokingMachine, type HostInjectedInput } from "./vocabulary.ts";
+import {
+  attachInputSchema,
+  declaresRunInput,
+  inputSchemaOf,
+  parsedNestedDoor,
+  invokingMachine,
+  type HostInjectedInput,
+} from "./vocabulary.ts";
 
 /** Lease cadence when the backend names none. Well inside the 30m default idle timeout, so a
  * few missed renewals in a row are survivable. It bounds only how long an orphan waits to be
@@ -83,75 +99,170 @@ export function leaseDelay(interval: number, which: "first" | "next", random: nu
   return interval * (1 - LEASE_JITTER + 2 * LEASE_JITTER * random);
 }
 
-/** What to attach, in workspace vocabulary only (ADR-0012 boundary): the one branch the body
- * works on, the pod's work group, and the review sha. Derived PER RUN from the wrapper's input,
- * which is what keeps it out here rather than in the options — and which is exactly why the two
- * IMAGES and the REPOS are NOT here (ADR-0049, ADR-0051): `jr2 up` must find them by walking the
- * Machine, and no walk can evaluate a function of run input. They are static `workspace()`
- * options instead; a Repo that IS a function of run input is a per-run slot, a mapper the walk
- * can see the shape of even though it cannot see the url. */
-export type WorkspaceSpec = {
-  branch: string;
-  /** The pod's work group (ADR-0005): `fsGroup`, default 2000. The two writing seats may run
-   * different uids — each image's own `USER` decides — and POSIX would then make the other seat's
-   * files read-only; fsGroup (group ownership) plus the default ACL the attach stamps on each
-   * repo root (group writability, umask-proof) closes that, both inert when the uids already
-   * match. The override exists for the image whose sessions already hold a gid of their own —
-   * a root sshd's logins rebuild groups from `/etc/group`, so pointing the work group at one
-   * they have costs no rebuild. Never a config key — pod composition is the spec's business. */
-  workGroup?: number;
-  /** Attach the detached review worktree at this sha (ADR-0028): `<branchDir>-review`, a sibling
-   * of the branch worktree, forced to exactly this sha on every attach. Creation-time seat only;
-   * the per-round refresh verb (the sha moves between review rounds) is a later, workflow-driven
-   * change. */
-  reviewSha?: string;
+// What the workspace hands the BODY (ADR-0012, ADR-0016): worktree geography only, keyed by Repo
+// Slot (ADR-0051) — so a path a prompt names is right in every Instance that consumes the Machine.
+// `endpoint` and `sandbox` are mechanism-internal — the Agent actor resolves them ambiently from
+// the enclosing wrapper (ambient.ts), so a workflow can no longer forget to thread them (the
+// baba71f incident: `sandbox` omitted, every tool call 403'd, fail-closed but silent).
+//
+// `TSlots` has NO default on purpose (ADR-0050): a body names the slots it reads, and
+// `workspace()` holds those names to the ones the wrapper declares. A default of `string` would
+// type `repos` as `Record<string, string>`, under which a misspelled slot reads as a path — the
+// silent widening the slot key exists to refuse. `string` WRITTEN is a different statement: the
+// body names no slot at all — it enumerates them, in the order the composer wrote — which is the
+// body under a wrapper that declares its map Open (`repos: open`, ADR-0051), where the slots are
+// the composer's words and no body could name them.
+/**
+ * What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot. A path
+ * is correct in each Instance that registers the Machine.
+ *
+ * `TSlots` is the names of the Repo Slots that the body reads. `workspace()` refuses a body that
+ * names a slot that the Workspace does not have. Write `string` for a body that names no slot and
+ * reads the folders in the order of `repos`, as under `repos: open`. Write `never` for a
+ * Workspace with no Repo Slot: its handles are `{ repos: {} }`, and its Agents work in `/work`.
+ */
+// `[TSlots] extends [never]`, not `TSlots extends never`: a bare `never` would distribute to `never`.
+export type WorkspaceHandles<TSlots extends string> = [TSlots] extends [never]
+  ? { repos: Record<never, string> }
+  : SlotHandles<TSlots>;
+
+/** The handles of a Workspace that declares Repo Slots. @internal */
+type SlotHandles<TSlots extends string> = {
+  /** The folder of each Repo Slot, `/work/<slot>`, in the order that `repos` declares the slots.
+   * `${handle}/default` is the clone, on the Binding's base. Any other Worktree is one the Machine
+   * cut with `worktree()`. */
+  repos: { [K in TSlots]: `/work/${K}` };
 };
 
+// The composition is the whole reason the door is declared on the wrapper and not on the body
+// (ADR-0033): `Workspaced<RunInput, Slot>` is what the body receives, `RunInput` is what a caller
+// may send, and no caller can send `workspace` (the handles do not exist until a Sandbox is
+// provisioned and attached). Naming it here keeps the body from hand-copying
+// {@link WorkspaceHandles}, which drifts. The slot argument is required, never defaulted, so
+// `workspace.repos.<slot>` is typed by the same keys the wrapper declares (ADR-0050, ADR-0051).
+//
+// The wrapper passes its input through UNTOUCHED, so a ROOT-placed wrapper's body also receives
+// what the host injected beside the door — `HostInjectedInput` today (the run's `instanceId`).
+// That is outside this type on purpose: it depends on where the wrapper sits, and `Workspaced` is
+// the composition the WRAPPER makes.
 /**
- * What the workspace hands the BODY (ADR-0012, ADR-0016): worktree geography only, keyed by Repo
- * Slot (ADR-0051) — so a path a prompt names is right in every Instance that consumes the Machine.
- * `endpoint` and `sandbox` are mechanism-internal — the Agent actor resolves them ambiently from
- * the enclosing wrapper (ambient.ts), so a workflow can no longer forget to thread them (the
- * baba71f incident: `sandbox` omitted, every tool call 403'd, fail-closed but silent).
+ * The input of a `workspace()` body: the run input, plus `workspace`, the handles that the
+ * Workspace adds (`workspace.repos`, the folder of each Repo Slot). Use it as the type of
+ * the body's input.
+ *
+ * The first argument is the run input: the `input` schema of the `workspace()`. The second is the
+ * Repo Slots that the body reads, by name (`"app"` or `"app" | "docs"`). Under `repos: open`, write
+ * `string`: the body cannot know the names, so it reads the slots in order. For a `workspace()`
+ * with no `repos`, write `never`. The second argument has no default.
+ *
+ * A body under a root `workspace()` also gets the fields of `HostInjectedInput`. Add them when the
+ * body reads them: `Workspaced<HostInjectedInput & RunInput, "app">`.
+ *
+ * Its fields are the fields of the run input, and `workspace`. The run input can have no fields:
+ * `Workspaced<z.infer<typeof door>, "app">` for the door `z.object({})` holds only `workspace`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   agent,
+ *   defineEvent,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
  *
- * `TSlots` has NO default on purpose (ADR-0050): a body names the slots it reads, and
- * `workspace()` holds those names to the ones the wrapper declares. A default of `string` would
- * type `repos` as `Record<string, string>`, under which a misspelled slot reads as a path — the
- * silent widening the slot key exists to refuse. `string` WRITTEN is a different statement: the
- * body names no slot at all — it enumerates them, in the order the composer wrote — which is the body
- * under a wrapper that declares its map Open (`repos: open`, ADR-0051), where the slots are the
- * composer's words and no body could name them.
+ * const done = defineEvent({
+ *   name: "done",
+ *   description: "Call this when REVIEW.md is written.",
+ *   input: z.object({}),
+ * });
+ * const runInput = z.object({ sha: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+ *
+ * // A handle is the slot's folder: `/work/app`. A helper returns `as const`, so that the compiler
+ * // sees the slot.
+ * const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: BodyInput; context: BodyInput },
+ *   events: [done],
+ *   actors: {
+ *     reviewer: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You review one commit and write REVIEW.md.",
+ *       workspace: "read",
+ *     }),
+ *     cut: worktree(),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "review",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     reviewing: {
+ *       invoke: {
+ *         src: "reviewer",
+ *         input: ({ context }) => ({
+ *           prompt: `Review commit ${context.sha}.`,
+ *           cwd: reviewTree(context),
+ *         }),
+ *       },
+ *       on: { done: "finished" },
+ *     },
+ *     finished: { 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" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   input: runInput,
+ *   repos: { app: "https://github.com/you/app.git" },
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/reference/decisions/0012-workspace-wrapper-machine.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
  */
-export type WorkspaceHandles<TSlots extends string> = {
-  /** Every slot's branch-worktree path: `/work/<slot>/<branch>`, keyed in DECLARATION ORDER. The
-   * kit gives no slot a privileged meaning — there is no `workdir` — because which tree an Agent
-   * works in is a fact about that Agent's Turn, not about the Workspace: a body that names its
-   * slots frames each Agent with its own, and a body that names none may give the order a
-   * meaning of its own (`task`: the first is the one the coder edits). The order is the kit's
-   * promise; the meaning is the Machine's (ADR-0051). */
-  repos: Record<TSlots, string>;
-  branch: string;
-  /** Detached review-worktree paths by slot (ADR-0028) — present only when the spec carried
-   * `reviewSha`. The reviewer's seat: hand one of these as its cwd/prompt frame. */
-  review?: Partial<Record<TSlots, string>>;
+export type Workspaced<TInput, TSlots extends string> = WithoutEmptyIndex<TInput> & {
+  workspace: WorkspaceHandles<TSlots>;
 };
 
+// `z.infer` of a door with no fields, `z.object({})`, is `Record<string, never>`: an index signature
+// that says each key holds `never`. Intersected with the handles, it makes each assign of a body
+// context fail (`n: number` is not `never`) with a diagnostic that does not name the cause. This
+// removes that index signature, and only one whose value is `never`, so the named fields stay
+// (`HostInjectedInput & Record<string, never>` keeps `instanceId: string`) and an input that is a
+// real map (`Record<string, string>`) is not changed. The alternative, a separate type for the empty
+// door, makes the author choose between two names for one statement.
+// It is not `@internal`: the Reference then shows this TSDoc, so a reader of `Workspaced` sees that
+// these are the fields of the run input. As plumbing, its page showed only the declaration.
 /**
- * A body's input under a Workspace: the run input the wrapper passes through, PLUS the handles it
- * injects. The composition is the whole reason the door is declared on the wrapper and not on the
- * body (ADR-0033) — `Workspaced<RunInput, Slot>` is what the body receives, `RunInput` is what a caller
- * may send, and no caller can send `workspace` (the handles do not exist until a Sandbox is
- * provisioned and attached). Naming it here keeps the body from hand-copying
- * {@link WorkspaceHandles}, which drifts. The second argument is the body's word for each Repo
- * Slot it reads (`Workspaced<RunInput, "target">`) — required, never defaulted, so
- * `workspace.repos.<slot>` is typed by the same keys the wrapper declares (ADR-0050, ADR-0051).
- *
- * The wrapper passes its input through UNTOUCHED, so a ROOT-placed wrapper's body also receives
- * what the host injected beside the door — `HostInjectedInput` today (the run's `instanceId`).
- * That is outside this type on purpose: it depends on where the wrapper sits, and `Workspaced` is
- * the composition the WRAPPER makes.
+ * The fields of the run input `T`. A string index signature whose value is `never` is not one of
+ * them: `z.infer` gives `Record<string, never>` for `z.object({})`, and this type makes it `{}`. The
+ * named fields of `T` stay. A different `T` does not change.
  */
-export type Workspaced<TInput, TSlots extends string> = TInput & { workspace: WorkspaceHandles<TSlots> };
+type WithoutEmptyIndex<T> = string extends keyof T
+  ? [T[string & keyof T]] extends [never]
+    ? { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] }
+    : T
+  : T;
 
 /**
  * What the watch says about a workspace (ADR-0021, ADR-0063): gone, or present — and, once the
@@ -190,6 +301,9 @@ export type PlaceRequest = {
   image?: string;
   user?: string;
   workGroup?: number;
+  /** The Held secrets the `workspace()`'s `secrets` list names (ADR-0059): the ones the Harness may
+   * put in a confined child's env, by Stand-in (ADR-0076). Names, never a value. Absent → none. */
+  secrets?: string[];
   repos: ProvisionedRepo[];
   resources?: Size;
   userResources?: Size;
@@ -237,17 +351,12 @@ export interface SandboxPort {
    */
   provision(name: string): Promise<{ endpoint: string }>;
   /** Post-Ready attach (ADR-0004): per slot, `git clone --shared` off the node's read-only
-   * cache (the `default/` checkout), then a branch worktree sibling — and, with `spec.reviewSha`, the detached
-   * review worktree (ADR-0028). Resolves with the worktree paths by slot; `stale` names the slots
-   * whose cache could not be fetched before this attach, with git's own error (ADR-0051: freshness
-   * degrades, absence does not). */
-  attach(req: {
-    name: string;
-    spec: WorkspaceSpec;
-    repos: Array<{ slot: string; url: string; ref?: string }>;
-  }): Promise<{
+   * cache (the `default/` checkout). A Machine cuts each Worktree (ADR-0075). Resolves with the
+   * folder of each slot; `stale` names the slots whose cache could not be fetched before this
+   * attach, with git's own error (ADR-0051: freshness degrades, absence does not). */
+  attach(req: { name: string; repos: Array<{ slot: string; url: string; ref?: string }> }): Promise<{
     repos: Record<string, string>;
-    review?: Record<string, string>;
+    bases?: Record<string, string>;
     stale?: Record<string, string>;
   }>;
   /**
@@ -277,8 +386,10 @@ export interface SandboxPort {
    * `OOMKilled` at or after `since`, the kill — its fault reason, starting with the fixed prefix
    * `memory limit`, and the data the next Turn's notice is made of (ADR-0062) — else undefined.
    * Asked when a Turn faults on a lost conversation; it may wait a moment for the operator's word,
-   * which can trail the Harness's restart. A backend that cannot see the container answers
-   * undefined, and every lost conversation stays lost — never an optional method (ADR-0021).
+   * which can trail the Harness's restart. Asked too before an admission into the Workspace whose
+   * watch shows a last end `OOMKilled`, with `since` that end: a kill while no Turn ran (ADR-0062).
+   * A backend that cannot see the container answers undefined, and every lost conversation stays
+   * lost — never an optional method (ADR-0021).
    */
   memoryFault(name: string, since: Date): Promise<MemoryKill | undefined>;
   /** Delete the Sandbox CR. Absent is success. */
@@ -348,12 +459,11 @@ export type WorkspaceWait = PlacingWait & { since: string };
 export const WORKSPACE_WAIT_KEY = "wait";
 
 type WsContext = {
-  /** The wrapper's own input, passed through to the body untouched (plus `workspace`). */
+  /** The wrapper's input, which the body gets (plus `workspace`). Under a parent, `place` replaces
+   * it with the door's parsed value. */
   runInput: Record<string, unknown>;
   /** This invocation's stable identity (the actor id the parent invoked/spawned us under). */
   wsId: string;
-  /** The resolved spec — computed once from input and persisted, like any other context data. */
-  spec: WorkspaceSpec;
   /** Every slot's resolved Binding, by slot, in declaration order — assigned at provision. */
   bindings?: Record<string, ResolvedBinding>;
   endpoint?: string;
@@ -363,6 +473,9 @@ type WsContext = {
   /** Persisted in context so the registrar can re-publish them on restore. */
   handles?: MechanismHandles;
   output?: unknown;
+  /** The body's Failure (ADR-0073), as plain data: kept while `failing` destroys, so a restore
+   * there sends the same Failure up. */
+  failure?: FailureInput;
 };
 
 /**
@@ -383,12 +496,14 @@ type WsContext = {
  * Repo Slots it carries, because a default would widen exactly where the phantom exists to refuse
  * — `JR2Repos<string>` offers `customize()` every key, and `AnyStateMachine` as the body offers no
  * Agent at all. `PoolMachine` names its worker the same way.
+ *
+ * @internal
  */
 export type WorkspaceMachine<TInput, TOutput, TBody extends AnyStateMachine, TSlots extends string> = StateMachine<
   any,
   any,
   any,
-  WrapperActors<"body", TBody, "place" | "provision" | "attach" | "registrar" | "lease" | "destroy">,
+  WrapperActors<"body", TBody, "place" | "provision" | "attach" | "registrar" | "lease" | "destroy" | "fail">,
   any,
   any,
   any,
@@ -435,8 +550,29 @@ export type WorkspaceMachine<TInput, TOutput, TBody extends AnyStateMachine, TSl
  */
 // The handles are keyed by the wrapper's DECLARED slots (ADR-0051), so a body demanding a slot the
 // wrapper never declared is refused here too; demanding fewer is fine, as with any other field.
+//
+// The provided side holds the raw door AND its `Workspaced` form. `Workspaced` removes the
+// `Record<string, never>` that `z.infer` gives the empty door, so `Workspaced` alone no longer
+// satisfies a body that writes that type itself (`z.infer<typeof door>`, alone or with the
+// handles). The raw door keeps those bodies legal, and the stripped form keeps a body that
+// declares `Workspaced<…>` legal. A key that the door does not carry is still refused.
+/** The input of a door-less Workspace: the body's, without the handles. `unknown` when the body
+ * asks for nothing else, and with `undefined` added when each field it asks for is optional. In
+ * both cases a parent has nothing that it must give, and xstate makes an invoke's `input` optional
+ * only for a type that holds `undefined`.
+ * @internal */
+type DoorlessInput<TBody extends AnyStateMachine> =
+  unknown extends InputFrom<TBody>
+    ? unknown
+    : [keyof Omit<InputFrom<TBody>, "workspace">] extends [never]
+      ? unknown
+      : {} extends Omit<InputFrom<TBody>, "workspace">
+        ? Omit<InputFrom<TBody>, "workspace"> | undefined
+        : Omit<InputFrom<TBody>, "workspace">;
+
+/** @internal */
 type BodyAcceptsDoor<TBody extends AnyStateMachine, TDoor, TSlots extends string> =
-  Workspaced<TDoor, TSlots> & HostInjectedInput extends InputFrom<TBody>
+  TDoor & Workspaced<TDoor, TSlots> & HostInjectedInput extends InputFrom<TBody>
     ? BodyNamesNoSlotUnderOpenMap<TBody, TSlots>
     : { "the body's declared input must accept the door plus the injected handles": Workspaced<TDoor, TSlots> };
 
@@ -467,6 +603,8 @@ type BodyNamesNoSlotUnderOpenMap<TBody extends AnyStateMachine, TSlots extends s
  * is the same one-direction assignability, on the `workspace` field alone: the handles the wrapper
  * will inject must satisfy what the body declares for them, so a body that names fewer slots, or
  * no handles at all, is fed a superset and passes, as ever.
+ *
+ * @internal
  */
 type BodyAcceptsSlots<TBody extends AnyStateMachine, TSlots extends string> =
   InputFrom<TBody> extends { workspace: infer THandles }
@@ -475,141 +613,452 @@ type BodyAcceptsSlots<TBody extends AnyStateMachine, TSlots extends string> =
       : { "the body's declared handles must accept the Repo Slots the wrapper declares": WorkspaceHandles<TSlots> }
     : unknown;
 
-/**
- * What the Sandbox is MADE OF (ADR-0037, ADR-0005) and which Repos it attaches (ADR-0051), as
- * STATIC options on the wrapper rather than fields of the per-run spec (ADR-0049). Static is the
- * whole point: `jr2 up` walks the registered Machines to find every `file:` context and build it,
- * every bound Repo and warm it, every open slot and refuse it (parts.ts) — and a spec is a function
- * of run input that no walk can evaluate. They are also never persisted — the provisioning state
- * re-reads them off the Machine it was invoked as, so a restore, a `provide()` and a `customize()`
- * all get the image and the slots the Machine carries NOW.
- *
- * Each image is one string in ADR-0037's two shapes: a `file:` URL to a docker context the
- * Machine's module ships (`import.meta.resolve("./image")`), or a registry ref its owner baked and
- * hosts.
- *
- * `TSlots` has no default, here and on the two option types below (ADR-0050): a value annotated
- * with a `string` slot set types `repos` as `Record<string, RepoSlot>`, under which a body naming
- * any slot passes the wrapper's check — the widening {@link WorkspaceHandles} refuses for the
- * same reason. The `workspace()` overloads infer it; an annotation names it.
- */
+// What the Sandbox is MADE OF (ADR-0037, ADR-0005) and which Repos it attaches (ADR-0051), as
+// STATIC options on the wrapper rather than a function of the run input (ADR-0049). Static is the
+// whole point: `jr2 up` walks the registered Machines to find every `file:` context and build it,
+// every bound Repo and warm it, every open slot and refuse it (parts.ts) — and no walk can evaluate a
+// function of run input. They are also never persisted — the provisioning state
+// re-reads them off the Machine it was invoked as, so a restore, a `provide()` and a `customize()`
+// all get the image and the slots the Machine carries NOW.
+//
+// Each image is one string in ADR-0037's two shapes: a `file:` URL to a docker context the
+// Machine's module ships (`import.meta.resolve("./image")`), or a registry ref its owner baked and
+// hosts.
+//
+// `TSlots` has no default, here and on the two option types below (ADR-0050): a value annotated
+// with a `string` slot set types `repos` as `Record<string, RepoSlot>`, under which a body naming
+// any slot passes the wrapper's check — the widening WorkspaceHandles refuses for the
+// same reason. The `workspace()` overloads infer it; an annotation names it.
+/** The options of a `workspace()` that say what its Sandbox is made of and which Repos it
+ * clones. They are the same for each run. */
 export type SandboxOptions<TSlots extends string, TInput = unknown> = {
-  /** The Sandbox Image. Absent → the Instance's `images/default`, then the stock Harness. */
+  /** The Sandbox Image: the image of the container where the Agent's Working tools and
+   * `command` Effects run. A `file:` URL to a docker context that your module ships
+   * (`import.meta.resolve("./image")`), which `jr2 up` builds, or a registry ref. Its floor is
+   * glibc and git; jr2 adds its own runtime at `/opt/jr2`. Default: the Instance's
+   * `images/default`, then jr2's Harness image. */
   image?: string;
-  /** The User Container (ADR-0005): its image, or `{ image, resources }` when the Machine states
-   * the seat's split of the Size (ADR-0060) — the widening ADR-0005 foresaw. Absent → the pod has
-   * no third container: there is no default, because the seat's whole identity is "what jr2 does
-   * not own" and jr2 has nothing to put there. Env and ports are deliberately not forwarded. With
-   * no split stated, the seat has no limit of its own and shares the pod's budget. */
+  // A gid is a fact of the images, so it is static.
+  /** The group id that owns the files in `/work`. Default: 2000. A non-negative integer. */
+  workGroup?: number;
+  // The widening ADR-0005 foresaw: `{ image, resources }` states the seat's split of the Size
+  // (ADR-0060). There is no default, because the seat's whole identity is "what jr2 does not own"
+  // and jr2 has nothing to put there. Env and ports are deliberately not forwarded.
+  /** The User Container: a third container in the Sandbox, for a service that must run beside the
+   * Agent, such as an sshd. Its image, in the same two forms as `image`, or `{ image, resources }`
+   * to give it a part of the Size. It runs its own entrypoint, with `/work` mounted. jr2 adds
+   * nothing to it. Default: none. Without `resources`, it has no limit of its own and shares the
+   * Size of the Sandbox. */
   user?: string | UserContainer;
+  // Agent Substrate's template size (ADR-0060), so the Workspace moves there unchanged. A fact of
+  // the Machine, like its image: the author knows the toolchain, the runner, the worker count.
   /**
-   * The Size (ADR-0060): the ceiling for the whole Sandbox, `limits.memory` and `limits.cpu` and
-   * nothing else — Agent Substrate's template size, so the Workspace moves there unchanged. A fact
-   * of the Machine, like its image: the author knows the toolchain, the runner, the worker count.
-   * jr2 reserves all of it (every request equals its limit) and enforces the CPU limit. Absent, or
-   * a field left out → the Instance's `sandbox.resources`, then the kit default (2Gi, 1 cpu). A
-   * composer retunes it with `customize(machine, { resources })`.
+   * The Size: the memory and cpu limit of the whole Sandbox, `{ limits: { memory, cpu } }`, such as
+   * `{ limits: { memory: "4Gi", cpu: "2" } }`. jr2 reserves all of it on the node: each request
+   * equals its limit. jr2 also enforces the cpu limit. Only `limits`,
+   * and in it only `memory` and `cpu`, are accepted. Default: the Instance's `sandbox.resources`,
+   * then 2Gi and 1 cpu. Under a Size that you give, a field you leave out takes the kit's value,
+   * not the Instance's. The Instance that registers the Machine can change it with
+   * `customize(machine, { resources })`.
    */
   resources?: Size;
+  // The handles keep this map's order, and the kit reads nothing into it (ADR-0051). Required
+  // here, at least one; a Workspace with no Repo Slot leaves it out, which is the
+  // `NoSlotWorkspaceOptions` overload, not an empty map. `repos: open` is the shape a packaged
+  // Machine takes when its body enumerates its checkouts rather than naming them
+  // (`@jr2/machines`'s `task`, whose first slot is the one the coder edits).
   /**
-   * The Repo Slots (ADR-0051), keyed by the Machine's own word for each — the key of the body's
-   * `workspace.repos` handles and the directory under `/work`. The handles keep this map's order,
-   * and the kit reads nothing into it. Required, at least one: a Workspace exists to work on a repository. Each slot is bound (a url,
-   * or `{ url, ref? }` — the package's own), open (`open` — the consumer binds it with
-   * `customize`), or per-run (a mapper over the door: `({ input }) => input.repo`).
+   * The Repo Slots: the repositories that the Sandbox clones, each under a name of your Machine's
+   * choice. The name is the key of `workspace.repos` in the body and the directory under `/work`.
+   * At least one slot. Leave `repos` out for a Workspace with no Repo Slot (see
+   * {@link NoSlotWorkspaceOptions}). Each value is one of:
+   * - a url, or `{ url, ref }`, where `ref` is the branch, the tag or the commit that the clone
+   *   stays on, and that a new branch starts from (default: the Repo's default branch);
+   * - `open`, for the Instance that registers the Machine to bind with `customize()`;
+   * - a function of the run input, `({ input }) => url` or `{ url, ref }`, when each run chooses.
    *
-   * Or the whole map Open (`repos: open`): the Machine names no slot, the composer names every
-   * one with `customize`, in an order the Machine may give a meaning to. The shape a packaged
-   * Machine takes when its body enumerates its checkouts rather than naming them (`@jr2/machines`'s
-   * `task`, whose first slot is the one the coder edits). Under it `TSlots` is `string`, and the body's handles must say so.
+   * Or `repos: open` for the whole map: the Machine names no slot, and the Instance that registers
+   * it names each one with `customize()`. The body's input is then `Workspaced<RunInput, string>`.
    */
   repos: Record<TSlots, RepoSlot<TInput>> | typeof open;
+  // Naming is placement (ADR-0059): a pod gets the Held secrets something in it names — this
+  // list, and the model keys of the Agents whose Turns run here, which their providers claim
+  // without being listed.
   /**
-   * The Held secrets this Workspace's pod gets (ADR-0059): names of `jr2.config.ts`'s `secrets`
-   * list. Its Custodian holds each one, and the Harness container sees its Stand-in. Naming is
-   * placement: a pod gets the Held secrets something in it names — this list, and the model keys
-   * of the Agents whose Turns run here, which their providers claim without being listed.
+   * The Held secrets that this Sandbox can use: names from the `secrets` list in `jr2.config.ts`.
+   * The Sandbox's Custodian holds each value and puts it into requests to the hosts of that Held
+   * secret. Listing a name also gives its Stand-in to the Agent's programs — each `bash` call, test,
+   * build and `command` — in their env under that name, so code in `/work` can spend it (ADR-0076).
+   * You need not list the model key of an Agent that runs here: its provider claims it, and the
+   * Harness gives it to the model calls alone. List the model key only when code in `/work` must
+   * call the model itself: such a call is outside the Turn's usage record. Each name once.
    */
   secrets?: readonly string[];
+  // The container exists only when an Effect below this `workspace()` is placed there (ADR-0068,
+  // ADR-0005). It runs as its own `USER`.
   /**
-   * The Sandbox Effector's image (ADR-0068, ADR-0005): the container that runs this Workspace's
-   * `push`, file-body `http` and credentialed `command` Effects, with the secrets they name. Absent → the
-   * Sandbox Image, whose floor already holds `git` (ADR-0037). Name one for the tools and the
-   * credentials kept out of the Agent's image (`terraform`, `aws`). A `file:` context or a
-   * registry ref, resolved like the User Container's image; it runs as its own `USER`. The
-   * container exists only when an Effect below this `workspace()` is placed there.
+   * The image of the Sandbox Effector. This container runs three kinds of Effect for this
+   * Workspace: a `push`, an `http` Effect with a Worktree file as its body, and a `command` with an
+   * Effect secret in its `env`. It gets the Effect secrets that those Effects name. Give an image
+   * when those Effects need tools or credentials that you keep out of the Sandbox Image, such as
+   * `terraform`. A `file:` URL or a registry ref, as for `image`. Default: the Sandbox Image,
+   * which already holds `git`.
    */
+  // The default is the Sandbox Image, whose floor already holds `git` (ADR-0037).
   effector?: { image: string };
 };
 
-/**
- * How a Workspace with a declared door is configured (ADR-0012, ADR-0033) — the wrapper's own
- * run-input schema, what the pod is made of, and the mapping from what comes through the door to
- * workspace vocabulary.
- */
+// How a Workspace with a declared door is configured (ADR-0012, ADR-0033) — the wrapper's own
+// run-input schema, what the pod is made of, and the mapping from what comes through the door to
+// workspace vocabulary.
+/** The options of a `workspace()` that declares the input that starts a run. */
 export type WorkspaceOptions<TSchema extends z.ZodObject, TSlots extends string> = SandboxOptions<
   TSlots,
   z.infer<TSchema>
 > & {
-  /** The wrapper's OWN declared run input (ADR-0033) — what a caller sends to start a run of it,
-   * what types `spec`'s `input`, and what the body is checked against. Deliberately NOT the body's
-   * schema: the body is fed the run input PLUS the injected `workspace` handles
-   * ({@link Workspaced}), which no caller can send, so the body's contract is the door plus
-   * something that does not exist yet. Symmetric with `PoolSpec.input`. */
+  // Deliberately NOT the body's schema (ADR-0033): the body is fed the run input PLUS the injected
+  // `workspace` handles ({@link Workspaced}), which no caller can send, so the body's contract is
+  // the door plus something that does not exist yet. Symmetric with `PoolSpec.input`.
+  /** The input that starts a run, as a `z.object`. jr2 checks each start against it. It also types
+   * the `input` of a per-run Repo Slot, and the body must accept it plus the
+   * `workspace` handles. Write it here, not on the body. */
   input: TSchema;
-  /** Map what came through the door to the workspace-domain spec: what to attach, on what ref,
-   * on which branch (ADR-0012's boundary — workflow configuration never enters it). */
-  spec: (args: { input: z.infer<TSchema> }) => WorkspaceSpec;
 };
 
+// How a Workspace with NO declared door is configured: absence is permissive (ADR-0033), so jr2
+// has nothing to infer from and says `unknown` rather than `any` — an honest "jr2 does not know",
+// which the mapper must narrow before it reads a field.
 /**
- * How a Workspace with NO declared door is configured: absence is permissive (ADR-0033), so jr2
- * has nothing to infer from and says `unknown` rather than `any` — an honest "jr2 does not know",
- * which the mapper must narrow before it reads a field. A wrapper that is fed by something other
- * than a caller — a pool worker, a nested invoke — may state what it is fed by annotating the
- * parameter (`spec: ({ input }: { input: Item }) => …`), which types the wrapper's input too. For
- * anything a caller starts, the honest fix is to declare `input`.
+ * The options of a `workspace()` with no `input`: it starts with any input. The `input` of a
+ * per-run Repo Slot is then `unknown`, and the mapper must check it before it reads a field.
+ *
+ * Use it for a Workspace that a Pool or another Machine starts. The body's `input` type says what
+ * that input is, and that also types the input of the Workspace. For a Workspace that a caller
+ * starts, declare `input`.
  */
 export type PermissiveWorkspaceOptions<TSlots extends string, TInput = unknown> = SandboxOptions<TSlots, TInput> & {
-  /** Never present on this path. Spelled out so a declared schema can never fall through to the
-   * permissive overload, where the body's door would go unchecked. */
+  // Spelled out so a declared schema can never fall through to the permissive overload, where the
+  // body's door would go unchecked.
+  /** Not present: a `workspace()` without `input` starts with any input. */
+  input?: never;
+};
+
+// A Workspace with no Repo Slot (ADR-0051): a Sandbox for one unit of work whose Agents and
+// Effects share `/work`, and no Worktree is in it — the steps of one job. Its own option types, not a
+// conditional on `TSlots`, because the slot overloads infer `TSlots` from `repos`, and no
+// inference reaches through a conditional type.
+/** The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+ * `repos` is left out. */
+export type NoSlotWorkspaceOptions<TSchema extends z.ZodObject> = Omit<SandboxOptions<never>, "repos"> & {
+  /** Not present: the Workspace has no Repo Slot. Its Agents work in `/work`. */
+  repos?: never;
+  /** The input that starts a run, as a `z.object`, as in {@link WorkspaceOptions}. */
+  input: TSchema;
+};
+
+/** The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input. */
+export type PermissiveNoSlotWorkspaceOptions = Omit<SandboxOptions<never>, "repos"> & {
+  /** Not present: the Workspace has no Repo Slot. Its Agents work in `/work`. */
+  repos?: never;
+  /** Not present: a `workspace()` without `input` starts with any input. */
   input?: never;
-  spec: (args: { input: TInput }) => WorkspaceSpec;
 };
 
 /**
- * Wrap a body Machine in Sandbox lifecycle (ADR-0012). `spec` maps the wrapper's input to the
- * workspace-domain spec; the body receives the wrapper's input plus `workspace` (the handles) —
- * `Workspaced<TInput, TSlots>`, which is also what the declared door checks the body against. The
- * wrapper's output is the body's output. A body ERROR is deliberately unhandled: it faults the run
- * loudly (RunStatus.fault) and leaves the Sandbox to the operator's idle-timeout GC — the trail
- * stays inspectable, and silent cleanup would destroy the evidence.
+ * Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot. The result is
+ * a Machine. Register it as a Workflow, or invoke it from another Machine as
+ * an actor slot.
+ *
+ * When a run enters it, the Workspace makes the Sandbox and waits for room on a node, with no
+ * deadline. It clones each Repo Slot to `/work/<slot>/default`, on the Binding's base, and makes no
+ * Worktree: the body cuts each Worktree that it needs with `worktree()`. A slot that is only read
+ * needs no cut. No work happens in `default/`. Then it runs the body with the run input plus
+ * `workspace`, the handles (see {@link Workspaced}). The Agents with Working tools and the `command` Effects in the body run in that Sandbox. An Agent
+ * with `workspace: "none"` runs on the Instance Harness. When the body reaches a final state, the
+ * Workspace deletes the Sandbox, and its output is the body's output. Push each branch before
+ * then: jr2 deletes the Sandbox's commits with it.
+ *
+ * The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as
+ * people in one checkout do. Each coder that needs its own branch gets its own Worktree of the one
+ * clone.
+ *
+ * Leave out `repos` for a Workspace with no Repo Slot: its Agents and `command` Effects share
+ * `/work`, as the steps of one job share a folder. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
+ * file of `/work` with `file(path)`. A `worktree()`, a `push`, and a `command` with an Effect secret in its
+ * `env`, need a Repo Slot, so jr2 refuses them there. jr2 deletes `/work` with the Sandbox: send what
+ * must stay before the body ends.
+ *
+ * Give each run a different branch, so that two runs do not push to one branch. Make it from a
+ * field of the run input, or from `instanceId` when the run input has no field that is different
+ * for each run: ``branch: `fix/${context.instanceId}` `` in the input of the cut. Add
+ * `HostInjectedInput` to the body's input type to read it. Only a root `workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets
+ * it only when its parent gives it.
+ *
+ * The Sandbox is Lost when its pod is evicted or its node goes. Then the body gets the event
+ * `workspace.lost`, and the body decides what to do. jr2 does not make the Lost Sandbox again.
+ *
+ * When the body fails (it invokes a `fail()` slot), the Workspace deletes the Sandbox, and then the
+ * same Failure goes up to the parent. With no parent to catch it, the run ends `failed`. When the
+ * body has a defect (an error that is not a Failure), the run faults: it ends `error`, and the
+ * Sandbox stays for you to inspect, until jr2's operator removes it after an idle timeout.
+ *
+ * Give the run input to `input`, not to the body: a body with an `input` schema of its own is
+ * refused. The types refuse a body whose input does not accept the run input plus the handles,
+ * with the message `the body's declared input must accept the door plus the injected handles`.
+ *
+ * It refuses, when you call it:
+ * - a body with a state that is not final, when that state and each state above it have no
+ *   `workspace.lost` route: ``workspace(): the body "<id>" has a state "<state>" that is not final,
+ *   and no route for "workspace.lost" is on it or on a state above — jr2 sends workspace.lost to the
+ *   body when its Sandbox is gone, and with no route the run faults: route it on the body's root,
+ *   as on: { "workspace.lost": "<the state that handles it>" } (ADR-0074)``
+ * - a body with its own `input`: ``workspace(): the body "<id>" declares its own run input, which
+ *   nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected
+ *   `workspace` handles, so the body's schema is not the door. Move it to the wrapper:
+ *   workspace(body, { input }) (ADR-0033).``
+ * - an empty `image`: ``workspace(): `image` must be a non-empty string (got <value>) — either a
+ *   `file:` URL to a docker context this module ships (`import.meta.resolve("./image")`) or a
+ *   registry ref (ADR-0037).``
+ * - an empty `repos`: ``workspace(): `repos: {}` names no Repo Slot — leave `repos` out for a
+ *   Workspace with no Repo Slot, or name a slot: `repos: { app: "https://…" }` (ADR-0051).``
+ * - a `repos` that is not a map or `open`: ``workspace(): `repos` must be a map of Repo Slots —
+ *   `repos: { app: "https://…" }` — or `open` whole, for a map the consumer names; leave it out
+ *   for a Workspace with no Repo Slot (ADR-0051).``
+ * - a bad Repo Slot name or value (see {@link RepoSlot})
+ * - a `workGroup` that is not a gid: ``workspace(): `workGroup` must be a gid (got <value>)``
+ * - a bad `secrets` list: ``workspace(): `secrets` must be a list of distinct names from
+ *   jr2.config.ts's `secrets` list (got <value>) — secrets: ["JIRA_TOKEN"] (ADR-0059).``
+ * - a bad `effector`: ``workspace(): `effector` is { image } — a `file:` URL to a docker context
+ *   or a registry ref (got <value>) — effector: { image: import.meta.resolve("./effector") }
+ *   (ADR-0068).``
+ * - a `user` that is not an image or `{ image, resources? }`: ``workspace(): `user` must be a
+ *   non-empty string (an image), or { image, resources? } (got <value>) — either a `file:` URL to a
+ *   docker context this module ships (`import.meta.resolve("./image")`) or a registry ref
+ *   (ADR-0037, ADR-0060).``, or ``workspace(): user.<key> is not accepted — the User Container is {
+ *   image, resources? } (ADR-0005, ADR-0060)`` (see {@link UserContainer})
+ * - a `resources` key other than `limits` or `requests`: ``workspace(): resources.<key> is not accepted — a
+ *   Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template size
+ *   (ADR-0060)``, or the same text for `resources.limits.<key>`. The other texts are in
+ *   {@link Size}.
+ *
+ * And when a run enters it, a per-run Repo Slot's mapper that gives no `url`, or a bad `ref`:
+ * ``workspace invalid: repos.<slot> mapper returned <fields> — the mapper derives from run
+ * input; does `jr2 run --input` carry every field this workflow's workspace() slot reads?``
+ *
+ * @param body - The Machine to run in the Sandbox. Its input is `Workspaced<RunInput, Slots>`.
+ * @param options - What the Sandbox is made of (`image`, `user`, `resources`, `effector`), the
+ *   Repo Slots it clones (`repos`), the Held secrets it can use (`secrets`), the pod's `fsGroup`
+ *   (`workGroup`), and the run input (`input`).
+ * @returns A Machine whose input is the run input and whose output is the body's output.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   command,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   workspace,
+ *   worktree,
+ *   type CommandOutput,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ ticket: z.string(), repo: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app" | "docs">;
+ *
+ * // The Worktree of this run. An Agent or a command that only reads `docs` uses `/work/docs/default`.
+ * const buildTree = (context: BodyInput) => `${context.workspace.repos.app}/build` as const;
+ *
+ * const passed = (output: CommandOutput): boolean =>
+ *   output.outcome === "exited" && output.code === 0;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: BodyInput; context: BodyInput },
+ *   actors: {
+ *     cut: worktree(),
+ *     build: command(["npm", "run", "build"]),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "build",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: buildTree(context), branch: `fix/${context.ticket}` }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     building: {
+ *       invoke: {
+ *         src: "build",
+ *         input: ({ context }) => ({ worktree: buildTree(context) }),
+ *         onDone: [
+ *           { guard: ({ event }) => passed(event.output), target: "built" },
+ *           { target: "broken" },
+ *         ],
+ *       },
+ *     },
+ *     built: { type: "final" },
+ *     broken: { invoke: { src: "fail", input: { reason: "npm run build 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, {
+ *   input: runInput,
+ *   image: "docker.io/library/node:24",
+ *   resources: { limits: { memory: "4Gi", cpu: "2" } },
+ *   repos: {
+ *     app: ({ input }) => input.repo,
+ *     docs: { url: "https://github.com/you/docs.git", ref: "main" },
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   command,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   workspace,
+ *   worktree,
+ *   type CommandOutput,
+ *   type HostInjectedInput,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
+ *
+ * const passed = (output: CommandOutput): boolean =>
+ *   output.outcome === "exited" && output.code === 0;
+ *
+ * // The run input has no field that is different for each run, so the branch comes from
+ * // `instanceId`.
+ * const runInput = z.object({});
+ * type BodyInput = Workspaced<z.infer<typeof runInput> & HostInjectedInput, "app">;
+ *
+ * const nightlyTree = (context: BodyInput) => `${context.workspace.repos.app}/nightly` as const;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: BodyInput; context: BodyInput },
+ *   actors: { cut: worktree(), test: command(["npm", "test"]), fail: fail() },
+ * }).createMachine({
+ *   id: "nightly",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: nightlyTree(context), branch: `nightly/${context.instanceId}` }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     testing: {
+ *       invoke: {
+ *         src: "test",
+ *         input: ({ context }) => ({ worktree: nightlyTree(context) }),
+ *         onDone: [
+ *           { guard: ({ event }) => passed(event.output), target: "tested" },
+ *           { target: "red" },
+ *         ],
+ *       },
+ *     },
+ *     tested: { type: "final" },
+ *     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, {
+ *   input: runInput,
+ *   image: "docker.io/library/node:24",
+ *   repos: { app: "https://github.com/you/app.git" },
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/guides/size-a-workspace.md
+ * @see docs/guides/add-tools-to-the-sandbox.md
+ * @see docs/reference/decisions/0012-workspace-wrapper-machine.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
  */
-export function workspace<TSchema extends z.ZodObject, TBody extends AnyStateMachine, TSlots extends string>(
+// `TSlots` defaults to `never`: with `repos` left out there is nothing to infer it from, and the
+// Workspace has no Repo Slot (ADR-0051). The no-slot options are a union member, not overloads of
+// their own, so a call with slots reports its error where it always did.
+export function workspace<TSchema extends z.ZodObject, TBody extends AnyStateMachine, TSlots extends string = never>(
   body: TBody & BodyAcceptsDoor<TBody, z.infer<TSchema>, TSlots>,
-  options: WorkspaceOptions<TSchema, TSlots>,
-): WorkspaceMachine<z.infer<TSchema>, OutputFrom<TBody>, TBody, TSlots>;
-export function workspace<TBody extends AnyStateMachine, TSlots extends string, TInput = unknown>(
+  options: WorkspaceOptions<TSchema, TSlots> | NoSlotWorkspaceOptions<TSchema>,
+  // The input is the door without the empty door's `Record<string, never>` (`{}` for `z.object({})`), so
+  // a parent can give `instanceId` to a nested body that reads it (ADR-0033).
+): WorkspaceMachine<WithoutEmptyIndex<z.infer<TSchema>>, OutputFrom<TBody>, TBody, TSlots>;
+/**
+ * Run a body Machine in a Sandbox, with no `input` schema: the Workspace starts with any input. Use
+ * it for a Workspace that a Pool or another Machine starts. {@link workspace} tells the rest, and
+ * what it refuses.
+ *
+ * @param body - The Machine to run in the Sandbox. Its input is the input of the Workspace plus
+ *   `workspace`, the handles.
+ * @param options - The options of the Sandbox. There is no `input`.
+ * @returns A Machine whose input is the run input and whose output is the body's output.
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md
+ */
+export function workspace<
+  TBody extends AnyStateMachine,
+  TSlots extends string = never,
+  // Nothing else annotates the input of a door-less Workspace, so the body says it.
+  TInput = DoorlessInput<TBody>,
+>(
   body: TBody & BodyAcceptsSlots<TBody, TSlots>,
-  options: PermissiveWorkspaceOptions<TSlots, TInput>,
+  // `undefined` is for the invoke alone: a run with no input gives a mapper `{}`.
+  options: PermissiveWorkspaceOptions<TSlots, Exclude<TInput, undefined>> | PermissiveNoSlotWorkspaceOptions,
 ): WorkspaceMachine<TInput, OutputFrom<TBody>, TBody, TSlots>;
 export function workspace(
   body: AnyStateMachine,
-  options: SandboxOptions<string, any> & { input?: z.ZodObject; spec: (args: { input: any }) => WorkspaceSpec },
+  options: Omit<SandboxOptions<string, any>, "repos"> & {
+    repos?: SandboxOptions<string, any>["repos"];
+    input?: z.ZodObject;
+  },
 ): AnyStateMachine {
+  // The body receives the wrapper's input plus the handles — `Workspaced<TInput, TSlots>`, which is also what the
+  // declared door checks the body against. A Failure of the body is caught: the wrapper destroys
+  // the Sandbox and fails again with the same payload (ADR-0073). Every other body error (a defect)
+  // is not caught: it faults the run (RunStatus.fault) and leaves the Sandbox to the operator's
+  // idle-timeout GC, so the trail stays as evidence.
+  //
   // A body that still declares its own run input is a dead declaration under the door design: the
   // wrapper never serves it, never validates against it, and feeds the body something it does not
   // describe. Silence would leave an author believing a contract that nothing enforces (ADR-0033).
-  if (inputSchemaOf(body)) {
+  // A body that `setup()` made keeps its zod `input` in the config with no door attached, so the
+  // check reads the config too: else the author loses the door with no message.
+  if (declaresRunInput(body)) {
     throw new Error(
       `workspace(): the body "${body.id}" declares its own run input, which nothing will ever ` +
         "serve or enforce — the wrapper feeds the body the run input PLUS the injected `workspace` " +
         "handles, so the body's schema is not the door. Move it to the wrapper: " +
-        "workspace(body, { input, spec }) (ADR-0033).",
+        "workspace(body, { input }) (ADR-0033).",
     );
   }
+  // A body state that cannot route `workspace.lost` (ADR-0074): with no route, the body would show
+  // healthy on the feed with no Sandbox. Here, because `workspace()` is the one place that knows
+  // that a Machine is a body. A body that is the kit's own wrapper (a `workspace()`, a `pool()`) is
+  // not judged: its states are jr2's, and the walk refuses a Workspace below a Workspace (ADR-0059).
+  if (!composesSandbox(body) && wrapperBodyOf(body) === undefined) refuseUnroutedLost(body);
   // Static, so checkable NOW rather than at the first provision — an empty or non-string image is
-  // the same derives-from-a-typo bug `assertSpec` catches for the spec, one build earlier.
+  // a derives-from-a-typo bug, and this catches it one build earlier.
   const image = options.image;
   if (image !== undefined && (typeof image !== "string" || !image)) {
     throw new Error(
@@ -623,16 +1072,22 @@ export function workspace(
   // any key Substrate would refuse, is a dependency the move to it would drop.
   if (options.resources !== undefined) assertSize("workspace(): resources", options.resources);
   // The slots, checked NOW for the same reason (ADR-0051): every value is one of the three forms,
-  // every key is a directory name, and there is at least one — a Workspace exists to work on a
-  // repository, and a wrapper with no slot would attach nothing and hand the body no checkout.
-  // An Open map defers all of that to the `customize` that fills it, which runs the same checks.
-  const repos = options.repos;
+  // and every key is a directory name. Left out, the Workspace has no Repo Slot and its steps share
+  // `/work`; written empty, it is refused, so "no slot" has one spelling and an empty map never
+  // reads as a map someone forgot to fill. An Open map defers all of that to the `customize` that
+  // fills it, which still asks for at least one: an Open map says the composer names the slots.
+  const repos = options.repos ?? {};
   if (repos !== open) {
-    if (typeof repos !== "object" || repos === null || Array.isArray(repos) || Object.keys(repos).length === 0) {
+    if (typeof repos !== "object" || repos === null || Array.isArray(repos)) {
       throw new Error(
-        'workspace(): `repos` must name at least one Repo Slot — `repos: { app: "https://…" }`, or ' +
-          "`open` for a slot the consumer binds, or a mapper over the door for one the run chooses — or be " +
-          "`open` whole, for a map the consumer names (ADR-0051).",
+        'workspace(): `repos` must be a map of Repo Slots — `repos: { app: "https://…" }` — or `open` whole, ' +
+          "for a map the consumer names; leave it out for a Workspace with no Repo Slot (ADR-0051).",
+      );
+    }
+    if (options.repos !== undefined && Object.keys(repos).length === 0) {
+      throw new Error(
+        "workspace(): `repos: {}` names no Repo Slot — leave `repos` out for a Workspace with no Repo Slot, " +
+          'or name a slot: `repos: { app: "https://…" }` (ADR-0051).',
       );
     }
     for (const [slot, value] of Object.entries(repos)) assertRepoSlot("workspace()", slot, value);
@@ -664,7 +1119,10 @@ export function workspace(
         `${JSON.stringify(effector)}) — effector: { image: import.meta.resolve("./effector") } (ADR-0068).`,
     );
   }
-  const wrapper = buildWorkspaceMachine(body, options.spec);
+  const workGroup = options.workGroup;
+  assertWorkGroup(workGroup);
+  if (repos === open || Object.keys(repos).length > 0) refuseUnnamedWorktrees(body);
+  const wrapper = buildWorkspaceMachine(body);
   // The wrapper is TRANSPARENT to its body (ADR-0049): `customize(machine, { agents })` on a
   // Workspace means the Machine inside, so the composer never spells `body` and never has to know
   // that jr2 wrapped anything.
@@ -679,6 +1137,7 @@ export function workspace(
     ...(options.user !== undefined ? { user: options.user } : {}),
     repos: repos === open ? open : { ...repos },
     ...(options.resources !== undefined ? { resources: options.resources } : {}),
+    ...(workGroup !== undefined ? { workGroup } : {}),
     ...(secrets !== undefined ? { secrets: [...secrets] } : {}),
     ...(effector !== undefined ? { effector: { image: effector.image } } : {}),
   });
@@ -696,41 +1155,75 @@ export function workspace(
 }
 
 /**
- * Fail a malformed spec BEFORE any pod exists. The spec derives from run input via the workflow's
- * mapping fn, so a `jr2 run --input` missing a field the mapping reads arrives here as `undefined` —
- * unchecked, it survives until the attach script's string ops and dies as "Cannot read properties
- * of undefined", with a Sandbox already provisioned and nothing pointing back at the input.
+ * Each Turn and each Effect that works in a Worktree says which, in a Workspace with Repo Slots: the
+ * walk's half of what `jr2Setup` refuses by type, for a plain `setup()`, for a nested key, and for a
+ * body with no typed handles. It sees an invoke with no input and a literal input. A mapper's answer
+ * is its start's to refuse. A Machine below the body is walked too: a child, and a Pool's worker,
+ * which is no invoke, so each Machine in `actors` is walked. A nested Workspace is not: its own
+ * `workspace()` call walks it, by its own Repo Slots.
  */
-function assertSpec(spec: WorkspaceSpec): void {
-  const bad: string[] = [];
-  if (typeof spec?.branch !== "string" || !spec.branch) bad.push(`branch (got ${JSON.stringify(spec?.branch)})`);
-  // The branch Worktree is a SIBLING of the pod-local clone at `<slot>/default/` (ADR-0004), so
-  // the one branch name that is not a worktree directory is `default`.
-  else if (spec.branch === "default")
-    bad.push(
-      'branch "default" (the pod-local clone\'s own directory — a branch Worktree sits beside `default/`, ADR-0004)',
-    );
-  if (spec?.reviewSha !== undefined && (typeof spec.reviewSha !== "string" || !spec.reviewSha))
-    bad.push(`reviewSha (got ${JSON.stringify(spec?.reviewSha)})`);
-  // A gid, so an integer — a float or a negative becomes a pod the API server rejects at
-  // admission, which surfaces as "never reached Ready" with nothing pointing back at the spec.
-  if (
-    spec?.workGroup !== undefined &&
-    (typeof spec.workGroup !== "number" || !Number.isInteger(spec.workGroup) || spec.workGroup < 0)
-  )
-    bad.push(`workGroup (got ${JSON.stringify(spec?.workGroup)}; want a gid)`);
-  if (bad.length) {
-    throw new Error(
-      `workspace spec invalid: ${bad.join("; ")} — the spec derives from run input; does ` +
-        "`jr2 run --input` carry every field this workflow's workspace() mapping reads?",
-    );
+function refuseUnnamedWorktrees(body: AnyStateMachine): void {
+  const faults: string[] = [];
+  const seen = new Set<AnyStateMachine>();
+  const walk = (machine: AnyStateMachine): void => {
+    if (seen.has(machine) || (machine !== body && composesSandbox(machine))) return;
+    seen.add(machine);
+    const actors = (machine.implementations.actors ?? {}) as Record<string, unknown>;
+    for (const logic of Object.values(actors)) if (isMachineLogic(logic)) walk(logic);
+    const nodes = [machine.root as unknown as InvokeNode];
+    for (const node of nodes) {
+      nodes.push(...Object.values(node.states));
+      const configs = [node.config.invoke ?? []].flat() as Array<{ input?: unknown } | undefined>;
+      node.invoke.forEach((inv, i) => {
+        const logic = typeof inv.src === "string" ? actors[inv.src] : inv.src;
+        if (isMachineLogic(logic)) walk(logic);
+        const key = keyOf(logic);
+        if (key === undefined) return;
+        const given = configs[i]?.input;
+        const written = (given as { consumerInput?: unknown } | undefined)?.consumerInput ?? given;
+        if (typeof written === "function") return;
+        if (typeof written === "object" && written !== null && key in written) return;
+        faults.push(
+          `state "${node.id}": "${typeof inv.src === "string" ? inv.src : inv.id}" names no \`${key}\`, and a Workspace ` +
+            'with Repo Slots says where each Turn and Effect works: a Worktree, or `cwd: "/work"` for a Turn',
+        );
+      });
+    }
+  };
+  walk(body);
+  if (faults.length) throw new Error(`workspace(): ${faults.join("; ")} (ADR-0057)`);
+}
+
+const isMachineLogic = (logic: unknown): logic is AnyStateMachine =>
+  typeof logic === "object" && logic !== null && "implementations" in logic;
+
+type InvokeNode = {
+  id: string;
+  states: Record<string, InvokeNode>;
+  config: { invoke?: unknown };
+  invoke: Array<{ src: unknown; id: string }>;
+};
+
+/** The key that says where this logic works, or undefined when it works nowhere in `/work`. */
+function keyOf(logic: unknown): "cwd" | "worktree" | undefined {
+  if (isAgent(logic)) return (logic.definition as { workspace?: unknown }).workspace === "none" ? undefined : "cwd";
+  if (!isEffect(logic)) return undefined;
+  const parts = logic.effect;
+  if (parts.kind === "command") return parts.cut ? undefined : "worktree";
+  return parts.kind === "http" && parts.file ? "worktree" : undefined;
+}
+
+/** A gid, so an integer: a float or a negative is a pod the API server rejects at admission. */
+function assertWorkGroup(workGroup: unknown): void {
+  if (workGroup !== undefined && (typeof workGroup !== "number" || !Number.isInteger(workGroup) || workGroup < 0)) {
+    throw new Error(`workspace(): \`workGroup\` must be a gid (got ${JSON.stringify(workGroup)})`);
   }
 }
 
 /**
  * Resolve every Repo Slot to a Binding, in declaration order (ADR-0051). A bound slot is its
  * Binding; a per-run slot is its mapper called over the run input, validated like the static forms
- * because it derives from `jr2 run --input` exactly as the spec does; an open slot nobody bound is
+ * because it derives from `jr2 run --input` ; an open slot nobody bound is
  * a fault BEFORE the port, naming the `customize` line that fixes it — the run-time twin of the
  * refusal `jr2 up`'s walk makes for a registered Machine, reached here only by a Machine that was
  * never registered as itself (a test seam, a nested invoke of an unbound import). The Machine is
@@ -770,7 +1263,7 @@ function resolveBindings(
       bad.push(`ref (got ${JSON.stringify(binding.ref)})`);
     if (bad.length) {
       throw new Error(
-        `workspace spec invalid: repos.${slot} mapper returned ${bad.join("; ")} — the mapper derives from run ` +
+        `workspace invalid: repos.${slot} mapper returned ${bad.join("; ")} — the mapper derives from run ` +
           "input; does `jr2 run --input` carry every field this workflow's workspace() slot reads?",
       );
     }
@@ -788,7 +1281,7 @@ function attachedRepos(bindings: Record<string, ResolvedBinding>): Array<{ slot:
   }));
 }
 
-function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any }) => WorkspaceSpec): AnyStateMachine {
+function buildWorkspaceMachine(body: AnyStateMachine): AnyStateMachine {
   /**
    * `placing` (ADR-0064): write the Sandbox and wait, with no deadline, for its pod to be
    * scheduled. jr2 cannot tell "full now" from "never fits", so a bound is the Machine's own
@@ -807,13 +1300,15 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
    * delete rides the abort, after any write in flight has settled. A wait that fails on its own —
    * the Sandbox Lost before its node, a write that half landed — is the same end: the delete comes
    * before the fault, and the fault carries the reason. The host stopping the run for a restart is
-   * not an end: the restored run re-enters `placing` and keeps its place.
+   * not an end: the restored run re-enters `placing` and keeps its place. Nor is a name that a live
+   * Workspace of the run holds when the delete would run: a parent that re-enters the state, or
+   * catches a Failure and invokes the same Machine again, gives its new Workspace the same invoke id,
+   * and so the same name, which that Workspace has placed again by then (ADR-0073).
    */
   const place = fromPromise<
-    { bindings: Record<string, ResolvedBinding> },
-    { wsId: string; spec: WorkspaceSpec; runInput: unknown }
+    { bindings: Record<string, ResolvedBinding>; runInput: Record<string, unknown> },
+    { wsId: string; runInput: Record<string, unknown> }
   >(async ({ input, self, system, signal }) => {
-    assertSpec(input.spec); // before the port: a bad spec must never cost a pod
     const binding = runBindingOf(system);
     // The images and the slots come off the WRAPPER, at invoke time, not out of context and not
     // out of a build-time closure (ADR-0049, ADR-0051). This state re-runs on every restore, so
@@ -822,14 +1317,21 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
     // content-addressed tag, which would outlive the image it names. The RESOLVED bindings are
     // persisted, because a per-run mapper's answer is this run's fact.
     const parts = sandboxPartsOf(invokingMachine(self));
+    const wrapper = self._parent;
+    // RunHost parsed a root run's door and added `instanceId`, so that value is final: a second
+    // parse would refuse the added key under a strict door and transform a value twice. A parent's
+    // input is parsed here, and a door value that is wrong costs no pod (ADR-0033).
+    const door = wrapper?._parent ? inputSchemaOf(invokingMachine(self)!) : undefined;
+    const runInput = door
+      ? parsedNestedDoor(door, input.runInput, ["instanceId"], "workspace input invalid, before any pod")
+      : input.runInput;
     const user = userSeatOf(parts.user);
     const path = actorSlotPath(self._parent);
     // Read before the port: a Workspace no walk can see placed nothing, and is refused with the slot form.
     const route = actorRoute(self._parent);
-    const bindings = resolveBindings({ workflow: binding.workflow, path }, parts.repos, input.runInput);
+    const bindings = resolveBindings({ workflow: binding.workflow, path }, parts.repos, runInput);
     const port = sandboxOf(system);
     const name = workspaceName(binding.runId, input.wsId);
-    const wrapper = self._parent;
     const child = wrapper ? actorPath(wrapper).join("/") : "";
     // A wait opened before a restart is the same wait: its start is in the wrapper's persisted
     // context, never in this actor's input, which a restore replays as it was first invoked.
@@ -862,7 +1364,9 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
         // work group's default (ADR-0005 puts it in pod composition, where the pod is built).
         ...(parts.image !== undefined ? { image: parts.image } : {}),
         ...(user.image !== undefined ? { user: user.image } : {}),
-        ...(input.spec.workGroup !== undefined ? { workGroup: input.spec.workGroup } : {}),
+        ...(parts.workGroup !== undefined ? { workGroup: parts.workGroup } : {}),
+        // The Held secrets the `workspace()` grants its confined children (ADR-0076): names only.
+        ...(parts.secrets?.length ? { secrets: [...parts.secrets] } : {}),
         repos: Object.entries(bindings).map(([slot, b]) => ({ slot, ...b })),
         // The Size as the Machine states it, re-read here like the images (ADR-0060): a redeploy
         // that retuned it reaches the next provision, and no snapshot holds it.
@@ -879,7 +1383,7 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
         if (binding.hostStopping) return;
         void placed
           .catch(() => {})
-          .then(() => port.destroy(name))
+          .then(() => (binding.heldSandboxes?.().has(name) ? undefined : port.destroy(name)))
           .catch(() => {}); // a delete that fails leaves the CR to the idle GC, as ever
       },
       { once: true },
@@ -900,7 +1404,7 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
         openedAt !== undefined ? Math.round(performance.now() - openedAt) : Math.max(0, Date.now() - Date.parse(since));
       binding.marker?.({ kind: "placed", child, since, after });
     }
-    return { bindings };
+    return { bindings, runInput };
   });
 
   /** `provisioning`: the placed pod's Ready, under the port's budget, which starts here (ADR-0064). */
@@ -909,9 +1413,12 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
   );
 
   const attach = fromPromise<
-    { repos: Record<string, string>; review?: Record<string, string>; stale?: Record<string, string> },
-    { wsId: string; spec: WorkspaceSpec; bindings: Record<string, ResolvedBinding> }
+    { repos: Record<string, string>; bases?: Record<string, string>; stale?: Record<string, string> },
+    { wsId: string; bindings: Record<string, ResolvedBinding> }
   >(async ({ input, system, signal }) => {
+    // No Repo Slot, nothing to clone (ADR-0051): the Harness's attach would refuse an empty list,
+    // and `/work` needs nothing from it — the pod's `fsGroup` already makes it the work group's.
+    if (Object.keys(input.bindings).length === 0) return { repos: {} };
     const port = sandboxOf(system);
     const name = workspaceName(runBindingOf(system).runId, input.wsId);
     // The attach is loss-aware (ADR-0021): a Sandbox gone or Lost under it fails the attach at
@@ -930,7 +1437,7 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
     signal.addEventListener("abort", () => unsubscribe(), { once: true });
     let out: Awaited<ReturnType<typeof port.attach>>;
     try {
-      out = await Promise.race([port.attach({ name, spec: input.spec, repos: attachedRepos(input.bindings) }), loss]);
+      out = await Promise.race([port.attach({ name, repos: attachedRepos(input.bindings) }), loss]);
     } finally {
       unsubscribe();
     }
@@ -1049,17 +1556,17 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
 
   // Every actor this wrapper runs is a NAMED SLOT (ADR-0049), the body first among them: a Machine
   // composes by invoking a declared `src`, and `body` is what `provide()`, `customize()`, Stately,
-  // the Console's join key and the `jr2 up` parts walk all reach it by. The mechanism's own six —
-  // place, provision, attach, registrar, lease, destroy — are named for the same price, and the
-  // Console shows what each state is doing instead of "inline".
+  // the Console's join key and the `jr2 up` parts walk all reach it by. The mechanism's own seven —
+  // place, provision, attach, registrar, lease, destroy, fail — are named for the same price, and the
+  // Console shows what each state is doing instead of "inline". `fail` is the unbranded logic: it
+  // sends the body's Failure up again, and the walk does not list it as a state that fails the run.
   return setup({
-    actors: { body, place, provision, attach, registrar, lease, destroy },
+    actors: { body, place, provision, attach, registrar, lease, destroy, fail: failLogic },
   }).createMachine({
     id: "workspace",
     context: ({ input, self }: { input: unknown; self: { id: string } }): WsContext => ({
       runInput: (input ?? {}) as Record<string, unknown>,
       wsId: self.id,
-      spec: spec({ input }),
     }),
     initial: "placing",
     states: {
@@ -1070,7 +1577,6 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
             src: "place",
             input: ({ context }) => ({
               wsId: (context as unknown as WsContext).wsId,
-              spec: (context as unknown as WsContext).spec,
               runInput: (context as unknown as WsContext).runInput,
             }),
             onDone: {
@@ -1078,6 +1584,8 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
               actions: assign({
                 bindings: ({ event }) =>
                   (event as unknown as { output: { bindings: Record<string, ResolvedBinding> } }).output.bindings,
+                runInput: ({ event }) =>
+                  (event as unknown as { output: { runInput: Record<string, unknown> } }).output.runInput,
                 wait: undefined,
               }),
             },
@@ -1115,7 +1623,6 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
             src: "attach",
             input: ({ context }) => ({
               wsId: (context as unknown as WsContext).wsId,
-              spec: (context as unknown as WsContext).spec,
               bindings: (context as unknown as WsContext).bindings!,
             }),
             onDone: {
@@ -1125,7 +1632,7 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
                   const ctx = context as WsContext;
                   const out = (
                     event as unknown as {
-                      output: { repos: Record<string, string>; review?: Record<string, string> };
+                      output: { repos: Record<string, string>; bases?: Record<string, string> };
                     }
                   ).output;
                   return {
@@ -1141,8 +1648,8 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
                     ...(ctx.bindings
                       ? { bindings: Object.fromEntries(Object.entries(ctx.bindings).map(([s, b]) => [s, b.url])) }
                       : {}),
-                    branch: ctx.spec.branch,
-                    ...(out.review ? { review: out.review } : {}),
+                    // Each slot's base: what the attach put `default/` on, sent with every cut.
+                    ...(out.bases ? { bases: out.bases } : {}),
                   };
                 },
               }),
@@ -1166,17 +1673,24 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
             src: "body",
             input: ({ context }: { context: WsContext }) => {
               const ctx = context;
-              const { repos, branch, review } = ctx.handles!;
-              // Body-facing subset only (ADR-0016): endpoint/sandbox are mechanism-internal.
-              return {
-                ...ctx.runInput,
-                workspace: { repos, branch, ...(review ? { review } : {}) } satisfies WorkspaceHandles<string>,
-              };
+              const { repos } = ctx.handles!;
+              // Body-facing subset only (ADR-0016): endpoint/sandbox are mechanism-internal. With
+              // no Repo Slot the handles are `{ repos: {} }` (WorkspaceHandles<never>).
+              return { ...ctx.runInput, workspace: { repos } };
             },
             onDone: {
               target: "teardown",
               actions: assign({ output: ({ event }) => (event as unknown as { output: unknown }).output }),
             },
+            // A Failure deletes the Sandbox before it goes up (ADR-0073). Guarded, so a defect
+            // takes no transition and goes up at once, as before: its Sandbox stays as evidence.
+            onError: {
+              guard: ({ event }: { event: { error?: unknown } }) => isFailure(event.error),
+              target: "failing",
+              actions: assign({
+                failure: ({ event }) => failurePayload((event as unknown as { error: Failure }).error),
+              }),
+            },
           },
           leaseInvoke(true),
         ],
@@ -1194,6 +1708,25 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
         },
       },
       done: { type: "final" },
+      // The body failed (ADR-0073): the same delete as `teardown`, then the same Failure goes up to
+      // the parent unchanged. No lease here: nothing judges a Sandbox that is being deleted.
+      failing: {
+        initial: "destroying",
+        states: {
+          destroying: {
+            invoke: {
+              src: "destroy",
+              input: ({ context }) => ({ wsId: (context as unknown as WsContext).wsId }),
+              onDone: "raising",
+              // A failed delete is the operator GC's problem, and the run host's (ADR-0012 backstop).
+              onError: "raising",
+            },
+          },
+          raising: {
+            invoke: { src: "fail", input: ({ context }) => (context as unknown as WsContext).failure! },
+          },
+        },
+      },
     },
     // Machine output must be declared at the ROOT in xstate v5 (a final state's own `output`
     // only rides the done event); the workspace's output is the body's, verbatim (ADR-0012).