@jr2/orchestrator 0.4.1 → 0.5.1

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
+// (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 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,20 @@ import {
 } from "xstate";
 import type { z } from "zod";
 import { registerAmbientHandles, type AmbientHandles } from "./ambient.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 +68,7 @@ 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, 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 +90,201 @@ 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. */
+// 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.
+/** What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two
+ * optional fields. jr2 calls `spec` with the run input when the run enters the Workspace. */
 export type WorkspaceSpec = {
+  /** The branch that the Workspace works on: each Repo Slot gets a Worktree for it, at
+   * `/work/<slot>/<branch>`, with each `/` in the branch written as `-`. Required, and not
+   * `default`, which is the directory of the clone. Your Machine decides its name. */
   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. */
+  // The pod's work group (ADR-0005): `fsGroup`. 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.
+  /** The group id that owns the files in `/work`. With it, the Sandbox Image and the User
+   * Container can both write those files when they run as different users. Default: 2000. Set it
+   * to a group id that the User Container's sessions already have, for example when a root sshd
+   * builds their groups from `/etc/group`. A non-negative integer. */
   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. */
+  // `<branchDir>-review`, a sibling of the branch worktree, forced to exactly this sha on every
+  // attach (ADR-0028). Creation-time seat only; the per-round refresh verb (the sha moves between
+  // review rounds) is a later, workflow-driven change.
+  /** A commit to check out in a second, detached Worktree beside each branch Worktree, for a
+   * reviewer: `/work/<slot>/<branch>-review`. The body gets its paths as `workspace.review`. */
   reviewSha?: string;
 };
 
+// A Workspace with no Repo Slot (ADR-0051) attaches nothing, so a branch and a review sha name
+// nothing: `never` refuses them where the spec is written, and `assertSpec` refuses them at run
+// time for the caller the types do not see.
+/** What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`. There is no
+ * branch and no review Worktree, because the Workspace has no Repo Slot. */
+export type NoSlotSpec = Pick<WorkspaceSpec, "workGroup"> & { branch?: never; reviewSha?: never };
+
+// 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 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).
+ * What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the
+ * branch. A path is correct in each Instance that registers the Machine.
  *
- * `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.
+ * `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 Worktrees in the order of `repos`, as under `repos: open`. Write `never` for a
+ * Workspace with no Repo Slot: its handles are `{ repos: {} }`, with no branch, and its Agents work
+ * in `/work`.
  */
-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). */
+// `[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 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).
+  /** The absolute path of each Repo Slot's Worktree, `/work/<slot>/<branch>`, in the order that
+   * `repos` declares the slots. Give one to an Agent's Turn as its `cwd`. */
   repos: Record<TSlots, string>;
+  /** The branch that the Workspace works on: the `branch` of the spec. */
   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. */
+  // The review seat (ADR-0028).
+  /** The path of each Repo Slot's review Worktree. Present only when the spec has `reviewSha`.
+   * Give one to a reviewer's Turn as its `cwd`. */
   review?: Partial<Record<TSlots, string>>;
 };
 
