@jr2/orchestrator 0.4.1 → 0.5.1

package/src/harness-client.ts

@@ -32,9 +32,10 @@
 // Sandbox's Service, and a CR at `phase: Ready` is not yet routable).
 //
 // `abort` is the third verb, and ADR-0024 wires it to the END OF THE INVOCATION: a turn ends with
-// the state that asked for it. It sweeps the running Submission and everything queued behind it to
-// the distinct `aborted` Settlement — worth having for observability, though jr2 never reads it
-// (the actor is stopped by then; see actor.ts).
+// the state that asked for it. It sweeps the running Submission and everything queued behind it,
+// and says its cause: `pick` when the Turn's own pick ended it, which settles the running
+// Submission `ended`; no cause otherwise, which settles it `aborted`. The outcome is worth having for
+// observability, though jr2 never reads it (the actor is stopped by then; see actor.ts).
 
 import { agentActorWith } from "./actor.ts";
 import type {
@@ -44,6 +45,7 @@ import type {
   AgentRunInput,
   AgentRunPort,
   AgentSettleOptions,
+  ListedKill,
 } from "./actor.ts";
 import type { AgentDeclaration, AgentDefinition, ThinkingLevel } from "./agent.ts";
 import {
@@ -66,12 +68,20 @@ import {
   STREAM_NEXT_OFFSET_HEADER,
   VIEW_HISTORY,
   VIEW_UPDATES,
+  type AbortCause,
+  type AbortRequest,
   type EchoEvent,
   type ExecRead,
   type ExecRequest,
   type LiveConversation,
   type LiveSetRequest,
   type LiveSetResponse,
+  type MemoryKillsResponse,
+  type NotKeptResponse,
+  MAX_KILL_NAME,
+  MAX_KILL_STAMP,
+  MAX_KILLS_BODY,
+  MAX_TOLD,
   type Notice,
   type Settlement,
   type StreamEvent,
@@ -81,8 +91,8 @@ import {
 /** The three-verb wire client (the injectable seam — structurally what `@flue/sdk`'s
  * `agents.{send,wait,abort}` was, minus the SDK). */
 export type HarnessClient = {
-  /** `POST /agents/:name/:id {message, cwd?, definition, model?, thinkingLevel?}` → the Admission,
-   * with `streamUrl` resolved absolute. The FRAME is `message` and `cwd` — what this Turn is about
+  /** `POST /agents/:name/:id {message, cwd?, definition, model?, thinkingLevel?, notices?, kept?}`
+   * → the Admission, with `streamUrl` resolved absolute. The FRAME is `message` and `cwd` — what this Turn is about
    * and where it works (ADR-0057), flat siblings on the body. The DEFINITION is the slot's,
    * carried by the Machine and sent with every admission (ADR-0049) — the Harness keeps no roster,
    * so `:name` alone would name nothing there — and it travels as IDENTITY alone, because this
@@ -101,19 +111,43 @@ export type HarnessClient = {
       thinkingLevel?: ThinkingLevel;
       /** The pending notices in this admission's scope (ADR-0062). Omitted when there are none. */
       notices?: Notice[];
+      /** The admission is for a conversation this process was told the Harness keeps (ADR-0062).
+       * The Harness that keeps none answers 404 and seats none: this verb throws
+       * {@link ConversationNotKept}. */
+      kept?: boolean;
       signal?: AbortSignal;
     },
   ): Promise<AgentAdmission>;
-  /** Follow the stream to this Submission's Settlement: resolve on `completed`, reject with
-   * `SettlementFault` on `failed`/`aborted`/404. A guard kill read on the way is handed to
-   * `onMemoryLimit` (ADR-0061). */
+  /** Follow the stream to this Submission's Settlement: resolve on `completed` alone — the run
+   * returned with the Turn still open, which the Agent actor answers with the nudge or the wake —
+   * and reject with `SettlementFault` on `failed`/`ended`/`aborted`/404. `ended` is no fault, and no
+   * live actor reads it: a Submission settles `ended` only after the Turn's own pick took the
+   * Machine out of the Agent's state. That stopped the actor that waits on it (ADR-0024), and a
+   * stopped actor drops every rejection. A guard kill read on the way is handed to `onMemoryLimit` (ADR-0061). */
   wait(admission: AgentAdmission, opts?: AgentSettleOptions): Promise<void>;
   /** `GET /agents/:name/:id?view=history`: does the Harness still hold this conversation? Only a
    * 404 says no (ADR-0027: a GET on an unknown conversation is 404); anything else — another
    * status, a transport failure — says yes, because unknown is never loss (ADR-0062). */
   holds(agentName: string, instanceId: string, opts?: { signal?: AbortSignal }): Promise<boolean>;
-  /** `POST /agents/:name/:id/abort`. The `{ aborted }` answer is dropped (ADR-0024). */
-  abort(agentName: string, instanceId: string, opts?: { signal?: AbortSignal }): Promise<void>;
+  /** `GET /memory-kills`: the pod's guard kills (ADR-0061, ADR-0062). A request that never left
+   * this host, and a draining Harness's 503, are sent again until `signal` ends the read — the
+   * caller owns the read's limit (the Agent actor's 5 s); with no signal, it is sent once. Any other
+   * answer but a 200 that reads — a Harness that keeps none, a transport failure, the caller's
+   * timeout — is `undefined`, "could not tell": the Harness still holds what it kept, and the next
+   * admission reads again. A kill with no id or time, with an id or a time outside the wire's bounds
+   * (`wire.ts`), or with a time that does not parse, is skipped; one whose `peak` or `limit` is not
+   * a size is kept without sizes, and one whose `told` holds an entry that is not a conversation, or
+   * a name outside the bounds, is kept without that entry — each fault said. Absent sizes are no fault: the pod left them out.
+   * Each fault is one line, said when it starts. A read that works says nothing, and the next fault
+   * after it is said again. */
+  memoryKills(opts?: { signal?: AbortSignal }): Promise<ListedKill[] | undefined>;
+  /** `POST /agents/:name/:id/abort`, with the body `{ cause, submissionId }` when a cause is given
+   * (`AbortRequest`). The `{ aborted }` answer is dropped (ADR-0024). */
+  abort(
+    agentName: string,
+    instanceId: string,
+    opts?: { signal?: AbortSignal; cause?: AbortCause; submissionId?: string },
+  ): Promise<void>;
 };
 
 export type HarnessClientOptions = {
@@ -148,8 +182,9 @@ export type HarnessClientOptions = {
   log?: (line: string) => void;
 };
 
-/** A Submission that settled `failed`/`aborted` — or whose conversation the Harness no longer
- * has (404) — surfaced to the actor as an `agent.fault`. Replaces the SDK's execution error. */
+/** A Submission that settled `failed`/`ended`/`aborted` — or whose conversation the Harness no
+ * longer has (404) — surfaced to the actor as an `agent.fault` while it still waits on the Turn.
+ * Replaces the SDK's execution error. */
 export class SettlementFault extends Error {
   /** The Settlement as the stream carried it; absent when the conversation itself was lost. */
   readonly settlement?: Settlement;
@@ -164,6 +199,83 @@ export class SettlementFault extends Error {
   }
 }
 
+/** An admission for a kept conversation (`kept`) that the Harness refused with 404: it keeps no
+ * such conversation, and it seated none (ADR-0062). `notKept` is what the Agent actor reads, as it
+ * reads `lost`: that module is wire-free. */
+export class ConversationNotKept extends Error {
+  readonly notKept = true;
+  constructor(message: string) {
+    super(message);
+    this.name = "ConversationNotKept";
+  }
+}
+
+/** The Harnesses whose memory kills this process could not read, each said once (`memoryKills`).
+ * Per process, not per client: an Agent actor builds a client for each Turn. */
+const killReadFaults = new Set<string>();
+
+/** The Harnesses whose kills — on the list or on a stream — held a field this process could not
+ * use, each said once until a clean read. Per process, like `killReadFaults`. Neither set is cleaned
+ * when a Workspace goes: no hook reaches this module from the Sandbox's destroy, and an entry is
+ * one URL per Sandbox this process ever read. */
+const badKillFaults = new Set<string>();
+
+/** Say once, until a clean read, that a Harness's kills held a field this process could not use. */
+function badKill(baseUrl: string, log: (line: string) => void, what: string): void {
+  if (badKillFaults.has(baseUrl)) return;
+  badKillFaults.add(baseUrl);
+  log(`harness ${baseUrl}: ${what} (ADR-0062)`);
+}
+
+/** A size as the guard writes one (`1.9Gi`, `512Mi`), short. The Agent's uid can write the file
+ * the list is read from, and these words go into the next Agent's Briefing as they are, so
+ * nothing else passes (ADR-0062). */
+function isSize(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 16 && /^\d{1,6}(\.\d{1,3})?(Ki|Mi|Gi|Ti)$/.test(value);
+}
+
+/** A string no longer than `max` characters. The bounds are the wire's (`wire.ts`), the same as
+ * the Harness's: the Harness counts the bytes of the JSON text, which are never fewer, so a kill it
+ * keeps is one this process keeps. An answer larger than `MAX_KILLS_BODY` is no list to act on:
+ * the Harness answers no list that large. */
+const fits = (v: unknown, max: number): v is string => typeof v === "string" && v.length <= max;
+
+/** One kill of the list as this process can use it, or undefined when it has no id or time, when
+ * its id or time is outside the wire's bounds, or when its time does not parse — the only kills
+ * that are dropped. Sizes that are not sizes are left out, so the kill is kept with no sizes; a
+ * `told` entry that is not a conversation, or whose name is outside the bounds, is left out of
+ * `told`. */
+function listedKill(value: unknown): ListedKill | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const { id, at, peak, limit, told } = value as Record<string, unknown>;
+  if (!fits(id, MAX_KILL_STAMP) || !fits(at, MAX_KILL_STAMP) || Number.isNaN(Date.parse(at))) return undefined;
+  const conversations = (Array.isArray(told) ? told.slice(0, MAX_TOLD) : []).filter(
+    (t): t is { agent: string; instanceId: string } =>
+      typeof t === "object" && t !== null && fits(t.agent, MAX_KILL_NAME) && fits(t.instanceId, MAX_KILL_NAME),
+  );
+  const sized = isSize(peak) && isSize(limit);
+  return {
+    id,
+    at,
+    told: conversations.map(({ agent, instanceId }) => ({ agent, instanceId })),
+    ...(sized ? { peak, limit } : {}),
+  };
+}
+
+/** Whether a listed kill came through as the wire states it. */
+function whole(raw: unknown, kill: ListedKill | undefined): boolean {
+  if (kill === undefined) return false;
+  const { peak, limit, told } = raw as { peak?: unknown; limit?: unknown; told?: unknown };
+  // Sizes the pod left out are no fault; sizes it sent that are not sizes are.
+  if (kill.limit === undefined && (peak !== undefined || limit !== undefined)) return false;
+  return Array.isArray(told) && Math.min(told.length, MAX_TOLD) === kill.told.length && told.length <= MAX_TOLD;
+}
+
+/** A timeout's abort reason (`AbortSignal.timeout`): a read that ran out of time, not an abandon. */
+function isTimeout(reason: unknown): boolean {
+  return reason instanceof DOMException && reason.name === "TimeoutError";
+}
+
 /** Build the real wire client from connection options. */
 export function createHarnessClient(options: HarnessClientOptions): HarnessClient {
   const { baseUrl } = options;
@@ -276,11 +388,26 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
             // The Briefing's news (ADR-0062): typed data, the Harness writes the words. Omitted
             // when there is none, so an admission without notices is byte-identical to before.
             ...(sendOptions.notices?.length ? { notices: sendOptions.notices } : {}),
+            // Omitted when unset, so an admission that is not for a kept conversation is
+            // byte-identical to before.
+            ...(sendOptions.kept ? { kept: true } : {}),
           }),
           signal: sendOptions.signal,
         },
         sendOptions.signal,
       );
