@jr2/orchestrator 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -42,11 +42,11 @@
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.1.4"
+    "@jr2/agent-protocol": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.1.4"
+    "@jr2/harness": "0.2.0"
   },
   "files": [
     "bin",

package/src/actor.ts

@@ -43,10 +43,16 @@
 // at all, and restore is a fresh process, so there is nothing to infer it from.
 
 import { fromCallback, type CallbackActorLogic } from "xstate";
-import { requireBoundAgent, type AgentDeclaration, type AgentDefinition, type ThinkingLevel } from "./agent.ts";
-import { ambientHandlesFor } from "./ambient.ts";
+import {
+  requireBoundAgent,
+  type AgentDeclaration,
+  type AgentDefinition,
+  type ThinkingLevel,
+  type WorkspaceAccess,
+} from "./agent.ts";
+import { ambientHandlesFor, type AmbientHandles } from "./ambient.ts";
 import { INSTANCE_HARNESS_SERVICE } from "./names.ts";
-import { agentAddress, resolveAccepts, runBindingOf } from "./registration.ts";
+import { agentAddress, continuedIid, resolveAccepts, runBindingOf } from "./registration.ts";
 
 /**
  * One admitted Submission — the durable re-attach handle (ADR-0016). The wire fields are
@@ -72,19 +78,33 @@ export type AgentAdmission = {
 };
 
 /**
- * What a WORKFLOW writes on an Agent slot's invoke (ADR-0015/0016/0049): this turn's prompt —
- * everything else is derived. The AGENT is not written here at all: the slot key is its name
- * (`actors: { coder: agent(def) }`, `src: "coder"`), so a name the Machine does not carry is a
- * compile error on `src` instead of a runtime miss. `jr2Setup.createMachine` wraps the invoke
- * input to finalize it into {@link AgentRunInput}: the slot key lands as `agentName`, the tool
- * menu derives from the invoking state's transitions, the instance id is minted (fresh session by
- * default; `session: "continue"` or a `conversation` pin derives a deterministic id so
- * re-invocations continue one conversation), and endpoint/sandbox resolve ambiently from the
- * enclosing `workspace()`.
+ * What a WORKFLOW writes on an Agent slot's invoke (ADR-0015/0016/0049/0057): this Turn's FRAME,
+ * its DIALS, and whether it CONTINUES — nothing else. The AGENT is not written here at all: the
+ * slot key is its name (`actors: { coder: agent(def) }`, `src: "coder"`), so a name the Machine
+ * does not carry is a compile error on `src` instead of a runtime miss.
+ *
+ * `jr2Setup.createMachine` wraps the invoke input to finalize it into {@link AgentRunInput}: the
+ * slot key lands as `agentName`, the tool menu derives from the invoking state's transitions, the
+ * instance id is MINTED (never written here — fresh by default; `continue: true` derives the
+ * Agent's one conversation in this Machine instance), and endpoint/sandbox resolve ambiently from
+ * the enclosing `workspace()`.
  */
 export type AgentTurnInput = {
-  /** This turn's task framing — lands as the conversation's next user message. */
+  /** Half this Turn's FRAME (ADR-0057) — what it is about: the prompt lands as the conversation's
+   * next user message. Neither identity nor a Dial. */
   prompt: string;
+  /**
+   * The other half of the FRAME (ADR-0057) — WHERE this Turn works: the absolute directory the
+   * Harness roots the Working tools at. Per Turn by nature, which is why no definition names one:
+   * a Worktree path (`/work/<slot>/<branch>`) exists only once a run has a branch.
+   *
+   * Absent, the actor resolves it before admission: a `workspace: "none"` Agent frames no
+   * directory (it has no Working tools to root — ADR-0028), a Workspace with ONE Repo Slot frames
+   * that slot's Worktree, a Workspace with more REFUSES the Turn (the kit gives no slot a meaning
+   * — ADR-0051 — so the state must say which), and a run with no Workspace at all frames nothing
+   * and the Harness keeps `/work`. A relative path is refused at admission, by the Harness.
+   */
+  cwd?: string;
   /**
    * This turn's DIALS (ADR-0018) — how hard to run, layered over the definition's own
    * values. One definition value may be carried by several Machines, so the same persona
@@ -92,38 +112,46 @@ export type AgentTurnInput = {
    * and the same reviewer on an architecture change want identical instructions and different
    * effort.
    *
-   * IDENTITY is deliberately absent — no `instructions`, `workspace` or `cwd` here. A call site
-   * that rewrote those would make the Agent's name a lie, and `workspace` in particular carries
+   * IDENTITY is deliberately absent — no `instructions` or `workspace` here. A call site that
+   * rewrote those would make the Agent's name a lie, and `workspace` in particular carries
    * ADR-0028's containment claim, which per-invocation escalation would void.
    */
   model?: string;
   thinkingLevel?: ThinkingLevel;
   /**
-   * Session continuity (ADR-0016). Absent = FRESH: every invocation is a new conversation
-   * (jr's lossy handoff — revision agents read notes + code, never the prior conversation).
-   * `"continue"` = the same `(state path, agent, scope)` re-invocation continues ONE
-   * conversation; the prompt lands as its next user turn.
-   */
-  session?: "continue";
-  /** Distinguishes conversations that would otherwise share a `continue` identity (e.g. a
-   * reviewer fresh per task: `scope: task.id`). */
-  scope?: string;
-  /**
-   * Pin the conversation to a workflow-chosen name — the CROSS-MACHINE continue (ADR-0016's
-   * opt-in continuation, where `session: "continue"` cannot reach: its derived id carries the
-   * invoking actor's path, so it only spans states of one machine). Invocations naming the same
-   * `conversation` derive ONE deterministic, run-scoped instance id (`<runId>/<name>/<agent>`)
-   * wherever in the actor tree they sit — a triage state before the `workspace()` and an assess
-   * state inside its body continue one conversation, the prompt landing as its next user turn.
-   * Only sound where every invocation lands on the same Harness, because a conversation is an
-   * Instance ID on ONE server: a `workspace: "none"` Agent (always the Instance Harness —
-   * definition-wins, ADR-0031) or a fixed explicit `endpoint`.
+   * Continue this Agent's ONE conversation in this Machine instance (ADR-0016, ADR-0057) — the
+   * whole continuation surface. Absent, every invocation is a FRESH conversation (jr's lossy
+   * handoff — revision agents read notes + code, never the prior conversation). Present, the
+   * prompt lands as the next user turn of that conversation, whichever state of the Machine
+   * invokes it: states differ by Menu (a coder in `implement` offers `finish`; the same coder in
+   * `fix` offers `finish` and `dispute`) and the conversation is wanted across them.
+   *
+   * It names nothing, because the id is STRUCTURAL — `<runId>/<machine actor path>/<agent>` — and
+   * a caller-chosen key could only restate that, or contradict it. Two Agents therefore never
+   * share a conversation (the name is in the id), and two Pool children never collide (each
+   * worker is its own Machine instance). A conversation jr2 has faulted is never continued: the
+   * next `continue` lands on a virgin one (ADR-0035, ADR-0057) — and re-briefing that Turn is the
+   * author's, because jr2 cannot write that prompt.
    */
-  conversation?: string;
-  /** Workspace-less runs only (stub Harness): explicit endpoint, no ambient resolution. */
+  continue?: true;
+};
+
+/**
+ * MECHANISM, not authoring surface (ADR-0057): where a Turn's Harness is and which Sandbox scopes
+ * its deliveries, STATED instead of resolved. It is the seat the stub tier sits in — a
+ * mechanics-tier test has no `workspace()` to resolve from, and a dev Harness is just a URL
+ * (ADR-0011) — so it is exported for those tests and for nothing else.
+ *
+ * A real run states neither: a Sandbox Agent resolves both ambiently from the enclosing
+ * `workspace()` (ADR-0016), and a `workspace: "none"` Agent lands on the Instance Harness
+ * (ADR-0031). Stated, it wins over both, because a URL a test wrote is the one thing no ambient
+ * walk can know about.
+ */
+export type AgentTurnPlacement = {
+  /** The Harness base URL this Turn is admitted over. */
   endpoint?: string;
-  /** Escape hatch: override the derived menu. */
-  tools?: readonly string[];
+  /** The Sandbox whose Adapter token may deliver this Turn's picks (ADR-0013). */
+  sandbox?: string;
 };
 
 /** What the actor is invoked with AFTER jr2Setup finalization: the durable handle, this turn's
@@ -149,6 +177,9 @@ export type AgentRunInput = {
    */
   sandbox?: string;
   prompt?: string;
+  /** The other half of this Turn's Frame (ADR-0057): where the Working tools are rooted. Rides the
+   * admit body beside the prompt; absent, the Harness keeps `/work`. */
+  cwd?: string;
   /** This turn's dials, passed through from {@link AgentTurnInput}. Plain strings, so they ride
    * the persisted child input; on restore the Submission already exists server-side with its
    * model fixed, so a re-attach never re-resolves them. */
@@ -160,20 +191,15 @@ export type AgentRunInput = {
    */
   attach?: AgentAdmission;
   /**
-   * This invocation is closed to the ADR-0035 reroll — set by the input mapper for
-   * `session: "continue"` and a `conversation` pin (both name an EXISTING conversation, and
-   * the runaway's one recovery is a fresh one — exactly what they opted out of), and for a
-   * caller-passed `instanceId` (fresh on its first invocation, but jr2 did not mint the id and
-   * must not derive reroll identity from one it does not own — ADR-0016's minting doctrine).
-   * A gated runaway goes straight to the terminal fault.
+   * This invocation CONTINUES an existing conversation — set by the input mapper from
+   * `continue: true` alone (ADR-0057), and nothing else. Two things hang off it:
    *
-   * A continuation carries NO check that it continues the same persona (ADR-0049, closing
-   * consequence, open): two Machines that each carry a `coder` slot and pin the same
-   * `conversation` continue one conversation under two definitions, and the second Turn gets its
-   * own instructions and Working-tool filter over the first's context. The ledger holds no
-   * definition to compare against, and adding a digest would refuse an edited-`instructions`
-   * redeploy too, which ADR-0030 lets continue — so the refusal waits on a persona identity that
-   * survives a retune.
+   *   - it is closed to the ADR-0035 reroll: the runaway's one recovery is a fresh conversation,
+   *     which is exactly what a continuation opted out of, and a continued Turn's prompt
+   *     ("Continue.") is meaningless replayed fresh. A gated runaway goes straight to the fault;
+   *   - a terminal `agent.fault` BURNS the conversation (ADR-0057): the epoch bumps in the host
+   *     ledger, so the next `continue` on this Agent mints a virgin id. Nothing is burned for a
+   *     fresh invocation, which already mints its own conversation.
    */
   continuation?: boolean;
   /** Event names (from the invoking Machine's vocabulary) this invocation accepts over MCP. */
@@ -277,6 +303,50 @@ function nudgePrompt(tools: readonly string[]): string {
   );
 }
 
+/**
+ * Where this Turn works — the Frame's other half (ADR-0057), resolved before admission.
+ *
+ * The state's own `cwd` IS the Frame and wins outright, for every Agent: what is resolved here is
+ * an ABSENT one, and a directory a state named is never second-guessed — a Menu-only Agent handed
+ * one simply has no Working tools to root there (ADR-0028/0031).
+ *
+ * Absent, a Menu-only Agent frames no directory; a Workspace with ONE Repo Slot frames that
+ * slot's Worktree, which privileges nothing because there is nothing to choose between (ADR-0051);
+ * a Workspace with more REFUSES the Turn, naming the slots in declaration order and the line that
+ * ends it, because the kit gives no slot a meaning and a wrong guess is the silent failure
+ * ADR-0057 was written for; and a run outside any Workspace frames nothing, so the Harness keeps
+ * `/work`.
+ *
+ * Resolution counts SLOTS, and a slot's Worktree is the writable branch checkout. The detached
+ * review Worktree (`AmbientHandles.review`, ADR-0028's reviewer seat) is never resolved to: it is
+ * per review round, so only the reviewing state knows which one, and it frames it (ADR-0028 hands
+ * the reviewer its path as "cwd and prompt"). A `workspace: "read"` Agent that frames nothing
+ * under a one-slot Workspace therefore works in the branch checkout with `write`/`edit` withheld
+ * and `bash` kept — the tool layer's hint, not containment (ADR-0028): containment is the
+ * detached review Worktree, and only a reviewing state that requested one can frame it.
+ *
+ * The refusal throws at invoke, like the Open-model fence: loudly, at the first Turn, before a
+ * surface is registered or a pod is spent.
+ */
+function frameCwd(
+  instanceId: string,
+  input: AgentRunInput,
+  workspace: WorkspaceAccess,
+  ambient: AmbientHandles | undefined,
+): string | undefined {
+  if (input.cwd !== undefined) return input.cwd;
+  if (workspace === "none") return undefined;
+  const slots = Object.keys(ambient?.repos ?? {});
+  if (slots.length === 0) return undefined;
+  if (slots.length === 1) return ambient!.repos[slots[0]!];
+  throw new Error(
+    `turn ${instanceId}: agent "${input.agentName}" works under a Workspace carrying more than one ` +
+      `Repo Slot (${slots.join(", ")}) 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)`,
+  );
+}
+
 /** One Agent slot's logic: the run-lifecycle actor closed over ONE definition and BRANDED with it
  * (ADR-0049). The brand is the whole resolution mechanism — the actor reads its definition off its
  * own closure, `jr2Setup` recognizes the slot by `isAgent`, and a `.provide()` that swaps the slot
@@ -285,7 +355,10 @@ function nudgePrompt(tools: readonly string[]): string {
  * The brand is a RUNTIME property, read back through `isAgent`, and deliberately NOT part of this
  * type: the unit-test seam is `provide({ actors: { coder: fake } })` (ADR-0049), and a required
  * `definition` here would make every fake carry a definition it never uses. */
-export type AgentLogic = CallbackActorLogic<AgentRunReceiveEvent, AgentTurnInput | AgentRunInput>;
+export type AgentLogic = CallbackActorLogic<
+  AgentRunReceiveEvent,
+  AgentTurnInput | (AgentTurnInput & AgentTurnPlacement) | AgentRunInput
+>;
 
 /**
  * Build one Agent slot's actor logic over an injected port factory — the seam `agent()` (bound to
@@ -313,7 +386,10 @@ export function agentActorWith(
   // Typed as the union so BOTH shapes typecheck on an invoke: jr2Setup machines write
   // AgentTurnInput (and the config wrapper finalizes it before the actor ever runs); plain
   // setup() machines must pass the finalized shape themselves — checked loudly below.
-  const logic = fromCallback<AgentRunReceiveEvent, AgentTurnInput | AgentRunInput>((args) => {
+  const logic = fromCallback<
+    AgentRunReceiveEvent,
+    AgentTurnInput | (AgentTurnInput & AgentTurnPlacement) | AgentRunInput
+  >((args) => {
     const { system, self, sendBack, receive } = args;
     const input = args.input as AgentRunInput;
     const { instanceId } = input;
@@ -339,6 +415,9 @@ export function agentActorWith(
     // are unreachable (ADR-0013).
     const binding = runBindingOf(system);
     const workspace = definition.workspace ?? "write";
+    // The enclosing workspace()'s handles, walked structurally up the actor parent chain — the
+    // Harness coordinates below and the Frame's `cwd` both read them (ADR-0013/0016/0057).
+    const ambient = ambientHandlesFor(self);
     let endpoint: string;
     let sandbox: string | undefined;
     if (input.endpoint) {
@@ -359,7 +438,6 @@ export function agentActorWith(
       // Workspace's. The Instance token still may (it is the operator, tokens.ts).
       sandbox = INSTANCE_HARNESS_SERVICE;
     } else {
-      const ambient = ambientHandlesFor(self);
       if (!ambient?.endpoint) {
         throw new Error(
           `turn ${instanceId}: agent "${input.agentName}" has workspace: "${workspace}" — ` +
@@ -371,6 +449,12 @@ export function agentActorWith(
       sandbox = input.sandbox ?? ambient.sandbox;
     }
 
+    // The Frame's other half (ADR-0057): WHERE this Turn works. Resolved HERE, before any surface
+    // is registered and before a pod is spent, because the answer is a fact about the run — a
+    // Worktree path exists only once a run has a branch, so no definition could have named it.
+    const cwd = frameCwd(instanceId, input, workspace, ambient);
+    const framed: AgentRunInput = cwd === undefined ? input : { ...input, cwd };
+
     // Register this invocation's event surface (throws on a name outside the INVOKING MACHINE's
     // vocabulary — ADR-0011's invoke-time check, scoped to `self._parent.logic` because names are
     // per-Machine — which errors the run loudly at the invoking state).
@@ -476,17 +560,23 @@ export function agentActorWith(
     // Any budget exhausting emits the ONE terminal `agent.fault { reason }`.
     void (async () => {
       const fault = (reason: string) => {
-        if (!stopped) sendBack({ type: "agent.fault", instanceId, reason } satisfies FaultTelemetry);
+        if (stopped) return;
+        // Burn the conversation before the fault lands (ADR-0057): the state the fault routes to
+        // may invoke this Agent again in the same macrostep, and its mapper must already read the
+        // bumped epoch. Continuations only — a fresh invocation mints its own conversation, so
+        // there is nothing to burn.
+        if (input.continuation) binding.bumpEpoch?.(continuedIid(self._parent, binding.runId, input.agentName));
+        sendBack({ type: "agent.fault", instanceId, reason } satisfies FaultTelemetry);
       };
       try {
         // Queue behind any abort still in flight for this iid (ADR-0024). Non-trivial only under
-        // `session: "continue"`, which is the only way two invocations share an instance id — and
+        // `continue: true`, which is the only way two invocations share an instance id — and
         // there it is mandatory: the Harness queues per conversation and an abort settles what
         // is queued behind it, so losing this race would kill the new turn before it ran, silently.
         await pendingAborts.get(instanceId);
         let admission = input.attach;
         if (!admission) {
-          admission = await client.admit(input, { definition, signal: controller.signal });
+          admission = await client.admit(framed, { definition, signal: controller.signal });
           ledger(admission);
           // The admission marker (ADR-0023): the Turn and its framing, once — a re-attach
           // continues a Turn already announced, and a nudge (below) is mechanism, not narrative
@@ -521,7 +611,7 @@ export function agentActorWith(
             currentIid = `${instanceId}-r${rerolls}`;
             registerSurface(currentIid);
             admission = await client.admit(
-              { ...input, attach: undefined, instanceId: currentIid },
+              { ...framed, attach: undefined, instanceId: currentIid },
               { definition, signal: controller.signal },
             );
             ledger(admission);
@@ -540,7 +630,7 @@ export function agentActorWith(
             reason: "no-signal nudge",
           });
           admission = await client.admit(
-            { ...input, attach: undefined, instanceId: currentIid, prompt: nudgePrompt(input.tools) },
+            { ...framed, attach: undefined, instanceId: currentIid, prompt: nudgePrompt(input.tools) },
             { definition, signal: controller.signal },
           );
           ledger(admission);

package/src/agent.ts

@@ -30,7 +30,11 @@ export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhi
  * (ADR-0031): the value the Agent actor reads off its own slot's definition to place the Turn. */
 export type WorkspaceAccess = "write" | "read" | "none";
 
-/** The plain-data Agent definition (ADR-0018). Must stay JSON-serializable: the definition rides
+/** The plain-data Agent definition (ADR-0018): IDENTITY plus one default. A Turn's Frame — what
+ * it is about and where it works — is not here and cannot be (ADR-0057): a Worktree path exists
+ * only once a run has a branch, so no definition written before the run could name one.
+ *
+ * Must stay JSON-serializable: the definition rides
  * the Turn to the Harness (ADR-0049), so anything non-serializable would be silently lost — grow
  * this contract deliberately. ADR-0028 added a restriction vocabulary (`workspace`), not an
  * extension one: custom tool implementations stay out of the contract. */
@@ -45,9 +49,6 @@ export type AgentDefinition = {
   instructions: string;
   /** Optional static description — observability, never sent to the model. */
   description?: string;
-  /** Working directory inside the Sandbox. Default `/work` — the pod volume the attach step put
-   * the worktrees on (ADR-0005); override only for non-Workspace layouts. */
-  cwd?: string;
   /** Reasoning effort. Omitted → the runtime's default. An invocation may override it for one
    * Turn (`AgentTurnInput.thinkingLevel`) — effort is a property of the task's difficulty, so the
    * same persona legitimately runs at different settings in different Machines. */
@@ -56,9 +57,9 @@ export type AgentDefinition = {
    * not `tools` (that names the control-plane Menu, what it may SAY). `"read"` withholds the
    * write/edit Working tools; bash stays, so this states intent and stops the honest path — the
    * detached review worktree is the containment. `"none"` withholds the ENTIRE Working toolset:
-   * the Menu-only Agent converses and picks from its Menu, nothing else (`cwd` is moot — only
-   * Working tools consume it) — and places the Turn on the Instance Harness (ADR-0031).
-   * Default `"write"`. */
+   * the Menu-only Agent converses and picks from its Menu, nothing else (so its Turn frames no
+   * directory — only Working tools consume one) — and places the Turn on the Instance Harness
+   * (ADR-0031). Default `"write"`. */
   workspace?: WorkspaceAccess;
 };
 

package/src/gate.ts

@@ -46,7 +46,7 @@ export const gate = fromCallback<DeliveredEvent, GateInput | undefined>(({ input
   const binding = runBindingOf(system);
   // The derived id is deterministic from machine structure, so recomputing it on every (re)start
   // is restore-stable and needs no input-mapper persistence — the mapper is only load-bearing
-  // where minting has a random component (mintIid's fresh-session suffix, ADR-0016).
+  // where minting has a random component (mintIid's fresh-Turn suffix, ADR-0016).
   const path = actorPath(self);
   const id = input.gate ?? path.join(".");
   if (!id) {

package/src/harness-client.ts

@@ -49,16 +49,21 @@ 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, definition, model?, thinkingLevel?}` → the Admission, with
-   * `streamUrl` resolved absolute. 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. The optional dials are this Submission's override layer (ADR-0018); omitted,
-   * the Harness runs the definition's own values. */
+  /** `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
+   * 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
+   * verb strips `description` (ADR-0057; see {@link admittedDefinition}). The optional dials are this Submission's override
+   * layer (ADR-0018); omitted, the Harness runs the definition's own values. */
   send(
     agentName: string,
     instanceId: string,
     options: {
       message: string;
+      /** Where the Working tools are rooted for this Turn (ADR-0057). Omitted, the Harness keeps
+       * `/work` — the stub-Harness run with no Workspace. */
+      cwd?: string;
       definition: AgentDefinition;
       model?: string;
       thinkingLevel?: ThinkingLevel;
@@ -190,9 +195,18 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
           headers: { "content-type": "application/json" },
           body: JSON.stringify({
             message: sendOptions.message,
+            // The other half of the Frame (ADR-0057): where this Turn works. Omitted only when
+            // UNSET, and the Harness keeps `/work`; anything else — including the empty string a
+            // miscomputed worktree path would produce — travels, because a `cwd` the Harness
+            // cannot read as an absolute path is a 400 there. Dropping it here would hand that
+            // Turn the `/work` default instead: the silent wrong directory ADR-0057 exists for.
+            ...(sendOptions.cwd === undefined ? {} : { cwd: sendOptions.cwd }),
             // The Agent this Turn runs (ADR-0049) — plain data, validated at admission by the
             // Harness, which 400s naming the slot rather than settling a Submission `failed`.
-            definition: sendOptions.definition,
+            // IDENTITY only: `description` is stripped here (ADR-0057). It is Console material —
+            // `machine-doc.ts` and the surface read it — and the Harness neither validates nor
+            // uses it, so it has no business on the Turn's wire.
+            definition: admittedDefinition(sendOptions.definition),
             // Omitted when unset, so an admission with no dials is byte-identical to before.
             ...(sendOptions.model ? { model: sendOptions.model } : {}),
             ...(sendOptions.thinkingLevel ? { thinkingLevel: sendOptions.thinkingLevel } : {}),
@@ -271,6 +285,15 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
   };
 }
 
+/** The definition as the ADMISSION carries it (ADR-0057): identity alone. `description` is
+ * Console material the Orchestrator strips before admission — the Harness has no use for it and
+ * no longer validates it. Every other field travels, so a field added to the definition reaches
+ * the Harness without a change here. */
+function admittedDefinition(definition: AgentDefinition): Omit<AgentDefinition, "description"> {
+  const { description: _description, ...identity } = definition;
+  return identity;
+}
+
 /** Build an `AgentRunPort` over an injected wire client. Stateless — the admission IS the handle. */
 export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
   return {
@@ -280,6 +303,10 @@ export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
       }
       return await client.send(input.agentName, input.instanceId, {
         message: input.prompt,
+        // The Frame's other half (ADR-0057) — absent on a workspace-less run, where `/work` is
+        // what the Harness keeps. Absent means UNSET: a cwd the mapper computed travels as it is,
+        // to the Harness's refusal if it is not a path.
+        ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
         definition: opts.definition,
         model: input.model,
         thinkingLevel: input.thinkingLevel,

package/src/registration.ts

@@ -156,6 +156,22 @@ export function actorPath(ref: AnyActorRef): string[] {
   return segments;
 }
 
+/**
+ * The Instance ID of an Agent's ONE continued conversation in one Machine instance (ADR-0057):
+ * `<runId>/<machine actor path>/<agent>`, which is also its epoch-0 spelling. `machine` is the
+ * actor of the INVOKING Machine — the invoke's own leaf id is deliberately absent, because every
+ * state of one Machine that says `continue` means the same conversation, and two Machine
+ * instances (two Pool children, whose ids are the items') can never meet.
+ *
+ * One derivation, two readers, so they cannot drift: `mintIid` builds every iid on it (a fresh
+ * Turn adds a random suffix, a burned conversation's successor its epoch), and the Agent actor
+ * names the conversation it burns with it.
+ */
+export function continuedIid(machine: AnyActorRef | undefined, runId: string, agentName: string): string {
+  const path = (machine ? actorPath(machine).join(".") : "") || "root";
+  return `${runId}/${path}/${agentName}`;
+}
+
 /** The address of a run's gate: gate ids are run-scoped by construction (ADR-0011). */
 export function gateAddress(runId: string, gate: string): string {
   return `gate/${runId}/${gate}`;
@@ -237,6 +253,22 @@ export type RunBinding = {
    * durable.
    */
   recordAdmission?: (instanceId: string, admission: AgentAdmission) => void;
+  /**
+   * The epoch ledger's READ half (ADR-0057): the current epoch of a continued conversation,
+   * keyed by its base Instance ID ({@link continuedIid}). The input mapper reads it AT MINT TIME,
+   * so the minted id persists with the input — a restore re-attaches the same conversation, and
+   * only a fresh transition (which re-runs the mapper) sees a bump. Optional: a bare unit-test
+   * binding has no burned conversations, so every conversation reads epoch 0.
+   */
+  epochOf?: (conversation: string) => number;
+  /**
+   * The epoch ledger's WRITE half (ADR-0057): the terminal `agent.fault` burns the conversation
+   * it ended, and the next `continue` on that Agent mints `<conversation>/<epoch>` — a virgin
+   * conversation. No fault leaves a conversation worth continuing (ADR-0035): a runaway either
+   * had its reroll or holds a poisoned context, and infra and no-signal mean the Harness that
+   * held it is unreachable. Persisted beside the snapshot with the admission ledger.
+   */
+  bumpEpoch?: (conversation: string) => void;
   /**
    * Surface absorbed-retry telemetry on the run feed (ADR-0016): attempts are observable, but
    * as `{ child, attempt }` — state-key-class data, never iids (ADR-0014's line holds on the
@@ -303,6 +335,12 @@ export function boundRunId(system: AnyActorSystem): string | undefined {
   return bindings.get(system)?.runId;
 }
 
+/** The epoch of a continued conversation, or 0 outside a jr2 host (and for one nothing has
+ * burned) — the SOFT read `jr2Setup`'s iid minting uses, beside {@link boundRunId}. */
+export function boundEpoch(system: AnyActorSystem, conversation: string): number {
+  return bindings.get(system)?.epochOf?.(conversation) ?? 0;
+}
+
 /** Actor-side: resolve the run this actor tree belongs to. Throws outside a jr2 host. */
 export function runBindingOf(system: AnyActorSystem): RunBinding {
   const binding = bindings.get(system);

package/src/run-host.ts

@@ -334,6 +334,19 @@ type RunBlob = {
   machine?: string;
   snapshot: unknown;
   agents?: Record<string, AgentAdmission>;
+  /**
+   * The EPOCH ledger (ADR-0057): a continued conversation's base Instance ID
+   * (`<runId>/<machine actor path>/<agent>`) → the epoch the next `continue` on it lands on. An
+   * entry appears only once a terminal `agent.fault` has burned that conversation; everything
+   * else reads 0, which is the unsuffixed id itself.
+   *
+   * It rides THIS blob rather than a store of its own for the same reasons `agents` does: it is
+   * per-run state with the run's exact lifetime, and saving it in the same write gives it the
+   * snapshot's atomicity — a restore that re-attached a Turn but forgot which conversations were
+   * burned would hand the next `continue` a dead one. Keyed by the BASE id (never the minted
+   * `<id>/<epoch>`), so one conversation has exactly one counter however often it burns.
+   */
+  epochs?: Record<string, number>;
   fault?: string;
 };
 
@@ -346,6 +359,8 @@ type LiveRun = {
   binding: RunBinding;
   /** The live admission ledger (ADR-0016): persisted as `RunBlob.agents`, seeded on restore. */
   agents: Record<string, AgentAdmission>;
+  /** The live epoch ledger (ADR-0057): persisted as `RunBlob.epochs`, seeded on restore. */
+  epochs: Record<string, number>;
   /** The error that killed the run, if it errored (xstate serializes Error to `{}`, so the
    * message is captured here at the observer and persisted onto the blob for `read`). */
   fault?: string;
@@ -534,6 +549,9 @@ export class RunHost {
           record,
           def,
           agents,
+          // The burned conversations come back with the admissions (ADR-0057): a restored run's
+          // next `continue` must land where this run's last one did, not on a dead conversation.
+          blob.epochs ?? {},
         );
         actor.start();
         reattached.push(stored.runId);
@@ -608,7 +626,7 @@ export class RunHost {
     // `sendBack` synchronously, so a pick that moved the Machine out of that state has already
     // destroyed this registration by now.
     //
-    // IDENTITY, not existence: under `session: "continue"` the next state re-registers the SAME
+    // IDENTITY, not existence: under `continue: true` the next state re-registers the SAME
     // address for its own turn, and that is a new turn — this one still ended.
     return {
       delivered: true,
@@ -929,6 +947,7 @@ export class RunHost {
     record: RunRecord,
     def: WorkflowDef,
     agents: Record<string, AgentAdmission> = {},
+    epochs: Record<string, number> = {},
   ): AnyActor {
     let live: LiveRun | undefined;
     let scheduled = false;
@@ -955,6 +974,17 @@ export class RunHost {
         const run = this.runs.get(record.runId);
         if (run && run.agents === agents) this.persist(run);
       },
+      // The epoch ledger's two halves (ADR-0057). The read is what the input mapper mints from;
+      // the write is the terminal `agent.fault` burning the conversation it ended, saved in the
+      // same RunBlob as the admission ledger — and, like it, saved AT THE WRITE rather than
+      // waiting for the next transition, because a crash between the fault and the next state's
+      // invoke would otherwise restore into the burned conversation.
+      epochOf: (conversation) => epochs[conversation] ?? 0,
+      bumpEpoch: (conversation) => {
+        epochs[conversation] = (epochs[conversation] ?? 0) + 1;
+        const run = this.runs.get(record.runId);
+        if (run && run.epochs === epochs) this.persist(run);
+      },
       // Absorbed-retry attempts go straight to the run's observers (SSE/CLI watch) — they are
       // feed events, not machine events (ADR-0016: the workflow sees only the terminal fault).
       telemetry: (event) => {
@@ -1002,7 +1032,7 @@ export class RunHost {
         if (ev.type === "@xstate.snapshot") schedule();
       },
     });
-    live = this.track(record, actor, def, agents, binding);
+    live = this.track(record, actor, def, agents, epochs, binding);
     return actor;
   }
 
@@ -1011,9 +1041,10 @@ export class RunHost {
     actor: AnyActor,
     def: WorkflowDef,
     agents: Record<string, AgentAdmission>,
+    epochs: Record<string, number>,
     binding: RunBinding,
   ): LiveRun {
-    const run: LiveRun = { record, actor, def, agents, binding, listeners: new Set(), feedSoFar: [] };
+    const run: LiveRun = { record, actor, def, agents, epochs, binding, listeners: new Set(), feedSoFar: [] };
     this.runs.set(record.runId, run);
     // Ordinary persistence rides the inspection stream (see `spawn`); the subscription exists
     // for the ERROR channel: an errored actor (an invoke threw — e.g. ADR-0011's invoke-time
@@ -1068,6 +1099,7 @@ export class RunHost {
       machine: fingerprintOf(run.def.machine),
       snapshot: serialized,
       agents: run.agents,
+      epochs: run.epochs,
       fault: run.fault,
     };
     const status = terminal ?? (machineStatus === "active" ? "live" : machineStatus);

package/src/setup.ts

@@ -46,7 +46,7 @@ import { eventMap, type EventDef, type EventFrom } from "@jr2/agent-protocol";
 import type { AgentRunInput, AgentTurnInput, FaultTelemetry } from "./actor.ts";
 import { isAgent } from "./agent.ts";
 import { gate } from "./gate.ts";
-import { actorPath, boundRunId } from "./registration.ts";
+import { boundEpoch, boundRunId, continuedIid } from "./registration.ts";
 import { attachInputSchema, attachVocabulary } from "./vocabulary.ts";
 
 /**
@@ -264,7 +264,9 @@ function deriveMenus(config: unknown, defs: Map<string, EventDef>, actors: Recor
       const wrapOne = (inv: LooseInvoke): LooseInvoke => {
         // The slot key IS the Agent name (ADR-0049) — read off the declaration, never authored.
         if (typeof inv?.src === "string" && isAgent(actors[inv.src])) {
-          return { ...inv, input: wrapAgentInput(inv.input, pick(names, "agent"), inv.src) };
+          const derived = pick(names, "agent");
+          if (derived.length === 0) refuseBuriedPicks(node, inv.src, path, pick);
+          return { ...inv, input: wrapAgentInput(inv.input, derived, inv.src) };
         }
         if (inv?.src === "gate") {
           const wrapped: LooseInvoke = { ...inv, input: wrapGateInput(inv.input, pick(names, "external")) };
@@ -291,32 +293,106 @@ function deriveMenus(config: unknown, defs: Map<string, EventDef>, actors: Recor
   return walk(config as LooseState, new Set(), []);
 }
 
+/**
+ * Refuse the one shape that LOOKS like a Menu and is not one (ADR-0015, ADR-0057): an Agent
+ * invoked on a state whose picks are written in its SUBSTATES.
+ *
+ * A Menu derives from the invoking state's own + ANCESTOR transitions, per statechart semantics,
+ * so a pick written below that state is one the Turn is never offered — the model is handed a
+ * Menu it cannot end its turn with, and the actor reads an empty Menu as a Turn that ended as
+ * intended, so nothing nudges and nothing faults: the run parks. Until ADR-0057 the `tools:`
+ * override papered over it; with the override gone the kit says it here, at build, where `jr2 up`
+ * walks every registered Machine.
+ *
+ * An EMPTY Menu is not itself wrong — a state moved by a Gate or a timer asks its Agent for text
+ * and nothing else — so only the contradiction is refused: no Menu here, and picks below.
+ */
+function refuseBuriedPicks(
+  node: LooseState,
+  agentName: string,
+  path: readonly string[],
+  pick: (names: Set<string>, kind: "agent" | "external") => string[],
+): void {
+  const below = new Set<string>();
+  const descend = (n: LooseState): void => {
+    for (const key of Object.keys(n.on ?? {})) if (!key.includes(".") && key !== "*") below.add(key);
+    for (const child of Object.values(n.states ?? {})) descend(child);
+  };
+  for (const child of Object.values(node.states ?? {})) descend(child);
+
+  const buried = pick(below, "agent");
+  if (buried.length === 0) return;
+  const state = path.length ? path.join(".") : "(the machine root)";
+  throw new Error(
+    `agent "${agentName}" is invoked on state "${state}", which derives an EMPTY Menu while the ` +
+      `states BELOW it handle ${buried.join(", ")} — a Menu is the invoking state's own plus its ` +
+      `ancestors' transitions (ADR-0015), so a pick written below is one the Turn can never be ` +
+      `offered, and a Turn with no Menu ends with no pick at all. Move it onto "${state}" (guard ` +
+      `it if it must not always be offered — ADR-0029), or, if this Turn is deliberately ` +
+      `menu-less, the pick belongs to another invoke.`,
+  );
+}
+
 const resolveInput = (orig: unknown, args: InputArgs): Record<string, unknown> =>
   (typeof orig === "function" ? (orig as (a: InputArgs) => unknown)(args) : (orig ?? {})) as Record<string, unknown>;
 
+/**
+ * Every key a Turn's input may carry (ADR-0057): the Frame (`prompt`, `cwd`), the Dials (`model`,
+ * `thinkingLevel`), `continue`, and the Placement seat the stub tier states (`endpoint`,
+ * `sandbox`). Anything else is refused at RUNTIME, because no type can catch it: an invoke's input
+ * is a function returning a union, and the conditional spreads authors write inside it defeat
+ * excess-property checking — so a misspelled `continue` or a key from some other surface would
+ * compile and then silently take a fresh conversation every Turn, the class of quiet wrong
+ * behavior ADR-0057 was written to end.
+ */
+const TURN_INPUT_KEYS: ReadonlySet<string> = new Set([
+  "prompt",
+  "cwd",
+  "continue",
+  "model",
+  "thinkingLevel",
+  "endpoint",
+  "sandbox",
+]);
+
+/** Refuse a Turn whose input carries a key a Turn has no use for, before anything is minted or
+ * admitted. The message names the slot, the keys found, and the whole surface (ADR-0057). */
+function refuseUnknownKeys(consumer: object, agentName: string): void {
+  const unknown = Object.keys(consumer).filter((key) => !TURN_INPUT_KEYS.has(key));
+  if (unknown.length === 0) return;
+  throw new Error(
+    `agent "${agentName}": the Turn's input carries ${unknown.map((k) => `\`${k}\``).join(", ")}, which a ` +
+      `Turn has no use for — its input is its Frame (\`prompt\`, \`cwd\`), its Dials (\`model\`, ` +
+      `\`thinkingLevel\`), and \`continue\` (ADR-0057)`,
+  );
+}
+
 /** Wrap an Agent slot's invoke input: name the Agent (the slot key), append the derived menu, and
  * finalize the mechanism fields. */
 function wrapAgentInput(orig: unknown, derived: string[], agentName: string) {
   return (args: InputArgs): AgentRunInput => {
     const consumer = resolveInput(orig, args) as Partial<AgentTurnInput & AgentRunInput>;
+    refuseUnknownKeys(consumer, agentName);
     return {
       agentName,
-      instanceId: consumer.instanceId ?? mintIid(consumer, agentName, args.self),
+      // jr2 mints every id (ADR-0016, ADR-0057): the Turn's input carries no id to honor, so
+      // nothing a Machine writes can address a conversation jr2 did not derive.
+      instanceId: mintIid(consumer, agentName, args.self),
       endpoint: consumer.endpoint,
       sandbox: consumer.sandbox,
       prompt: consumer.prompt,
+      // The Frame's other half (ADR-0057) — WHERE this Turn works. Passed through as written; the
+      // actor resolves an ABSENT one against the enclosing Workspace, which only it can see.
+      cwd: consumer.cwd,
       // This turn's dials (ADR-0018) — passed straight through; the Harness layers
       // them over the definition when the Submission starts.
       model: consumer.model,
       thinkingLevel: consumer.thinkingLevel,
-      // ADR-0035's reroll gate: closed to `session: "continue"` and a `conversation` pin (the
-      // runaway recovery is a FRESH conversation — exactly what they opted out of), and to a
-      // caller-passed iid — fresh on first use, but not jr2-minted, so no reroll identity may
-      // derive from it (ADR-0016's minting doctrine).
-      ...(consumer.session === "continue" || consumer.conversation || consumer.instanceId
-        ? { continuation: true }
-        : {}),
-      tools: consumer.tools ?? derived,
+      // ADR-0035's reroll gate: closed to `continue: true`, which names an EXISTING conversation
+      // while the runaway's one recovery is a fresh one — exactly what it opted out of.
+      ...(consumer.continue === true ? { continuation: true } : {}),
+      // The Menu (ADR-0015): always the derived one, since ADR-0057 retired the override.
+      tools: derived,
     };
   };
 }
@@ -330,31 +406,30 @@ function wrapGateInput(orig: unknown, derived: string[]) {
 }
 
 /**
- * Mint the instance id (ADR-0016). It is minted in the INPUT MAPPER — not the actor — because
- * the input is the persistence vehicle: restore re-spawns from the persisted input without
- * re-running the mapper (same conversation), while a fresh transition re-runs it (new one).
+ * Mint the instance id (ADR-0016, ADR-0057). It is minted in the INPUT MAPPER — not the actor —
+ * because the input is the persistence vehicle: restore re-spawns from the persisted input
+ * without re-running the mapper (same conversation), while a fresh transition re-runs it.
  *
- * - Default (fresh session, jr's lossy handoff): a new conversation per invocation — a random
- *   suffix under a readable `<runId>/<actor-path>/<agent>` prefix.
- * - `session: "continue"` (+ optional `scope`): the iid derives deterministically from
- *   `(run, actor path, agent, scope)`, so re-invocations continue ONE flue conversation. The
- *   actor path excludes the root actor (its id is generated per process — everything below it
- *   is author-named and stable across restore). Invoking a continue iid that is already live
- *   fails loudly at the registration table (one live surface per address).
- * - `conversation` (the cross-machine continue): a workflow-chosen name REPLACES the actor path,
- *   so invocations in different machines — a pre-workspace triage state and a state inside the
- *   `workspace()` body — derive one iid and continue one conversation. Same determinism, same
- *   restore behavior, same already-live check as `session: "continue"`.
+ * Both spellings are built on {@link continuedIid}, `<runId>/<machine actor path>/<agent>` — the
+ * Agent's ONE conversation in this Machine instance. The machine actor path excludes the root
+ * actor (its id is generated per process) and the invoke's own leaf id (states of one Machine
+ * share the conversation, ADR-0057), so two Pool children — whose ids are their items' — can
+ * never meet.
+ *
+ * - Default (FRESH, jr's lossy handoff): a new conversation per invocation — that id plus a
+ *   random suffix.
+ * - `continue: true`: that id exactly, at epoch 0 — the author writes a boolean, because in a
+ *   state machine the identity (the run, the Machine instance, the Agent slot) is already on the
+ *   page. Once jr2 has faulted the conversation, the ledger's epoch suffixes it (`<id>/1`,
+ *   `<id>/2`, …): a virgin conversation, since no fault leaves one worth continuing (ADR-0035).
+ *   **Epoch 0 is never spelled** — the unsuffixed id IS the first conversation, which keeps the
+ *   common case readable on the Harness route, in the ledger and in the logs. Invoking a live
+ *   continued id fails loudly at the registration table (one live surface per address).
  */
-function mintIid(
-  consumer: { session?: "continue"; scope?: string; conversation?: string },
-  agentName: string,
-  self: AnyActorRef,
-): string {
+function mintIid(consumer: { continue?: true }, agentName: string, self: AnyActorRef): string {
   const runId = boundRunId(self.system) ?? "local";
-  const scope = consumer.scope ? `/${consumer.scope}` : "";
-  if (consumer.conversation) return `${runId}/${consumer.conversation}/${agentName}${scope}`;
-  const path = actorPath(self).join(".") || "root";
-  if (consumer.session === "continue") return `${runId}/${path}/${agentName}${scope}`;
-  return `${runId}/${path}/${agentName}${scope}/${randomUUID().slice(0, 8)}`;
+  const conversation = continuedIid(self, runId, agentName);
+  if (!consumer.continue) return `${conversation}/${randomUUID().slice(0, 8)}`;
+  const epoch = boundEpoch(self.system, conversation);
+  return epoch === 0 ? conversation : `${conversation}/${epoch}`;
 }

package/src/stub-harness.ts

@@ -6,7 +6,8 @@
 // silent real Harness, and e2e drives it by playing the agent against `/mcp/<iid>` instead.
 //
 // Wire (ADR-0027 — the normative model of the five endpoints; `@jr2/harness` serves it for real):
-//   POST /agents/:name/:id  {message, definition, model?, thinkingLevel?} → 200 { streamUrl, offset, submissionId }
+//   POST /agents/:name/:id  {message, cwd?, definition, model?, thinkingLevel?} → 200 { streamUrl, offset, submissionId }
+//     (`message` and `cwd` are the Turn's Frame — what it is about and where it works, ADR-0057)
 //   GET  /agents/:name/:id?offset=…[&view=updates] → 200 `[]` + Stream-Next-Offset/Up-To-Date
 //   GET  /agents/:name/:id?…&live=long-poll        → parked; 204 + same headers on timeout
 //   POST /agents/:name/:id/abort                   → 200 { aborted }
@@ -32,15 +33,19 @@
 import { createServer } from "node:http";
 import type { AddressInfo, Socket } from "node:net";
 
-/** One admission of an Agent: which slot, which durable exchange, the prompt, the DEFINITION the
- * Machine's slot carried here (ADR-0049), and this Submission's dials (ADR-0018) — captured so a
- * mechanics-tier test can assert which Agent a state ran and at what settings, exactly as it
- * asserts the prompt. The stub is inert and never READS the definition: a real Harness runs it,
- * this one only proves it rode the wire. */
+/** One admission of an Agent: which slot, which durable exchange, this Turn's FRAME (the prompt
+ * and where it works — ADR-0057), the DEFINITION the Machine's slot carried here (ADR-0049), and
+ * this Submission's dials (ADR-0018) — captured so a mechanics-tier test can assert which Agent a
+ * state ran, at what settings and in which directory, exactly as it asserts the prompt. The stub
+ * is inert and never READS any of it: a real Harness runs the Turn, this one only proves each
+ * piece rode the wire. */
 export type Admission = {
   agentName: string;
   instanceId: string;
   message?: string;
+  /** Where the Working tools would be rooted (ADR-0057). Absent when the Turn carried no `cwd`,
+   * which is the workspace-less run a real Harness answers with `/work`. */
+  cwd?: string;
   definition?: Record<string, unknown>;
   model?: string;
   thinkingLevel?: string;
@@ -122,12 +127,21 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
       req.on("data", (chunk: Buffer) => (body += chunk));
       req.on("end", () => {
         const sent = safeParse(body) as
-          | { message?: string; definition?: Record<string, unknown>; model?: string; thinkingLevel?: string }
+          | {
+              message?: string;
+              cwd?: string;
+              definition?: Record<string, unknown>;
+              model?: string;
+              thinkingLevel?: string;
+            }
           | undefined;
         const admission: Admission = {
           agentName: decodeURIComponent(agentName),
           instanceId: decodeURIComponent(instanceId),
           message: sent?.message,
+          // Recorded only when the Frame carried one, so an admission without a `cwd` reads as
+          // the absence it is rather than a directory the state never named (ADR-0057).
+          ...(sent?.cwd === undefined ? {} : { cwd: sent.cwd }),
           ...(sent?.definition ? { definition: sent.definition } : {}),
           ...(sent?.model ? { model: sent.model } : {}),
           ...(sent?.thinkingLevel ? { thinkingLevel: sent.thinkingLevel } : {}),

package/src/vocabulary.ts

@@ -82,7 +82,8 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
 /**
  * What the HOST adds to the input of the machine a run STARTS with, beside the door
  * (`RunHost.start`). One field today: the run's seed Instance ID, minted with the run and
- * reported by `jr2 status`, so an external caller can address the run's first conversation.
+ * reported by `jr2 status`. It names the RUN, never a conversation — jr2 mints every Agent
+ * Instance ID in the input mapper (ADR-0016, ADR-0057), and a Machine cannot pass one in.
  *
  * It is deliberately NOT door material (ADR-0033): no caller sends it — `start` overwrites
  * whatever arrived, after the parse — and it is never served as JSON Schema, so putting it in a