@jr2/orchestrator 0.1.4 → 0.2.1

package/src/instance.ts

@@ -29,7 +29,7 @@ import { RunHost } from "./run-host.ts";
 import type { RunRecord } from "./run-host.ts";
 import { SqliteSnapshotStore } from "./snapshot-store.ts";
 import type { SnapshotStore } from "./snapshot-store.ts";
-import { createAuthenticator, loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import { createAuthenticator, harnessToken, loadSigningKey, mintInstanceToken } from "./tokens.ts";
 import type { SandboxPort } from "./workspace.ts";
 
 export type InstanceOptions = {
@@ -113,19 +113,25 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   }
   await store.init();
 
-  // Resolved BEFORE the host: the Instance token is also the echo bearer (ADR-0023), so the
-  // host's echo pusher closes over it. Served under in step 4 below, unchanged.
+  // Resolved BEFORE the host, and the signing key with it: the host derives every Harness bearer
+  // from the key (ADR-0058) — admission, stream, abort, echo. The key is loaded from (or minted
+  // into) the instance folder, NOT generated per process: live Sandboxes outlive a restart, their
+  // Adapters still bear tokens this key signed, and their Harnesses still check bearers it derived.
+  // The Instance token is per-boot; the key is not. Both are served under in step 4 below.
   const instanceToken = opts.instanceToken ?? mintInstanceToken();
+  const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));
 
   const host = new RunHost({
     store,
     reconcile: opts.reconcile,
     sandbox: opts.sandbox,
     instanceHarness: opts.instanceHarness,
+    harnessBearer: (placement) => harnessToken(signingKey, placement),
     // The run-narrative echo (ADR-0023): tee a run's feed to its enclosing Workspace's Harness,
-    // authenticated as the instance. The wire push is here and the fire-and-forget is the
-    // host's, so a Harness that refuses (or is gone) costs a log line at most.
-    echo: (endpoint) => createEchoPush({ baseUrl: endpoint, token: instanceToken }),
+    // bearing that Workspace's Harness bearer (ADR-0058) — never the Instance token, which would
+    // otherwise pass through a process the Agent executes code beside. The wire push is here and
+    // the fire-and-forget is the host's, so a Harness that refuses (or is gone) costs a log line.
+    echo: (endpoint, bearer) => createEchoPush({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
     // A run left `live` to be retried is otherwise unexplained — the announce line names it, this
     // says why (ADR-0030). stderr, because it is a fault, not the boot's structured result.
     onRestoreError: (runId, err) =>
@@ -153,10 +159,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // discoverable by asking after a specific run id nobody knows to ask about.
   const restored = await host.restore();
 
-  // 4. Serve, authenticated (ADR-0013). The signing key is loaded from (or minted into) the
-  // instance folder, NOT generated per process: live Sandboxes outlive a restart, and their
-  // Adapters still bear tokens this key signed. The Instance token is per-boot; the key is not.
-  const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));
+  // 4. Serve, authenticated (ADR-0013) — the token and key resolved above.
   const auth = createAuthenticator({ instanceToken, signingKey });
   // The Repos are read PER REQUEST, never snapshotted here: a cache the agent cloned minutes
   // after boot must show as present the next time anyone asks (ADR-0048/0051).

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}`;
@@ -230,6 +246,13 @@ export type RunBinding = {
    * absent, a `"none"` Agent without an explicit `endpoint` fails loudly.
    */
   instanceHarness?: string;
+  /**
+   * The Harness bearer for a placement (ADR-0058): `harnessToken(signingKey, placement)`, closed
+   * over the key by the host. The Agent actor asks it for the pod its Turn resolved to; the echo
+   * attach asks it for the Workspace's. Absent (bare unit-test bindings, the stub path), no bearer
+   * is sent — which only a Harness that checks nothing accepts.
+   */
+  harnessBearer?: (placement: string) => string;
   /**
    * Record an Agent invocation's durable admission in the host ledger (ADR-0016): persisted
    * beside the snapshot in the same RunBlob save, keyed by iid (globally unique, so the map is
@@ -237,6 +260,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
@@ -251,12 +290,13 @@ export type RunBinding = {
   marker?: (event: TurnMarker) => void;
   /**
    * Attach the run-narrative echo to a Workspace's Harness (ADR-0023): the host replays the
-   * run's feed-so-far to `endpoint`, then tees live; returns the detach. Called by `workspace()`'s
+   * run's feed-so-far to `endpoint` — the Harness in `placement`'s pod, pushed with that
+   * placement's bearer (ADR-0058) — then tees live; returns the detach. Called by `workspace()`'s
    * registrar — the same restore-safe seat the ambient handles ride — and scoped to the OWNING
    * run by construction: the binding is per-run, so a sibling run's feed is unreachable.
    * Host-supplied; absent = no echo.
    */
-  echo?: (endpoint: string) => () => void;
+  echo?: (endpoint: string, placement: string) => () => void;
   /**
    * The HOST is ending this run for its own reasons (ADR-0024). An Agent invocation ending
    * normally ends the Agent's turn — the state stopped waiting — but `RunHost.stop()` is the one
@@ -303,6 +343,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

@@ -312,13 +312,18 @@ export type RunHostOptions = {
   sandbox?: SandboxPort;
   /** The Instance Harness base URL (ADR-0031) — where `workspace: "none"` Turns are admitted. */
   instanceHarness?: string;
+  /** The Harness bearer for a placement (ADR-0058) — `startInstance` closes `harnessToken` over the
+   * signing key. Handed to every run's binding, and to the echo pusher below. Absent, no Harness
+   * call bears one: only the stub Harness answers such a host. */
+  harnessBearer?: (placement: string) => string;
   /**
    * Build the run-narrative echo pusher for one Workspace's Harness (ADR-0023) — the seam a fake
-   * echo server rides in tests; `startInstance` binds the real wire push (harness-client.ts),
-   * closed over the Instance token. Absent = no echo: a host without it runs identically, because
-   * the echo is a courtesy view of the feed, never a dependency of the run.
+   * echo server rides in tests; `startInstance` binds the real wire push (harness-client.ts).
+   * `bearer` is that Workspace's Harness bearer (ADR-0058), when the host derives one. Absent = no
+   * echo: a host without it runs identically, because the echo is a courtesy view of the feed,
+   * never a dependency of the run.
    */
-  echo?: (endpoint: string) => (events: EchoEvent[]) => Promise<void>;
+  echo?: (endpoint: string, bearer: string | undefined) => (events: EchoEvent[]) => Promise<void>;
 };
 
 /** What we persist per run: the machine snapshot wrapped with the run metadata restore needs.
@@ -334,6 +339,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 +364,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;
@@ -368,7 +388,11 @@ export class RunHost {
   private readonly onRestoreError?: (runId: string, err: unknown) => void;
   private readonly sandbox?: SandboxPort;
   private readonly instanceHarness?: string;
-  private readonly echoFactory?: (endpoint: string) => (events: EchoEvent[]) => Promise<void>;
+  private readonly harnessBearer?: (placement: string) => string;
+  private readonly echoFactory?: (
+    endpoint: string,
+    bearer: string | undefined,
+  ) => (events: EchoEvent[]) => Promise<void>;
   private readonly workflowDefs = new Map<string, WorkflowDef>();
   private readonly runs = new Map<string, LiveRun>();
   /**
@@ -386,6 +410,7 @@ export class RunHost {
     this.onRestoreError = opts.onRestoreError;
     this.sandbox = opts.sandbox;
     this.instanceHarness = opts.instanceHarness;
+    this.harnessBearer = opts.harnessBearer;
     this.echoFactory = opts.echo;
   }
 
@@ -534,6 +559,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 +636,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,
@@ -865,11 +893,11 @@ export class RunHost {
    * Scoped to the OWNING run's lineage by construction: it reads one run's buffer and listeners
    * and nothing else — a sibling run's events cannot reach this endpoint through here.
    */
-  private attachEcho(runId: string, endpoint: string): () => void {
+  private attachEcho(runId: string, endpoint: string, placement: string): () => void {
     const run = this.runs.get(runId);
     const factory = this.echoFactory;
     if (!run || !factory) return () => {};
-    const push = factory(endpoint);
+    const push = factory(endpoint, this.harnessBearer?.(placement));
     let chain = Promise.resolve();
     let reported = false;
     const enqueue = (events: EchoEvent[]): void => {
@@ -929,6 +957,7 @@ export class RunHost {
     record: RunRecord,
     def: WorkflowDef,
     agents: Record<string, AgentAdmission> = {},
+    epochs: Record<string, number> = {},
   ): AnyActor {
     let live: LiveRun | undefined;
     let scheduled = false;
@@ -946,6 +975,7 @@ export class RunHost {
       table: this.table,
       sandbox: this.sandbox,
       instanceHarness: this.instanceHarness,
+      ...(this.harnessBearer ? { harnessBearer: this.harnessBearer } : {}),
       // The admission ledger's write half (ADR-0016): the Agent actor reports the durable handle the
       // moment the Harness admits it, and the ledger hits the store in the same RunBlob save. An
       // admission arriving around stop/untrack still lands in `agents` but skips the save,
@@ -955,6 +985,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) => {
@@ -969,7 +1010,7 @@ export class RunHost {
         if (run && run.binding === binding) this.feed(run, event);
       },
       // The run-narrative echo attach (ADR-0023), called from `workspace()`'s registrar.
-      echo: (endpoint) => this.attachEcho(record.runId, endpoint),
+      echo: (endpoint, placement) => this.attachEcho(record.runId, endpoint, placement),
     };
     let bound = false;
     const actor = createActor(machine, {
@@ -1002,7 +1043,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 +1052,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 +1110,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/sandbox-kubectl.ts

@@ -69,7 +69,7 @@ import { readImageRefs, resolveSandboxImage, resolveUserImage, type ImageRefs }
 import { CA_CONFIGMAP, IMAGES_KEY, IMAGES_MOUNT, REPOS_MOUNT } from "./names.ts";
 import { repoIdentity } from "./repo-identity.ts";
 import type { RepoResources } from "./repos.ts";
-import { sandboxToken } from "./tokens.ts";
+import { harnessTokenDigest, sandboxToken } from "./tokens.ts";
 import type { ProvisionedRepo, SandboxPort, WorkspaceSpec } from "./workspace.ts";
 
 /** Run one kubectl invocation to completion. `input` is piped to stdin (`apply -f -`). */
@@ -423,15 +423,23 @@ export function kubectlSandbox(opts: KubectlSandboxOptions = {}): SandboxPort {
   ];
 
   // The Harness container's env: the instance's passthrough (`harness.env` — e.g. model
-  // config) first, then the mechanism-owned vars (the Adapter address, the CA trust path), which
-  // win on collision. Note the asymmetry stands (ADR-0013): user env/envFrom land on the HARNESS
-  // container only — never on the Adapter, whose env is minted here and carries the pod's only
-  // credential.
-  const harnessEnv = (): HarnessEnvVar[] => [
-    ...(opts.env ?? []),
-    { name: "JR2_ADAPTER_URL", value: `http://127.0.0.1:${adapterPort}` },
-    ...(opts.caBundle ? [{ name: "NODE_EXTRA_CA_CERTS", value: `${CA_MOUNT}/ca.crt` }] : []),
-  ];
+  // config) first, then the mechanism-owned vars (the Adapter address, the CA trust path, the
+  // wire's gate), which win on collision. Note the asymmetry stands (ADR-0013): user env/envFrom
+  // land on the HARNESS container only — never on the Adapter, whose env is minted here and
+  // carries the pod's only credential.
+  //
+  // The gate rides LAST (ADR-0058): the digest of the bearer the Orchestrator derives for THIS
+  // Sandbox. A digest because the Agent reads this env; last because a `harness.env` entry of the
+  // same name must not be able to choose the Harness's credential.
+  const harnessEnv = (name: string): HarnessEnvVar[] => {
+    if (!opts.signingKey) throw new Error("kubectlSandbox: a Harness needs a signingKey to check its bearer");
+    return [
+      ...(opts.env ?? []),
+      { name: "JR2_ADAPTER_URL", value: `http://127.0.0.1:${adapterPort}` },
+      ...(opts.caBundle ? [{ name: "NODE_EXTRA_CA_CERTS", value: `${CA_MOUNT}/ca.crt` }] : []),
+      { name: "JR2_HARNESS_TOKEN_SHA256", value: harnessTokenDigest(opts.signingKey, name) },
+    ];
+  };
 
   /**
    * The two init steps, in order (ADR-0037). They are plain container fragments the operator
@@ -573,7 +581,7 @@ export function kubectlSandbox(opts: KubectlSandboxOptions = {}): SandboxPort {
         // this used to carry was unreachable. The seat's own vars (the fallback `HOME`) come
         // FIRST, so the instance's `harness.env` can still override them the way it overrides
         // anything the image set.
-        env: [...seat.env, ...harnessEnv()],
+        env: [...seat.env, ...harnessEnv(req.name)],
         ...(opts.envFrom?.length ? { envFrom: opts.envFrom } : {}),
         // What the AGENT gets: an address on its own loopback, and no credential anywhere. This is
         // the only thing in the pod that tells it how to reach its Machine (ADR-0013).

package/src/server.ts

@@ -25,7 +25,6 @@
 // previous deploy bound — an Instance that drops its last `workspace()` leaves `jr2 gc` able to
 // collect what it stopped using.
 
-import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { loadConfig } from "./config.ts";
 import { loadWorkflows, startInstance, type RunningInstance } from "./instance.ts";
@@ -70,10 +69,7 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
   // by nature, which is what lets live Sandboxes outlive orchestrator restarts (ADR-0013).
   const namespace = env.JR2_NAMESPACE;
 
-  // Resolved HERE, not left for startInstance to mint: every Sandbox Harness gets the token's
-  // sha-256 as its echo gate (ADR-0023, below), so the token must exist before the first
-  // provision. From the instance Secret when deployed; per-boot for a host-booted fixture,
-  // exactly as before.
+  // From the instance Secret when deployed; per-boot for a host-booted fixture.
   const instanceToken = env.JR2_INSTANCE_TOKEN ?? mintInstanceToken();
 
   // The data-plane switch (ADR-0012/0031/0051): a registered Machine COMPOSES a Sandbox — read off
@@ -124,13 +120,6 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
             name: "JR2_HARNESS_JSON",
             valueFrom: { configMapKeyRef: { name: HARNESS_CONFIGMAP, key: HARNESS_CONFIG_KEY } },
           },
-          // The echo gate (ADR-0023): the Harness verifies echo bearers against this sha-256. The
-          // digest, never the token — the Agent executes code in the Harness container, and a
-          // digest inverts to nothing (the Instance token itself never enters a Sandbox, ADR-0013).
-          {
-            name: "JR2_ECHO_TOKEN_SHA256",
-            value: createHash("sha256").update(instanceToken).digest("base64url"),
-          },
           ...(config?.harness?.env ?? []).filter((v) => v.valueFrom !== undefined),
         ],
         envFrom: [{ secretRef: { name: HARNESS_ENV_SECRET } }, ...(config?.harness?.envFrom ?? [])],

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}`;
 }