@jr2/orchestrator 0.4.1 → 0.6.0

package/src/size.ts

@@ -23,15 +23,73 @@
 /** A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory). */
 export type Quantity = string | number;
 
+// A Size (ADR-0060, GLOSSARY.md "Size"): `limits.memory` and `limits.cpu`, nothing else. A field
+// left out resolves down the chain (`resolveSize`) — the Instance's `sandbox.resources`, then the
+// kit default (`KIT_SIZE`). The same shape is the User Container's split (`userSeatOf`,
+// `splitSize`), where a field left out means the seat has no limit of its own for it and shares
+// the pod's budget.
 /**
- * A Size (ADR-0060, GLOSSARY.md "Size"): `limits.memory` and `limits.cpu`, nothing else. A field
- * left out resolves down the chain (`resolveSize`) — the Instance's `sandbox.resources`, then the
- * kit default of 2Gi and 1 cpu.
+ * The Size of a Workspace: the most memory and cpu that its whole Sandbox can use. jr2 reserves
+ * all of it on the node. Thus a Sandbox never gets less than its Size and never uses more.
  *
- * The same shape is the User Container's split (`user: { image, resources }`), where a field left
- * out means the seat has no limit of its own for it and shares the pod's budget.
+ * Write it as `{ limits: { memory, cpu } }`. You can write it in three places: the `resources`
+ * option of `workspace()`, `customize(machine, { resources })`, and `sandbox.resources` in
+ * `jr2.config.ts`. The Size is a fact of the Machine. The Instance's `sandbox.resources` applies
+ * only to a Workspace that states no Size. A field that neither states comes from the kit default:
+ * memory `2Gi`, cpu `1`.
+ *
+ * The same shape is the User Container's part of the Size, in `user: { image, resources }`. There,
+ * a field you leave out gives the User Container no limit of its own: it shares the pod's budget.
+ *
+ * It refuses any key but `limits.memory` and `limits.cpu`, where you write it. The message names
+ * the field: `<where>` is where you wrote the Size, for example `workspace(): resources`.
+ *
+ * - `<where>.requests is not accepted — jr2 reserves the whole Size, so every request equals its
+ *   limit — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template
+ *   size (ADR-0060)`
+ * - `<where>.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing else —
+ *   Agent Substrate's template size (ADR-0060)`
+ * - `<where>.limits.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing
+ *   else — Agent Substrate's template size (ADR-0060)`
+ * - `<where>.limits.memory: <value> is not a positive quantity (e.g. "2Gi", "512Mi")`, and for
+ *   cpu, `<where>.limits.cpu: <value> is not a positive quantity (e.g. "2", "1500m")`
+ *
+ * `jr2 up` also refuses a Size that leaves the Harness container less than its floor. The message
+ * starts with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or
+ * with `the Size leaves the Harness container no cpu:`. The text that follows names each number
+ * and where it came from.
+ *
+ * @example
+ * ```ts
+ * import { customize, type Size } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * const size: Size = { limits: { memory: "4Gi", cpu: "2" } };
+ *
+ * export const machine = customize(task, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ *   resources: size,
+ * });
+ * ```
+ *
+ * @see docs/guides/size-a-workspace.md
+ * @see docs/concepts/workspaces.md
+ * @see docs/reference/decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md
  */