+      if (sendOptions.kept && res.status === 404) {
+        // "Not kept" only with the Harness's marker: a 404 from anything else — a proxy, a route
+        // that moved — is a failed admission, as before.
+        const body = (await res.json().catch(() => undefined)) as Partial<NotKeptResponse> | undefined;
+        const detail = typeof body?.error === "string" ? body.error : res.statusText || "no detail";
+        if (body?.kept === false) {
+          throw new ConversationNotKept(
+            `harness admission refused (404): ${detail} — the Harness does not keep this conversation (ADR-0062)`,
+          );
+        }
+        throw new Error(`harness admission failed (404): ${detail}`);
+      }
       if (!res.ok) {
         throw new Error(`harness admission failed (${res.status}): ${await errorDetail(res)}`);
       }
@@ -340,8 +467,19 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
 
         for (const event of events) {
           if (event.type === "memory-limit") {
-            const { peak, limit, conversationId, position } = event;
-            opts?.onMemoryLimit?.({ peak, limit, source: `${conversationId}@${position.batch}.${position.index}` });
+            const { id, peak, limit, conversationId, position } = event;
+            // A size that is not one is not put in a Briefing (the Agent's uid can write the record):
+            // the kill is kept, with no sizes, and the fault is said.
+            const sized = isSize(peak) && isSize(limit);
+            if (!sized)
+              badKill(baseUrl, log, "a memory kill on a stream has sizes that are not sizes — kept without them");
+            // An older Harness's event has no id: keyed by its place on the stream, exactly as the
+            // Orchestrator before raised it, so a replayed read is the same kill and it can never
+            // mark a later kill seen. An id too long to be one is no id.
+            const kill = fits(id, MAX_KILL_STAMP)
+              ? { id }
+              : { id: `${conversationId}@${position.batch}.${position.index}`, legacy: true as const };
+            opts?.onMemoryLimit?.({ ...kill, ...(sized ? { peak, limit } : {}) });
             continue;
           }
           if (event.type !== "submission-settled" || event.submissionId !== admission.submissionId) continue;
@@ -355,21 +493,108 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
     async holds(agentName, instanceId, opts) {
       const url = new URL(conversationUrl(agentName, instanceId));
       url.searchParams.set("view", VIEW_HISTORY);
-      try {
-        const res = await fetchImpl(url.toString(), { headers: authorization, signal: opts?.signal });
-        // Drain the body so the socket is released; the snapshot itself is not the question.
-        await res.body?.cancel().catch(() => undefined);
-        return res.status !== 404;
-      } catch (err) {
-        if (opts?.signal?.aborted) throw err;
-        return true;
+      // Asked as a restart is seen, when the new container may not listen yet: a request that
+      // never left this host, and a draining Harness's 503, are sent again until the caller's
+      // signal ends the wait — then, and on any other failure, unknown is never loss.
+      let backoffMs = backoffInitialMs;
+      for (;;) {
+        let again = false;
+        try {
+          const res = await fetchImpl(url.toString(), { headers: authorization, signal: opts?.signal });
+          // Drain the body so the socket is released; the snapshot itself is not the question.
+          await res.body?.cancel().catch(() => undefined);
+          if (res.status !== DRAINING) return res.status !== 404;
+          again = true;
+        } catch (err) {
+          if (opts?.signal?.aborted && !isTimeout(opts.signal.reason)) throw err;
+          again = !opts?.signal?.aborted && neverDelivered(err);
+        }
+        if (!again || opts?.signal === undefined) return true;
+        try {
+          await sleep(jittered(backoffMs), opts.signal);
+        } catch (err) {
+          if (opts.signal.aborted && !isTimeout(opts.signal.reason)) throw err;
+          return true;
+        }
+        backoffMs = Math.min(backoffMs * 2, backoffMaxMs);
+      }
+    },
+
+    async memoryKills(opts) {
+      const url = new URL("/memory-kills", baseUrl).toString();
+      // Idempotent, so re-sent on what `postAdmission` re-sends — a request that never left this
+      // host, a draining Harness's 503 — on the same ladder, until the caller's signal ends it. The
+      // limit is the caller's alone, so there is one clock for it.
+      let backoffMs = backoffInitialMs;
+      let why: string;
+      for (;;) {
+        let again = false;
+        try {
+          const res = await fetchImpl(url, { headers: authorization, signal: opts?.signal });
+          if (res.status === 200 && Number(res.headers.get("content-length") ?? 0) > MAX_KILLS_BODY) {
+            await res.body?.cancel().catch(() => undefined);
+            why = `the answer is larger than ${MAX_KILLS_BODY} bytes`;
+          } else if (res.status === 200) {
+            const text = await res.text();
+            const kills =
+              text.length > MAX_KILLS_BODY ? undefined : (JSON.parse(text) as Partial<MemoryKillsResponse>).kills;
+            if (Array.isArray(kills)) {
+              // A read that works ends the fault: the next fault is said again.
+              killReadFaults.delete(baseUrl);
+              const read = kills.map(listedKill);
+              const usable = read.filter((kill): kill is ListedKill => kill !== undefined);
+              const flawed = kills.filter((raw, i) => !whole(raw, read[i])).length;
+              if (flawed === 0) badKillFaults.delete(baseUrl);
+              else {
+                badKill(
+                  baseUrl,
+                  log,
+                  `${flawed} of its memory kills are not the wire's shape — those with no id or time, or with one outside the wire's bounds or a time that does not parse, are skipped, the others are kept without the fields that were wrong`,
+                );
+              }
+              return usable;
+            }
+            why = "the answer is not a list of kills";
+          } else {
+            why = `HTTP ${res.status}: ${await errorDetail(res)}`;
+            again = res.status === DRAINING;
+          }
+        } catch (err) {
+          // A local abandon propagates, as in every other verb; a timeout the caller set is none.
+          if (opts?.signal?.aborted && !isTimeout(opts.signal.reason)) throw err;
+          why = transportDetail(err);
+          again = !opts?.signal?.aborted && neverDelivered(err);
+        }
+        if (!again || opts?.signal === undefined) break;
+        try {
+          await sleep(jittered(backoffMs), opts?.signal);
+        } catch (err) {
+          if (opts?.signal?.aborted && !isTimeout(opts.signal.reason)) throw err;
+          why = "the read's time ran out";
+          break;
+        }
+        backoffMs = Math.min(backoffMs * 2, backoffMaxMs);
+      }
+      // One line for each fault: said when it starts. A read that works says nothing, and the next
+      // fault after it is said again.
+      if (!killReadFaults.has(baseUrl)) {
+        killReadFaults.add(baseUrl);
+        log(
+          `harness ${baseUrl}: cannot read its memory kills (${why}) — no notice from them now; the Harness keeps them, and the next admission reads again (ADR-0062)`,
+        );
       }
+      return undefined;
     },
 
     async abort(agentName, instanceId, opts) {
+      // No cause, no body: the request an Orchestrator from before `cause` sent, byte for byte.
+      const body: AbortRequest | undefined = opts?.cause
+        ? { cause: opts.cause, ...(opts.submissionId ? { submissionId: opts.submissionId } : {}) }
+        : undefined;
       const res = await fetchImpl(`${conversationUrl(agentName, instanceId)}/abort`, {
         method: "POST",
-        headers: authorization,
+        headers: body ? { ...authorization, "content-type": "application/json" } : authorization,
+        ...(body ? { body: JSON.stringify(body) } : {}),
         signal: opts?.signal,
       });
       if (!res.ok) {
@@ -407,6 +632,7 @@ export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
         model: input.model,
         thinkingLevel: input.thinkingLevel,
         ...(opts.notices?.length ? { notices: opts.notices } : {}),
+        ...(opts.kept ? { kept: true } : {}),
         signal: opts.signal,
       });
     },
@@ -419,11 +645,23 @@ export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
       return await client.holds(agentName, instanceId, opts);
     },
 