+// 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.
 /**
- * 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 input of a `workspace()` body: the run input, plus `workspace`, the handles that the
+ * Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`). 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, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const done = defineEvent({
+ *   name: "done",
+ *   description: "Call this when REVIEW.md is written.",
+ *   input: z.object({}),
+ * });
+ * const runInput = z.object({ branch: z.string(), sha: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+ *
+ * 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",
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "review",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+ *   initial: "reviewing",
+ *   states: {
+ *     reviewing: {
+ *       invoke: {
+ *         src: "reviewer",
+ *         input: ({ context }) => ({
+ *           prompt: `Review commit ${context.sha} on ${context.workspace.branch}.`,
+ *           cwd: context.workspace.review?.app ?? context.workspace.repos.app,
+ *         }),
+ *       },
+ *       on: { done: "finished" },
+ *     },
+ *     finished: { type: "final" },
+ *     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" },
+ *   spec: ({ input }) => ({ branch: input.branch, reviewSha: input.sha }),
+ * });
+ * ```
  *
- * 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.
+ * @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 Workspaced<TInput, TSlots extends string> = TInput & { workspace: WorkspaceHandles<TSlots> };
+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.
+/**
+ * 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.
+ */
+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
@@ -277,8 +410,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. */
@@ -353,7 +488,7 @@ type WsContext = {
   /** 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;
+  spec: AnySpec;
   /** Every slot's resolved Binding, by slot, in declaration order — assigned at provision. */
   bindings?: Record<string, ResolvedBinding>;
   endpoint?: string;
@@ -363,6 +498,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 +521,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 +575,15 @@ 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.
+/** @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 +614,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,132 +624,426 @@ 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 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 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. */
+  // 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 or commit that the Worktree 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. The Agent sees only a Stand-in. You need not list the model key of an Agent that runs
+   * here: its provider claims it. 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 `spec` and 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;
+  // ADR-0012's boundary: workflow configuration never enters the spec.
+  /**
+   * A function from the run input to the Workspace's {@link WorkspaceSpec}: the `branch` it works
+   * on, and optionally `reviewSha` and `workGroup`. jr2 calls it when the run enters the
+   * Workspace.
+   *
+   * The input of `spec` also holds `instanceId`, the seed Instance ID of the run (see
+   * {@link HostInjectedInput}). Use it to give each run a branch of its own:
+   * ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. Only a root `workspace()` gets
+   * it from jr2. A `workspace()` that a different Machine invokes gets only the input that its
+   * parent gives it, so that parent must give `instanceId` when `spec` reads it.
+   */
+  // The type says `instanceId` is present also below the root, where only the parent can supply it:
+  // the same permissive answer the body guard gives (BodyAcceptsDoor), because no type can see where
+  // the wrapper sits. The alternative, `Partial<HostInjectedInput>`, makes each root `spec` that reads
+  // it write a fallback for a value that is always there.
+  spec: (args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput }) => 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 `spec`
+ * is then `unknown`, and `spec` must check it before it reads a field.
+ *
+ * Use it for a Workspace that a Pool or another Machine starts. Give the parameter of `spec` a
+ * type to say what that input is: `spec: ({ input }: { input: Item }) => …`. 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 function from the input to the Workspace's {@link WorkspaceSpec}. Its `input` is
+   * `unknown` unless you give the parameter a type: `spec: ({ input }: { input: Item }) => …`. */
   spec: (args: { input: TInput }) => WorkspaceSpec;
 };
 