-export type Size = { limits: { memory?: Quantity; cpu?: Quantity } };
+export type Size = {
+  /** The two limits. Write `limits: {}` to state no field: each field then comes from the next
+   * source. */
+  limits: {
+    /** The memory limit, as a Kubernetes quantity: `"4Gi"`, `"512Mi"`, or a number of bytes.
+     * It must be more than zero. When you leave it out, it comes from the next source, as above. */
+    memory?: Quantity;
+    /** The cpu limit, as a Kubernetes quantity: `"2"`, `"1500m"`, or a number of cpus. It must be
+     * more than zero. jr2 enforces it. When you leave it out, it comes from the next source, as
+     * above. */
+    cpu?: Quantity;
+  };
+};
 
 /** The kit's default Size (ADR-0060). Node gives each process a V8 heap of about 55% of its
  * container limit, and `tsc` on a mid-size repo aborted below about 1.1Gi, so 1Gi fails a common
@@ -303,11 +361,65 @@ export function splitSize(size: ResolvedSize, user?: Size): SizeSplit {
 
 // --- the User Container seat -------------------------------------------------------------------
 
+// The User Container as a Machine states it (ADR-0005, ADR-0060): an image in ADR-0037's two
+// shapes, and optionally its split of the Size. The object form exists for the split alone.
 /**
- * The User Container as a Machine states it (ADR-0005, ADR-0060): an image in ADR-0037's two
- * shapes, and optionally its split of the Size. The object form exists for the split alone.
+ * The User Container in its object form: its image, and its part of the Workspace's Size. The User
+ * Container is an optional container of your own in the Sandbox pod. It runs its own entrypoint
+ * with `/work` mounted, and jr2 never builds into it, probes it or sends it commands. Use it for a
+ * service that must run without an Agent, such as an sshd.
+ *
+ * Write it in the `user` option of `workspace()` or of `customize()`. That option also takes the
+ * image as a string; use this object form only to give the User Container a part of the Size. A
+ * `customize()` that names `user` replaces the whole User Container, its part of the Size
+ * included.
+ *
+ * It refuses, where you write it. `<where>` is `workspace()` or `customize()`:
+ *
+ * - an image that is not a non-empty string. The message starts with
+ *   `` <where>: `user` must be a non-empty string (an image), or { image, resources? } ``.
+ * - `<where>: user.<key> is not accepted — the User Container is { image, resources? } (ADR-0005,
+ *   ADR-0060)`
+ *
+ * `resources` is checked as a {@link Size}, with the same refusals.
+ *
+ * `jr2 up` refuses a part that leaves the Harness container less than its floor. The message starts
+ * with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or with
+ * `the Size leaves the Harness container no cpu:`. The text that follows names each number and
+ * where it came from.
+ *
+ * @example
+ * ```ts
+ * import { customize, type UserContainer } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * const sshd: UserContainer = {
+ *   image: "registry.example.com/sshd:1.0",
+ *   resources: { limits: { memory: "256Mi", cpu: "250m" } },
+ * };
+ *
+ * export const machine = customize(task, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ *   user: sshd,
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/size-a-workspace.md
+ * @see docs/reference/decisions/0005-sandbox-pod-composition.md
+ * @see docs/reference/decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md
  */
