@jr2/orchestrator 0.4.1 → 0.5.1

package/src/run-output.ts

@@ -0,0 +1,38 @@
+// The output of a run (ADR-0015). xstate v5 gives a Machine one output: the `output` at its root,
+// beside `id` and `states`. The `output` of a final state directly below the root goes to that root
+// `output` as `event.output`, and to nothing else. Thus a Machine that writes an `output` on such a
+// final state and no root `output` ends with no output: its run status shows none, and the `onDone`
+// of an invoke of it gets `event.output` as `undefined`. `types.output` does not stop this, so the
+// load walk refuses the shape and the refusal gives the fix.
+//
+// A final state inside a compound state is legal: its `output` is the `event.output` of the `onDone`
+// of that compound state. A Machine with no `output` anywhere is legal too: its result is in its
+// `context`, and it says nothing false about an output.
+
+import type { AnyStateMachine, StateNode } from "xstate";
+
+/**
+ * Refuse a Machine whose root has no `output` while a final state directly below the root declares
+ * one (see the module comment). Thrown at build by `jr2Setup.createMachine` and at load by
+ * `partsOf`, so a Machine built with xstate's own `createMachine` is refused where `jr2 check`,
+ * `jr2 up` and the Orchestrator read it.
+ */
+export function refuseLostOutput(machine: AnyStateMachine): void {
+  const root = machine.root as StateNode<any, any>;
+  if (root.config.output !== undefined) return;
+  const lost = Object.values(root.states as Record<string, StateNode<any, any>>).filter(
+    (node) => node.type === "final" && node.config.output !== undefined,
+  );
+  if (!lost.length) return;
+  const names = lost.map((node) => `"${node.id}"`).join(", ");
+  const many = lost.length > 1;
+  const [states, declare, reach, write, keep, pass] = many
+    ? ["final states", "declare", "these outputs reach", "one", "them on the final states", "them"]
+    : ["final state", "declares", "this output reaches", "it", "it on the final state", "it"];
+  throw new Error(
+    `machine "${machine.id}": ${states} ${names} ${declare} an output, and the root has no output — xstate v5 ` +
+      `gives a run only its root output, so ${reach} nothing and the run ends with none: write ${write} at the ` +
+      `root, as output: ({ context }) => ..., or keep ${keep} and pass ${pass} on with output: ({ event }) => ` +
+      `event.output at the root`,
+  );
+}

package/src/sandbox-effect.ts

@@ -53,7 +53,7 @@ import type {
   PushParts,
   Unknown,
 } from "./effect.ts";
-import { lastPushOf, pushPairsOf } from "./effect.ts";
+import { lastPushOf, needsASlot, pushPairsOf } from "./effect.ts";
 import {
   createEffectorClient,
   EffectorForged,
@@ -126,12 +126,30 @@ function slotOf(kind: string, slot: string, named: string | undefined, ambient:
     return named;
   }
   if (slots.length === 1) return slots[0]!;
+  const why = slots.length === 0 ? needsASlot(kind) : undefined;
+  if (why !== undefined)
+    throw new Error(`${kind} "${slot}" runs under a Workspace with no Repo Slot: ${why} (ADR-0051)`);
   throw new Error(
     `${kind} "${slot}" runs under a Workspace carrying ${slots.length === 0 ? "no" : "more than one"} Repo Slot ` +
       `(${slots.join(", ") || "none"}) — say which: { slot: "<slot>" } (ADR-0051)`,
   );
 }
 