+// 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, and `spec` is optional. */
+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;
+  /** A function from the run input to the Workspace's {@link NoSlotSpec}: only `workGroup`.
+   * Default: no `workGroup`. */
+  spec?: (args: { input: WithoutEmptyIndex<z.infer<TSchema>> & HostInjectedInput }) => NoSlotSpec;
+};
+
+/** The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input. */
+export type PermissiveNoSlotWorkspaceOptions<TInput = unknown> = 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;
+  /** A function from the input to the Workspace's {@link NoSlotSpec}: only `workGroup`. Default:
+   * no `workGroup`. */
+  spec?: (args: { input: TInput }) => NoSlotSpec;
+};
+
 /**
- * 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 Worktree of each Repo Slot on one
+ * branch. 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 and makes its Worktree on the `branch` that `spec` gives. 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 the branch before
+ * then: jr2 deletes the Sandbox's commits with it.
+ *
+ * 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, and `spec` is optional and gives only
+ * `workGroup`. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
+ * file of `/work` with `file(path)`. 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: ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. The input of
+ * `spec` holds `instanceId` with no cast, also for the door `z.object({})`. 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, spec }) (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 `spec` that is not a function, or no `spec` on a Workspace with Repo Slots: ``workspace():
+ *   `spec` must be a function from the run input to the spec — spec: ({ input }) => ({ branch }) —
+ *   and only a Workspace with no Repo Slot may leave it out (ADR-0051).``
+ * - 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 spec without a `branch` (or with `branch: "default"`), or with a bad
+ * `reviewSha` or `workGroup`: ``workspace spec invalid: <fields> — the spec derives from run input;
+ * does `jr2 run --input` carry every field this workflow's workspace() mapping reads?``. With no
+ * Repo Slot, a spec with a `branch` or a `reviewSha`: ``workspace spec invalid: <field> (the
+ * Workspace has no Repo Slot, so it has no branch and no review Worktree; its spec gives only
+ * workGroup) …``
+ *
+ * @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 run input
+ *   (`input`), and the function from the run input to the branch (`spec`).
+ * @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,
+ *   jr2Setup,
+ *   workspace,
+ *   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">;
+ *
+ * const passed = (output: CommandOutput): boolean =>
+ *   output.outcome === "exited" && output.code === 0;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: BodyInput },
+ *   actors: {
+ *     build: command(["npm", "run", "build"], { slot: "app" }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "build",
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "building",
+ *   states: {
+ *     building: {
+ *       invoke: {
+ *         src: "build",
+ *         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" } } },
+ *     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" },
+ *   },
+ *   spec: ({ input }) => ({ branch: `fix/${input.ticket}` }),
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   command,
+ *   fail,
+ *   jr2Setup,
+ *   workspace,
+ *   type CommandOutput,
+ *   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({});
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
+ *   actors: { test: command(["npm", "test"], { slot: "app" }), fail: fail() },
+ * }).createMachine({
+ *   id: "nightly",
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "testing",
+ *   states: {
+ *     testing: {
+ *       invoke: {
+ *         src: "test",
+ *         onDone: [
+ *           { guard: ({ event }) => passed(event.output), target: "tested" },
+ *           { target: "red" },
+ *         ],
+ *       },
+ *     },
+ *     tested: { type: "final" },
+ *     red: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+ *     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" },
+ *   spec: ({ input }) => ({ branch: `fix/${input.instanceId}` }),
+ * });
+ * ```
+ *
+ * @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 `spec` 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, and `spec`. 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, TInput = unknown>(
   body: TBody & BodyAcceptsSlots<TBody, TSlots>,
-  options: PermissiveWorkspaceOptions<TSlots, TInput>,
+  options: PermissiveWorkspaceOptions<TSlots, TInput> | PermissiveNoSlotWorkspaceOptions<TInput>,
 ): 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;
+    spec?: (args: { input: any }) => WorkspaceSpec | NoSlotSpec;
+  },
 ): AnyStateMachine {
+  // `spec` maps the wrapper's input to the workspace-domain spec (ADR-0012); 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` " +
@@ -608,6 +1051,11 @@ export function workspace(
         "workspace(body, { input, spec }) (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.
   const image = options.image;
@@ -623,16 +1071,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 +1118,15 @@ export function workspace(
         `${JSON.stringify(effector)}) — effector: { image: import.meta.resolve("./effector") } (ADR-0068).`,
     );
   }
-  const wrapper = buildWorkspaceMachine(body, options.spec);
+  // A Workspace with slots cuts a branch, so it needs `spec`; one with none may leave it out. The
+  // types say so; this says so to a caller the types do not see, by name, before any run.
+  if (options.spec !== undefined ? typeof options.spec !== "function" : repos === open || Object.keys(repos).length) {
+    throw new Error(
+      "workspace(): `spec` must be a function from the run input to the spec — spec: ({ input }) => ({ branch }) — " +
+        "and only a Workspace with no Repo Slot may leave it out (ADR-0051).",
+    );
+  }
+  const wrapper = buildWorkspaceMachine(body, options.spec ?? (() => ({})));
   // 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.
@@ -701,16 +1163,29 @@ export function workspace(
  * 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.
  */
