@jr2/orchestrator 0.3.0 → 0.5.1

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.
@@ -32,6 +38,7 @@
 
 import { createServer } from "node:http";
 import type { AddressInfo, Socket } from "node:net";
+import type { Notice } from "./wire.ts";
 
 /** 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
@@ -49,11 +56,13 @@ export type Admission = {
   definition?: Record<string, unknown>;
   model?: string;
   thinkingLevel?: string;
+  /** The notices the admission carried (ADR-0062). Absent when it carried none. */
+  notices?: Notice[];
 };
 
 /** 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`). */
@@ -99,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;
     }
 
@@ -133,6 +164,7 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
               definition?: Record<string, unknown>;
               model?: string;
               thinkingLevel?: string;
+              notices?: Notice[];
             }
           | undefined;
         const admission: Admission = {
@@ -145,6 +177,7 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
           ...(sent?.definition ? { definition: sent.definition } : {}),
           ...(sent?.model ? { model: sent.model } : {}),
           ...(sent?.thinkingLevel ? { thinkingLevel: sent.thinkingLevel } : {}),
+          ...(sent?.notices?.length ? { notices: sent.notices } : {}),
         };
         admissions.push(admission);
         const submissionId = `stub-${++submissionSeq}`;

package/src/sync-client.ts

@@ -0,0 +1,54 @@
+// The sync's client (ADR-0067): after a push whose published commit is not the Agent's own, the
+// Orchestrator asks the Workspace's Harness to move the Agent's branch to it (`POST /sync`), carrying the bundle the Sandbox
+// Effector wrote. The bundle travels through here, never through a shared volume: the Worktree is
+// read-only on the credentialed side, and nothing the Effector writes is a channel into the Agent's
+// container but this one call, which moves one ref. The Harness's answer is a report the next push
+// never trusts.
+
+import type { SyncAnswer, SyncRequest } from "./wire.ts";
+
+/** The Harness's sync, as a push drives it. It never throws: a Harness that cannot be reached, or
+ * that refuses, answers `not-synced` with the reason — the push's outcome stands either way. */
+export interface SyncPort {
+  sync(req: SyncRequest, signal: AbortSignal): Promise<SyncAnswer>;
+}
+export type SyncPortFactory = (endpoint: string, bearer?: string) => SyncPort;
+
+/** How long a sync may take before it answers `not-synced`: its git steps are bounded at 120 s each. */
+const SYNC_TIMEOUT_MS = 5 * 60_000;
+
+export function createSyncPort(options: {
+  baseUrl: string;
+  /** The Workspace's Harness bearer (ADR-0058). */
+  token?: string;
+  /** Injectable for socket-free tests. Default: global `fetch`. */
+  fetch?: typeof fetch;
+}): SyncPort {
+  const fetchImpl = options.fetch ?? fetch;
+  return {
+    sync: async (req, signal) => {
+      const url = new URL("/sync", options.baseUrl).toString();
+      try {
+        const res = await fetchImpl(url, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+          },
+          body: JSON.stringify(req),
+          // Bounded: a Harness that never answers is a sync that did not finish, never a push held open.
+          signal: AbortSignal.any([signal, AbortSignal.timeout(SYNC_TIMEOUT_MS)]),
+        });
+        const text = await res.text();
+        if (!res.ok) return { sync: "not-synced", reason: `the Harness refused the sync (${res.status}): ${text}` };
+        return JSON.parse(text) as SyncAnswer;
+      } catch (err) {
+        return { sync: "not-synced", reason: `the Harness could not be reached: ${(err as Error).message}` };
+      }
+    },
+  };
+}
+
+/** The real factory: the Workspace's Harness, with its bearer. */
+export const harnessSyncPort: SyncPortFactory = (endpoint, bearer) =>
+  createSyncPort({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) });

package/src/timers.ts

