@jr2/orchestrator 0.4.1 → 0.6.0

package/src/sandbox-effect.ts

@@ -53,7 +53,7 @@ import type {
   PushParts,
   Unknown,
 } from "./effect.ts";
-import { lastPushOf, pushPairsOf } from "./effect.ts";
+import { cutRowOf, lastPushOf, needsASlot, pushPairsOf, worktreePathFault, type LaterOutcome } from "./effect.ts";
 import {
   createEffectorClient,
   EffectorForged,
@@ -89,6 +89,7 @@ import {
 import { open } from "./open.ts";
 import type { OpenOf } from "./open-effect.ts";
 import { boundRun, type AnyActorSystem } from "./registration.ts";
+import type { AnyWorktreePath } from "./worktree.ts";
 import { repoKey } from "./repo-identity.ts";
 import { harnessSyncPort, type SyncPortFactory } from "./sync-client.ts";
 import type { SyncAnswer } from "./wire.ts";
@@ -126,23 +127,51 @@ 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)`,
   );
 }
 
+/**
+ * The cut behind an Effect's `worktree`, or why there is none. A push, a credentialed command and a
+ * file body act with a credential, so a path alone does not name their target: the path must be a
+ * Worktree a cut made in this Sandbox, and the branch is the cut's record. Nothing reads HEAD, and
+ * no input names a branch, so a Chart cannot fill one, and `git switch` in the Worktree moves nothing.
+ */
+function cutTargetOf(
+  worktree: unknown,
+  ctx: Pick<KindContext, "ambient" | "binding">,
+  opts: { repo?: string },
+): { target: { repo: string; path: string; branch: string | null } } | { fault: string } {
+  const bad = worktreePathFault(worktree, ctx.ambient);
+  if (bad !== undefined) return { fault: bad };
+  const row = cutRowOf(ctx.binding?.effectRows?.() ?? {}, ctx.ambient.sandbox, worktree);
+  if (row === undefined) return { fault: `no cut made ${String(worktree)} in this Sandbox: cut it with worktree()` };
+  if (opts.repo !== undefined && row.repo !== opts.repo) {
+    return { fault: `${String(worktree)} is a Worktree of Repo Slot "${row.repo}", not of "${opts.repo}"` };
+  }
+  return { target: row };
+}
+
 /** 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 } {
-  const worktree = ambient.repos[repoSlot]!;
+export function repoRefOf(
+  ambient: AmbientHandles,
+  repoSlot: string,
+  worktree: string = ambient.repos[repoSlot]!,
+): RepoRef & { url: string } {
   const url = ambient.bindings?.[repoSlot];
   if (url === undefined) {
     throw new Error(`Repo Slot "${repoSlot}" has no Binding url in its Workspace's handles — a jr2 defect`);
   }
   const rel = posix.relative(WORK_ROOT, worktree);
   return {
-    gitDir: posix.join(posix.dirname(rel), "default", ".git"),
+    // The clone of the slot, read from the slot and not from the Worktree's folder.
+    gitDir: posix.join(repoSlot, "default", ".git"),
     worktree: rel,
     cache: repoKey(url),
     url,
@@ -151,42 +180,197 @@ 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`. */
+  // Static, so that `jr2 up` places the credential per slot.
+  /**
+   * 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. */
-export type PushInput<O extends PushOptions> = (O["pin"] extends true ? { sha: string } : unknown) &
+/** The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and
+ * `{ message }` with `squash`. It names no branch: jr2 reads it from the cut's record, so no word of
+ * a Chart reaches a remote branch. The other keys are refused by name, because each is a key of a
+ * cut or a Turn, and a mapper's excess key is no compile error otherwise. */
+export type PushInput<O extends PushOptions> = {
+  /** The Worktree to push: `event.output.path` of its cut, of the push's Repo Slot. */
+  worktree: O extends { slot: infer S extends string } ? `/work/${S}/${string}` : AnyWorktreePath;
+  branch?: never;
+  to?: never;
+  cwd?: never;
+  path?: never;
+} & (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.
+ *
+ * The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   push,
+ *   type PushOutput,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
+ *
+ * type Input = Workspaced<{ branch: string; sha: string }, "app">;
+ *
+ * const releaseTree = (context: Input) => `${context.workspace.repos.app}/release` as const;
+ *
+ * // 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: { cut: worktree({ expect: "existing" }), publish: push({ pin: true }), fail: fail() },
+ * }).createMachine({
+ *   id: "release",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: releaseTree(context), branch: context.branch }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "publishing" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     publishing: {
+ *       invoke: {
+ *         src: "publish",
+ *         input: ({ context }) => ({ worktree: releaseTree(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" } } },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ * });
+ * ```
+ *
+ * @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 });
+  | (Omit<Extract<PushWireOutput, { outcome: "pushed" }>, "bundle"> & { sync: SyncState; syncReason?: string })
+  | LaterOutcome;
 
 export function pushParts(options: PushOptions = {}): PushParts {
-  const inputKeys = [...(options.pin ? ["sha"] : []), ...(options.squash ? ["message"] : [])];
+  const inputKeys = ["worktree", ...(options.pin ? ["sha"] : []), ...(options.squash ? ["message"] : [])];
   return {
     kind: "push",
     pin: options.pin === true,
@@ -232,8 +416,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 +432,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"> {
@@ -309,6 +494,7 @@ type KindContext = {
   slot: string;
   signal: AbortSignal;
   mark: (marker: Omit<EffectMarker, "kind" | "slot" | "effect">) => void;
+  input: unknown;
 };
 
 /** How one Sandbox kind builds its start and what a restore may send again. */
@@ -321,13 +507,25 @@ type KindSpec = {
   /** The Repo Slot the Effect runs on, written to its settled row. */
   repoOf: (ambient: AmbientHandles, slot: string) => string;
   /** The start for this run; `pinned` is the commit the intent row recorded. */
-  build: (input: unknown, ambient: AmbientHandles, slot: string, pinned?: string, extra?: StartExtra) => StartRequest;
+  build: (
+    input: unknown,
+    ambient: AmbientHandles,
+    slot: string,
+    pinned?: string,
+    extra?: StartExtra,
+    binding?: ReturnType<typeof boundRun>,
+  ) => StartRequest;
   /** Run before a start is sent (a push: the last sync again, and the ledger's pair). */
   before?: (ctx: KindContext) => Promise<StartExtra>;
   /** Run on the Effector's settled output before it is ledgered (a push: the sync). */
   finish?: (output: unknown, ctx: KindContext) => Promise<unknown>;
   /** What a settled output becomes for the Machine. */
   deliver?: (output: unknown) => unknown;
+  /** Why this start cannot be sent, as the kind's own output: a word an Agent or a Chart can say.
+   * It settles before any intent row: nothing went out. */
+  refuse?: (ctx: KindContext) => unknown;
+  /** The fields of the settled row that a later Effect reads. */
+  rowFields?: (ctx: KindContext) => { branch?: string; worktree?: string; repo?: string };
 };
 
 type StartExtra = { pairs?: readonly Pair[] };
@@ -406,6 +604,9 @@ async function drive<I, O>(
       kind: spec.kind,
       slot,
       ...(ambient ? { sandbox: ambient.sandbox, ...repoField(spec, ambient, slot) } : {}),
+      ...(ambient && spec.rowFields
+        ? spec.rowFields({ ambient, binding, id, slot, signal, mark, input: snapshot.input })
+        : {}),
       output,
       at: now(),
     });
@@ -447,7 +648,7 @@ async function drive<I, O>(
   // A credentialed command's stop goes through this port when its state exits (ADR-0067).
   const run = running.get(self);
   if (spec.kind === "command" && run) run.port = port;
-  const ctx: KindContext = { ambient, binding, id, slot, signal, mark };
+  const ctx: KindContext = { ambient, binding, id, slot, signal, mark, input: snapshot.input };
 
   const find = async (): Promise<{ found: EffectState | undefined } | undefined> => {
     try {
@@ -477,12 +678,12 @@ async function drive<I, O>(
       });
       const extra = spec.before ? await spec.before(ctx) : {};
       if (signal.aborted) return;
-      await send(spec.build(snapshot.input, ambient, slot, pinned, extra), pinned);
+      await send(spec.build(snapshot.input, ambient, slot, pinned, extra, binding), pinned);
       return;
     }
     if (spec.kind === "http" && spec.idempotent) {
       mark({ stage: "started", text: `${spec.label(ambient)} (sent again: it is idempotent)` });
-      await send(spec.build(snapshot.input, ambient, slot), undefined);
+      await send(spec.build(snapshot.input, ambient, slot, undefined, undefined, binding), undefined);
       return;
     }
     settle(unknown(`${why}; not run again`));
@@ -503,9 +704,14 @@ async function drive<I, O>(
     return;
   }
 
+  const refusal = spec.refuse?.(ctx);
+  if (refusal !== undefined) {
+    settle(refusal);
+    return;
+  }
   const extra = spec.before ? await spec.before(ctx) : {};
   if (signal.aborted) return;
-  const req = spec.build(snapshot.input, ambient, slot, undefined, extra);
+  const req = spec.build(snapshot.input, ambient, slot, undefined, extra, binding);
   const big = tooLarge(req);
   if (big) {
     settle(big);
@@ -579,7 +785,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 +867,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;
@@ -713,40 +921,65 @@ export function pushWith<const O extends PushOptions>(
   portFactory: EffectorPortFactory,
   options?: O,
   syncPorts: SyncPortFactory = harnessSyncPort,
-): EffectLogic<PushInput<O> | void, PushOutput> {
+): EffectLogic<PushInput<O>, PushOutput> {
   const parts = pushParts(options);
   const repoOf = (ambient: AmbientHandles, slot: string) => slotOf("push", slot, parts.slot, ambient);
-  const worktreeOf = (ctx: KindContext) => ctx.ambient.repos[repoOf(ctx.ambient, ctx.slot)]!;
   const syncOf = (ctx: KindContext) =>
     syncPorts(ctx.ambient.endpoint, ctx.binding?.harnessBearer?.(ctx.ambient.sandbox));
+  const worktreeOf = (input: unknown) => (input as { worktree?: unknown } | undefined)?.worktree;
+  /** The target of this push: the cut's row. `refuse` has run, so a build finds one; a restored push
+   * finds it too, because a row outlives the restart. */
+  const targetOf = (ctx: Pick<KindContext, "ambient" | "binding" | "input" | "slot">) => {
+    const found = cutTargetOf(worktreeOf(ctx.input), ctx, { repo: repoOf(ctx.ambient, ctx.slot) });
+    if ("fault" in found) throw new Error(`push "${ctx.slot}": ${found.fault}`);
+    return found.target as { repo: string; path: string; branch: string };
+  };
   return sandboxLogic(portFactory, parts, {
     kind: "push",
     idempotent: false,
     repeatsPinned: true,
-    label: (ambient) => `push ${ambient.branch}${parts.sign ? " (signed)" : ""}`,
+    label: () => `push${parts.sign ? " (signed)" : ""}`,
     repoOf,
-    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);
+    // Anything a Chart or a pick can say, so it is output (ADR-0067): `rejected` at stage start.
+    refuse: (ctx) => {
+      const found = cutTargetOf(worktreeOf(ctx.input), ctx, { repo: repoOf(ctx.ambient, ctx.slot) });
+      const fault =
+        "fault" in found
+          ? found.fault
+          : found.target.branch === null
+            ? `${found.target.path} is detached: a push publishes the branch of a Worktree, and it holds none`
+            : undefined;
+      if (fault === undefined) return undefined;
+      return { outcome: "rejected", stage: "start", reason: `${fault}; nothing was pushed` };
+    },
+    rowFields: (ctx) => {
+      const found = cutTargetOf(worktreeOf(ctx.input), ctx, { repo: repoOf(ctx.ambient, ctx.slot) });
+      if ("fault" in found || found.target.branch === null) return {};
+      return { branch: found.target.branch };
+    },
+    build: (input, ambient, slot, pinned, extra, binding) => {
+      const target = targetOf({ ambient, binding, input, slot });
+      const ref = repoRefOf(ambient, target.repo, target.path);
+      const req = pushStartOf(parts, ref, target.branch, input as { sha?: string; message?: string }, extra?.pairs);
       if (pinned) req.push.pin = pinned;
       return req;
     },
-    // Every push of this Workspace's Repo Slot — one branch, one remote — that published gives the
-    // Effector a pair, oldest first (ADR-0067). The newest one's sync, when it did not finish, runs
-    // again first, in that slot's Worktree and from the bundle the row keeps while it is the newest
+    // Every push of this Repo Slot's branch that published gives the Effector a pair, oldest first
+    // (ADR-0067). The newest one's sync, when it did not finish, runs again first, in this push's
+    // Worktree and from the bundle the row keeps while it is the newest
     // push and its sync did not finish (`dropSavedTails`); the push does not depend on it.
     before: async (ctx) => {
       const rows = ctx.binding?.effectRows?.() ?? {};
       const repo = repoOf(ctx.ambient, ctx.slot);
-      const last = lastPushOf(rows, ctx.ambient.sandbox, repo, ctx.id);
+      const target = targetOf(ctx);
+      const last = lastPushOf(rows, ctx.ambient.sandbox, repo, target.branch, ctx.id);
       if (last === undefined) return {};
       const { row, rowId, output } = last;
       if (output.sync === "busy" || output.sync === "not-synced") {
         const answer = await syncOf(ctx).sync(
           {
-            worktree: worktreeOf(ctx),
-            branch: ctx.ambient.branch,
+            worktree: target.path,
+            branch: target.branch,
             published: output.published,
             source: output.source,
             ...(typeof output.bundle === "string" ? { bundle: output.bundle } : {}),
@@ -758,7 +991,7 @@ export function pushWith<const O extends PushOptions>(
         ctx.binding?.recordEffect?.(rowId, { ...row, output: { ...output, ...syncFields(answer) } });
       }
       // Each row's `squashed` rides beside its pair: a push that maps the same commit names what it is.
-      return { pairs: pushPairsOf(rows, ctx.ambient.sandbox, repo, ctx.id) };
+      return { pairs: pushPairsOf(rows, ctx.ambient.sandbox, repo, target.branch, ctx.id) };
     },
     // After every pushed outcome whose published commit is not the Agent's own — signed copies, or
     // one squashed commit, signed or not (ADR-0067): the sync, in the Workspace's Harness, from the
@@ -769,10 +1002,11 @@ export function pushWith<const O extends PushOptions>(
       const o = output as PushWireOutput;
       if (o.outcome !== "pushed") return o;
       if (o.published === o.source) return { ...o, sync: "skipped" satisfies SyncState };
+      const target = targetOf(ctx);
       const answer = await syncOf(ctx).sync(
         {
-          worktree: worktreeOf(ctx),
-          branch: ctx.ambient.branch,
+          worktree: target.path,
+          branch: target.branch,
           published: o.published,
           source: o.source,
           ...(o.bundle !== undefined ? { bundle: o.bundle } : {}),
@@ -787,7 +1021,7 @@ export function pushWith<const O extends PushOptions>(
       const { bundle: _bundle, ...rest } = o;
       return rest;
     },
-  }) as EffectLogic<PushInput<O> | void, PushOutput>;
+  }) as EffectLogic<PushInput<O>, PushOutput>;
 }
 
 /** The sync's answer as the output's fields: its state, and its reason when it moved nothing. */
@@ -800,8 +1034,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,17 +1062,38 @@ 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)`,
-    repoOf: (ambient, slot) => slotOf("http", slot, body.slot, ambient),
+    // 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 ? "(a file of /work)" : "(a Worktree file)"),
+    repoOf: (ambient, slot) => slotOf("http", slot, undefined, ambient),
+    // The same row check as a push: a word of a Chart must not choose what leaves the Sandbox with a
+    // credential. `refused`, the kind's own form.
+    refuse: (ctx) => {
+      const named = (ctx.input as { worktree?: unknown } | undefined)?.worktree;
+      if (Object.keys(ctx.ambient.repos).length === 0) {
+        return named === undefined
+          ? undefined
+          : { outcome: "refused", reason: `no Worktree in a Workspace with no Repo Slot; nothing was sent` };
+      }
+      if (named === undefined) {
+        throw new Error(
+          `http "${ctx.slot}" reads a Worktree file, under a Workspace with Repo Slots, and its input names no \`worktree\``,
+        );
+      }
+      const found = cutTargetOf(named, ctx, {});
+      return "fault" in found ? { outcome: "refused", reason: `${found.fault}; nothing was sent` } : undefined;
+    },
     build: (input, ambient, slot) => {
-      let value: unknown = input;
+      const { worktree: named, ...rest } = (input ?? {}) as { worktree?: string };
+      let value: unknown = rest;
       if (def.input !== undefined) {
-        const parsed = def.input.safeParse(input);
+        const parsed = def.input.safeParse(rest);
         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]!);
+      // With no Repo Slot the file is in `/work`, which its steps share (ADR-0051).
+      const worktree = named === undefined ? "." : posix.relative(WORK_ROOT, named);
       const segments = fromInput<readonly string[]>(body.segments, value);
       return fileStartOf(parts, worktree, {
         path: fromInput<string>(body.path, value)!,
@@ -847,7 +1103,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,
@@ -859,10 +1116,30 @@ export function credentialedCommandWith(
     idempotent: false,
     repeatsPinned: true,
     label: () => parts.argv.map((a) => (typeof a === "string" ? a : `<${(a as Arg).arg}>`)).join(" "),
-    repoOf: (ambient, slot) => slotOf("command", slot, parts.slot, ambient),
-    build: (input, ambient, slot, pinned) => {
-      const repoSlot = slotOf("command", slot, parts.slot, ambient);
-      const ref = repoRefOf(ambient, repoSlot);
+    repoOf: (ambient, slot) => slotOf("command", slot, undefined, ambient),
+    // The same row check as a push, in the form a command that could not start has (ADR-0067). No
+    // Repo Slot at all is a defect of the Machine, as for a push: a throw, and `onError` (ADR-0051).
+    refuse: (ctx) => {
+      if (Object.keys(ctx.ambient.repos).length === 0) {
+        throw new Error(
+          `command "${ctx.slot}" runs under a Workspace with no Repo Slot: ${needsASlot("command")} (ADR-0051)`,
+        );
+      }
+      const found = cutTargetOf((ctx.input as { worktree?: unknown } | undefined)?.worktree, ctx, {});
+      const fault =
+        "fault" in found
+          ? found.fault
+          : found.target.branch === null
+            ? `${found.target.path} is detached, and a credentialed command runs on a commit of a branch`
+            : undefined;
+      return fault === undefined
+        ? undefined
+        : { outcome: "exited", code: 127, tail: `jr2: ${fault}; nothing was run\n` };
+    },
+    build: (input, ambient, slot, pinned, _extra, binding) => {
+      const found = cutTargetOf((input as { worktree?: unknown } | undefined)?.worktree, { ambient, binding }, {});
+      if ("fault" in found) throw new Error(`command "${slot}": ${found.fault}`);
+      const ref = repoRefOf(ambient, found.target.repo, found.target.path);
       const approved = pin ? (input as { sha?: unknown } | undefined)?.sha : undefined;
       if (pin && (typeof approved !== "string" || !/^[0-9a-f]{40}$/.test(approved))) {
         throw new Error(`command "${slot}" (pin): its input's sha is not a full commit id`);
@@ -871,7 +1148,7 @@ export function credentialedCommandWith(
         parts,
         argvOf(input, slot),
         ref,
-        ambient.branch,
+        found.target.branch!,
         pinned ?? (approved as string | undefined),
       );
     },
@@ -879,12 +1156,121 @@ 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 a Worktree 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 }) }`.
+ *
+ * Its input names the Worktree: `{ worktree }`. It has no branch. jr2 reads the branch from the
+ * `worktree()` cut of that path, so an Agent that moves `HEAD` does not change what jr2 pushes.
+ *
+ * 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`. A
+ * `worktree` that no cut made in this Sandbox, a Worktree of another Repo Slot, and a detached
+ * Worktree are `rejected` at `stage` `start`, and nothing is pushed. 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,
+ *   isReady,
+ *   jr2Setup,
+ *   push,
+ *   workspace,
+ *   worktree,
+ *   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 fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+ *
+ * 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.",
+ *     }),
+ *     cut: worktree(),
+ *     publish: push({ sign: true }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "fix-test",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".failed", "agent.fault": ".failed" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: fixTree(context), branch: "fix-test" }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     coding: {
+ *       invoke: {
+ *         src: "coder",
+ *         input: ({ context }) => ({ prompt: "Fix the failing test, and commit the fix.", cwd: fixTree(context) }),
+ *       },
+ *       // 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",
+ *         // jr2 reads the branch from the cut of this Worktree.
+ *         input: ({ context }) => ({ worktree: fixTree(context) }),
+ *         onDone: [
+ *           { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
+ *           { target: "failed" },
+ *         ],
+ *       },
+ *     },
+ *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+ *     // 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" } },
+ * });
+ * ```
+ *
+ * @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> {
+export function push<const O extends PushOptions>(options?: O): EffectLogic<PushInput<O>, 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);
 }