+/** Where a file body's path is read from, relative to the work root: the Repo Slot's Worktree, or
+ * the work root itself (`.`) in a Workspace with no Repo Slot, whose steps share `/work` (ADR-0051).
+ * The Effector opens the file beneath it either way (ADR-0067). */
+function fileRootOf(slot: string, named: string | undefined, ambient: AmbientHandles): string {
+  if (named === undefined && Object.keys(ambient.repos).length === 0) return ".";
+  return posix.relative(WORK_ROOT, ambient.repos[slotOf("http", slot, named, ambient)]!);
+}
+
+/** The branch of a Workspace with Repo Slots. A kind that reads it resolved a slot first, and a
+ * Workspace with a slot always has a branch, so its absence is a jr2 defect. */
+function branchOf(ambient: AmbientHandles): string {
+  if (ambient.branch === undefined) throw new Error("a Workspace with a Repo Slot has no branch — a jr2 defect");
+  return ambient.branch;
+}
+
 /** The slot's repositories, relative to the work root: the Agent's common git dir is the pod-local
  * clone's, beside the branch Worktree (ADR-0004); the cache is the Binding's key (ADR-0051). */
 export function repoRefOf(ambient: AmbientHandles, repoSlot: string): RepoRef & { url: string } {
@@ -151,36 +169,159 @@ export function repoRefOf(ambient: AmbientHandles, repoSlot: string): RepoRef &
 
 // --- The definitions -------------------------------------------------------------------------------
 
-/** `push()`'s options (ADR-0067). */
+/** The options of `push()`. */
 export type PushOptions = {
-  /** The Effect's input names the commit (`{ sha }`, one a Gate approved); absent, the Agent's
-   * branch tip when the Effect starts. A pinned push the Agent pruned is refused by the remote,
-   * never substituted. */
+  // A pinned commit the Agent pruned is refused by the remote, never substituted (ADR-0067).
+  /**
+   * `true`: the input of the Effect names the commit to push (`{ sha }`, a full commit id, for
+   * example one that a Gate approved). Default: the tip of the Agent's branch when the Effect
+   * starts. When the Agent removed that commit from its branch, the remote refuses the push. jr2
+   * never pushes another commit in its place.
+   *
+   * When it starts, it refuses a `sha` that is not a full commit id: `push({ pin: true }): its
+   * input's sha is not a full commit id (got <sha>)`.
+   */
   pin?: boolean;
-  /** Push signed copies; the matching `git.credentials` entry's `sign` names the key. */
+  /**
+   * `true`: push signed copies of the commits. The `sign` field of the `git.credentials` entry that
+   * the Binding matches names the key. Default `false`.
+   *
+   * At `jr2 up`, it refuses an entry with no `sign` field: `<push> signed, and git.credentials
+   * entry "<match>" holds no sign field — add sign: { sshKey: "<a Secret with identity>", name:
+   * "<committer name>", email: "<committer email>" } to it; the email must belong to the forge
+   * account that holds the key (ADR-0051, ADR-0067)`. `<push>` names the push: `workflow
+   * "<workflow>": push "<slot>" pushes Repo Slot "<name>" (<url>)`.
+   */
   sign?: boolean;
-  /** Squash into one commit; the Effect's input carries the message (`{ message }`). Signed, its
-   * committer is the signer's; unsigned, the matching `git.credentials` entry's `committer`, which
-   * `jr2 up` requires when the entry has no `sign` (ADR-0067). */
+  /**
+   * `true`: push one commit that holds all the changes. The input of the Effect gives its message
+   * (`{ message }`). Signed, its committer is the signer. Unsigned, it is the `committer` of the
+   * `git.credentials` entry that the Binding matches. Default `false`.
+   *
+   * When it starts, it refuses an input with no message: `push({ squash: true }): its input
+   * carries no message`.
+   *
+   * At `jr2 up`, it refuses an unsigned squash whose entry has no `sign` and no `committer`:
+   * `<push> squashed without sign, and git.credentials entry "<match>" holds neither sign nor
+   * committer — the squashed commit is new and needs a committer; add committer: { name:
+   * "<committer name>", email: "<committer email>" } to it, or sign the push — push({ squash:
+   * true, sign: true }) — and add sign: { sshKey: "<a Secret with identity>", name: "<committer
+   * name>", email: "<committer email>" } to it (ADR-0051, ADR-0067)`.
+   */
   squash?: boolean;
-  /** Replace what the remote holds. */
+  /** `true`: replace what the remote branch holds. Default `false`. */
   force?: boolean;
-  /** The Repo Slot pushed — needed only where the Workspace carries several. */
+  /**
+   * The Repo Slot to push. Write it only when the Workspace has more than one.
+   *
+   * When it starts, it refuses:
+   * - no `slot` under a Workspace with more than one Repo Slot: `push "<slot>" runs under a
+   *   Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" }
+   *   (ADR-0051)`
+   * - a `slot` that the Workspace does not have: `push "<slot>" names Repo Slot "<name>", which
+   *   its Workspace does not carry (<slots>)`
+   * - a Workspace with no Repo Slot: `push "<slot>" runs under a Workspace with no Repo Slot: a
+   *   push publishes a Repo Slot's branch, and there is none — declare one: repos: { app: "<url>" }
+   *   (ADR-0051)`. `jr2 up` refuses it first, with the same reason.
+   */
   slot?: string;
-  /** Default 5m. Past it with no answer: output `unknown`. */
+  /**
+   * How long jr2 waits for the push: a number and a unit, such as `"90s"` or `"5m"`. Default
+   * `"5m"`. With no answer in that time, the output is `unknown`. It refuses a value that is not a
+   * positive duration: `timeout "<timeout>" is not a positive duration (like "30s", "5m")`.
+   */
   timeout?: Duration;
 };
 
-/** A push's input: what `pin` and `squash` add. */
+/** The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`. */
 export type PushInput<O extends PushOptions> = (O["pin"] extends true ? { sha: string } : unknown) &
   (O["squash"] extends true ? { message: string } : unknown);
 
-/** The sync's answer as a push's output carries it: a field beside the outcome, never the outcome. */
+/**
+ * The sync's answer as a push's output carries it: a field beside the outcome, never the outcome.
+ *
+ * @internal
+ */
 export type SyncState = SyncAnswer["sync"];
 
-/** A push's output, as the Machine routes on it: `pushed | rejected | diverged | unknown`, and beside
- * `pushed` the sync's answer — `synced | already | skipped | busy | not-synced`, with its reason
- * when it did not move the branch. The sync's bundle never reaches the Machine. */
+// The sync's bundle never reaches the Machine: `deliver` drops it from the output (ADR-0067).
+/**
+ * The output of a `push` Effect: what the `onDone` of its state gets as `event.output`. Every
+ * outcome is output, so route on `outcome`:
+ *
+ * - `pushed`: the remote has the commit. `published` is the commit on the remote, and `source` is
+ *   the Agent's commit that it comes from. They are the same commit, unless the push was signed or
+ *   squashed. `previous` is what the remote had before, and `unchanged` is `true` when the remote
+ *   had the commit already. `squashed` is `signed` or `unsigned` when the commit on the remote is
+ *   one squashed commit. `via` tells how jr2 found the new commits after a signed push:
+ *   `ancestry`, `pair`, `cherry` or `force`.
+ * - `rejected`: git or the remote refused the push. `stage` tells where, `reason` tells why, and
+ *   `detail` has the words of git.
+ * - `diverged`: the commit on the remote is not in the history of the Agent's branch, and jr2
+ *   could not pair it with a commit there. Nothing was pushed. `reason` tells why, and `published`
+ *   and `source` name the two commits.
+ * - `unknown`: jr2 cannot tell what the push did. `reason` tells why.
+ *
+ * Beside `pushed`, `sync` tells what jr2 did to the Agent's branch after the push:
+ *
+ * - `synced`: the commit on the remote is not the Agent's own, and jr2 moved the branch to the
+ *   published commits.
+ * - `already`: the branch has the published commit already.
+ * - `skipped`: the remote has the Agent's own commit, so the branch does not move.
+ * - `busy`: a rebase, merge, cherry-pick or revert of the branch is in progress. Nothing changed.
+ * - `not-synced`: the branch did not move.
+ *
+ * With `busy` or `not-synced`, `syncReason` tells why, and jr2 tries again before the next push.
+ *
+ * @example
+ * ```ts
+ * import { fail, jr2Setup, push, type PushOutput, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * type Input = Workspaced<{ sha: string }, "app">;
+ *
+ * // A push that did not happen (`rejected` or `diverged`) is a different problem from one jr2
+ * // cannot see (`unknown`).
+ * const notPushed = (output: PushOutput): boolean =>
+ *   output.outcome === "rejected" || output.outcome === "diverged";
+ *
+ * const body = jr2Setup({
+ *   types: {} as { context: Input; input: Input },
+ *   actors: { publish: push({ pin: true }), fail: fail() },
+ * }).createMachine({
+ *   id: "release",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "publishing",
+ *   states: {
+ *     publishing: {
+ *       invoke: {
+ *         src: "publish",
+ *         input: ({ context }) => ({ sha: context.sha }),
+ *         onDone: [
+ *           { guard: ({ event }) => event.output.outcome === "pushed", target: "published" },
+ *           { guard: ({ event }) => notPushed(event.output), target: "notPushed" },
+ *           { target: "unknown" },
+ *         ],
+ *       },
+ *     },
+ *     published: { type: "final" },
+ *     // Not final states: each one fails the run, with its own reason.
+ *     notPushed: { invoke: { src: "fail", input: { reason: "the remote refused the push" } } },
+ *     unknown: { invoke: { src: "fail", input: { reason: "jr2 cannot tell if the push happened" } } },
+ *     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: "release" }),
+ * });
+ * ```
+ *
+ * @see docs/guides/push-and-sign-a-branch.md
+ * @see docs/concepts/effects.md
+ * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
+ */
 export type PushOutput =
   | Exclude<PushWireOutput, { outcome: "pushed" }>
   | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string });