-export type UserContainer = { image: string; resources?: Size };
+export type UserContainer = {
+  /** The image: a `file:` URL to a docker context that your module ships
+   * (`import.meta.resolve("./sshd")`), which `jr2 up` builds, or a registry ref. It must not be
+   * empty. */
+  image: string;
+  /** This container's part of the Workspace's Size, as a Size. jr2 takes it from the Harness
+   * container's part. A field you leave out gives this container no limit of its own for it: it
+   * shares the pod's budget. Default: no part. */
+  resources?: Size;
+};
 
 /** The `user` option in either shape, read as its two halves. */
 export function userSeatOf(user: string | UserContainer | undefined): { image?: string; resources?: Size } {

package/src/snapshot-store.ts

@@ -4,7 +4,8 @@
 // store is owed — with `:memory:` for tests. A persist survives a process crash, not a power loss
 // (WAL, `synchronous=NORMAL`), and the write stays synchronous so the row is on disk before the
 // Machine's next side effect runs. `markLost` records a run whose live state could not be
-// re-hydrated (e.g. its flue handle is gone); a non-live row lives a week, then `sweep` deletes it.
+// re-hydrated (e.g. its flue handle is gone), keeping any snapshot the row had; a non-live row
+// lives a week, then `sweep` deletes it.
 
 import { DatabaseSync } from "node:sqlite";
 import type { StoredSnapshot } from "./durability.ts";
@@ -37,18 +38,31 @@ export interface SnapshotStore {
    * silently to the live one, which makes resolution unsound.
    */
   findIdsByPrefix(prefix: string, limit: number): Promise<string[]>;
+  /**
+   * The run whose blob carries the idempotency key `effect` (`dispatchedBy.effect`, ADR-0071), in
+   * any status, or undefined: what answers a re-sent dispatch with the run it already started. A
+   * row `markLost` wrote with no save before it has no snapshot, and so no key; a swept row is gone
+   * with its key.
+   */
+  findByDispatch(effect: string): Promise<string | undefined>;
   save(runId: string, snapshot: unknown, status?: string): Promise<void>;
+  /**
+   * Record a run whose live state could not be re-hydrated. An upsert: a row that was saved KEEPS
+   * its snapshot and its idempotency key, because a lost dispatched run must keep answering its
+   * key — a re-send from its caller would otherwise start a second run (ADR-0071). Only a run with
+   * no row before gets a row with no snapshot.
+   */
   markLost(runId: string, reason: string): Promise<void>;
   /**
    * Record a run this Orchestrator can no longer read (ADR-0030, ADR-0069) — refused, not resumed:
    * the Assembly its snapshot names is not on the volume, was published for another Kit version or
    * does not load, or its Machine's shape does not match the snapshot's stamp.
    *
-   * Unlike {@link markLost} this KEEPS the snapshot. A lost run has nothing left to look at, so
-   * nulling it costs nothing; a drifted run is intact and only unreadable by this Orchestrator,
-   * and it is the one a human most needs to inspect. Nulling it would also hide the run
-   * entirely: `read()` returns undefined for a null blob, so `jr2 status <id>` would answer
-   * `no run` — a refusal indistinguishable from a run that never existed.
+   * An UPDATE of a row that is there, and it KEEPS the snapshot: a drifted run is intact and only
+   * unreadable by this Orchestrator, and it is the one a human most needs to inspect. Nulling it
+   * would also hide the run entirely: `read()` returns undefined for a null blob, so
+   * `jr2 status <id>` would answer `no run` — a refusal indistinguishable from a run that never
+   * existed. It keeps the row's idempotency key too (ADR-0071).
    */
   markDrifted(runId: string, reason: string): Promise<void>;
   close(): Promise<void>;
@@ -62,6 +76,20 @@ type Row = {
   updated_at: string;
 };
 
+/** The lookup `findByDispatch` runs, exported so a test can ask the planner about THIS statement,
+ * not a copy of it: the column is indexed, so the plan is a seek. */
+export const FIND_BY_DISPATCH_SQL = `SELECT run_id FROM machine_snapshots
+  WHERE dispatch_effect = ? ORDER BY rowid LIMIT 1`;
+
+/** The idempotency key a blob carries at `dispatchedBy.effect` (ADR-0071), or null. */
+function dispatchEffectOf(snapshot: unknown): string | null {
+  if (typeof snapshot !== "object" || snapshot === null) return null;
+  const by = (snapshot as { dispatchedBy?: unknown }).dispatchedBy;
+  if (typeof by !== "object" || by === null) return null;
+  const effect = (by as { effect?: unknown }).effect;
+  return typeof effect === "string" ? effect : null;
+}
+
 export class SqliteSnapshotStore implements SnapshotStore {
   private readonly db: DatabaseSync;
 
@@ -83,6 +111,16 @@ export class SqliteSnapshotStore implements SnapshotStore {
         updated_at TEXT
       )
     `);
+    // The idempotency key of a dispatched run (ADR-0071) is copied out of its blob into a column of
+    // its own when `save` writes the row, and the column is indexed. Not an expression index over
+    // `json_extract(snapshot, …)`: that runs on every row and THROWS on a blob SQLite's JSON parser
+    // refuses (nested about a thousand deep), so one such row would fail its own save and every
+    // later `init()` over the volume. A column also costs no JSON parse a save.
+    const columns = this.db.prepare(`PRAGMA table_info(machine_snapshots)`).all() as Array<{ name: string }>;
+    if (!columns.some((c) => c.name === "dispatch_effect")) {
+      this.db.exec(`ALTER TABLE machine_snapshots ADD COLUMN dispatch_effect TEXT`);
+    }
+    this.db.exec(`CREATE INDEX IF NOT EXISTS machine_snapshots_dispatch_effect ON machine_snapshots(dispatch_effect)`);
   }
 
   async load(runId: string): Promise<StoredSnapshot | null> {
@@ -151,18 +189,24 @@ export class SqliteSnapshotStore implements SnapshotStore {
     return rows.map((row) => row.run_id);
   }
 
+  async findByDispatch(effect: string): Promise<string | undefined> {
+    const row = this.db.prepare(FIND_BY_DISPATCH_SQL).get(effect) as { run_id: string } | undefined;
+    return row?.run_id;
+  }
+
   async save(runId: string, snapshot: unknown, status = "live"): Promise<void> {
     this.db
       .prepare(
-        `INSERT INTO machine_snapshots (run_id, status, snapshot, reason, updated_at)
-         VALUES (?, ?, ?, NULL, ?)
+        `INSERT INTO machine_snapshots (run_id, status, snapshot, reason, updated_at, dispatch_effect)
+         VALUES (?, ?, ?, NULL, ?, ?)
          ON CONFLICT(run_id) DO UPDATE SET
            status = excluded.status,
            snapshot = excluded.snapshot,
            reason = NULL,
-           updated_at = excluded.updated_at`,
+           updated_at = excluded.updated_at,
+           dispatch_effect = excluded.dispatch_effect`,
       )
-      .run(runId, status, JSON.stringify(snapshot), new Date().toISOString());
+      .run(runId, status, JSON.stringify(snapshot), new Date().toISOString(), dispatchEffectOf(snapshot));
   }
 
   async markLost(runId: string, reason: string): Promise<void> {

package/src/stub-harness.ts

@@ -5,20 +5,26 @@
 // the durable stream open, and never act — the Machine parks exactly as it would against a
 // 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, 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)
+// Wire (ADR-0027 — the normative model of the conversation endpoints; `@jr2/harness` serves it for
+// real), and the pod's memory kills, which a stub never has (ADR-0062):
+//   POST /agents/:name/:id  {message, cwd?, definition, model?, thinkingLevel?, notices?, kept?} → 200 { streamUrl, offset, submissionId }
+//     (`message` and `cwd` are the Turn's Frame — what it is about and where it works, ADR-0057;
+//     `kept` admits as any POST does, because the stub keeps every conversation — the real Harness
+//     answers 404 when it keeps none, ADR-0062)
 //   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 }
+//   POST /agents/:name/:id/abort  [{cause?}]       → 200 { aborted }
 //   GET  /agents/:name/:id?view=history            → 200 { …, settlements }
+//   GET  /memory-kills                             → 200 { kills: [] }
 // (the client's `wait(admission)` long-polls `streamUrl?view=updates` from the admission offset;
 // an empty stream parks it — exactly the "admitted, never settles" semantics the mechanics tier
 // needs.) The client then re-polls calmly at the long-poll cadence. `close()` severs parked polls.
 //
-// A stub submission therefore ends exactly one way: ABORTED, when the state that asked for the
-// turn stops waiting (ADR-0024). That is what `history`'s `settlements` carries, and it is the
-// only place a black-box test can see a turn end — the run itself is untouched by an abort.
+// A stub submission therefore ends one way: the sweep, when the state that asked for the turn stops
+// waiting (ADR-0024). Its outcome follows the sweep's cause, as the real Harness's does: `ended` for
+// the running Submission when the Turn's own pick ended it (`cause: "pick"`), `aborted` for every
+// other Submission and every other end. That is what `history`'s `settlements` carries, and it is
+// the only place a black-box test can see a turn end — the run itself is untouched by an abort.
 //
 // This can later grow scriptable behavior or be swapped for a real local Harness without
 // touching actor code — it is only a different URL.
@@ -55,8 +61,8 @@ export type Admission = {
 };
 
 /** One settled submission, in the shape `history()` reports it. The stub settles submissions for
- * exactly one reason — an abort (ADR-0024) — so `outcome` has exactly one value here. */
-export type StubSettlement = { submissionId: string; outcome: "aborted" };
+ * exactly one reason — an abort (ADR-0024) — so `outcome` is one of the two a sweep gives. */
+export type StubSettlement = { submissionId: string; outcome: "ended" | "aborted" };
 
 export type StubHarnessOptions = {
   /** Listen port. Default 0 → ephemeral (read back from `url`). */
@@ -102,17 +108,39 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
     // End every in-flight and queued submission for one instance (`agents.abort` — ADR-0024).
     // Answers `{ aborted }`: whether there was anything to end, exactly as the real Harness
     // does for an idle instance. Settlement is recorded here rather than pushed on the stream, because nothing is
-    // listening — the actor that asked for the turn is already stopped.
+    // listening — the actor that asked for the turn is already stopped. The body's cause decides the
+    // running Submission's outcome, the first unsettled one (`AbortRequest`): `ended` for `pick` with
+    // that Submission's id; no body, another id, or any other cause, `aborted`. What is queued
+    // behind it never ran: `aborted`.
     const aborting = req.method === "POST" && ABORT_PATH.exec(url.pathname);
     if (aborting) {
       const [, agentName, instanceId] = aborting as unknown as [string, string, string];
-      const k = key(decodeURIComponent(agentName), decodeURIComponent(instanceId));
-      const ended = unsettled.get(k)?.splice(0) ?? [];
-      const settled = settlements.get(k) ?? [];
-      settled.push(...ended.map((submissionId) => ({ submissionId, outcome: "aborted" as const })));
-      settlements.set(k, settled);
+      let body = "";
+      req.on("data", (chunk: Buffer) => (body += chunk));
+      req.on("end", () => {
+        const sent = safeParse(body) as { cause?: unknown; submissionId?: unknown } | undefined;
+        const k = key(decodeURIComponent(agentName), decodeURIComponent(instanceId));
+        const ended = unsettled.get(k)?.splice(0) ?? [];
+        const byPick = sent?.cause === "pick" && sent.submissionId === ended[0];
+        const settled = settlements.get(k) ?? [];
+        settled.push(
+          ...ended.map((submissionId, i) => ({
+            submissionId,
+            outcome: byPick && i === 0 ? ("ended" as const) : ("aborted" as const),
+          })),
+        );
+        settlements.set(k, settled);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ aborted: ended.length > 0 }));
+      });
+      return;
+    }
+
+    // The pod's memory kills (ADR-0062): a stub runs no process, so none. Answered, not a 404, so a
+    // Turn the stub admits logs no failed read.
+    if (req.method === "GET" && url.pathname === "/memory-kills") {
       res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({ aborted: ended.length > 0 }));
+      res.end(JSON.stringify({ kills: [] }));
       return;
     }
 

package/src/timers.ts

@@ -106,11 +106,15 @@ export function scheduledFor(ref: AnyActorRef): Array<{ id: string; event: Event
  * Install it before `start()` (the root's creation event is early enough): a timer armed before the
  * wrap is not seen. The same xstate internals as the rest of this module; the canary is the same.
  */
-export function watchTimers(system: AnyActorRef["system"]): (source: unknown, event: unknown) => boolean {
+export function watchTimers(
+  system: AnyActorRef["system"],
+  hooks: TimerHooks = {},
+): (source: unknown, event: unknown) => boolean {
   const scheduler = system.scheduler;
   const { schedule, cancel } = scheduler;
   const armed = new Map<string, { source: AnyActorRef; event: EventObject }>();
   scheduler.schedule = (source, target, event, delay, id = Math.random().toString(36).slice(2)) => {
+    hooks.arming?.(source);
     schedule(source, target, event, delay, id);
     armed.set(keyOf(source, id), { source, event });
   };
@@ -129,6 +133,15 @@ export function watchTimers(system: AnyActorRef["system"]): (source: unknown, ev
   };
 }
 
+/** What `watchTimers` tells as the scheduler arms a timer: `arming` is called with the timer's
+ * source just before xstate schedules it, and xstate then arms it on the system's clock in the same
+ * call. xstate schedules in the deferred effects of the event whose actions armed the timer, so the
+ * source still takes that event. The run host keeps each timer's cause this way (`cause.ts`,
+ * ADR-0024). */
+export type TimerHooks = {
+  arming?: (source: AnyActorRef) => void;
+};
+
 /**
  * Start a restored run, then schedule each recorded timer again on it. One function, so the order
  * cannot be got wrong: re-armed BEFORE `start()`, a timer is armed twice and fires twice, because

package/src/tokens.ts

@@ -17,17 +17,20 @@
 //                   (`JR2_PUBLISH_TOKEN`), read by `jr2 up` through the kube API only. Every other
 //                   route answers it 403: it is a known token, but not one that route accepts.
 //
-//   Sandbox token   the Custodian's credential. Authorizes exactly: deliver to `kind: "agent"`
-//                   registrations whose Sandbox is THIS one. Never a Gate (a compromised Agent
-//                   must not approve its own review), never another Sandbox (`coding.ts`'s iids
-//                   are derivable and feature ids are readable from the Work Source, so a merely
-//                   run-scoped token would let one feature's coder inject a verdict into another
-//                   feature's reviewer). Delivered as a Secret mounted into the Custodian
-//                   container ALONE, which the Agent cannot read; the Harness holds its
-//                   Stand-in (ADR-0059).
-//                   The signed name is a POD hosting Turns, not a Sandbox CR per se: the Instance
-//                   Harness's Custodian holds one signed for that placement's Service name
-//                   (ADR-0031), scoping it to the Menu-only registrations placed there.
+//   Sandbox token   the Custodian's credentials, two of them, each valid on its own routes alone
+//                   (ADR-0076). Both are signed names of a POD hosting Turns — a Sandbox, or the
+//                   Instance Harness's Service name (ADR-0031) — and both live in the Custodian
+//                   container ALONE, which no Workspace code reaches (ADR-0059):
+//     control token   `agent:<pod>.<sig>`. Delivers to `kind: "agent"` registrations whose pod is
+//                   THIS one, and only for the slot the Harness states (`X-Jr2-Slot`), on the
+//                   four agent routes. The Harness process alone holds its secret Stand-in.
+//     fetch token     `<pod>.<sig>`. Asks for a fetch for THIS Sandbox (ADR-0053), on
+//                   `POST /sandboxes/<pod>/fetch` alone. Its Stand-in is public: it can do
+//                   nothing else.
+//                   Neither is ever a Gate's (a compromised Agent must not approve its own review),
+//                   and neither reaches another pod (`coding.ts`'s iids are derivable and feature
+//                   ids are readable from the Work Source, so a merely run-scoped token would let
+//                   one feature's coder inject a verdict into another feature's reviewer).
 //
 // And one bearer the other way (ADR-0058), which is no principal here because this server never
 // checks it:
@@ -53,17 +56,53 @@ export type Principal =
   /** `jr2 up`, publishing an Assembly (ADR-0069). Only `PUT /assembly` accepts it: it is not an
    * Instance principal, so it reads no run and starts none. */
   | { kind: "publisher" }
-  /** One Sandbox's Custodian, speaking for the Agent in that pod — and for no one else. */
-  | { kind: "sandbox"; sandbox: string };
+  /** One Sandbox's fetch token (ADR-0053, ADR-0076): asks for a fetch for that Sandbox, and does
+   * nothing else. */
+  | { kind: "sandbox"; sandbox: string }
+  /** One pod's control token (ADR-0076), with the slot the Harness stated for the conversation
+   * (`X-Jr2-Slot`): speaks on the agent routes for that slot's registrations in that pod, and for no
+   * other. */
+  | { kind: "agent"; sandbox: string; slot: string };
 
-/** Resolve a bearer token to a principal; undefined = not a token we minted (→ 401). */
-export type Authenticator = (bearer: string | undefined) => Principal | undefined;
+/** The header the Harness states a control request's slot in (ADR-0076): the Agent's actor path
+ * and agent name, its continued conversation's Instance ID without the run id. */
+export const SLOT_HEADER = "x-jr2-slot";
 
-/** The Sandbox token for one Sandbox: its name, signed. Same name + key → same token, always. */
+/** Resolve a bearer token, and the slot a control request states, to a principal; undefined = not a
+ * token we minted, or a control token with no slot (→ 401). */
+export type Authenticator = (bearer: string | undefined, slot?: string) => Principal | undefined;
+
+/** The fetch token for one Sandbox: its name, signed. Same name + key → same token, always. The
+ * bare form of ADR-0013's Sandbox token; since ADR-0076 it opens the fetch route alone. */
 export function sandboxToken(key: Buffer, sandbox: string): string {
   return `${sandbox}.${sign(key, sandbox)}`;
 }
 
+/** The domain of a control token's signed name (ADR-0076). No DNS label holds a `:`, so a control
+ * token is never read as a fetch token, nor the reverse. */
+const CONTROL_PREFIX = "agent:";
+
+/**
+ * The control token for one pod (ADR-0076): what the Custodian puts in place of the secret control
+ * Stand-in on the agent routes. A signed name like the fetch token — same key, same deterministic
+ * re-mint — in its own `agent:` domain. No slot is inside it: the Harness states the slot on each
+ * request, and the Orchestrator checks it against the registration's.
+ */
+export function controlToken(key: Buffer, pod: string): string {
+  const name = `${CONTROL_PREFIX}${pod}`;
+  return `${name}.${sign(key, name)}`;
+}
+
+/**
+ * The secret control Stand-in for one pod (ADR-0076, ADR-0059): the bearer the Harness process
+ * alone holds, as a file under `/run/jr2/` that no confined child can read, and that the Custodian
+ * swaps for {@link controlToken} on the agent routes. A 43-character base64url HMAC, so no
+ * Workspace code can guess it. Its own `control-standin:` domain keeps it apart from every token.
+ */
+export function controlStandIn(key: Buffer, pod: string): string {
+  return sign(key, `control-standin:${pod}`);
+}
+
 /**
  * The Harness bearer for one placement (ADR-0058): what the Orchestrator presents on every Harness
  * wire call — admit, stream, abort, echo — to the Harness in the pod `placement` names (a
@@ -138,37 +177,65 @@ export function createAuthenticator(opts: {
   /** The publish token (ADR-0069). Absent → no bearer resolves to the publisher. */
   publishToken?: string;
 }): Authenticator {
-  return (bearer) => {
+  return (bearer, slot) => {
     if (!bearer) return undefined;
     if (constantTimeEqual(bearer, opts.instanceToken)) return { kind: "instance" };
     if (opts.publishToken !== undefined && constantTimeEqual(bearer, opts.publishToken)) return { kind: "publisher" };
     const cut = bearer.lastIndexOf(".");
     if (cut <= 0) return undefined;
-    const sandbox = bearer.slice(0, cut);
-    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, sandbox))) return undefined;
-    return { kind: "sandbox", sandbox };
+    const name = bearer.slice(0, cut);
+    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, name))) return undefined;
+    // A control token (ADR-0076), read BEFORE the bare form. A control request states its slot; one
+    // that states none is refused like an unknown token, so no route ever sees a control principal
+    // without a slot.
+    if (name.startsWith(CONTROL_PREFIX)) {
+      const pod = name.slice(CONTROL_PREFIX.length);
+      if (!isPodName(pod) || !slot) return undefined;
+      return { kind: "agent", sandbox: pod, slot };
+    }
+    // The bare fetch token, in its own domain alone: a name in any other domain (`harness:`,
+    // `control-standin:`, `held-standin:` …) is not a Sandbox's, whatever key signed it.
+    if (!isPodName(name)) return undefined;
+    return { kind: "sandbox", sandbox: name };
   };
 }
 
+/** A pod's name as a token signs it: a DNS-1123 name, so it holds no `:` and no `/` — the marks of
+ * every other signed domain (ADR-0076). */
+function isPodName(name: string): boolean {
+  return /^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(name);
+}
+
 /**
- * May this principal deliver to this agent registration? The Instance token may (it is the
- * operator). A Sandbox token may only when the registration records ITS name — which is why
- * an Agent registration carries `sandbox` at all (ADR-0013). The recorded name is the pod hosting the Turn:
- * a Workspace's Sandbox, or `jr2-instance-harness` for a Menu-only registration (ADR-0031). An
- * agent registration with NO name at all is an explicit-`endpoint` run (the stub Harness on the
- * host, in no pod): no Sandbox token can claim it.
+ * May this principal speak on this agent registration's routes — its surface, a pick, a delivery's
+ * poll, a notice's acknowledgment? The Instance token may (it is the operator). A control token may
+ * only when the registration records ITS pod — which is why an Agent registration carries `sandbox`
+ * at all (ADR-0013) — AND the slot the Harness stated is the registration's (ADR-0076). The recorded
+ * pod is the one hosting the Turn: a Workspace's Sandbox, or `jr2-instance-harness` for a Menu-only
+ * registration (ADR-0031). An agent registration with NO pod at all is an explicit-`endpoint` run
+ * (the stub Harness on the host, in no pod): no pod's token can claim it. A fetch token never may:
+ * it opens the fetch route alone.
+ *
+ * The slot check finds a routing fault. It is not the boundary: only the Harness process holds the
+ * control Stand-in, so only the Harness can state a slot at all (ADR-0076).
  */
-export function mayDeliverToAgent(principal: Principal, registrationSandbox: string | undefined): boolean {
+export function mayDeliverToAgent(principal: Principal, registration: { sandbox?: string; slot?: string }): boolean {
   if (principal.kind === "instance") return true;
-  if (principal.kind !== "sandbox") return false;
-  return registrationSandbox !== undefined && registrationSandbox === principal.sandbox;
+  if (principal.kind !== "agent") return false;
+  return (
+    registration.sandbox !== undefined &&
+    registration.sandbox === principal.sandbox &&
+    registration.slot !== undefined &&
+    registration.slot === principal.slot
+  );
 }
 
 /**
- * May this principal ask for a fetch on this Sandbox (ADR-0053)? A Sandbox token may ask for its
+ * May this principal ask for a fetch on this Sandbox (ADR-0053)? A fetch token may ask for its
  * OWN pod and no other — the scope is the caches that pod mounts, and the route refuses a Repo it
  * does not. The Instance token may, on the same grounds it may deliver to any agent surface: it is
- * the operator. The publish token may not: it opens the publish door and no other (ADR-0069).
+ * the operator. A control token may not: it opens the agent routes alone (ADR-0076). The publish
+ * token may not: it opens the publish door and no other (ADR-0069).
  */
 export function mayAskForSandbox(principal: Principal, sandbox: string): boolean {
   if (principal.kind === "instance") return true;
@@ -176,7 +243,15 @@ export function mayAskForSandbox(principal: Principal, sandbox: string): boolean
   return principal.sandbox === sandbox;
 }
 
-function sign(key: Buffer, value: string): string {
+/** Whether a principal is an Agent's — a control token or a fetch token. A Gate refuses every one
+ * (ADR-0013, ADR-0076): an Agent never reaches a Gate. */
+export function isAgentPrincipal(principal: Principal): boolean {
+  return principal.kind === "agent" || principal.kind === "sandbox";
+}
+
+/** An HMAC of `value` under the signing key, base64url (43 characters). Exported so every signed
+ * name and Stand-in derives one way. */
+export function sign(key: Buffer, value: string): string {
   return createHmac("sha256", key).update(value).digest("base64url");
 }