@jr2/orchestrator 0.1.0

package/src/server.ts

@@ -0,0 +1,220 @@
+// The deployed orchestrator's entrypoint (ADR-0019): the process the instance image runs — and, by
+// the same token, the e2e tier's per-scenario fixture (ADR-0010 boots exactly this process on the
+// host). Configuration is env, kube-style; the instance folder is the process cwd (the image bakes
+// engine + `workflows/` there, ADR-0008). No dev.json, no hot-reload, no stub Harness: those were
+// host-dev affordances, and there is no host dev mode.
+//
+//   PORT               listen port (default 4000 — what the Service targets)
+//   HOST               listen hostname (default 0.0.0.0: pods must be reachable off-loopback)
+//   JR2_INSTANCE_TOKEN  the Instance credential (ADR-0013), from the instance's Secret; minted
+//                      per boot when absent (then only the announce line knows it — fixtures set it)
+//   JR2_SIGNING_KEY     base64 key Sandbox tokens are signed with; from the Secret so live Sandboxes
+//                      survive a pod restart. Absent → minted into `<dir>/.jr2/secret` (dev-grade).
+//   JR2_NAMESPACE       the pod's own namespace (Deployment fieldRef) — presence = "deployed":
+//                      Sandboxes are driven in it, and the Adapters' route home is Service DNS.
+//   <git.credentials[].token>
+//                      each token env var the config names rides the instance Secret (ADR-0051):
+//                      the Orchestrator materializes it into the Repo's credential Secret.
+//
+// The first stdout line is one JSON object `{ url, workflows }` — the discovery seam a fixture (or
+// a human tailing pod logs) parses instead of racing the socket. Deployed with a data plane, the
+// boot then creates one `Repo` resource per identity its Machines bind (ADR-0051) and announces
+// each as `{ repo, url, bound: true }` — or `{ repo, error }` — one line apiece, after serving:
+// a Repo the cluster refuses is a degraded Repo (ADR-0048), never a boot that did not happen.
+// Deployed WITHOUT one, the same pass still runs and binds nothing, which unlabels every Repo a
+// 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";
+import {
+  HARNESS_CONFIGMAP,
+  HARNESS_CONFIG_KEY,
+  HARNESS_ENV_SECRET,
+  IMAGES_KEY,
+  IMAGES_MOUNT,
+  INSTANCE_HARNESS_PORT,
+  INSTANCE_HARNESS_SERVICE,
+  ORCHESTRATOR_SERVICE,
+} from "./names.ts";
+import { partsOf, type CarriedRepo } from "./parts.ts";
+import { kubectlRepoFetches, type RepoFetches } from "./repo-fetch.ts";
+import { kubectlRepos, type RepoResources } from "./repos.ts";
+import { kubectlSandbox, type KubectlExec } from "./sandbox-kubectl.ts";
+import { loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import type { SandboxPort } from "./workspace.ts";
+
+export type ServerMainOptions = {
+  /** The instance folder (deployed: the image's WORKDIR; fixtures: a temp instance). */
+  dir: string;
+  /** The environment to read the contract above from (deployed: `process.env`). */
+  env: Record<string, string | undefined>;
+  /** Where the one-line JSON announcement goes (deployed: stdout). */
+  announce: (line: string) => void;
+  /** The kubectl process seam behind the data plane's two ports, injectable for tests.
+   * Deployed: the `kubectl` on PATH. */
+  exec?: KubectlExec;
+};
+
+/** Boot the instance the env describes; resolves once serving (the caller owns signals/exit). */
+export async function serverMain(opts: ServerMainOptions): Promise<RunningInstance> {
+  const { env } = opts;
+  const config = await loadConfig(opts.dir);
+  const port = env.PORT !== undefined ? Number(env.PORT) : 4000;
+  const signingKey =
+    env.JR2_SIGNING_KEY !== undefined ? Buffer.from(env.JR2_SIGNING_KEY, "base64") : await loadSigningKey(opts.dir);
+
+  // Deployed (JR2_NAMESPACE set): Adapters dial the orchestrator at its own Service DNS — stable
+  // 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.
+  const instanceToken = env.JR2_INSTANCE_TOKEN ?? mintInstanceToken();
+
+  // The data-plane switch (ADR-0012/0031/0051): a registered Machine COMPOSES a Sandbox — read off
+  // the same walk `jr2 up` makes — and this process is deployed in a cluster → wire the kubectl
+  // Sandbox backend. Otherwise an instance without a data plane (workspace() invocations fault
+  // pointedly). The walk loads the same modules `startInstance` registers below; Node's module
+  // cache makes them one import.
+  const carried = partsOf((await loadWorkflows(opts.dir)).map((w) => w.machine));
+  const dataPlane = carried.composesSandbox && namespace !== undefined;
+  let sandbox: SandboxPort | undefined;
+  let repos: RepoResources | undefined;
+  let fetches: RepoFetches | undefined;
+  // The Repo port hangs off DEPLOYED, not off the data plane: this boot's reconcile is the only
+  // writer that ever REMOVES `jr2.dev/bound` (repos.ts), and an Instance that drops its last
+  // `workspace()` still owns the Repos its earlier deploys bound. So the port is built whenever
+  // there is a cluster to drive, and the walk — now naming nothing — unlabels every one of them,
+  // which is what puts them on `jr2 gc`'s clock. Gate it on the data plane instead and they stay
+  // bound forever: uncollectable resources, with their node caches behind them.
+  if (namespace !== undefined) {
+    const credentials = config?.git?.credentials ?? [];
+    // The Repo resources (ADR-0051): created by this process, cloned by the operator's cache agent
+    // on every node that needs them. The port resolves `git.credentials` into each resource's
+    // `secretRef`, reading a token entry's env var off this process — the Instance Secret is
+    // `envFrom` on the Deployment, so `jr2 up` is what put it there.
+    repos = kubectlRepos({ namespace, credentials, env, ...(opts.exec ? { exec: opts.exec } : {}) });
+    if (dataPlane) {
+      // The ask a pod makes when something inside it fetches (ADR-0053): it marks the Sandbox CR
+      // and waits on the same status the provision waits on. Gated on the DATA PLANE, unlike the
+      // Repo port above — there is nothing to ask for where no Sandbox is ever composed, and the
+      // only caller is a pod that would have to exist to call it.
+      fetches = kubectlRepoFetches({ namespace, ...(opts.exec ? { exec: opts.exec } : {}) });
+      sandbox = kubectlSandbox({
+        // The fence (ADR-0051): a per-run url must match one of these, or the provision refuses it.
+        credentials,
+        // Where a provision records the Repos it names, before the CR names them.
+        repos,
+        // Named here the same way HARNESS_CONFIGMAP is: a jr2-owned mount path, deliberately NOT an
+        // env knob — there is no image escape hatch left to configure (ADR-0038). Note what this
+        // buys: the map is read per provision, so an instance whose `jr2-images` ConfigMap is not yet
+        // mounted still BOOTS and serves — only a provision fails, pointing at `jr2 up`. That is the
+        // correct blast pattern, and the stale-read window is one kubelet propagation.
+        imagesPath: join(IMAGES_MOUNT, IMAGES_KEY),
+        // The Harness containers' env (ADR-0018): what this instance can REACH (the custom provider
+        // — no Agents, they ride each Turn since ADR-0049), then the instance's own valueFrom
+        // entries (literal values already live in the jr2-harness-env Secret below).
+        env: [
+          {
+            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 ?? [])],
+        // Presence only — the PEM itself was materialized into the jr2-ca ConfigMap by `jr2 up`
+        // (ADR-0020); the in-cluster config eval never reads the file.
+        caBundle: config?.harness?.caBundle !== undefined,
+        // Which nodes are Sandbox nodes (ADR-0052) — the CR carries it, the operator reads no config.
+        ...(config?.sandbox ? { placement: config.sandbox } : {}),
+        orchestratorUrl: `http://${ORCHESTRATOR_SERVICE}.${namespace}.svc:${port}`,
+        signingKey,
+        namespace,
+        ...(opts.exec ? { exec: opts.exec } : {}),
+      });
+    }
+  }
+
+  const inst = await startInstance({
+    dir: opts.dir,
+    port,
+    hostname: env.HOST ?? "0.0.0.0",
+    instanceToken,
+    signingKey,
+    sandbox,
+    dataPlane,
+    // Read per request, never snapshotted: the Repos as the cluster reports them right now. An
+    // instance without a data plane reports none — `GET /repos` answers `{ dataPlane: false,
+    // repos: [] }` (http.ts), and what its dropped Machines left behind is `jr2 gc`'s to name.
+    ...(dataPlane && repos ? { repos: () => repos.list() } : {}),
+    // The pod's route out (ADR-0053), same shape: read per request, off the port.
+    ...(fetches ? { fetchRepo: (name: string, identity: string) => fetches.fetch(name, identity) } : {}),
+    // Where a Menu-only Turn runs (ADR-0031): the Instance Harness's deterministic Service DNS.
+    // `jr2 up` converges the Deployment behind it whenever any definition declares
+    // `workspace: "none"`, so deployed, the address exists exactly when it is needed.
+    instanceHarness: namespace
+      ? `http://${INSTANCE_HARNESS_SERVICE}.${namespace}.svc:${INSTANCE_HARNESS_PORT}`
+      : undefined,
+  });
+  // Resumed runs are routine and stay quiet; runs this boot did NOT resume are not, so they ride
+  // the announce line (ADR-0030) — the one thing every boot prints, whatever is reading it. Without
+  // this, `drifted` is only reachable by asking after a run id nobody knows to ask about.
+  const { lost, drifted, failed } = inst.restored;
+  opts.announce(
+    JSON.stringify({
+      url: inst.url,
+      workflows: inst.workflows,
+      ...(lost.length ? { lost } : {}),
+      ...(drifted.length ? { drifted } : {}),
+      ...(failed.length ? { failed } : {}),
+    }),
+  );
+  // After serving, never awaited: the bound Repos' resources (ADR-0051). Serving does not wait on
+  // the cluster — a run whose Repo the boot could not record still finds its provision ensuring
+  // it again — and a refusal is one announced line per Repo, in ADR-0048's shape. A deployed
+  // instance that binds nothing still runs this: the walk names no Repo, so the reconcile is the
+  // whole of it, and every resource an earlier deploy bound becomes evictable.
+  if (repos) void ensureBound(repos, carried.repos, opts.announce);
+  return inst;
+}
+
+/**
+ * The boot's half of ADR-0051's "the Orchestrator creates Repo resources": one per identity the
+ * registered Machines bind, so statically known repositories are KNOWN before a run asks (the
+ * cache agent probes each; a node clones on first demand) — then
+ * the bound label reconciled, so a slot unbound since the last deploy is a Repo `jr2 gc` may
+ * evict. The boot is the ONE writer of a bound resource's spec: a redeploy that moved a url or a
+ * credential restates it here, and no provision does. Sequential, and each failure its own
+ * line: a wrong url on one Machine must not hide the others.
+ */
+async function ensureBound(
+  repos: RepoResources,
+  bound: CarriedRepo[],
+  announce: (line: string) => void,
+): Promise<void> {
+  for (const repo of bound) {
+    try {
+      await repos.bind({ url: repo.url, identity: repo.identity, key: repo.key });
+      announce(JSON.stringify({ repo: repo.key, url: repo.url, bound: true }));
+    } catch (err) {
+      announce(JSON.stringify({ repo: repo.key, url: repo.url, error: (err as Error).message }));
+    }
+  }
+  try {
+    await repos.reconcileBound(bound.map((r) => r.key));
+  } catch (err) {
+    announce(JSON.stringify({ repos: bound.map((r) => r.key), error: (err as Error).message }));
+  }
+}

package/src/setup.ts

@@ -0,0 +1,360 @@
+// `jr2Setup` — the authoring surface (ADR-0015): an xstate `setup()` analog, not a DSL. It returns
+// xstate's public `SetupReturn`, so `.createMachine()` yields a plain `StateMachine` — Stately-
+// inspectable, `.provide()`-testable, constructible with no jr2 runtime. What the wrapper adds:
+//
+//   - the MECHANISM events (`agent.fault`, `workspace.lost`, …) are injected into the event
+//     union, and the WORKFLOW event types derive from the zod defs — hand-written `EventFrom`
+//     unions retire;
+//   - the jr2 `gate` actor is pre-registered with typed input (a consumer actor under the same
+//     name wins — the unit-test seam), and every Agent SLOT the machine declares
+//     (`actors: { coder: agent(def) }` — ADR-0049) gets the same input finalization by brand;
+//   - because it takes the defs AS VALUES, `createMachine` validates that every event key
+//     appearing anywhere in the machine maps to a def — closing xstate's nested-`on` typo hole
+//     (unknown keys in nested states typecheck silently upstream) with a load-time failure;
+//   - the vocabulary is attached to the machine object (`vocabularyOf` — vocabulary.ts), which
+//     is what lets the `export const events` manifest die (ADR-0011 revised). It is scoped to
+//     THIS Machine: `gate` and the Agent slots resolve names against the Machine that invoked
+//     them, so a Machine nested by plain `invoke` keeps its own names and this one never sees
+//     them (ADR-0049);
+//   - an optional `input` on the createMachine config — a zod object — declares what a RUN of
+//     this machine is started with (ADR-0033). It rides the machine object beside the vocabulary
+//     (`inputSchemaOf`), never the xstate config: the host validates `POST /workflows/:name/runs`
+//     bodies against it and serves it as JSON Schema; absent, the door stays permissive.
+//
+// The typing follows the proven declared-signature pattern (report-xstate §1): the public
+// signature is precise, the implementation is loosely typed with ONE jr2-internal cast at the
+// return. The consumer surface has none.
+
+import { randomUUID } from "node:crypto";
+import {
+  setup,
+  type ActionFunction,
+  type AnyActorRef,
+  type AnyStateMachine,
+  type DelayConfig,
+  type EventObject,
+  type GuardPredicate,
+  type MachineContext,
+  type MetaObject,
+  type NonReducibleUnknown,
+  type ParameterizedObject,
+  type SetupReturn,
+  type UnknownActorLogic,
+} from "xstate";
+import type { z } from "zod";
+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 { attachInputSchema, attachVocabulary } from "./vocabulary.ts";
+
+/**
+ * The events jr2's own mechanism delivers into any workflow machine, injected into every jr2Setup
+ * union. Dotted names by construction (`NAME_RE` forbids dots in workflow event names), so they
+ * can never collide with a def.
+ */
+export type MechanismEvent = FaultTelemetry | { type: "workspace.lost" };
+
+/** The full event union a jr2Setup machine sees: the defs' derived types plus the mechanism's. */
+export type WorkflowEvent<TDefs extends readonly EventDef[]> = EventFrom<TDefs[number]> | MechanismEvent;
+
+/** The jr2 actor every workflow can invoke by name without listing it (ADR-0015). `gate` is the
+ * whole set: an Agent is not pre-registered, because it is not one logic — it is the slot the
+ * Machine declares, `actors: { coder: agent(def) }` (ADR-0049). */
+const jr2Actors = { gate };
+type JR2Actors = typeof jr2Actors;
+
+/** Consumer actors merge OVER the pre-registered set: same name → the consumer's logic wins. */
+type MergedActors<TActors extends Record<string, UnknownActorLogic>> = Omit<JR2Actors, keyof TActors> & TActors;
+
+// Local equivalents of xstate's non-exported setup() mapped helpers (setup.d.ts) — same shapes,
+// so the declared signature below composes with the public `ActionFunction`/`GuardPredicate`.
+type ToParameterizedObject<T extends Record<string, ParameterizedObject["params"] | undefined>> = {
+  [K in keyof T & string]: { type: K; params: T[K] };
+}[keyof T & string];
+type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
+  [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
+}[keyof TActors & string];
+
+/**
+ * Author a workflow machine (ADR-0015). Like `setup()`, but `types.events` is gone: the event
+ * union derives from `events` (defineEvent defs, taken as values) plus the mechanism events.
+ */
+export function jr2Setup<
+  TContext extends MachineContext = MachineContext,
+  const TDefs extends readonly EventDef[] = readonly EventDef[],
+  TActors extends Record<string, UnknownActorLogic> = {},
+  TActions extends Record<string, ParameterizedObject["params"] | undefined> = {},
+  TGuards extends Record<string, ParameterizedObject["params"] | undefined> = {},
+  TDelay extends string = never,
+  TTag extends string = string,
+  TInput = NonReducibleUnknown,
+  TOutput extends NonReducibleUnknown = NonReducibleUnknown,
+  TEmitted extends EventObject = EventObject,
+  TMeta extends MetaObject = MetaObject,
+>(def: {
+  /** context/input/output/tags/emitted/meta — never `events`; the union is derived. */
+  types?: {
+    context?: TContext;
+    input?: TInput;
+    output?: TOutput;
+    tags?: TTag;
+    emitted?: TEmitted;
+    meta?: TMeta;
+  };
+  /** This Machine's vocabulary, as values — the single source for types, validation, delivery. */
+  events: TDefs;
+  actors?: TActors;
+  actions?: {
+    [K in keyof TActions]: ActionFunction<
+      TContext,
+      WorkflowEvent<TDefs>,
+      WorkflowEvent<TDefs>,
+      TActions[K],
+      ToProvidedActor<MergedActors<TActors>>,
+      ToParameterizedObject<TActions>,
+      ToParameterizedObject<TGuards>,
+      TDelay,
+      TEmitted
+    >;
+  };
+  guards?: {
+    [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>;
+  };
+  delays?: {
+    [K in TDelay]: DelayConfig<
+      TContext,
+      WorkflowEvent<TDefs>,
+      ToParameterizedObject<TActions>["params"],
+      WorkflowEvent<TDefs>
+    >;
+  };
+}): SetupReturn<
+  TContext,
+  WorkflowEvent<TDefs>,
+  MergedActors<TActors>,
+  {},
+  TActions,
+  TGuards,
+  TDelay,
+  TTag,
+  TInput,
+  TOutput,
+  TEmitted,
+  TMeta
+> {
+  const inner = setup({
+    types: def.types,
+    actors: { ...jr2Actors, ...(def.actors ?? {}) },
+    actions: def.actions,
+    guards: def.guards,
+    delays: def.delays,
+  } as never);
+
+  const createMachine = (config: never): AnyStateMachine => {
+    // The declared run input (ADR-0033) rides the config under xstate's own word for what a
+    // machine receives at creation — and is pulled OFF before xstate sees it: a zod schema is
+    // not machine structure, and it must never reach the fingerprint/serialization paths that
+    // read `machine.config`. It is attached beside the vocabulary below.
+    const { input: inputSchema, ...machineConfig } = config as { input?: z.ZodObject } & Record<string, unknown>;
+
+    // Resolve the defs first (duplicates and reserved semantics fail HERE, naming the machine —
+    // the same loud failure `eventMap` gave the manifest, moved to machine-build time)…
+    const defs = eventMap((machineConfig as { id?: string }).id ?? "(machine)", def.events);
+
+    // …then rewrite the config (ADR-0015): every Agent-slot/`gate` invoke's input is wrapped to
+    // append its DERIVED menu and finalize the mechanism fields. Static — the walk sees the same
+    // config the Console will — and the derived names still ride serializable input, so the
+    // ADR-0007 restore path and invoke-time `resolveAccepts` validation are unchanged.
+    const machine = (inner.createMachine as unknown as (c: never) => AnyStateMachine)(
+      deriveMenus(machineConfig, defs, def.actors ?? {}) as never,
+    );
+
+    // Close the nested-`on` typo hole (ADR-0015): with the manifest dead, a typo'd key would
+    // silently become vocabulary — so every non-dotted key the machine handles anywhere must map
+    // to a def. Walk every node's `transitions` map, not `machine.events` (which filters out
+    // targetless/actionless transitions — exactly where a typo'd key would hide). Dotted names
+    // (`agent.*`, `workspace.*`, `xstate.*`, delayed transitions) are mechanically jr2's/xstate's;
+    // `*` is the wildcard descriptor.
+    const walk = (node: AnyStateMachine["root"]): void => {
+      for (const descriptor of node.transitions.keys()) {
+        if (descriptor === "*" || descriptor.includes(".")) continue;
+        if (!defs.has(descriptor)) {
+          throw new Error(
+            `machine "${machine.id}" handles event "${descriptor}", which no def in jr2Setup({ events }) ` +
+              `declares (declared: ${[...defs.keys()].join(", ") || "none"}) — a typo, or a missing defineEvent`,
+          );
+        }
+      }
+      for (const child of Object.values(node.states)) walk(child);
+    };
+    walk(machine.root);
+
+    attachVocabulary(machine, defs);
+    if (inputSchema) attachInputSchema(machine, inputSchema);
+    return machine;
+  };
+
+  // The one jr2-internal cast (report-xstate §1): re-assert the merged SetupReturn over the
+  // loosely-built implementation. The consumer-facing types are the declared signature's.
+  return { ...inner, createMachine } as unknown as SetupReturn<
+    TContext,
+    WorkflowEvent<TDefs>,
+    MergedActors<TActors>,
+    {},
+    TActions,
+    TGuards,
+    TDelay,
+    TTag,
+    TInput,
+    TOutput,
+    TEmitted,
+    TMeta
+  >;
+}
+
+// --- Menu derivation (ADR-0015) ------------------------------------------------------------------
+// A state that invokes an AGENT SLOT gets, as its Agent's tool menu, the workflow events its
+// transitions handle — own + bubbled ancestors, per statechart semantics — filtered to audience
+// ∈ {agent, any}; a `gate` gets the same set filtered to {external, any}. The invoking actor
+// kind is the primary router; `audience` on the def exists to RESTRICT (tag the security-
+// sensitive events). Explicit `tools:`/`accepts:` on the invoke input remain as escape hatches.
+//
+// An agent invoke is identified by its LOGIC, not by a reserved src name: the walk looks the
+// invoke's `src` up in the setup's own `actors` map and asks `isAgent` (ADR-0049). That is also
+// where the Agent's NAME comes from — the slot key, injected into the wrapped input, so nothing
+// downstream (the iid, the Harness route, the markers) has to be authored twice.
+//
+// The walk also NAMES unnamed gate invokes with their state key path (ADR-0011):
+// the gate actor derives its default id from its own actor path, so the invoke id is the leaf
+// segment of a caller-facing name — `humanReview` beats xstate's `0.task-with-review.humanReview`.
+// Naming here is id QUALITY only; uniqueness comes from the path mechanism in gate.ts.
+
+type LooseInvoke = { src?: unknown; input?: unknown; [k: string]: unknown };
+type LooseState = {
+  on?: Record<string, unknown>;
+  invoke?: LooseInvoke | LooseInvoke[];
+  states?: Record<string, LooseState>;
+  [k: string]: unknown;
+};
+type InputArgs = { context: unknown; event: unknown; self: AnyActorRef };
+
+/** Rewrite a machine config, wrapping every Agent-slot/`gate` invoke input (immutably). */
+function deriveMenus(config: unknown, defs: Map<string, EventDef>, actors: Record<string, UnknownActorLogic>): unknown {
+  const pick = (names: Set<string>, kind: "agent" | "external"): string[] =>
+    [...names].filter((name) => {
+      const d = defs.get(name);
+      return !!d && (d.audience === kind || d.audience === "any");
+    });
+
+  const walk = (node: LooseState, inherited: Set<string>, path: readonly string[]): LooseState => {
+    const names = new Set(inherited);
+    for (const key of Object.keys(node.on ?? {})) {
+      if (!key.includes(".") && key !== "*") names.add(key);
+    }
+
+    let out = node;
+    if (node.invoke) {
+      const invokes = Array.isArray(node.invoke) ? node.invoke : [node.invoke];
+      // >1 unnamed gate in one state would collide on the state-key id; suffix ONLY then, so
+      // the common case (one gate per state) keeps the clean name.
+      const unnamedGates = invokes.filter((inv) => inv?.src === "gate" && inv.id == null).length;
+      let ordinal = 0;
+      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) };
+        }
+        if (inv?.src === "gate") {
+          const wrapped: LooseInvoke = { ...inv, input: wrapGateInput(inv.input, pick(names, "external")) };
+          // A machine-root gate (empty path) is left to xstate's default id: a `""` id would be
+          // worse than a noisy one, and the derived gate id still works.
+          if (inv.id == null && path.length) {
+            const key = path.join(".");
+            wrapped.id = unnamedGates > 1 ? `${key}.${ordinal++}` : key;
+          }
+          return wrapped;
+        }
+        return inv;
+      };
+      out = { ...node, invoke: Array.isArray(node.invoke) ? node.invoke.map(wrapOne) : wrapOne(node.invoke) };
+    }
+    if (node.states) {
+      const states: Record<string, LooseState> = {};
+      for (const [key, child] of Object.entries(node.states)) states[key] = walk(child, names, [...path, key]);
+      out = { ...(out === node ? node : out), states };
+    }
+    return out;
+  };
+
+  return walk(config as LooseState, new Set(), []);
+}
+
+const resolveInput = (orig: unknown, args: InputArgs): Record<string, unknown> =>
+  (typeof orig === "function" ? (orig as (a: InputArgs) => unknown)(args) : (orig ?? {})) as Record<string, unknown>;
+
+/** 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>;
+    return {
+      agentName,
+      instanceId: consumer.instanceId ?? mintIid(consumer, agentName, args.self),
+      endpoint: consumer.endpoint,
+      sandbox: consumer.sandbox,
+      prompt: consumer.prompt,
+      // 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,
+    };
+  };
+}
+
+/** Wrap a gate invoke input: append the derived accepted set. */
+function wrapGateInput(orig: unknown, derived: string[]) {
+  return (args: InputArgs): Record<string, unknown> => {
+    const consumer = resolveInput(orig, args);
+    return { ...consumer, accepts: (consumer.accepts as readonly string[] | undefined) ?? derived };
+  };
+}
+
+/**
+ * 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).
+ *
+ * - 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"`.
+ */
+function mintIid(
+  consumer: { session?: "continue"; scope?: string; conversation?: string },
+  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)}`;
+}