@@ -232,8 +373,8 @@ export function pushStartOf(
   };
 }
 
-/** A file-body http's start for one run (ADR-0067): the definition's parts, the url's segments, and the
- * Worktree file as the body. */
+/** A file-body http's start for one run (ADR-0067): the definition's parts, the url's segments, and
+ * the Worktree file as the body. */
 export function fileStartOf(
   parts: HttpParts,
   worktree: string,
@@ -248,7 +389,8 @@ export function fileStartOf(
   return { ...http, body: { file: { worktree, path: run.path, ...(contentType ? { contentType } : {}) } } };
 }
 
-/** A credentialed command's env as its definition names it. */
+/** The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect
+ * secret, or `secret("name").path` for the path of a file that holds it. */
 export type CommandEnv = Readonly<Record<string, { readonly secret: string; readonly path: unknown }>>;
 
 export function commandEnvParts(env: CommandEnv): Pick<CommandParts, "env" | "secrets" | "openSecret"> {
@@ -579,7 +721,8 @@ async function drive<I, O>(
   }
 }
 
-/** The settled row's Repo Slot, or none when the Workspace does not name one the kind can run on. */
+/** The settled row's Repo Slot, or none when the Workspace does not name one the kind can run on.
+ */
 function repoField(spec: KindSpec, ambient: AmbientHandles, slot: string): { repo?: string } {
   try {
     return { repo: spec.repoOf(ambient, slot) };
@@ -660,9 +803,10 @@ function stoppedText(state: EffectState | undefined): string {
 }
 
 /** A start over the bytes an Effector reads is sent nowhere, and settles as its kind's own outcome
- * (ADR-0067): an http `refused`; a push `rejected` at stage `start` — nothing pushed; a credentialed
- * command `exited` 127 with the reason in its tail, the Effector's own form for a command that
- * could not start. An Agent's pick parameter — a squash message, an argv part — can reach the bound. */
+ * (ADR-0067): an http `refused`; a push `rejected` at stage `start` — nothing pushed; a
+ * credentialed command `exited` 127 with the reason in its tail, the Effector's own form for a
+ * command that could not start. An Agent's pick parameter — a squash message, an argv part — can
+ * reach the bound. */
 function tooLarge(req: StartRequest): HttpOutput | PushWireOutput | CommandWireOutput | undefined {
   const bytes = Buffer.byteLength(JSON.stringify(req), "utf8");
   if (bytes <= MAX_START_BYTES) return undefined;
@@ -728,7 +872,7 @@ export function pushWith<const O extends PushOptions>(
     build: (input, ambient, slot, pinned, extra) => {
       const repoSlot = slotOf("push", slot, parts.slot, ambient);
       const ref = repoRefOf(ambient, repoSlot);
-      const req = pushStartOf(parts, ref, ambient.branch, input as { sha?: string; message?: string }, extra?.pairs);
+      const req = pushStartOf(parts, ref, branchOf(ambient), input as { sha?: string; message?: string }, extra?.pairs);
       if (pinned) req.push.pin = pinned;
       return req;
     },
@@ -746,7 +890,7 @@ export function pushWith<const O extends PushOptions>(
         const answer = await syncOf(ctx).sync(
           {
             worktree: worktreeOf(ctx),
-            branch: ctx.ambient.branch,
+            branch: branchOf(ctx.ambient),
             published: output.published,
             source: output.source,
             ...(typeof output.bundle === "string" ? { bundle: output.bundle } : {}),
@@ -772,7 +916,7 @@ export function pushWith<const O extends PushOptions>(
       const answer = await syncOf(ctx).sync(
         {
           worktree: worktreeOf(ctx),
-          branch: ctx.ambient.branch,
+          branch: branchOf(ctx.ambient),
           published: o.published,
           source: o.source,
           ...(o.bundle !== undefined ? { bundle: o.bundle } : {}),
@@ -800,8 +944,9 @@ function syncFields(answer: SyncAnswer): { sync: SyncState; syncReason?: string
 
 export { lastPushOf };
 
-/** An http whose body is a Worktree file (ADR-0067), over an injected port factory — the seam `http()`
- * and the unit tests share. It runs in the Sandbox Effector of the Workspace whose body invokes it. */
+/** An http whose body is a Worktree file (ADR-0067), over an injected port factory — the seam
+ * `http()` and the unit tests share. It runs in the Sandbox Effector of the Workspace whose body
+ * invokes it. */
 export function httpFileWith<
   S extends z.ZodType | undefined = undefined,
   const U extends HttpDefinition<S>["url"] = string,
@@ -827,7 +972,10 @@ export function httpFileWith<S extends z.ZodType | undefined = undefined>(
     kind: "http",
     idempotent: parts.idempotent,
     repeatsPinned: false,
-    label: () => `http ${parts.method} ${parts.target.scheme}://${parts.target.host} (a Worktree file)`,
+    // With no Repo Slot the file is in `/work`, which is no Worktree (ADR-0051).
+    label: (ambient) =>
+      `http ${parts.method} ${parts.target.scheme}://${parts.target.host} ` +
+      (Object.keys(ambient.repos).length === 0 && body.slot === undefined ? "(a file of /work)" : "(a Worktree file)"),
     repoOf: (ambient, slot) => slotOf("http", slot, body.slot, ambient),
     build: (input, ambient, slot) => {
       let value: unknown = input;
@@ -836,8 +984,7 @@ export function httpFileWith<S extends z.ZodType | undefined = undefined>(
         if (!parsed.success) throw new Error(`http "${slot}": its input does not match the definition's input schema`);
         value = parsed.data;
       }
-      const repoSlot = slotOf("http", slot, body.slot, ambient);
-      const worktree = posix.relative(WORK_ROOT, ambient.repos[repoSlot]!);
+      const worktree = fileRootOf(slot, body.slot, ambient);
       const segments = fromInput<readonly string[]>(body.segments, value);
       return fileStartOf(parts, worktree, {
         path: fromInput<string>(body.path, value)!,
@@ -847,7 +994,8 @@ export function httpFileWith<S extends z.ZodType | undefined = undefined>(
   });
 }
 
-/** A command whose env names a secret: it runs in the Sandbox Effector against the pinned commit. */
+/** A command whose env names a secret: it runs in the Sandbox Effector against the pinned commit.
+ */
 export function credentialedCommandWith(
   portFactory: EffectorPortFactory,
   parts: CommandParts,
@@ -871,7 +1019,7 @@ export function credentialedCommandWith(
         parts,
         argvOf(input, slot),
         ref,
-        ambient.branch,
+        branchOf(ambient),
         pinned ?? (approved as string | undefined),
       );
     },
@@ -879,12 +1027,99 @@ export function credentialedCommandWith(
 }
 
 /**
- * THE authoring surface for a push (ADR-0067): `actors: { publish: push({ sign: true }) }`, invoked
- * from a Workspace's body. It pushes the Workspace's branch to its Repo Slot's Binding from the
- * Sandbox Effector, with the push credential of the `git.credentials` entry the Binding matches.
- * Every outcome is output: `pushed | rejected | diverged | unknown`.
+ * Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+ * Put it in `actors`, and invoke it from the body of a `workspace()`: `actors: { publish: push({
+ * sign: true }) }`.
+ *
+ * It runs in the Sandbox Effector of the Workspace, with the push credential of the
+ * `git.credentials` entry that the Binding matches. The Agent never reads that credential. It
+ * pushes one commit: the tip of the Agent's branch when the Effect starts, or, with `pin`, the
+ * commit that the input names. After an Orchestrator restart, jr2 pushes only that same commit
+ * again. With `sign` or `squash`, the commit on the remote is not the Agent's own. Then jr2 moves
+ * the Agent's branch to it.
+ *
+ * Every outcome is output (`PushOutput`): `pushed`, `rejected`, `diverged` or `unknown`. Each
+ * field of {@link PushOptions} tells what it refuses. When it starts, it also refuses a push
+ * outside a Workspace: `push "<slot>" runs in the Sandbox Effector of a Workspace, and its state is
+ * not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`.
+ *
+ * @param options - Optional. Each field tells what it does.
+ * @returns An Effect, for `actors`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   agent,
+ *   defineEvent,
+ *   fail,
+ *   jr2Setup,
+ *   push,
+ *   workspace,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
+ *
+ * const committed = defineEvent({
+ *   name: "committed",
+ *   description: "Say that the fix is committed.",
+ *   input: z.object({}),
+ * });
+ *
+ * type Input = Workspaced<{}, "app">;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { context: Input; input: Input },
+ *   events: [committed],
+ *   actors: {
+ *     coder: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You are a careful engineer.",
+ *     }),
+ *     publish: push({ sign: true }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "fix-test",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".failed", "agent.fault": ".failed" },
+ *   initial: "coding",
+ *   states: {
+ *     coding: {
+ *       invoke: { src: "coder", input: { prompt: "Fix the failing test, and commit the fix." } },
+ *       // The Agent moves the Machine on with a pick. An Agent's actor never ends, so `onDone`
+ *       // never fires.
+ *       on: { committed: "publishing" },
+ *     },
+ *     publishing: {
+ *       invoke: {
+ *         src: "publish",
+ *         onDone: [
+ *           { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
+ *           { target: "failed" },
+ *         ],
+ *       },
+ *     },
+ *     done: { type: "final" },
+ *     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
+ *     failed: { invoke: { src: "fail", input: { reason: "the fix was not pushed" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   spec: () => ({ branch: "fix-test" }),
+ * });
+ * ```
+ *
+ * @see docs/guides/push-and-sign-a-branch.md
+ * @see docs/concepts/effects.md
+ * @see docs/guides/give-the-cluster-git-credentials.md
+ * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
+ * @see docs/reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md
  */
 export function push<const O extends PushOptions>(options?: O): EffectLogic<PushInput<O> | void, PushOutput> {
+  // After an Orchestrator restart, a push is sent again with only the commit its intent row holds
+  // (ADR-0067): a run is a function of the commit, never of the Agent's tip now.
   return pushWith(sandboxEffectorPort, options);
 }
 

package/src/sandbox-kube.ts

@@ -1394,7 +1394,9 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
       const endpoint = sandbox?.status?.endpoint;
       if (!endpoint) throw new Error(`Sandbox "${req.name}" has no endpoint to attach through — is it gone?`);
       if (req.repos.length === 0) {
-        throw new Error("the attach names no Repo Slot — nothing to attach (a workspace() declares at least one)");
+        throw new Error(
+          "the attach names no Repo Slot — nothing to attach (a Workspace with no Repo Slot skips the attach, ADR-0051)",
+        );
       }
       const body: AttachRequest = {
         slots: req.repos.map((r) => {

package/src/secret-placement.ts

@@ -6,7 +6,8 @@
 //   - the Instance Harness: the model keys of the `"none"` Agents it hosts, and nothing else (they
 //     cannot execute code, ADR-0031, so nothing else is theirs to use);
 //   - an Effector: what its Effects name with `secret("name")` — the Instance Effector what its
-//     `http` Effects name; a Workspace's Sandbox Effector what its file-body `http`s and
+//     `http` Effects name and the token of each `dispatch` with a target (ADR-0071; a dispatch with
+//     no target runs in the Orchestrator's own process and names nothing); a Workspace's Sandbox Effector what its file-body `http`s and
 //     credentialed `command`s name. The push credential its `push`es spend is not placed here: the provision
 //     names the entry the slot's url matches on the Sandbox, by reference (git-push.ts, ADR-0051).
 //
@@ -27,6 +28,7 @@ import {
   type HeldLookups,
 } from "./held-secrets.ts";
 import type { JR2Config } from "./config.ts";
+import { needsASlot } from "./effect.ts";
 import { declaredPushKinds, pushRefusal } from "./git-push.ts";
 import { INSTANCE_HARNESS_HELD_POD } from "./names.ts";
 import { routeText, type CarriedEffect, type WorkspacePod } from "./parts.ts";
@@ -140,7 +142,29 @@ export function refuseEffectSecrets(config: JR2Config, walk: PlacementWalk): voi
     // An empty value is refused later with the list's own rule (`sourceOf`): it is an unset variable.
     if (namedBy.has(e.name) && e.value) shortRefusal(e, e.value.length);
   }
-  for (const ws of walk.workspaces) pushesOf(config, ws);
+  for (const ws of walk.workspaces) {
+    refuseWithNoSlot(ws);
+    pushesOf(config, ws);
+  }
+}
+
+/**
+ * A Workspace with no Repo Slot (ADR-0051) has no branch and no commit, so the two Sandbox Effector kinds that
+ * run on a commit of a slot's branch have none: a `push`, and a `command` with an Effect secret
+ * (ADR-0067). Refused here, before anything is built, as the invoke would refuse them mid-run. A
+ * file-body `http` reads `/work` and stays.
+ */
+function refuseWithNoSlot(ws: PlacedWorkspace): void {
+  if (!ws.pod.noSlot) return;
+  for (const effect of ws.pod.effects) {
+    // Every `command` placed in a Sandbox Effector names a secret: the others run beside the Agent.
+    const why = needsASlot(effect.kind);
+    if (why === undefined) continue;
+    throw new Error(
+      `workflow "${ws.workflow}": ${effect.kind} "${effect.name}" runs in ${workspaceLabel(ws)}, which has no Repo ` +
+        `Slot: ${why} (ADR-0051)`,
+    );
+  }
 }
 
 /**
@@ -153,7 +177,7 @@ export function secretPlacementsOf(
   walk: PlacementWalk,
   lookups: Pick<HeldLookups, "secretKeys" | "valueLength"> = {},
 ): SecretPlacements {
-  const { entries, namedBy, http } = namesOf(config, walk);
+  const { entries, namedBy, instancePlaced } = namesOf(config, walk);
   const { pods, redundant } = heldPodsOf(config, walk, new Set(entries.map((e) => e.name)));
   const claimed = new Set(pods.flatMap((p) => p.names));
 
@@ -207,12 +231,12 @@ export function secretPlacementsOf(
     report.push(`${label}: secrets lists ${name}, which its Agents' provider claims already — redundant`);
   }
 
-  const instanceSecrets = new Set(http.flatMap((p) => p.effect.secrets));
+  const instanceSecrets = new Set(instancePlaced.flatMap((p) => p.effect.secrets));
   const instance =
-    http.length === 0
+    instancePlaced.length === 0
       ? undefined
       : effectorPlan(
-          http,
+          instancePlaced,
           secrets.filter((s) => instanceSecrets.has(s.name)),
           values,
         );
@@ -267,6 +291,7 @@ function sandboxPlanOf(
       x.scheme === t.scheme && x.host === t.host && x.port === t.port && x.secrets.join() === t.secrets.join();
     if (!targets.some(same)) targets.push(t);
   }
+  refuseWithNoSlot(ws);
   const pushes = pushesOf(config, ws);
   const commands = ws.pod.effects.some((e) => e.kind === "command" && (e.secrets?.length ?? 0) > 0);
   return {
@@ -322,10 +347,12 @@ function pushesOf(config: JR2Config, ws: PlacedWorkspace): SandboxPush[] {
   return out;
 }
 
-function effectorPlan(http: HttpPlaced[], secrets: EffectSecret[], values: Record<string, string>): EffectorPlan {
+function effectorPlan(placed: InstancePlaced[], secrets: EffectSecret[], values: Record<string, string>): EffectorPlan {
   const targets: EffectorTargetConfig[] = [];
-  for (const { effect } of http) {
-    // An Open url has no target, so it allows nothing: `jr2 up` refuses it before this (ADR-0054).
+  for (const { effect } of placed) {
+    // An Open url or an Open dispatch target has no target, so it allows nothing: `jr2 up` refuses
+    // it before this (ADR-0054). A dispatch's target is its origin, its one secret the token
+    // (ADR-0071).
     if (effect.target === undefined) continue;
     const t = { ...effect.target, secrets: [...effect.secrets].sort() };
     const same = (x: EffectorTargetConfig) =>
@@ -337,12 +364,17 @@ function effectorPlan(http: HttpPlaced[], secrets: EffectSecret[], values: Recor
     secrets,
     values,
     targets,
-    longestTimeoutMs: Math.max(...http.map((p) => p.effect.timeoutMs)),
-    effects: http.map((p) => `${p.workflow}/${p.effect.name}`),
+    // The grace a rollout gives a replica covers the http Effects alone (ADR-0071): a dispatch is
+    // idempotent by construction, so a `wait` a rollout cuts is sent again under its key and its
+    // poll resumes, and a wait of hours never stretches the Effector's grace.
+    longestTimeoutMs: Math.max(0, ...placed.flatMap((p) => (p.effect.kind === "http" ? [p.effect.timeoutMs] : []))),
+    effects: placed.map((p) => `${p.workflow}/${p.effect.name}`),
   };
 }
 
-type HttpPlaced = { workflow: string; effect: Extract<CarriedEffect, { method: string }> };
+/** An Effect the Instance Effector runs: an http one with no Worktree file, or a dispatch with a
+ * target (ADR-0068, ADR-0071). */
+type InstancePlaced = { workflow: string; effect: Extract<CarriedEffect, { kind: "http" | "dispatch" }> };
 
 /** A Workspace as a human reads it: its workflow and the placement route to it, an inline hop as
  * `invoked inline in state <id>`. */
@@ -423,11 +455,14 @@ function namesOf(config: JR2Config, walk: PlacementWalk) {
     }
     byName.set(e.name, e);
   }
-  // Every Effect that names a secret names it, whatever its kind: an `http` one in the Instance
-  // Effector, a file-body `http` and a credentialed `command` in their Workspace's Sandbox Effector.
+  // Every Effect that names a secret names it, whatever its kind: an `http` one and a `dispatch`'s
+  // token in the Instance Effector, a file-body `http` and a credentialed `command` in their
+  // Workspace's Sandbox Effector. A dispatch with no target is placed "orchestrator" and names none
+  // (ADR-0071).
   const namedBy = new Map<string, Array<{ label: string; where: string }>>();
-  const http = walk.effects.filter(
-    (p): p is HttpPlaced => p.effect.kind === "http" && p.effect.placement === "instance",
+  const instancePlaced = walk.effects.filter(
+    (p): p is InstancePlaced =>
+      (p.effect.kind === "http" || p.effect.kind === "dispatch") && p.effect.placement === "instance",
   );
   // Keyed by the Effect's placement route and slot name, as workspacePodsOf keys a pod's Effects:
   // two slots of one name in one workflow — one in a workspace(), one outside it — are two Effects,
@@ -463,7 +498,7 @@ function namesOf(config: JR2Config, walk: PlacementWalk) {
       namedBy.set(name, [...(namedBy.get(name) ?? []), { label, where }]);
     }
   }
-  return { entries, namedBy, http };
+  return { entries, namedBy, instancePlaced };
 }
 
 /** An Effect secret shorter than 8 characters is refused, and the refusal says why. */

package/src/server.ts

@@ -295,6 +295,9 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
     instanceHarness: namespace
       ? `http://${INSTANCE_HARNESS_SERVICE}.${namespace}.svc:${INSTANCE_HARNESS_PORT}`
       : undefined,
+    // What a foreign dispatch names this Orchestrator by at the callee's door (ADR-0071): its
+    // namespace, which is stable and not secret — never a run's Instance ID.
+    ...(namespace ? { orchestratorName: namespace } : {}),
     // Where an http Effect runs (ADR-0068): the Instance Effector's headless Service. `jr2 up`
     // converges it whenever a registered Machine carries an http Effect.
     ...(namespace ? { instanceEffector: `${INSTANCE_EFFECTOR}.${namespace}.svc:${EFFECTOR_PORT}` } : {}),