@@ -0,0 +1,191 @@
+// A run's pending timers across a restart (ADR-0007).
+//
+// xstate 5 keeps a delayed event (`after`, a named delay, a delayed `raise` or `sendTo`) on the
+// actor SYSTEM's scheduler, not in the Machine snapshot. `getPersistedSnapshot()` carries no trace
+// of it, and a restored actor runs no entry actions again, so nothing schedules it again: the
+// timer is lost, not restarted. xstate 5 has a `snapshot.scheduler` seam in `createSystem`, but
+// the Actor constructor never passes it.
+//
+// So the run host records each pending timer's absolute DEADLINE beside the snapshot, in the same
+// blob, and schedules it again on the restored system after `start()`. The author writes plain
+// `after`. The scheduled id is xstate's own (`xstate.after.<delay>.<stateId>` for an `after`), so
+// the state's exit `cancel(id)` still cancels a re-armed timer.
+//
+// This reads an xstate INTERNAL: `system.getSnapshot()._scheduledEvents` (typed in xstate's
+// `ActorSystem`, but underscored), `system.scheduler.schedule`, and `system.scheduler.cancel`
+// (wrapped for the length of `start()`). An xstate bump can break it; the raw-xstate tests in
+// test/timers.test.ts are the canary. xstate 6 persists timers in the snapshot and re-arms them
+// itself, with the same deadline and clamp: on xstate 6, delete this module.
+
+import type { AnyActorRef, EventObject } from "xstate";
+
+/** One pending delayed event, JSON-safe. An actor is named by its path of child ids below the
+ * run's root (`[]` is the root). */
+export type PendingTimer = {
+  source: string[];
+  target: string[];
+  /** xstate's scheduled id. */
+  id: string;
+  event: EventObject;
+  /** The delay as last scheduled, ms: the upper bound on what remains (see {@link startAndRearm}). */
+  delay: number;
+  /** Wall-clock ms at which it is due, on the host's clock (`now`). */
+  deadline: number;
+};
+
+function childrenOf(ref: AnyActorRef): Record<string, AnyActorRef> {
+  return (ref.getSnapshot() as { children?: Record<string, AnyActorRef> }).children ?? {};
+}
+
+function pathOf(root: AnyActorRef, ref: AnyActorRef, path: string[] = []): string[] | undefined {
+  if (ref === root) return path;
+  for (const [id, child] of Object.entries(childrenOf(root))) {
+    const found = pathOf(child, ref, [...path, id]);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+function refAt(root: AnyActorRef, path: string[]): AnyActorRef | undefined {
+  let ref: AnyActorRef | undefined = root;
+  for (const id of path) ref = ref && childrenOf(ref)[id];
+  return ref;
+}
+
+/** xstate's key for a scheduled event: one per source actor and id. */
+const keyOf = (source: AnyActorRef, id: string) => `${source.sessionId}.${id}`;
+
+const clamp = (ms: number, delay: number) => Math.min(delay, Math.max(0, ms));
+
+/**
+ * The run's pending timers, read off its actor system. Call at persist time: the scheduler's table
+ * and the snapshot are read in the same tick, so they agree. A timer whose source or target is not
+ * in the run's tree (a delayed send to an actor outside it) is not recorded; jr2 has no such idiom.
+ *
+ * xstate stamps a timer's start with `Date.now()`, so the time that remains is read on that clock;
+ * the deadline is `now + remaining`, on the host's clock. With the default `now` the two are one
+ * clock and the deadline is xstate's own `startedAt + delay`.
+ */
+export function pendingTimers(root: AnyActorRef, now = Date.now()): PendingTimer[] {
+  const wall = Date.now();
+  const out: PendingTimer[] = [];
+  for (const s of Object.values(root.system.getSnapshot()._scheduledEvents)) {
+    const source = pathOf(root, s.source);
+    const target = pathOf(root, s.target);
+    if (!source || !target) continue;
+    const remaining = clamp(s.startedAt + s.delay - wall, s.delay);
+    out.push({ source, target, id: s.id, event: s.event, delay: s.delay, deadline: now + remaining });
+  }
+  return out;
+}
+
+/**
+ * The pending delayed events whose TARGET is `ref`, from any source: what Rest asks (rest.ts) —
+ * an `after`, a named delay, a delayed `raise` or `sendTo(self)`, a child's delayed `sendParent`.
+ * The same table {@link pendingTimers} persists and {@link startAndRearm} re-arms, so Rest reads
+ * the same timers after a restore as before it.
+ */
+export function scheduledFor(ref: AnyActorRef): Array<{ id: string; event: EventObject }> {
+  return Object.values(ref.system.getSnapshot()._scheduledEvents)
+    .filter((s) => s.target === ref)
+    .map((s) => ({ id: s.id, event: s.event }));
+}
+
+/**
+ * Watch a run's actor system for timers that FIRE: the returned function says whether one relayed
+ * event is a timer the system scheduled — an `after`, a named delay, a delayed `raise` or `sendTo` —
+ * and not an event an actor sent at once. Both reach the inspection stream from the same source with
+ * the same shape; only the scheduler knows the difference, and it forgets a timer as it fires it.
+ *
+ * So `scheduler.schedule` and `scheduler.cancel` are wrapped for the life of the system: each armed
+ * timer is kept by its key with the event object xstate relays when it fires (the same object, not
+ * a copy). A relayed event is a fired timer when its source and event object are an armed timer's
+ * and that timer is no longer in the scheduler's table; it is then forgotten. A re-armed timer
+ * (`startAndRearm`) goes through the same `schedule`, so a restored run recognises it too.
+ *
+ * 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"],
+  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 });
+  };
+  scheduler.cancel = (source, id) => {
+    armed.delete(keyOf(source, id));
+    cancel(source, id);
+  };
+  return (source, event) => {
+    for (const [key, row] of armed) {
+      if (row.event !== event || row.source !== source) continue;
+      if (key in system.getSnapshot()._scheduledEvents) continue;
+      armed.delete(key);
+      return true;
+    }
+    return false;
+  };
+}
+
+/** 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
+ * the system's own `start()` schedules whatever is already in its table; and `start()` is where
+ * xstate builds the children, so a child's path resolves only after it.
+ *
+ * `start()` drains the mailbox: a child that sends on start (an author's `fromCallback`) can move
+ * the Machine out of a state before any timer is re-armed. That exit's `cancel(id)` finds nothing
+ * armed yet. So every cancel during `start()` is recorded, and a row it names is not re-armed: a
+ * state exit cancels the timer whether it happens during `start()` or after it.
+ *
+ * A child stopped during `start()` takes its timers with it, but xstate stops a child with
+ * `scheduler.cancelAll`, which walks the table, and the table is still empty: no cancel is seen.
+ * If its parent state is entered again, a NEW child sits at the same path. So each row's actors are
+ * resolved BEFORE `start()` (the restored tree already holds them), and a row is re-armed only on
+ * the same actors after it. A row of a stopped child then fires into nothing, not into its
+ * replacement.
+ *
+ * Remaining time is `deadline - now`, clamped to `[0, delay]`. A deadline that passed while the
+ * Orchestrator was down fires at once. A wall clock that went BACKWARDS cannot push a timer past its
+ * own delay. A wall clock that jumped forwards fires a timer early: only the wall clock survives a
+ * process, so the deadline is a wall-clock time. Rows are scheduled in deadline order, so timers
+ * that are all overdue (remaining 0) fire in the order they fell due, as in an uninterrupted run.
+ */
+export function startAndRearm(root: AnyActorRef, timers: readonly PendingTimer[], now = Date.now()): void {
+  const scheduler = root.system.scheduler;
+  const cancel = scheduler.cancel;
+  const cancelled = new Set<string>();
+  const rows = [...timers]
+    // `sort` is stable: equal deadlines keep the order xstate scheduled them in.
+    .sort((a, b) => a.deadline - b.deadline)
+    .map((t) => ({ t, source: refAt(root, t.source), target: refAt(root, t.target) }));
+  scheduler.cancel = (source, id) => {
+    cancelled.add(keyOf(source, id));
+    cancel(source, id);
+  };
+  try {
+    root.start();
+  } finally {
+    scheduler.cancel = cancel;
+  }
+  for (const { t, source, target } of rows) {
+    if (!source || !target || cancelled.has(keyOf(source, t.id))) continue;
+    if (refAt(root, t.source) !== source || refAt(root, t.target) !== target) continue;
+    scheduler.schedule(source, target, t.event, clamp(t.deadline - now, t.delay), t.id);
+  }
+}

package/src/tokens.ts

@@ -3,13 +3,20 @@
 // a per-pod NetworkPolicy cannot distinguish its packets from the Custodian's. Only authentication
 // closes this, and only the token bounds what a caller may DO (as opposed to where it may talk).
 //
-// Two principals, and the asymmetry between them is the whole design:
+// Three principals. The asymmetry between the first two is the whole design; the third is a door
+// key, not a seat:
 //
 //   Instance token  the human/CLI credential. Full trust: gates, run control, agent surfaces.
 //                   From the instance Secret (`JR2_INSTANCE_TOKEN`); minted per boot when absent,
 //                   announced once on stdout (fixtures capture it). An Agent never has it — it
 //                   never enters a Sandbox.
 //
+//   Publish token   `jr2 up`'s credential for `PUT /assembly` alone (ADR-0069). A publish imports
+//                   code into the process that holds the ServiceAccount, so it must cost what an
+//                   image roll cost: cluster write access. From the instance Secret
+//                   (`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
@@ -43,6 +50,9 @@ import { join } from "node:path";
 export type Principal =
   /** The instance's own operator: the CLI, a human, a webhook translator holding the token. */
   | { kind: "instance" }
+  /** `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 };
 
@@ -77,7 +87,20 @@ export function harnessTokenDigest(key: Buffer, placement: string): string {
   return createHash("sha256").update(harnessToken(key, placement)).digest("base64url");
 }
 
-/** Mint the per-boot Instance token (opaque and random — it names nothing, it just IS the trust). */
+/**
+ * The signing key of one Effector placement (ADR-0068): `HMAC(signing key, "effector:" + placement)`,
+ * as the Harness bearer is derived (ADR-0058). The Orchestrator signs every request to that
+ * Effector with it and verifies every answer; the Effector reads it from a file in its own mount,
+ * which `jr2 up` writes (`instance` → the `jr2-instance-effector` Secret). Derived, not stored: a
+ * restarted Orchestrator derives the key a live Effector already holds. The `effector:` prefix
+ * keeps it apart from every Sandbox token and Harness bearer. The key's bytes are this string's.
+ */
+export function effectorKey(key: Buffer, placement: string): string {
+  return sign(key, `effector:${placement}`);
+}
+
+/** Mint the per-boot Instance token (opaque and random — it names nothing, it just IS the trust).
+ * The publish token is minted the same way when the Secret supplies none (ADR-0069). */
 export function mintInstanceToken(): string {
   return randomBytes(32).toString("base64url");
 }
@@ -109,10 +132,16 @@ export async function loadSigningKey(dir: string): Promise<Buffer> {
  * A token we did not mint resolves to nothing, and the caller is refused — there is no anonymous
  * principal, and no route decides for itself whether it needs one.
  */
-export function createAuthenticator(opts: { instanceToken: string; signingKey: Buffer }): Authenticator {
+export function createAuthenticator(opts: {
+  instanceToken: string;
+  signingKey: Buffer;
+  /** The publish token (ADR-0069). Absent → no bearer resolves to the publisher. */
+  publishToken?: string;
+}): Authenticator {
   return (bearer) => {
     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);
@@ -131,6 +160,7 @@ export function createAuthenticator(opts: { instanceToken: string; signingKey: B
  */
 export function mayDeliverToAgent(principal: Principal, registrationSandbox: string | undefined): boolean {
   if (principal.kind === "instance") return true;
+  if (principal.kind !== "sandbox") return false;
   return registrationSandbox !== undefined && registrationSandbox === principal.sandbox;
 }
 
@@ -138,10 +168,11 @@ export function mayDeliverToAgent(principal: Principal, registrationSandbox: str
  * May this principal ask for a fetch on this Sandbox (ADR-0053)? A Sandbox 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. Nothing else can hold either, so there is no third case.
+ * the operator. 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;
+  if (principal.kind !== "sandbox") return false;
   return principal.sandbox === sandbox;
 }
 

package/src/vocabulary.ts

@@ -54,10 +54,32 @@ export function vocabularyOf(machine: AnyStateMachine): Map<string, EventDef> |
  * silently accepting a name nobody declared.
  */
 export function invokingMachine(self: AnyActorRef): AnyStateMachine | undefined {
-  const logic = (self._parent as { logic?: unknown } | undefined)?.logic as AnyStateMachine | undefined;
+  // An Open body's actor (ADR-0070) delegates to the Machine compiled from the Chart it binds, and
+  // its own logic is no Machine: the bound Machine is the scope of the Agents and Gates its states
+  // invoke, so it is asked first.
+  const parent = self._parent;
+  const bound = parent ? boundMachines.get(parent) : undefined;
+  if (bound) return bound;
+  const logic = (parent as { logic?: unknown } | undefined)?.logic as AnyStateMachine | undefined;
   return logic?.root ? logic : undefined;
 }
 
+// The Machine an Open body's actor runs (ADR-0070): compiled from the Chart the run bound, per
+// actor, at start and again at restore. Keyed on the ACTOR, not on a config: two runs of one
+// wrapper bind two Charts under the same slot. Kept here, beside the vocabulary, so this module
+// stays a leaf: open-body.ts writes it, and `invokingMachine` reads it.
+const boundMachines = new WeakMap<AnyActorRef, AnyStateMachine>();
+
+/** Record the Machine an Open body's actor runs. jr2-internal: the Open body's logic calls it. */
+export function attachBoundMachine(actor: AnyActorRef, machine: AnyStateMachine): void {
+  boundMachines.set(actor, machine);
+}
+
+/** The Machine an Open body's actor runs, or undefined for any other actor. */
+export function boundMachineFor(actor: AnyActorRef): AnyStateMachine | undefined {
+  return boundMachines.get(actor);
+}
+
 // The declared run input (ADR-0033): the one piece of a machine's vocabulary the event defs
 // missed — what a run of it is STARTED with. Same key choice as the vocabulary above, for the
 // same reasons (per-machine attribution, no global registry, transparent across `.provide()`).
@@ -79,22 +101,120 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
   return inputSchemas.get(machine.config);
 }
 
+/** A zod schema, by its shape: the Instance can resolve a zod of its own, so `instanceof` does not
+ * tell. */
+export function isZodSchema(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "_zod" in value &&
+    typeof (value as { safeParse?: unknown }).safeParse === "function"
+  );
+}
+
+/** The run input that a machine declares: the door that `jr2Setup` attached, or a zod `input` on
+ * its `createMachine` config that no door reads (a machine that `setup()` made). */
+export function declaresRunInput(machine: AnyStateMachine): boolean {
+  return inputSchemaOf(machine) !== undefined || isZodSchema((machine.config as { input?: unknown }).input);
+}
+
+// Who may send what, per state (ADR-0015): the seats the menu-derivation walk computed. Same key
+// choice as the vocabulary, for the same reasons. The Machine's doc carries them; `jr2 up` and the
+// Console show them, so an author reads the audience rule's answer for their own Machine.
+
+/** One party's seat on one state: the state's id, the party, and the names it may send there —
+ * for an Agent the derived set its guards narrow; for a Gate its accepted set, unless the Gate's
+ * input names `accepts:` itself. */
+export type MachineSeat = { state: string; party: "agent" | "gate"; agent?: string; names: string[] };
+
+const seatTables = new WeakMap<MachineKey, MachineSeat[]>();
+
+/** Attach a Machine's seats. jr2-internal: `jr2Setup.createMachine` calls it. */
+export function attachSeats(machine: AnyStateMachine, seats: MachineSeat[]): void {
+  seatTables.set(machine.config, seats);
+}
+
+/** The seats of a Machine built by `jr2Setup`, in walk order; empty for any other Machine. */
+export function seatsOf(machine: AnyStateMachine): MachineSeat[] {
+  return seatTables.get(machine.config) ?? [];
+}
+
+/** One line per seat — `<state> agent:<slot>: [names]` or `<state> gate: [names]`. */
+export function seatLine(seat: MachineSeat): string {
+  const party = seat.party === "agent" ? `agent:${seat.agent}` : "gate";
+  return `${seat.state} ${party}: [${seat.names.join(", ")}]`;
+}
+
+const loadWarnings = new WeakMap<MachineKey, string[]>();
+
+/** Attach the load warnings `jr2Setup.createMachine` found (ADR-0015). jr2-internal. */
+export function attachLoadWarnings(machine: AnyStateMachine, warnings: string[]): void {
+  loadWarnings.set(machine.config, warnings);
+}
+
+/** What the build found legal and suspect — a mode nothing enters, a pick a Gate above takes from
+ * the Agent below, one name written for two parties on one path. `jr2 up` prints them; the
+ * Machine's doc carries them. A Machine `customize()` bound an Open argv in is rebuilt around a
+ * config of its own, which carries the walk's findings for the bound argv (ADR-0054). Empty for a
+ * Machine not built by `jr2Setup`. */
+export function loadWarningsOf(machine: AnyStateMachine): string[] {
+  return loadWarnings.get(machine.config) ?? [];
+}
+
+// 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`. 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
+// door schema would publish it and demand of every caller a field the host supplies anyway.
+//
+// It is also PLACEMENT-DEPENDENT: only the ROOT machine is started with it. A machine invoked
+// further down is fed by its parent, which passes what it chooses. No type can see where a machine
+// sits, so the one contract that must reason about this — `workspace()`'s body guard — takes the
+// permissive answer and counts these keys as PROVIDED, which lets a body declare the field
+// honestly. Counting them as provided (rather than subtracting them from what the body demands)
+// is what keeps their TYPE checked: `instanceId` is a string, and a body asking for anything else
+// is still rejected.
 /**
- * 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`. 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.
+ * The fields that jr2 adds to the input of the Machine that a run starts, beside the input that
+ * the caller sent. Today it is one field: `instanceId`, an id that jr2 makes for the run.
+ *
+ * Add it to the type of your root Machine's input when the Machine reads it:
+ * `HostInjectedInput & RunInput`. Do not put it in the `input` schema that a run starts with. No
+ * caller sends it. jr2 writes it over any value that a caller sends.
+ *
+ * Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
+ * that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
+ * `workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
+ *
+ * The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
+ * ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+ *
+ * It is not the run id. Use it, for example, to give each run a branch of its own.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ ticket: z.string() });
+ * type Input = HostInjectedInput & z.infer<typeof runInput>;
  *
- * 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
- * door schema would publish it and demand of every caller a field the host supplies anyway.
+ * export const machine = jr2Setup({
+ *   types: {} as { input: Input; context: Input; output: { run: string; ticket: string } },
+ * }).createMachine({
+ *   id: "ticket",
+ *   input: runInput,
+ *   context: ({ input }) => input,
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ *   output: ({ context }) => ({ run: context.instanceId, ticket: context.ticket }),
+ * });
+ * ```
  *
- * It is also PLACEMENT-DEPENDENT: only the ROOT machine is started with it. A machine invoked
- * further down is fed by its parent, which passes what it chooses. No type can see where a machine
- * sits, so the one contract that must reason about this — `workspace()`'s body guard — takes the
- * permissive answer and counts these keys as PROVIDED, which lets a body declare the field
- * honestly. Counting them as provided (rather than subtracting them from what the body demands)
- * is what keeps their TYPE checked: `instanceId` is a string, and a body asking for anything else
- * is still rejected.
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md
  */
 export type HostInjectedInput = { instanceId: string };