-function assertSpec(spec: WorkspaceSpec): void {
+function assertSpec(spec: AnySpec, noSlot: boolean): void {
+  if (typeof spec !== "object" || spec === null) {
+    throw new Error(
+      `workspace spec invalid: the spec is ${JSON.stringify(spec)}, not an object — \`spec\` returns one, ` +
+        "such as { branch } (ADR-0051)",
+    );
+  }
   const bad: string[] = [];
-  if (typeof spec?.branch !== "string" || !spec.branch) bad.push(`branch (got ${JSON.stringify(spec?.branch)})`);
+  // No Repo Slot, nothing attached (ADR-0051): a branch or a review sha would name nothing, and a
+  // value jr2 silently ignores is the failure the refusals exist for.
+  const nothing =
+    "(the Workspace has no Repo Slot, so it has no branch and no review Worktree; its spec gives only workGroup)";
+  if (noSlot) {
+    if (spec?.branch !== undefined) bad.push(`branch ${nothing}`);
+    if (spec?.reviewSha !== undefined) bad.push(`reviewSha ${nothing}`);
+  } else 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))
+  if (!noSlot && 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.
@@ -779,6 +1254,15 @@ function resolveBindings(
   return bindings;
 }
 
+/** A spec as the wrapper holds it: a Workspace's with Repo Slots, or one with none (ADR-0051). */
+type AnySpec = WorkspaceSpec | NoSlotSpec;
+
+/** Does this Workspace declare no Repo Slot (ADR-0051)? An Open map is not "none": its slots are
+ * the composer's, and `customize()` names at least one. */
+function noSlot(slots: SandboxParts["repos"]): boolean {
+  return slots !== open && Object.keys(slots).length === 0;
+}
+
 /** The port-facing view of the persisted bindings, in declaration order. */
 function attachedRepos(bindings: Record<string, ResolvedBinding>): Array<{ slot: string; url: string; ref?: string }> {
   return Object.entries(bindings).map(([slot, b]) => ({
@@ -788,7 +1272,7 @@ function attachedRepos(bindings: Record<string, ResolvedBinding>): Array<{ slot:
   }));
 }
 
-function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any }) => WorkspaceSpec): AnyStateMachine {
+function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any }) => AnySpec): 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 +1291,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 }
+    { wsId: string; spec: AnySpec; runInput: 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,6 +1308,7 @@ 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));
+    assertSpec(input.spec, noSlot(parts.repos)); // before the port: a bad spec must never cost a pod
     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.
@@ -879,7 +1366,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 },
@@ -910,8 +1397,11 @@ 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> }
+    { wsId: string; spec: AnySpec; 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 +1420,9 @@ 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]);
+      // A Workspace with slots holds a `WorkspaceSpec`: `place` refused one without a branch.
+      const spec = input.spec as WorkspaceSpec;
+      out = await Promise.race([port.attach({ name, spec, repos: attachedRepos(input.bindings) }), loss]);
     } finally {
       unsubscribe();
     }
@@ -1049,11 +1541,12 @@ 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 => ({
@@ -1141,7 +1634,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,
+                    // No branch with no Repo Slot (ADR-0051): nothing was cut.
+                    ...(ctx.spec.branch !== undefined ? { branch: ctx.spec.branch } : {}),
                     ...(out.review ? { review: out.review } : {}),
                   };
                 },
@@ -1167,16 +1661,25 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
             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>,
-              };
+              // Body-facing subset only (ADR-0016): endpoint/sandbox are mechanism-internal. With
+              // no Repo Slot the handles are `{ repos: {} }` (WorkspaceHandles<never>).
+              const handles: WorkspaceHandles<string> | WorkspaceHandles<never> =
+                branch === undefined ? { repos: {} } : { repos, branch, ...(review ? { review } : {}) };
+              return { ...ctx.runInput, workspace: handles };
             },
             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 +1697,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).