-    async abort(agentName: string, instanceId: string, opts?: { signal?: AbortSignal }): Promise<void> {
+    async memoryKills(opts?: { signal?: AbortSignal }): Promise<ListedKill[] | undefined> {
+      return await client.memoryKills(opts);
+    },
+
+    async abort(
+      agentName: string,
+      instanceId: string,
+      opts?: { signal?: AbortSignal; cause?: AbortCause; submissionId?: string },
+    ): Promise<void> {
       // The result (`{ aborted }` — whether there was work to end) is dropped: by the time this
       // runs the state has already moved on, and an idle instance is exactly as fine as a
       // stopped one. Settlement is asynchronous and nothing here is listening (ADR-0024).
-      await client.abort(agentName, instanceId, { signal: opts?.signal });
+      await client.abort(agentName, instanceId, {
+        signal: opts?.signal,
+        ...(opts?.cause ? { cause: opts.cause } : {}),
+        ...(opts?.submissionId ? { submissionId: opts.submissionId } : {}),
+      });
     },
   };
 }
@@ -508,22 +746,130 @@ export function createLiveSetPush(options: {
 }
 
 /**
- * THE authoring surface for an Agent (ADR-0049): one definition in, one actor slot out —
- * `jr2Setup({ actors: { coder: agent({ model, instructions }) } })`, invoked as `src: "coder"`.
- * The slot key is the Agent's name (the Harness route, the minted iid, the markers), so a name
- * the Machine does not carry is a compile error on `src`, and two Machines in one run may each
- * carry their own `coder`.
+ * Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it. Put it
+ * under `actors` in `jr2Setup`, and invoke it by its key: `actors: { coder: agent(…) }`, then
+ * `invoke: { src: "coder", input: { prompt } }`. The key is the Agent's name.
+ *
+ * The invoke's `input` is the Turn: `prompt` (required), `cwd`, `model`, `thinkingLevel` and
+ * `continue`. `cwd` is the absolute directory where the Working tools work. Absent, it is the
+ * Worktree of the Workspace's one Repo Slot. `continue: true` continues the Agent's conversation
+ * in this Machine. Absent, each Turn starts a new conversation. `continue` is the literal `true`,
+ * not a `boolean`. A Turn can join only a conversation that an earlier Turn started with
+ * `continue: true`. Thus in a retry loop, put `continue: true` on each Turn, also on the first, so
+ * that attempt 2 sees attempt 1. Then a Runaway on the first Turn gets no second start, because a
+ * continued Turn gets none (ADR-0035). Spread it only when a state must start a clean conversation
+ * on some Turns only: `...(context.clean ? {} : { continue: true as const })`. A clean Turn does not
+ * start the continued conversation again: the next Turn with `continue: true` joins the earlier
+ * one. The Turn ends when the state that invoked the Agent exits, usually on a pick from the
+ * Agent's Menu.
  *
- * Everything live is constructed per-invocation from serializable input: the wire client from
- * `input.endpoint` (which Sandbox's Harness — or the wire-compatible dev stub; either way it's
- * only a URL, one code path). Lives here, not in actor.ts, so the actor logic and its unit tests
- * never touch the wire.
+ * The actor of an Agent never finishes, so an `onDone` on its invoke never runs. Give the Agent a
+ * pick, such as `finish`, and route on it. When a Turn fails with no pick, jr2 sends the event
+ * `agent.fault` to the Machine. It is an event, not an error of the invoke, so an `onError` does
+ * not get it. Route it on each state that invokes an Agent, or once on a state above them:
+ * `on: { "agent.fault": "failed" }`. `jr2 check` and `jr2 up` refuse a state that invokes an
+ * Agent with no route for it, and an `agent.fault` that no transition takes ends the run `error`.
  *
- * It takes a DECLARATION (ADR-0054), so a packaged Machine may write `agent({ model: open, … })`
- * and leave the one part it cannot honestly fill to whoever registers it. What rides the Turn is
- * still an `AgentDefinition`: the actor narrows on start and refuses an Open one there.
+ * An Agent with `workspace: "write"` or `"read"` works in a Sandbox, so invoke it inside a
+ * `workspace()` body. An Agent with `workspace: "none"` can run anywhere. A model can lack the
+ * definition's thinking level: see {@link ThinkingLevel}.
+ *
+ * When a Turn starts, it refuses:
+ * - a key in `input` that a Turn does not have: ``agent "<slot>": the Turn's input carries
+ *   `<key>`, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials
+ *   (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
+ * - no `cwd` under a Workspace with more than one Repo Slot: ``turn <id>: agent "<slot>" works
+ *   under a Workspace carrying more than one Repo Slot (<slots>) and its Turn framed no `cwd` —
+ *   say which Worktree it works in (`cwd: context.workspace.repos.<slot>`, one of those), because
+ *   the kit gives no slot a meaning (ADR-0051) and a Turn's Frame is where it works (ADR-0057)``
+ * - a `cwd` that is not an absolute path: ``agent "<slot>": the Turn's Frame carries a `cwd` that
+ *   is not an absolute path — the Frame says WHERE this Turn works (ADR-0057), and a Turn rooted
+ *   anywhere else would work in the wrong directory silently``. The Harness makes this refusal
+ *   when it admits the Turn, and the error starts with `harness admission failed (400): `.
+ * - an Agent with Working tools outside a `workspace()`: ``turn <id>: agent "<slot>" has
+ *   workspace: "<access>" — invoke it inside a workspace() (ambient resolution), or pass an
+ *   explicit `endpoint` (workspace-less stub path)``
+ * - a `model` that is still `open`: ``agent "<slot>" has an Open model — nobody bound it; bind it
+ *   where the Machine is registered (`customize(<machine>, { agents: { <slot>: { model:
+ *   "<provider>/<model>" } } })`), because a packaged Machine cannot pick a model on your behalf
+ *   (ADR-0054)``. `jr2 up` refuses this before it builds anything.
+ *
+ * @param declaration - The Agent's definition (see {@link AgentDefinition}). `model` may be `open`
+ *   in a Machine that you publish as a package.
+ * @returns The actor logic of the Agent's slot.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const finish = defineEvent({
+ *   name: "finish",
+ *   description: "Call this when `node --test` passes.",
+ *   input: z.object({}),
+ * });
+ * const runInput = z.object({ branch: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: BodyInput; context: BodyInput },
+ *   events: [finish],
+ *   actors: {
+ *     coder: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You fix failing tests. You change no test.",
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "fix",
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+ *   initial: "coding",
+ *   states: {
+ *     coding: {
+ *       invoke: {
+ *         src: "coder",
+ *         input: ({ context }) => ({
+ *           prompt: "Make `node --test` pass, then commit.",
+ *           cwd: context.workspace.repos.app,
+ *           thinkingLevel: "high",
+ *         }),
+ *       },
+ *       on: { finish: "done" },
+ *     },
+ *     done: { type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   input: runInput,
+ *   repos: { app: "https://github.com/you/app.git" },
+ *   spec: ({ input }) => ({ branch: input.branch }),
+ * });
+ * ```
+ *
+ * @see docs/concepts/agents-and-turns.md
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md
+ * @see docs/reference/decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md
  */
 export function agent(declaration: AgentDeclaration): AgentLogic {
+  // THE authoring surface for an Agent (ADR-0049): one definition in, one actor slot out. The
+  // slot key is the Agent's name (the Harness route, the minted iid, the markers), so a name the
+  // Machine does not carry is a compile error on `src`, and two Machines in one run may each carry
+  // their own `coder`.
+  //
+  // Everything live is constructed per-invocation from serializable input: the wire client from
+  // `input.endpoint` (which Sandbox's Harness — or the wire-compatible dev stub; either way it's
+  // only a URL, one code path). Lives here, not in actor.ts, so the actor logic and its unit
+  // tests never touch the wire.
+  //
+  // It takes a DECLARATION (ADR-0054), so a packaged Machine may write `agent({ model: open, … })`
+  // and leave the one part it cannot honestly fill to whoever registers it. What rides the Turn
+  // is still an `AgentDefinition`: the actor narrows on start and refuses an Open one there.
   return agentActorWith(
     (endpoint, bearer) => createHarnessAgentRunClient({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
     declaration,
@@ -600,26 +946,174 @@ export function createExecPort(options: {
 }
 
 /**
- * THE authoring surface for a `command` Effect (ADR-0067): `actors: { tests: command(["pnpm",
- * "test"]) }`, invoked as `src: "tests"`. `argv` is never shell text — an `arg("x")` entry is ONE
- * argument, filled from the invoke's input — and `sh -c` is the author's explicit choice. It runs
- * in the Harness container of the enclosing Workspace's Sandbox, in a Repo Slot's Worktree
- * (`slot`, needed only where the Workspace carries several); outside a Workspace it is refused.
- * Every outcome is output: `exited | timeout | killed | unknown`.
+ * Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a
+ * state invokes it. Put it under `actors` and invoke it by its key: `actors: { tests:
+ * command(["node", "--test"]) }`, then `invoke: { src: "tests", onDone: … }`.
+ *
+ * `argv` is a list, never shell text: each entry is one argument. An `arg("name")` entry is filled
+ * from the invoke's `input` (`input: { name: "…" }`), as one argument whatever its text. To use a
+ * shell, write it: `["sh", "-c", "…"]`.
+ *
+ * Where it runs:
+ * - With no Effect secret in `env`, in the Harness container of the enclosing Workspace's Sandbox.
+ *   It runs in the Worktree of a Repo Slot, or in `/work` in a Workspace with no Repo Slot. The
+ *   Agent's Working tools also run in this container.
+ * - With an Effect secret in `env`, in the Sandbox Effector, against a commit of the branch. This
+ *   is the branch tip when it starts, or with `pin: true` the commit that the invoke's `input.sha`
+ *   names. The output then says `dirty: true` when the Worktree held edits that the command did
+ *   not see.
+ *
+ * Every outcome is output for `onDone`, never an error: `{ outcome: "exited", code, tail }`,
+ * `{ outcome: "timeout", tail }`, `{ outcome: "killed", signal, tail }`, or `{ outcome: "unknown",
+ * reason }` when jr2 cannot know what happened. `tail` is the end of the output stream.
+ *
+ * After an Orchestrator restart:
+ * - A command with no Effect secret in `env` never runs twice. jr2 attaches to it again, or settles
+ *   `unknown`.
+ * - A command with an Effect secret in `env` runs again when the Sandbox Effector no longer holds
+ *   it. It runs against the same commit. If jr2 has no commit for it, it settles `unknown`.
+ *
+ * When the state exits, the command stops: jr2 kills its process group. `onError` is only for a
+ * Machine or config defect.
+ *
+ * It refuses, when you call it:
+ * - an empty `argv`: `command(argv): argv is a non-empty list — each entry one argument, never
+ *   shell text`
+ * - an entry that is not a string or `arg()`: `command(argv): an argv entry is a string or
+ *   arg("name"), got <entry>`
+ * - a `timeout` that is not a positive duration: `command: timeout "<timeout>" is not a positive
+ *   duration (like "90s", "10m", "1h")`
+ * - an `env` name that is not a variable name, or `PATH`, `HOME` or `TMPDIR`: ``command(argv, {
+ *   env }): "<name>" is not a variable the author sets — PATH, HOME and TMPDIR are the Effector's
+ *   (ADR-0067)``
+ * - `pin: true` with no Effect secret in `env`: ``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` ``
+ *
+ * And when it starts, with no Effect secret in `env`:
+ * - outside a `workspace()`: `command "<slot>" runs in the Harness container of a Workspace, and
+ *   its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
+ * - 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)`
+ * - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
+ *   its Workspace does not carry (<slots>)`
+ * - an `arg()` with no string in `input`: `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
+ *   arg's name are in the text: `argv slot <file>`. `<type>` is `nothing` when `input` has no such
+ *   field, or the type of its value, such as `number`.
+ *
+ * And when it starts, with an Effect secret in `env`:
+ * - outside a `workspace()`: `command "<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)`
+ * - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
+ *   Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" }
+ *   (ADR-0051)`
+ * - 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)`. `jr2 up` refuses it first, with the same reason
+ * - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
+ *   its Workspace does not carry (<slots>)`
+ * - `pin: true` and an `input.sha` that is not a full commit id: `command "<slot>" (pin): its
+ *   input's sha is not a full commit id`
+ * - an `arg()` with no string in `input`: the same text as above.
+ *
+ * @param argv - The program and its arguments: strings and `arg("name")` entries. Or `open`, in a
+ *   Machine that you publish as a package, for the Instance that registers it to bind with
+ *   `customize()`.
+ * @param options - Optional. `slot`: the Repo Slot whose Worktree the command runs in; needed only
+ *   where the Workspace has more than one. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
+ *   `"10m"`; when it expires, the output is `timeout`. `tail`: how many characters of the end of
+ *   the output stream to keep, default 4096. `env`: environment variables. Each value is
+ *   `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a
+ *   file that holds it. `pin`: `true` to run against the commit in `input.sha`. Use `pin` only
+ *   with an Effect secret in `env`.
+ * @returns The actor logic of the Effect's slot. Its output is a `CommandOutput`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { arg, command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ branch: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: BodyInput },
+ *   actors: {
+ *     tests: command(["node", "--test", arg("file")], { timeout: "5m" }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "check",
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "testing",
+ *   states: {
+ *     testing: {
+ *       invoke: {
+ *         src: "tests",
+ *         input: { file: "test/greet.test.js" },
+ *         onDone: [
+ *           {
+ *             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
+ *             target: "passed",
+ *           },
+ *           { target: "failed" },
+ *         ],
+ *       },
+ *     },
+ *     passed: { type: "final" },
+ *     // Not final states: each one fails the run, and the run ends `failed`.
+ *     failed: { invoke: { src: "fail", input: { reason: "the test did not pass" } } },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   input: runInput,
+ *   repos: { app: "https://github.com/you/app.git" },
+ *   spec: ({ input }) => ({ branch: input.branch }),
+ * });
+ * ```
+ *
+ * @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
+ * @see docs/reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md
+ */
+export function command<const A extends readonly (string | Arg)[], const Opt extends CommandOptions = CommandOptions>(
+  argv: A,
+  options?: Opt,
+): EffectLogic<CommandInput<A, Opt["pin"]>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>;
+/**
+ * Make a `command` Effect whose argv is Open: `command(open, options)`, in a Machine that you
+ * publish as a package. The Instance that registers the Machine binds the argv one time:
+ * `customize(machine, { effects: { <slot>: { argv } } })`. {@link command} tells the rest, and
+ * what it refuses.
+ *
+ * @param argv - `open`.
+ * @param options - Optional. The same options as for a written argv.
+ * @returns The actor logic of the Effect's slot. Its output is a `CommandOutput`.
+ *
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
  */
 export function command<const Opt extends CommandOptions = CommandOptions>(
   argv: typeof open,
   options?: Opt,
 ): EffectLogic<OpenCommandInput<Opt["pin"]>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<Opt>>;
-export function command<const A extends readonly (string | Arg)[], const Opt extends CommandOptions = CommandOptions>(
-  argv: A,
-  options?: Opt,
-): EffectLogic<CommandInput<A, Opt["pin"]>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>;
 export function command(
   argv: readonly (string | Arg)[] | typeof open,
   options: CommandOptions = {},
   // The implementation of the overloads above: each one states the input type.
 ): EffectLogic<any, CommandOutput> {
+  // THE authoring surface for a `command` Effect (ADR-0067). `argv` is never shell text — an
+  // `arg("x")` entry is ONE argument, filled from the invoke's input — and `sh -c` is the author's
+  // explicit choice. Bound to the real exec port here; `commandWith` in effect.ts is the seam the
+  // unit tests share.
+  //
   // An Open argv (ADR-0054) is the composer's to bind with `customize()`; see open-effect.ts.
   return commandWith(
     (endpoint, bearer) => createExecPort({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),