@jr2/orchestrator 0.4.1 → 0.5.1

package/src/effect.ts

@@ -4,9 +4,11 @@
 // route on, the input kept in the persisted snapshot, a `src` typo as a compile error, and
 // `.provide()` as the unit-test seam.
 //
-// Two kinds exist: `command`, run in the Harness container of the enclosing Workspace's Sandbox
-// (the Harness's `/exec/:id`, ADR-0067), here; and `http`, run in the Instance Effector
-// (http-effect.ts, ADR-0068). What this module adds to xstate is what makes an Effect safe to
+// The kinds: `command`, run in the Harness container of the enclosing Workspace's Sandbox (the
+// Harness's `/exec/:id`, ADR-0067), here; `http`, run in the Instance Effector (http-effect.ts,
+// ADR-0068); `push`, in the Sandbox Effector (sandbox-effect.ts); and `dispatch`, which starts a run
+// of a registered Workflow, in the Orchestrator's own process or, toward another Orchestrator, in
+// the Instance Effector (dispatch-effect.ts, ADR-0071). What this module adds to xstate is what makes an Effect safe to
 // restart:
 //
 //   - THE LEDGER. The run host keeps one row per Effect, in the run's blob beside the snapshot
@@ -53,8 +55,58 @@ import {
 
 // --- Parts: what `jr2 up` and the Machine doc read off a slot, without running anything ---------
 
-/** One argv entry an Effect's input fills: ONE argument, whatever its bytes (never shell text). */
+// ONE argument, whatever its bytes: never shell text.
+/** One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it. It
+ * is one argument, whatever its text. No shell reads it. */
 export type Arg<N extends string = string> = { readonly arg: N };
+
+/**
+ * Mark one argv entry of a `command` that the input of the Effect fills. `arg("file")` is one
+ * argument: the value of the `file` key of the input, whatever its characters. No shell reads it.
+ *
+ * The input of the Effect then has a string key for each `arg`. Give it in the `input` of the
+ * `invoke`, or use `fromPick` to give it from a pick.
+ *
+ * When it starts, with no string in the input for an entry, the Effect fails (its `onError`
+ * route): `command "<slot>": argv slot <<name>> has no string value in its input (got <type>) —
+ * map it in the invoke's input`. The angle brackets around the name are in the text.
+ *
+ * @param name - The key of the input that fills this entry.
+ * @returns The argv entry, for the argv list of `command`.
+ *
+ * @example
+ * ```ts
+ * import { arg, command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * type Input = Workspaced<{ file: string }, "app">;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { context: Input; input: Input },
+ *   actors: { lint: command(["npx", "eslint", arg("file")]), fail: fail() },
+ * }).createMachine({
+ *   id: "lint",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "lint",
+ *   states: {
+ *     lint: {
+ *       invoke: { src: "lint", input: ({ context }) => ({ file: context.file }), onDone: "done" },
+ *     },
+ *     done: { type: "final" },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   spec: () => ({ branch: "lint" }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/effects.md
+ * @see docs/guides/run-a-command-or-call-a-url.md
+ * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
+ */
 export const arg = <const N extends string>(name: N): Arg<N> => ({ arg: name });
 
 /** A `command` Effect's plain data. */
@@ -103,10 +155,10 @@ export type HttpParts = {
   readonly maxBody: number;
   /** Marked by the author: a restore that cannot find the Effect sends it again. */
   readonly idempotent: boolean;
-  /** The body is a Worktree file (`body: file(...)`, ADR-0067): the Effect runs in the Sandbox Effector
-   * of the Workspace whose body invokes it. `slot` is the Repo Slot whose Worktree holds the file —
-   * needed only where the Workspace carries several. Absent: a json, text or no body, in the
-   * Instance Effector. */
+  /** The body is a Worktree file (`body: file(...)`, ADR-0067): the Effect runs in the Sandbox
+   * Effector of the Workspace whose body invokes it. `slot` is the Repo Slot whose Worktree holds
+   * the file — needed only where the Workspace carries several. Absent: a json, text or no body, in
+   * the Instance Effector. */
   readonly file?: { readonly slot?: string; readonly contentType?: string };
 };
 
@@ -128,6 +180,33 @@ export type PushParts = {
   readonly inputKeys: readonly string[];
 };
 
+/** A `dispatch` Effect's target: another Orchestrator's origin and the secret that holds its
+ * Instance token, by name (ADR-0071). */
+export type DispatchTarget = { readonly url: string; readonly token: string };
+
+/**
+ * A `dispatch` Effect's plain data (ADR-0071): the Workflow it starts a run of, as `jr2 run` names
+ * it (`review`, or `<wrapper>/<name>` for a named Chart), whether it waits for that run to end, the
+ * bound on the start (or the wait), and the target. No target: it runs in the Orchestrator's own
+ * process, through the run host, with no wire and no token. A target: it runs in the Instance
+ * Effector, which holds the token as an Effect secret.
+ */
+export type DispatchParts = {
+  readonly kind: "dispatch";
+  readonly workflow: string;
+  readonly wait: boolean;
+  readonly timeoutMs: number;
+  readonly target?: DispatchTarget;
+  /** The keys of the slot's input schema: what a pick param may fill. Undefined with no schema:
+   * the callee's door alone checks the body, so the load walk reads everything (ADR-0071). */
+  readonly inputKeys: readonly string[] | undefined;
+  /** `[target.token]`, or none in-process: what places the token (ADR-0068). */
+  readonly secrets: readonly string[];
+  /** Always false: a target's token is never `secret(open)` — the whole target is the Open part
+   * (ADR-0071). */
+  readonly openSecret: boolean;
+};
+
 /**
  * An Effect whose url or argv a package left Open (ADR-0054): the same parts with the sentinel in
  * that one place. The kind, the placement, the timeout and the secrets the other parts name are
@@ -140,21 +219,36 @@ export type OpenHttpParts = Omit<HttpParts, "url" | "target"> & {
   readonly target: typeof open;
 };
 
+/** A `dispatch` whose target a package left Open (ADR-0071): the composer binds the url and the
+ * token together, once. */
+export type OpenDispatchParts = Omit<DispatchParts, "target"> & { readonly target: typeof open };
+
 /** Every kind's parts, bound or with an Open part. */
-export type EffectParts = CommandParts | HttpParts | PushParts | OpenCommandParts | OpenHttpParts;
+export type EffectParts =
+  | CommandParts
+  | HttpParts
+  | PushParts
+  | OpenCommandParts
+  | OpenHttpParts
+  | DispatchParts
+  | OpenDispatchParts;
 
 /** The kinds, as their parts name them. */
-export const EFFECT_KINDS: ReadonlySet<string> = new Set(["command", "http", "push"]);
+export const EFFECT_KINDS: ReadonlySet<string> = new Set(["command", "http", "push", "dispatch"]);
 
 /**
  * Where an Effect runs, derived from its kind and what it names, never authored (ADR-0067,
  * ADR-0068): a `command` that names no secret in the Harness container of its Workspace; an
  * `http` Effect with no Worktree file in the Instance Effector; an `http` whose body is a Worktree
- * file, a `push` and a `command` that names a secret in the Sandbox Effector of its Workspace.
+ * file, a `push` and a `command` that names a secret in the Sandbox Effector of its Workspace; a
+ * `dispatch` with no target in the Orchestrator's own process, and one with a target (an Open one
+ * included: it has one once bound) in the Instance Effector (ADR-0071).
  */
-export type Placement = "harness" | "instance" | "sandbox";
+export type Placement = "harness" | "instance" | "sandbox" | "orchestrator";
 export function placementOf(parts: EffectParts): Placement {
   switch (parts.kind) {
+    case "dispatch":
+      return parts.target === undefined ? "orchestrator" : "instance";
     case "http":
       return parts.file ? "sandbox" : "instance";
     case "push":
@@ -192,9 +286,12 @@ export function targetText(parts: { readonly target: HttpParts["target"] | typeo
 }
 
 /** The keys an Effect's input has, read off its parts: a command's argv slot names (and `sha` with
- * `pin`); an http Effect's input schema keys; a push's `sha` and `message`. Undefined for an Open
- * argv: its slots are the composer's, unknown until `customize()` binds it (ADR-0054). */
+ * `pin`); an http Effect's input schema keys; a push's `sha` and `message`; a dispatch's input
+ * schema keys. Undefined for an Open argv: its slots are the composer's, unknown until
+ * `customize()` binds it (ADR-0054); and for a dispatch with no input schema: the callee's door is
+ * the only check, so nothing here says what it reads (ADR-0071). */
 export function inputKeysOf(parts: EffectParts): string[] | undefined {
+  if (parts.kind === "dispatch") return parts.inputKeys === undefined ? undefined : [...parts.inputKeys];
   if (parts.kind !== "command") return [...parts.inputKeys];
   if (parts.argv === open) return undefined;
   return [...parts.argv.flatMap((a) => (typeof a === "string" ? [] : [a.arg])), ...(parts.pin ? ["sha"] : [])];
@@ -202,14 +299,111 @@ export function inputKeysOf(parts: EffectParts): string[] | undefined {
 
 // --- Output -------------------------------------------------------------------------------------
 
-/** The outside world may have acted, and jr2 cannot tell: the Harness lost the exec, or its state
- * exited while it ran. Output the Machine routes on; never repeated by jr2. */
+/** The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
+ * For example, the Harness lost the exec, or its state exited while it ran. Route on it. jr2 does
+ * not run the Effect again. */
 export type Unknown = { outcome: "unknown"; reason: string };
 
-/** A `command` Effect's output: it exited, its timeout killed it, a signal killed it, or unknown. A
- * credentialed command's says `dirty` when the Worktree held edits it did not see (ADR-0067). */
+// `dirty` is a credentialed command's alone (ADR-0067): it runs in the Sandbox Effector against
+// the pinned commit, never the live Worktree.
+/**
+ * The output of a `command` Effect: what the `onDone` of its state gets as `event.output`. Every
+ * outcome is output. A failed program is output too. Route on `outcome`:
+ *
+ * - `exited`: the program ended. `code` is its exit code. A program that the container does not
+ *   have is `exited` with code 127.
+ * - `timeout`: the command ran past its `timeout`, and jr2 killed it.
+ * - `killed`: a signal ended it. `signal` names the signal.
+ * - `unknown`: jr2 cannot tell what the command did, for example because the Harness restarted
+ *   while it ran. `reason` tells why. jr2 does not run it again.
+ *
+ * `tail` is the end of what the command wrote, at most the `tail` option of `command` in
+ * characters. `dirty` is `true` when a command that names an Effect secret ran against a commit,
+ * and the Worktree held changes that it did not see.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   command,
+ *   type CommandOutput,
+ *   fail,
+ *   jr2Setup,
+ *   workspace,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
+ *
+ * type Input = Workspaced<{}, "app">;
+ *
+ * const passed = (output: CommandOutput): boolean =>
+ *   output.outcome === "exited" && output.code === 0;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { context: Input; input: Input },
+ *   actors: { tests: command(["npm", "test"], { timeout: "15m" }), fail: fail() },
+ * }).createMachine({
+ *   id: "tests",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "testing",
+ *   states: {
+ *     testing: {
+ *       invoke: {
+ *         src: "tests",
+ *         onDone: [
+ *           { guard: ({ event }) => passed(event.output), target: "green" },
+ *           { target: "red" },
+ *         ],
+ *       },
+ *     },
+ *     green: { type: "final" },
+ *     // Not a final state: a final state means `done`, and the run ends `failed` here.
+ *     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, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   spec: () => ({ branch: "tests" }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/effects.md
+ * @see docs/guides/run-a-command-or-call-a-url.md
+ * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
+ */
 export type CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown;
 
+// Reach is output, as an http Effect's is (ADR-0067): a body a model wrote can be fixed through
+// the Chain, so a refusal is output too.
+/**
+ * The output of a `dispatch` Effect. Route on `outcome`:
+ *
+ * - `started`: the Orchestrator accepted the new run. `run` is its id.
+ * - `settled`: with `wait`, the new run ended. `status` is `done`, `failed`, `error`, `cancelled`,
+ *   `lost` or `drifted`, and `output` is the output of its Machine. For `failed`, `output` is the
+ *   Failure, `{ reason, detail? }`. `status` is `live` when the timeout came first, and the run
+ *   continues.
+ * - `refused`: the Orchestrator started no run. `status` is the HTTP status: 400 for an input that
+ *   the Workflow does not take, 404 for a Workflow that it does not have, 409 for a named Chart that
+ *   cannot run now, 422 for a Chart that it refuses. `report` holds the lines of the refusal.
+ * - `unreachable`: the Orchestrator of the target did not answer. No run started.
+ * - `unknown`: jr2 cannot tell if a run started.
+ *
+ * @see docs/concepts/effects.md
+ */
+export type DispatchOutput =
+  | { outcome: "started"; run: string }
+  | {
+      outcome: "settled";
+      run: string;
+      status: "done" | "failed" | "error" | "cancelled" | "lost" | "drifted" | "live";
+      output?: unknown;
+    }
+  | { outcome: "refused"; status: number; report: string[] }
+  | { outcome: "unreachable"; reason: string }
+  | Unknown;
+
 // --- The ledger row (persisted in the run's blob, ADR-0007) --------------------------------------
 
 /**
@@ -238,6 +432,19 @@ export type EffectRow =
       pinned?: string;
       at: string;
     }
+  /** A dispatch's intent (ADR-0071): where it runs, and — once the start's answer names it — the
+   * run it started. A dispatch is idempotent by construction: its ledger id rides every start as
+   * the door's key, so a restore sends it again and gets the same run. */
+  | {
+      state: "intent";
+      kind: "dispatch";
+      slot: string;
+      placement: "orchestrator" | "instance";
+      idempotent: true;
+      wait: boolean;
+      run?: string;
+      at: string;
+    }
   /** `sandbox` and `repo`: the Workspace and the Repo Slot an Effect of the Sandbox Effector ran on
    * — every later push of its own Workspace and Repo Slot (one branch, one remote) sends its pair,
    * and the newest push's unfinished sync runs again in that slot's Worktree. */
@@ -250,7 +457,9 @@ export type EffectRow =
       output: unknown;
       at: string;
     }
-  | { state: "aborted"; kind: EffectParts["kind"]; slot: string; at: string };
+  /** `run`: for a dispatch, the run it started, kept past the abort — the callee runs on, and the
+   * caller's row still names it (ADR-0071). */
+  | { state: "aborted"; kind: EffectParts["kind"]; slot: string; run?: string; at: string };
 
 /**
  * Retention (ADR-0067): drop, in place, the output tail of every settled row once a save on disk
@@ -297,26 +506,33 @@ const TAILS: Record<EffectRow["kind"], readonly string[]> = {
   // every later push of its Repo Slot sends the pair (`pushPairsOf`), and the newest push's sync
   // runs again when it did not finish. The sync's bundle and git's words are its tail.
   push: ["bundle", "detail"],
+  // A dispatch's tail is the callee's output, which `GET /runs/<id>` serves for as long as the run
+  // is kept, and a refusal's report, which can carry the callee door's whole schema: the feed's
+  // settled marker carries both whole. The row keeps the outcome, the run id, its status and the
+  // door's HTTP status (ADR-0071).
+  dispatch: ["output", "report"],
 };
 
-/** A kind's tail for one output. The NEWEST push of its Repo Slot whose sync did not finish
- * (`busy`, `not-synced`) keeps its bundle: the sync that runs again before the next push of that
- * slot moves the branch from it, and the Agent's store may not hold the published commits without it.
- * Once a sync finished, or once a newer push of the slot published, the bundle goes: only the
- * newest push's sync runs again (`lastPushOf`), so an older bundle has no reader. */
+/** A kind's tail for one output. The NEWEST push of its Repo Slot whose sync did not finish (`busy`,
+ * `not-synced`) keeps its bundle: the sync that runs again before the next push of that slot moves
+ * the branch from it, and the Agent's store may not hold the published commits without it. Once a
+ * sync finished, or once a newer push of the slot published, the bundle goes: only the newest
+ * push's sync runs again (`lastPushOf`), so an older bundle has no reader. */
 function tailsOf(kind: EffectRow["kind"], output: Record<string, unknown>, newest: boolean): readonly string[] {
   if (kind === "push" && newest && (output.sync === "busy" || output.sync === "not-synced")) return ["detail"];
   return TAILS[kind];
 }
 
-/** A settled push row that published: its pair, and its sync's answer and bundle when it has them. */
+/** A settled push row that published: its pair, and its sync's answer and bundle when it has them.
+ */
 export type PushedRow = { published: string; source: string; sync?: SyncAnswer["sync"]; bundle?: string } & Record<
   string,
   unknown
 >;
 
 /** The ledger's last push of a Workspace's Repo Slot that published: its row, by `at`, never this
- * Effect's (`self`). A Workspace with two Repo Slots has two branches on two remotes, so two pairs. */
+ * Effect's (`self`). A Workspace with two Repo Slots has two branches on two remotes, so two pairs.
+ */
 export function lastPushOf(
   rows: Readonly<Record<string, EffectRow>>,
   sandbox: string,
@@ -386,14 +602,15 @@ export type EffectMarker = {
   effect: string;
   stage: "started" | "output" | "settled" | "aborted";
   text?: string;
-  output?: CommandOutput | HttpOutput;
+  output?: CommandOutput | HttpOutput | DispatchOutput;
 };
 
 // --- The port -----------------------------------------------------------------------------------
 
 /** The Harness's exec, as the Effect drives it. `read` answers undefined for an exec the Harness
  * does not know (404): it restarted, and jr2 settles `unknown`. `start` rejects with `ExecNotSent`
- * only when the request certainly never reached the Harness — the one failure it is sent again on. */
+ * only when the request certainly never reached the Harness — the one failure it is sent again on.
+ */
 export interface ExecPort {
   start(id: string, req: ExecRequest, signal: AbortSignal): Promise<void>;
   read(id: string, offset: number | undefined, signal: AbortSignal): Promise<ExecRead | undefined>;
@@ -416,9 +633,13 @@ type Fault = { type: "jr2.effect.error"; error: unknown };
 
 /** An Effect slot's logic: xstate `ActorLogic`, typed by its input and output, branded with its
  * parts. The brand is a runtime property (`isEffect`) and part of the type, as `definition` is
- * not on an Agent's: nothing substitutes a fake for an Effect's parts. */
+ * not on an Agent's: nothing substitutes a fake for an Effect's parts.
+ *
+ * @internal
+ */
 export type EffectLogic<I, O> = ActorLogic<EffectSnapshot<O, I>, EventObject, I> & EffectSlot;
 
+/** @internal */
 type ArgNames<A extends readonly unknown[]> = A[number] extends infer E ? (E extends Arg<infer N> ? N : never) : never;
 /** A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`);
  * none when there is neither. */
@@ -428,36 +649,110 @@ export type CommandInput<A extends readonly unknown[], P = false> = [
   ? void
   : { [K in ArgNames<A> | ([P] extends [true] ? "sha" : never)]: string };
 
-/** An Open argv's input (ADR-0054): its slots are the composer's, so any key is one string — what
- * the package's invoke hands it, read by the argv the composer binds. The compiler checks no slot
- * against it: one the invoke does not supply faults when the Effect starts (`argvOf`). */
+// An Open argv's slots are the composer's (ADR-0054), so any key is one string — what the
+// package's invoke hands it, read by the argv the composer binds (`argvOf`).
+/** The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds,
+ * and with `pin`, the commit (`{ sha }`). The compiler cannot check the names. When the input has
+ * no string for an `arg()`, the Effect fails when it starts. */
 export type OpenCommandInput<P = false> = Readonly<Record<string, string>> &
   ([P] extends [true] ? { sha: string } : unknown);
 
+/** A length of time: a positive number and a unit, `s`, `m` or `h`. For example `"90s"`, `"10m"`
+ * or `"1h"`. */
 export type Duration = `${number}s` | `${number}m` | `${number}h`;
 
+/** The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its
+ * output it keeps, its Effect secrets, and the commit it runs against. */
 export type CommandOptions = {
-  /** The Repo Slot whose Worktree is the cwd — needed only where the Workspace carries several. */
+  /**
+   * The Repo Slot whose Worktree is the working directory of the command. Write it only when the
+   * Workspace has more than one Repo Slot. In a Workspace with no Repo Slot, the command starts in
+   * `/work`, the folder that the steps of the Workspace share.
+   *
+   * The command starts in the root of that Worktree. To run it in a subfolder, give the path as an
+   * argument, or write `["sh", "-c", "cd <dir> && <program>"]`.
+   *
+   * When it starts, it refuses:
+   * - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
+   *   Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it
+   *   runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`. When `env` names an Effect secret,
+   *   the text is `command "<slot>" runs under a Workspace carrying more than one Repo Slot
+   *   (<slots>) — say which: { slot: "<slot>" } (ADR-0051)`.
+   * - with an Effect secret in `env`, a Workspace with no Repo Slot: `command "<slot>" runs under
+   *   a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a
+   *   Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and
+   *   it runs in /work beside the Agent (ADR-0051)`.
+   * - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
+   *   its Workspace does not carry (<slots>)`.
+   */
   slot?: string;
-  /** Default 10m. On expiry the Harness kills the process group: output `timeout`. */
+  /**
+   * How long the command can run: a number and a unit, such as `"90s"`, `"10m"` or `"1h"`.
+   * Default `"10m"`. When the time ends, jr2 kills the process group, and the output is
+   * `timeout`. It refuses a value that is not a positive duration: `command: timeout "<timeout>"
+   * is not a positive duration (like "90s", "10m", "1h")`.
+   */
   timeout?: Duration;
-  /** Characters of the stream's end kept in the output. Default 4096. */
+  /** The number of characters that `tail` keeps from the end of what the command wrote. Default
+   * 4096. */
   tail?: number;
-  /** The env, each a secret's value — `secret("x")` — or its file's path — `secret("x").path`
-   * (ADR-0067). Naming a secret places the command in the Sandbox Effector, against the pinned
-   * commit; with none it runs in the Harness container. */
+  // Naming a secret is the placement (ADR-0067, ADR-0068): there is no placement key.
+  /**
+   * The environment variables of the command, each an Effect secret. `secret("x")` gives the
+   * value, and `secret("x").path` gives the path of a file that holds the value. When `env` names
+   * one, the command runs in the Sandbox Effector against one commit, not in the Worktree that the
+   * Agent changes. Without `env`, it runs in the Harness container, beside the Agent.
+   *
+   * It refuses a name that is not a variable name, and `PATH`, `HOME` and `TMPDIR`: ``command(argv,
+   * { env }): "<name>" is not a variable the author sets — PATH, HOME and TMPDIR are the
+   * Effector's (ADR-0067)``.
+   */
   env?: CommandEnv;
-  /** A credentialed command's commit: the Effect's input names it (`{ sha }`, an approved one);
-   * absent, the Agent's branch tip when it starts. */
+  /**
+   * Only for a command whose `env` names an Effect secret. `true`: the input of the Effect names
+   * the commit to run against (`{ sha }`, a full commit id, for example one that a Gate approved).
+   * Default: the tip of the Agent's branch when the Effect starts.
+   *
+   * It refuses `pin: true` on a command that names no Effect secret: ``command(argv, { pin: true
+   * }) names no secret in its env: `pin` chooses the commit a credentialed command runs against in
+   * the Sandbox Effector, and a command that names no secret runs in the live Worktree (ADR-0067)
+   * — name its secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` ``.
+   *
+   * When it starts, it refuses an input `sha` that is not a full commit id: `command "<slot>"
+   * (pin): its input's sha is not a full commit id`.
+   */
   pin?: boolean;
 };
 
 /** The Open part a command's options state (ADR-0054): its secret, when its env holds
- * `secret(open)` or its `.path`. */
+ * `secret(open)` or its `.path`.
+ *
+ * @internal
+ */
 export type EnvOpenParts<Opt> = Opt extends { readonly env: infer E }
   ? OpenSecretIn<E extends Readonly<Record<string, infer V>> ? V : never>
   : never;
 
+/**
+ * Why an Effect kind cannot run in a Workspace with no Repo Slot (ADR-0051, ADR-0067), or undefined
+ * when it can: a `push` and a credentialed `command` run on a commit of a slot's branch, and that
+ * Workspace has none. The invoke and the `jr2 up` walk refuse with the same words.
+ */
+export function needsASlot(kind: string): string | undefined {
+  if (kind === "push")
+    return 'a push publishes a Repo Slot\'s branch, and there is none — declare one: repos: { app: "<url>" }';
+  if (kind === "command") {
+    return (
+      "a command with an Effect secret runs against one commit of a Repo Slot's branch, and there is none — " +
+      "declare a Repo Slot, or name no secret in its env, and it runs in /work beside the Agent"
+    );
+  }
+  return undefined;
+}
+
+/** The work root of a Sandbox pod (ADR-0004): where a command runs in a Workspace with no Repo Slot. */
+const WORK_ROOT = "/work";
+
 const DEFAULT_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_TAIL = 4096;
 /** How long a re-asked request waits, at most, after a transport failure. */
@@ -852,8 +1147,10 @@ function argvOf(slot: string, parts: CommandParts, input: unknown): string[] {
 
 /**
  * The cwd: a Repo Slot's Worktree (ADR-0051). Named by `slot`, or the one slot where the Workspace
- * carries one; a Workspace with none keeps the Harness's own (`/work`). Several and none named is
- * refused, as a Turn's Frame is (ADR-0057): the kit gives no slot a meaning.
+ * carries one; a Workspace with none runs it in `/work`, which its steps share. Named, never left to
+ * the Harness: a spawn with no cwd runs in the Sandbox Image's own `WORKDIR`, which is the image's.
+ * Several and none named is refused, as a Turn's Frame is (ADR-0057): the kit gives no slot a
+ * meaning.
  */
 function cwdOf(slot: string, parts: CommandParts, ambient: AmbientHandles): { cwd?: string } {
   const slots = Object.keys(ambient.repos);
@@ -867,7 +1164,7 @@ function cwdOf(slot: string, parts: CommandParts, ambient: AmbientHandles): { cw
     }
     return { cwd };
   }
-  if (slots.length === 0) return {};
+  if (slots.length === 0) return { cwd: WORK_ROOT };
   if (slots.length === 1) return { cwd: ambient.repos[slots[0]!]! };
   throw new Error(
     `command "${slot}" runs under a Workspace carrying more than one Repo Slot (${slots.join(", ")}) and names ` +