@jr2/orchestrator 0.3.0 → 0.5.1

package/src/mechanism-routes.ts

@@ -0,0 +1,168 @@
+// A mechanism event must have a route (ADR-0074). jr2 sends `agent.fault` to the Machine that
+// invoked an Agent when the Agent's Turn cannot go on (ADR-0016), and `workspace()` sends
+// `workspace.lost` to its body when the Sandbox is gone (ADR-0012), and an Open body sends a
+// Chart's unrouted `agent.fault` to the Machine that invoked it (ADR-0070). Each is a relayed
+// event, and xstate drops an event that no active state handles. So the walk refuses a state that cannot
+// route one, and the run host faults a run in which none took one.
+//
+// - `refuseUnroutedAgentFault`: a state that invokes an Agent, or an Open body that can run one
+//   (it lends an Agent or allows a model), when that state and all its ancestors have no
+//   `agent.fault` route. In `jr2Setup().createMachine` and in the load walk (`partsOf`), beside the
+//   lost-output refusal, so `jr2 check`, `jr2 up` and the Orchestrator's load show it. Not for a
+//   compiled Chart: there the route is optional, and the Open body sends an `agent.fault` that no
+//   transition of the Chart takes to the Machine that invoked it (open-body.ts; ADR-0070).
+// - `refuseUnroutedLost`: a non-final leaf state of a `workspace()` body, when that state and all
+//   its ancestors have no `workspace.lost` route. In `workspace()`, the one place that knows that a
+//   Machine is a body. A compound or parallel state is not judged by itself: an event goes to the
+//   active leaves first, so a route on each leaf (or above it) is a route for the compound state.
+//   A final state of the root ends the body, so it is not judged. A nested final state is judged
+//   when its compound state has no `onDone`: the body then stays in the compound state, and a
+//   route on the compound state or above it is the route. The line names the compound state. A
+//   final state of a parallel region is not judged: the other regions are active, and their leaves
+//   are judged.
+// - `unroutedMechanismEvent`: the runtime half, for a route that the walk cannot judge (a guard
+//   that is false when the event comes). The run host reads it off each microstep.
+//
+// A route is any transition for the event: one with actions only counts, because it can be a
+// deliberate `reenter: true` that invokes the Agent again. jr2 does not judge what a route does.
+// A wildcard (`"*"`, `"agent.*"`) that takes the event is a route too, as it is at runtime.
+
+import type { AnyStateMachine, StateNode } from "xstate";
+import { isAgent } from "./agent.ts";
+import { isOpenBody, openBodyDeclarationOf } from "./open-body.ts";
+
+/** The two mechanism events that must have a route. */
+const ROUTED_MECHANISM_EVENTS = ["agent.fault", "workspace.lost"] as const;
+
+type Node = StateNode<any, any>;
+
+/** Does a descriptor of a state's `on` take this event type? xstate's own match: the exact type,
+ * `"*"`, or a partial wildcard like `"agent.*"`. */
+function takes(descriptor: string, type: string): boolean {
+  if (descriptor === type || descriptor === "*") return true;
+  return descriptor.endsWith(".*") && type.startsWith(descriptor.slice(0, -1));
+}
+
+/** Does this state, or a state above it, have a route for `type`? */
+function routedAt(node: Node, type: string): boolean {
+  for (let at: Node | undefined = node; at !== undefined; at = at.parent) {
+    for (const descriptor of at.transitions.keys()) if (takes(descriptor, type)) return true;
+  }
+  return false;
+}
+
+/** Every state node of the tree below (and with) `node`, in document order. */
+function statesOf(node: Node): Node[] {
+  const out: Node[] = [node];
+  const children = Object.values(node.states as Record<string, Node>).sort((a, b) => a.order - b.order);
+  for (const child of children) out.push(...statesOf(child));
+  return out;
+}
+
+/** The text of one or more state ids, quoted. */
+function quoted(ids: readonly string[]): string {
+  return ids.map((id) => `"${id}"`).join(", ");
+}
+
+/** Is this slot an Open body that can run an Agent whose `agent.fault` comes to the Machine? One
+ * that lends an Agent or lets a Chart add its own: the body sends the Machine a Chart's unrouted
+ * `agent.fault`. A lent Machine routes its own Agents, and the walk judges it by itself. */
+function runsChartAgents(logic: unknown): boolean {
+  if (!isOpenBody(logic)) return false;
+  const decl = openBodyDeclarationOf(logic);
+  return (decl.lends.agents?.length ?? 0) > 0 || decl.allows.models.length > 0;
+}
+
+/**
+ * Refuse a Machine with a state that invokes an Agent, or an Open body that can run one, when that
+ * state and all its ancestors have no `agent.fault` route (ADR-0074). The slots are the Machine's
+ * own `actors`. Throws one line that names each state, the event and the route to write.
+ */
+export function refuseUnroutedAgentFault(machine: AnyStateMachine): void {
+  const actors = (machine.implementations.actors ?? {}) as Record<string, unknown>;
+  const agents: string[] = [];
+  const bodies: string[] = [];
+  for (const node of statesOf(machine.root as Node)) {
+    if (routedAt(node, "agent.fault")) continue;
+    const srcs = node.invoke.map((inv) => (typeof inv.src === "string" ? actors[inv.src] : undefined));
+    if (srcs.some((logic) => isAgent(logic))) agents.push(node.id);
+    else if (srcs.some((logic) => runsChartAgents(logic))) bodies.push(node.id);
+  }
+  if (!agents.length && !bodies.length) return;
+  const clause = (ids: string[], what: string) =>
+    `${ids.length > 1 ? "states" : "state"} ${quoted(ids)} ${ids.length > 1 ? "invoke" : "invokes"} ${what}`;
+  const what = [
+    ...(agents.length ? [clause(agents, "an Agent")] : []),
+    ...(bodies.length ? [clause(bodies, "an Open body that can run an Agent")] : []),
+  ].join(", and ");
+  const many = agents.length + bodies.length > 1;
+  throw new Error(
+    `machine "${machine.id}": ${what}, and no route for "agent.fault" is on ${many ? "them" : "it"} or on a state ` +
+      `above — jr2 sends agent.fault when the Agent's Turn cannot go on, and with no route the run faults: route it ` +
+      `on that state or on a state above it, as on: { "agent.fault": "<the state that handles it>" } (ADR-0074)`,
+  );
+}
+
+/** Does the body stay in this final state? It does when the final state is nested, its compound
+ * state has no `onDone`, and that compound state is no region of a parallel state. */
+function staysIn(final: Node): boolean {
+  const parent = final.parent;
+  if (parent === undefined || parent.parent === undefined) return false;
+  if (parent.parent.type === "parallel") return false;
+  return !parent.transitions.has(`xstate.done.state.${parent.id}`);
+}
+
+/**
+ * Refuse a `workspace()` body with a state that is not final, that it can stay in, when that state
+ * and all its ancestors have no `workspace.lost` route (ADR-0074). Throws one line that names each
+ * state, the event and the route to write.
+ */
+export function refuseUnroutedLost(body: AnyStateMachine): void {
+  // The leaves: an atomic state, a root with no child state, or a final state that the body can stay
+  // in. A history state is no state the body is in.
+  const unrouted = statesOf(body.root as Node)
+    .filter((node) => Object.keys(node.states).length === 0 && node.type !== "history")
+    .filter((node) => node.type !== "final" || staysIn(node))
+    .filter((node) => !routedAt(node, "workspace.lost"))
+    // The body stays in the compound state of a final state that it can stay in, and that state is
+    // not final: the line names it.
+    .map((node) => (node.type === "final" ? node.parent!.id : node.id));
+  if (!unrouted.length) return;
+  const many = unrouted.length > 1;
+  throw new Error(
+    `workspace(): the body "${body.id}" has ${many ? "states" : "a state"} ${quoted(unrouted)} that ` +
+      `${many ? "are" : "is"} not final, and no route for "workspace.lost" is on ${many ? "them" : "it"} or on a ` +
+      `state above — jr2 sends workspace.lost to the body when its Sandbox is gone, and with no route the run ` +
+      `faults: route it on the body's root, as on: { "workspace.lost": "<the state that handles it>" } (ADR-0074)`,
+  );
+}
+
+/** The parts of an `@xstate.microstep` inspection event that the runtime check reads. */
+export type MicrostepView = {
+  actorRef: { id: string; getSnapshot(): unknown; logic?: unknown };
+  event: { type: string; reason?: unknown };
+  snapshot?: unknown;
+  _transitions?: readonly unknown[];
+};
+
+/**
+ * The fault of a microstep in which a Machine got `agent.fault` or `workspace.lost` and took no
+ * transition for it (ADR-0074), or undefined for every other microstep. The text names the event,
+ * the Machine and its state, and the event's `reason`. For `workspace.lost` this is the body's
+ * microstep: the wrapper always takes its own transition, to forward the event to the body.
+ */
+export function unroutedMechanismEvent(ev: MicrostepView): string | undefined {
+  const type = ev.event?.type;
+  if (!(ROUTED_MECHANISM_EVENTS as readonly string[]).includes(type)) return undefined;
+  if (ev._transitions === undefined || ev._transitions.length > 0) return undefined;
+  const snapshot = (ev.snapshot ?? ev.actorRef.getSnapshot()) as { value?: unknown; status?: string } | undefined;
+  if (snapshot?.status !== undefined && snapshot.status !== "active") return undefined;
+  const machine = (ev.actorRef.logic as { id?: unknown } | undefined)?.id;
+  const name = typeof machine === "string" ? machine : ev.actorRef.id;
+  const reason = typeof ev.event.reason === "string" && ev.event.reason !== "" ? ev.event.reason : "no reason given";
+  return (
+    `machine "${name}" got "${type}" in state ${JSON.stringify(snapshot?.value ?? null)}, and no transition took ` +
+    `it (${reason}) — no route for "${type}" is on that state or on a state above, or the guard of each route ` +
+    `was false: route it with a transition that is always taken (ADR-0074)`
+  );
+}

package/src/model-keys.generated.ts

@@ -0,0 +1,53 @@
+// Made from @earendil-works/pi-ai 1.4.0 by `just model-keys` (packages/harness/scripts/model-keys.ts).
+// Do not edit: run the recipe at each pi bump. `model-keys.ts` says what the table means (ADR-0059).
+
+import type { ModelKey } from "./model-keys.ts";
+
+export const MODEL_KEYS: Readonly<Record<string, ModelKey>> = {
+  // No default host: the calls go to more than one host: bedrock-runtime.us-east-1.amazonaws.com, bedrock-runtime.eu-central-1.amazonaws.com.
+  AWS_BEARER_TOKEN_BEDROCK: { providers: ["amazon-bedrock"] },
+  ANT_LING_API_KEY: { providers: ["ant-ling"], host: "api.ant-ling.com" },
+  ANTHROPIC_AUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_OAUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_API_KEY: { providers: ["anthropic"], host: "api.anthropic.com" },
+  // No default host: the catalog names no base URL.
+  AZURE_OPENAI_API_KEY: { providers: ["azure"] },
+  BASETEN_API_KEY: { providers: ["baseten"], host: "inference.baseten.co" },
+  CEREBRAS_API_KEY: { providers: ["cerebras"], host: "api.cerebras.ai" },
+  // No default host: a base URL is a template.
+  CLOUDFLARE_API_KEY: { providers: ["cloudflare-ai-gateway", "cloudflare-workers-ai"] },
+  DEEPSEEK_API_KEY: { providers: ["deepseek"], host: "api.deepseek.com" },
+  FIREWORKS_API_KEY: { providers: ["fireworks"], host: "api.fireworks.ai" },
+  COPILOT_GITHUB_TOKEN: { providers: ["github-copilot"], host: "api.individual.githubcopilot.com" },
+  GEMINI_API_KEY: { providers: ["google"], host: "generativelanguage.googleapis.com" },
+  // No default host: a base URL is a template.
+  GOOGLE_CLOUD_API_KEY: { providers: ["google-vertex"] },
+  GROQ_API_KEY: { providers: ["groq"], host: "api.groq.com" },
+  HF_TOKEN: { providers: ["huggingface"], host: "router.huggingface.co" },
+  KIMI_API_KEY: { providers: ["kimi-coding"], host: "api.kimi.com" },
+  META_API_KEY: { providers: ["meta"], host: "api.meta.ai" },
+  MINIMAX_API_KEY: { providers: ["minimax"], host: "api.minimax.io" },
+  MINIMAX_CN_API_KEY: { providers: ["minimax-cn"], host: "api.minimaxi.com" },
+  MISTRAL_API_KEY: { providers: ["mistral"], host: "api.mistral.ai" },
+  // No default host: the calls go to more than one host: api.moonshot.ai, api.moonshot.cn.
+  MOONSHOT_API_KEY: { providers: ["moonshotai", "moonshotai-cn"] },
+  NVIDIA_API_KEY: { providers: ["nvidia"], host: "integrate.api.nvidia.com" },
+  OPENAI_API_KEY: { providers: ["openai"], host: "api.openai.com" },
+  OPENCODE_API_KEY: { providers: ["opencode", "opencode-go"], host: "opencode.ai" },
+  OPENROUTER_API_KEY: { providers: ["openrouter"], host: "openrouter.ai" },
+  QWEN_TOKEN_PLAN_API_KEY: {
+    providers: ["qwen-token-plan", "qwen-token-plan-individual"],
+    host: "token-plan.ap-southeast-1.maas.aliyuncs.com",
+  },
+  QWEN_TOKEN_PLAN_CN_API_KEY: { providers: ["qwen-token-plan-cn"], host: "token-plan.cn-beijing.maas.aliyuncs.com" },
+  RADIUS_API_KEY: { providers: ["radius"], host: "radius.pi.dev" },
+  TOGETHER_API_KEY: { providers: ["together"], host: "api.together.ai" },
+  AI_GATEWAY_API_KEY: { providers: ["vercel-ai-gateway"], host: "ai-gateway.vercel.sh" },
+  XAI_API_KEY: { providers: ["xai"], host: "api.x.ai" },
+  XIAOMI_API_KEY: { providers: ["xiaomi"], host: "api.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_AMS_API_KEY: { providers: ["xiaomi-token-plan-ams"], host: "token-plan-ams.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_CN_API_KEY: { providers: ["xiaomi-token-plan-cn"], host: "token-plan-cn.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_SGP_API_KEY: { providers: ["xiaomi-token-plan-sgp"], host: "token-plan-sgp.xiaomimimo.com" },
+  ZAI_API_KEY: { providers: ["zai"], host: "api.z.ai" },
+  ZAI_CODING_CN_API_KEY: { providers: ["zai-coding-cn"], host: "open.bigmodel.cn" },
+};

package/src/model-keys.ts

@@ -1,17 +1,29 @@
 // The known model keys (ADR-0059): every env var pi's catalog reads a provider's credential from,
 // the catalog provider(s) that read it, and the one host those providers' calls go to by default.
 //
-// A COPY of pi's data at the exact pin `@jr2/harness` holds, because this package has no pi
-// dependency and must not grow one: `jr2 up` reads this table host-side (R1, and the default
-// `hosts` of a held secret), and the in-cluster Orchestrator never touches pi. The copy cannot
-// drift silently — `@jr2/harness`'s `model-keys.test.ts` checks it against pi itself, env names per
-// provider and every provider's default host, in the default gate. A pi bump that adds or moves a
-// provider fails there first, the same canary role Harness conformance plays (ADR-0027).
+// pi's data at the exact pin `@jr2/harness` holds, made into plain data by a script, because this
+// package has no pi dependency and must not grow one: `jr2 up` reads this table host-side (R1, and
+// the default `hosts` of a held secret), and the in-cluster Orchestrator never touches pi. The table
+// is `model-keys.generated.ts`, and `just model-keys` writes it from pi-ai at each pi bump
+// (`packages/harness/scripts/model-keys.ts`). It cannot drift silently: `@jr2/harness`'s
+// `model-keys.test.ts` checks it against pi itself, env names per provider and every provider's
+// default host, in the default gate. A pi bump that adds or moves a provider fails there first, the
+// same canary role Harness conformance plays (ADR-0027).
 //
 // `host` is present only when every model of every provider that reads the name goes to ONE static
 // host. It is absent when there is none: the base URL is a template (`{location}`, an account id),
 // the providers disagree (MOONSHOT_API_KEY serves two regions), or the host is regional (Bedrock).
 // A held secret with such a name must then say its `hosts` itself (§3.4 of the spec, R5).
+//
+// Two facts the data does not say. anthropic reads three names: AUTH_TOKEN goes as `Authorization:
+// Bearer`, the other two as `x-api-key` (an `sk-ant-oat` value is an OAuth token, which a Stand-in
+// never is). AWS_BEARER_TOKEN_BEDROCK is the bearer form of Bedrock auth, which pi reads through
+// its credential chain; SigV4 credentials cannot be held at all — a signature is not a header a
+// Stand-in can be swapped into — and `jr2 up` warns on them (`SIGNING_CREDENTIALS`).
+
+import { MODEL_KEYS } from "./model-keys.generated.ts";
+
+export { MODEL_KEYS };
 
 /** One known model-key env name. */
 export type ModelKey = {
@@ -21,58 +33,6 @@ export type ModelKey = {
   host?: string;
 };
 
-export const MODEL_KEYS: Readonly<Record<string, ModelKey>> = {
-  // anthropic reads three names. AUTH_TOKEN goes as `Authorization: Bearer`, the other two as
-  // `x-api-key` (an `sk-ant-oat` value is an OAuth token, which a Stand-in never is).
-  ANTHROPIC_API_KEY: { providers: ["anthropic"], host: "api.anthropic.com" },
-  ANTHROPIC_AUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
-  ANTHROPIC_OAUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
-  OPENAI_API_KEY: { providers: ["openai"], host: "api.openai.com" },
-  GEMINI_API_KEY: { providers: ["google"], host: "generativelanguage.googleapis.com" },
-  // `https://{location}-aiplatform.googleapis.com` — regional, so no default.
-  GOOGLE_CLOUD_API_KEY: { providers: ["google-vertex"] },
-  COPILOT_GITHUB_TOKEN: { providers: ["github-copilot"], host: "api.individual.githubcopilot.com" },
-  // The bearer form of Bedrock auth. Regional, so no default. (SigV4 credentials cannot be held at
-  // all — a signature is not a header a Stand-in can be swapped into — and `jr2 up` warns on them.)
-  AWS_BEARER_TOKEN_BEDROCK: { providers: ["amazon-bedrock"] },
-  ANT_LING_API_KEY: { providers: ["ant-ling"], host: "api.ant-ling.com" },
-  QWEN_TOKEN_PLAN_API_KEY: {
-    providers: ["qwen-token-plan"],
-    host: "token-plan.ap-southeast-1.maas.aliyuncs.com",
-  },
-  QWEN_TOKEN_PLAN_CN_API_KEY: { providers: ["qwen-token-plan-cn"], host: "token-plan.cn-beijing.maas.aliyuncs.com" },
-  // The catalog names no base URL: an Azure deployment is the user's own resource.
-  AZURE_OPENAI_API_KEY: { providers: ["azure-openai-responses"] },
-  NVIDIA_API_KEY: { providers: ["nvidia"], host: "integrate.api.nvidia.com" },
-  DEEPSEEK_API_KEY: { providers: ["deepseek"], host: "api.deepseek.com" },
-  GROQ_API_KEY: { providers: ["groq"], host: "api.groq.com" },
-  CEREBRAS_API_KEY: { providers: ["cerebras"], host: "api.cerebras.ai" },
-  XAI_API_KEY: { providers: ["xai"], host: "api.x.ai" },
-  // pi reads the name, and its catalog lists no model for the provider at this pin.
-  RADIUS_API_KEY: { providers: ["radius"] },
-  OPENROUTER_API_KEY: { providers: ["openrouter"], host: "openrouter.ai" },
-  AI_GATEWAY_API_KEY: { providers: ["vercel-ai-gateway"], host: "ai-gateway.vercel.sh" },
-  ZAI_API_KEY: { providers: ["zai"], host: "api.z.ai" },
-  ZAI_CODING_CN_API_KEY: { providers: ["zai-coding-cn"], host: "open.bigmodel.cn" },
-  MISTRAL_API_KEY: { providers: ["mistral"], host: "api.mistral.ai" },
-  MINIMAX_API_KEY: { providers: ["minimax"], host: "api.minimax.io" },
-  MINIMAX_CN_API_KEY: { providers: ["minimax-cn"], host: "api.minimaxi.com" },
-  // Two providers, two hosts (`.ai` and `.cn`): no single default.
-  MOONSHOT_API_KEY: { providers: ["moonshotai", "moonshotai-cn"] },
-  HF_TOKEN: { providers: ["huggingface"], host: "router.huggingface.co" },
-  FIREWORKS_API_KEY: { providers: ["fireworks"], host: "api.fireworks.ai" },
-  TOGETHER_API_KEY: { providers: ["together"], host: "api.together.ai" },
-  // Two providers, one host.
-  OPENCODE_API_KEY: { providers: ["opencode", "opencode-go"], host: "opencode.ai" },
-  KIMI_API_KEY: { providers: ["kimi-coding"], host: "api.kimi.com" },
-  // Account-templated base URLs.
-  CLOUDFLARE_API_KEY: { providers: ["cloudflare-workers-ai", "cloudflare-ai-gateway"] },
-  XIAOMI_API_KEY: { providers: ["xiaomi"], host: "api.xiaomimimo.com" },
-  XIAOMI_TOKEN_PLAN_CN_API_KEY: { providers: ["xiaomi-token-plan-cn"], host: "token-plan-cn.xiaomimimo.com" },
-  XIAOMI_TOKEN_PLAN_AMS_API_KEY: { providers: ["xiaomi-token-plan-ams"], host: "token-plan-ams.xiaomimimo.com" },
-  XIAOMI_TOKEN_PLAN_SGP_API_KEY: { providers: ["xiaomi-token-plan-sgp"], host: "token-plan-sgp.xiaomimimo.com" },
-};
-
 /** Every catalog provider id some known model key belongs to — the set `harness.catalog` may name. */
 export const MODEL_KEY_PROVIDERS: ReadonlySet<string> = new Set(
   Object.values(MODEL_KEYS).flatMap((key) => key.providers),

package/src/mount-digest.ts

@@ -0,0 +1,53 @@
+// What a mounted ConfigMap holds, as one digest (ADR-0038, ADR-0069). A publish rolls no pod, so
+// the Orchestrator reads `jr2-images` and `jr2-held` through mounts the kubelet refreshes on its
+// own period. `jr2 up` digests the data it applied, `GET /assembly` reports the digest of what the
+// process reads, and the publish waits until the two agree. Then the door's checks, and the
+// provisions that follow the converge, read the data this converge wrote.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { HELD_CONFIGMAP, HELD_MOUNT, IMAGES_CONFIGMAP, IMAGES_MOUNT } from "./names.ts";
+
+/** The ConfigMaps the Orchestrator reads through a mount, by name, and where each is mounted. */
+export const MOUNTED_CONFIGMAPS: Readonly<Record<string, string>> = {
+  [IMAGES_CONFIGMAP]: IMAGES_MOUNT,
+  [HELD_CONFIGMAP]: HELD_MOUNT,
+};
+
+/** One digest of a ConfigMap's `data`: the same bytes give the same digest at both ends. */
+export function configMapDigest(data: Readonly<Record<string, string>>): string {
+  const entries = Object.keys(data)
+    .sort()
+    .map((key) => [key, data[key]]);
+  return createHash("sha256").update(JSON.stringify(entries)).digest("hex").slice(0, 16);
+}
+
+/**
+ * The digest of a mounted ConfigMap, read from its mount (ADR-0069). The kubelet writes each key
+ * as a file and keeps its own entries under names that start with `.`, which are not data. An
+ * absent mount reads as `undefined`.
+ */
+export async function readMountDigest(dir: string): Promise<string | undefined> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return undefined;
+  }
+  const data: Record<string, string> = {};
+  for (const name of names.filter((n) => !n.startsWith("."))) data[name] = await readFile(join(dir, name), "utf8");
+  return configMapDigest(data);
+}
+
+/** Every mounted ConfigMap's digest, by name; a mount that is absent is left out. */
+export async function readMountDigests(
+  mounts: Readonly<Record<string, string>> = MOUNTED_CONFIGMAPS,
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const [name, dir] of Object.entries(mounts)) {
+    const digest = await readMountDigest(dir);
+    if (digest !== undefined) out[name] = digest;
+  }
+  return out;
+}

package/src/names.ts

@@ -9,7 +9,7 @@ export const ORCHESTRATOR_PORT = 4000;
 /** The instance-owned Secret: Instance token + signing key (+ orchestrator-side creds). */
 export const INSTANCE_SECRET = "jr2-instance";
 
-/** The Instance Harness's Deployment + Service name (ADR-0031): converged by `jr2 up` whenever any
+/** The Instance Harness's StatefulSet + Service name (ADR-0031): converged by `jr2 up` whenever any
  * Agent definition declares `workspace: "none"`, and the deterministic Service DNS the Agent actor
  * resolves such a Turn to. Doubles as the delivery scope a Menu-only registration records — the
  * name the placement's Sandbox token is signed for (tokens.ts, ADR-0013), which its Custodian holds. The port is the
@@ -17,6 +17,19 @@ export const INSTANCE_SECRET = "jr2-instance";
 export const INSTANCE_HARNESS_SERVICE = "jr2-instance-harness";
 export const INSTANCE_HARNESS_PORT = 8080;
 
+/** The Instance Effector (ADR-0068): its Deployment, headless Service, NetworkPolicy and Secret all
+ * carry this name. `jr2 up` converges them when a registered Machine places an Effect there. The
+ * port is the Effector's own (`JR2_EFFECTOR_PORT` default) — none of the Harness pod's ports. */
+export const INSTANCE_EFFECTOR = "jr2-instance-effector";
+export const EFFECTOR_PORT = 8082;
+
+/** Where a Harness persists its conversations, and the env var that tells it so (ADR-0031): one
+ * fixed path in both placements — the Instance Harness's PersistentVolumeClaim (deploy.ts) and a
+ * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. */
+export const CONVERSATIONS_DIR = "/conversations";
+export const CONVERSATIONS_DIR_ENV = "JR2_CONVERSATIONS_DIR";
+export const CONVERSATIONS_VOLUME = "conversations";
+
 /** The harness config ConfigMap the stock Harness boots from (ADR-0018): what this instance can
  * REACH — the custom model provider minus its key, and the catalog providers' gateways (ADR-0059). No Agents ride it: a Machine carries its own
  * (ADR-0049), and the definition rides each admission, so this holds deployment facts alone
@@ -50,17 +63,40 @@ export const CA_CONFIGMAP = "jr2-ca";
 /** Held secrets (ADR-0059). The per-Instance CA — its key included — that `jr2 up` alone reads over
  * the kube API, and that NO pod mounts: every leaf is issued before a pod starts. */
 export const HELD_CA_SECRET = "jr2-held-ca";
-/** The literal held values, one key per name — mounted into the Custodian and nothing else. */
+/** The prefix of each pod's literal held values (`heldSecretsSecret`): one Secret per pod, one key
+ * per name it holds — mounted into that pod's Custodian and nothing else. */
 export const HELD_SECRETS_SECRET = "jr2-held-secrets";
-/** One leaf per bound `host:port` (`<stem>.crt`, `<stem>.key`) — the Custodian's alone. */
+/** The literal held values of one pod (ADR-0059): `jr2-held-secrets-<pod>`. */
+export function heldSecretsSecret(pod: string): string {
+  return `${HELD_SECRETS_SECRET}-${pod}`;
+}
+/** One leaf per bound `host:port` (`<stem>.crt`, `<stem>.key`) — the Custodians' alone. */
 export const HELD_TLS_SECRET = "jr2-held-tls";
-/** `held.json` (what `jr2 up` resolved) plus the Custodian's bootstrap and script. Always applied,
- * possibly holding no secret: every Harness pod runs a Custodian. */
+/** What `jr2 up` DECLARES about held secrets: each pod's held manifest (`heldManifestKey` — names,
+ * bindings, headers; never a value) and the Custodian's program once (`CUSTODIAN_PROGRAM_KEY`).
+ * Nothing rendered per pod lives here: a shared object stops at 1 MiB, and Envoy's files are a
+ * pod's own, rendered where the pod is made (`sandboxCustodianConfigMap`,
+ * `INSTANCE_CUSTODIAN_CONFIGMAP`). Always applied, possibly holding no secret: every Harness pod
+ * runs a Custodian. */
 export const HELD_CONFIGMAP = "jr2-held";
-/** Where the Orchestrator reads `held.json`, per provision — a mount, so a held-secret edit reaches
- * future Sandboxes without rolling the Orchestrator (the `jr2-images` pattern, ADR-0038). */
+/** Where the Orchestrator reads a Workspace's held manifest, per provision — a mount, so a
+ * held-secret edit reaches future Sandboxes without rolling the Orchestrator (the `jr2-images`
+ * pattern, ADR-0038). */
 export const HELD_MOUNT = "/etc/jr2/held";
-export const HELD_KEY = "held.json";
+/** The `jr2-held` key of one pod's manifest. */
+export const heldManifestKey = (pod: string): string => `held-${pod}.json`;
+/** The `jr2-held` key of the Custodian's fixed Lua — `custodian.lua` as written, once per Instance;
+ * each pod's own script loads it by this name from its config mount. */
+export const CUSTODIAN_PROGRAM_KEY = "program.lua";
+/** The ConfigMap with the Instance Harness's Custodian's two rendered files (`envoy.json`,
+ * `custodian.lua`), written by `jr2 up`: the one pod it makes. */
+export const INSTANCE_CUSTODIAN_CONFIGMAP = "jr2-held-custodian";
+/** The ConfigMap with one Sandbox's Custodian's two rendered files, written by the Orchestrator at
+ * provision and owned by the Sandbox CR — the `<name>-token` family: it goes with the pod. */
+export const sandboxCustodianConfigMap = (sandbox: string): string => `${sandbox}-custodian`;
+/** The Instance Harness's pod, as its held objects are keyed. A Workspace's is `ws-<digest>`
+ * (`workspaceHeldPod`), so the two cannot collide. */
+export const INSTANCE_HARNESS_HELD_POD = "instance";
 
 /** The Custodian's listeners (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
  * HTTPS proxy on loopback, the kubelet's probe, and the control listener the Menu and the ask ride
@@ -100,3 +136,25 @@ export const ANNOTATION_REPO_LAST_ATTACHED = "jr2.dev/last-attached";
  * that started before the ask does not satisfy it. The Lease's shape: an annotation, written by
  * the Orchestrator, read by the operator. */
 export const askedAnnotation = (key: string): string => `jr2.dev/asked-${key}`;
+
+/** The two PriorityClasses `jr2 up` creates, cluster-scoped, beside the CRDs (ADR-0060) — unless
+ * `priorityClasses` in jr2.config.ts names existing ones. `jr2-control` (100000,
+ * PreemptLowerPriority) is for the Orchestrator, the operator and the Repo cache agent: small, fixed,
+ * and needed by every Sandbox. `jr2-sandbox` (1000, preemptionPolicy Never) is for Sandboxes and the
+ * Instance Harness: an ordinary pod cannot preempt a live Workspace, and a waiting Sandbox evicts
+ * nobody. Both stay far below the system classes. */
+export const PRIORITY_CLASS_CONTROL = "jr2-control";
+export const PRIORITY_CLASS_SANDBOX = "jr2-sandbox";
+
+/** The voluntary-disruption opt-outs (ADR-0060) a Sandbox pod and the Instance Harness pod carry:
+ * moving either loses work (`/work`; live conversations). No PodDisruptionBudget — `maxUnavailable:
+ * 0` blocks node upgrades without end. */
+export const NO_DISRUPT_ANNOTATIONS = {
+  "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
+  "karpenter.sh/do-not-disrupt": "true",
+} as const;
+
+/** The API server's CA as the kubelet mounts it with the Pod's ServiceAccount. The Orchestrator
+ * Deployment points `NODE_EXTRA_CA_CERTS` at it, so the Orchestrator's own Kubernetes client
+ * (kube-client.ts, ADR-0063) trusts the API server with built-in `fetch` and no TLS code. */
+export const SERVICE_ACCOUNT_CA = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt";

package/src/notices.ts

@@ -0,0 +1,141 @@
+// The Orchestrator's notices (ADR-0062): what happened that the next Turn cannot find out for
+// itself — a memory kill in its Workspace, a conversation that is new — kept as plain data in the
+// run's persisted state (ADR-0007), beside the admission and epoch ledgers, and handed to the next
+// admission in scope. The Harness writes every word; this is only the keeping.
+//
+// Delivered ONCE, and "delivered" means LEDGERED: a notice leaves the pending set in the same save
+// that records the admission it rode. A restart before that save finds it still pending and the
+// restored Turn's admission carries it again; a restart after it does not. Between `take` and that
+// save the notice is RESERVED, in memory only, so a second admission in the same scope cannot carry
+// it too — and a restart forgets reservations along with everything else in memory.
+
+import type { Notice } from "./wire.ts";
+
+/** Where an admission may hear notices: its continued conversation's base Instance ID (ADR-0057)
+ * and its Workspace's Sandbox name. Either may be absent — a fresh Turn has no conversation to be
+ * told about, and a Menu-only Agent works in no Workspace. `only`, when set, narrows the take to
+ * the notices raised by these sources: what a nudge or a wake carries (ADR-0062). `except` leaves
+ * out the notices raised by these: what a re-admission of the same Turn was told already;
+ * `exceptPrefix` every notice whose source starts so — all guard kills, when that is not known. */
+export type NoticeScope = {
+  conversation?: string;
+  workspace?: string;
+  only?: readonly string[];
+  except?: readonly string[];
+  exceptPrefix?: string;
+};
+
+/** One pending notice: the notice, and the conversation or Workspace it goes to. `source` names
+ * the event that raised it, so the same event raised twice — two Turns lost to one kernel kill, a
+ * stream read replayed after a restore — is one notice. */
+export type PendingNotice = { id: string; notice: Notice; to: string; source?: string };
+
+/** The persisted form (`RunBlob.notices`). `seen` is every source ever raised, so a delivered
+ * notice is not raised again by a late or replayed witness of the same event. */
+export type NoticeLedgerState = { pending: PendingNotice[]; seen: string[] };
+
+/** What one admission takes: the notices it carries, and their ids for the ledger write. */
+export type TakenNotices = {
+  ids: string[];
+  notices: Notice[];
+  /** Every notice taken, with the source it was raised with — what `restore` puts back when no
+   * model heard the admission. */
+  raised?: Array<{ notice: Notice; source?: string }>;
+};
+
+export class NoticeLedger {
+  readonly #pending: PendingNotice[];
+  readonly #seen: Set<string>;
+  readonly #reserved = new Set<string>();
+  readonly #newId: () => string;
+
+  constructor(state: NoticeLedgerState | undefined, newId: () => string) {
+    this.#pending = [...(state?.pending ?? [])];
+    this.#seen = new Set(state?.seen ?? []);
+    this.#newId = newId;
+  }
+
+  /** Raise a notice for `to` (a conversation's base id, or a Sandbox name — the notice's own
+   * `scope` says which). `older` are the sources of earlier events that this one tells the same as —
+   * a burst of guard kills, read at once: they are marked raised and give no notice of their own.
+   * Answers whether anything changed — a notice pending, or a source marked — so the caller saves
+   * only then. */
+  raise(notice: Notice, to: string, source?: string, older: readonly string[] = []): boolean {
+    let changed = false;
+    for (const seen of older) {
+      if (this.#seen.has(seen)) continue;
+      this.#seen.add(seen);
+      changed = true;
+    }
+    if (source !== undefined) {
+      if (this.#seen.has(source)) return changed;
+      this.#seen.add(source);
+    } else {
+      // A notice with no source is one notice with a pending twin that has none either. A notice
+      // WITH a source keeps its own entry, so a take by source (`only`, `except`) finds it; equal
+      // ones are one notice in the admission (`take`).
+      const same = JSON.stringify(notice);
+      if (this.#pending.some((p) => p.source === undefined && p.to === to && JSON.stringify(p.notice) === same)) {
+        return changed;
+      }
+    }
+    this.#pending.push({ id: this.#newId(), notice, to, ...(source === undefined ? {} : { source }) });
+    return true;
+  }
+
+  /** Reserve every unreserved notice in this admission's scope, in the order raised. Equal notices —
+   * two kills that tell the same thing — are said once, and every id is reserved. */
+  take(scope: NoticeScope): TakenNotices {
+    const taken = this.#pending.filter(
+      (p) =>
+        !this.#reserved.has(p.id) &&
+        (scope.only === undefined || (p.source !== undefined && scope.only.includes(p.source))) &&
+        (scope.except === undefined || p.source === undefined || !scope.except.includes(p.source)) &&
+        (scope.exceptPrefix === undefined || p.source === undefined || !p.source.startsWith(scope.exceptPrefix)) &&
+        (p.notice.scope === "conversation" ? p.to === scope.conversation : p.to === scope.workspace),
+    );
+    for (const p of taken) this.#reserved.add(p.id);
+    const said = new Set<string>();
+    const notices = taken.flatMap((p) => {
+      const key = JSON.stringify(p.notice);
+      if (said.has(key)) return [];
+      said.add(key);
+      return [p.notice];
+    });
+    return {
+      ids: taken.map((p) => p.id),
+      notices,
+      raised: taken.map((p) => ({ notice: p.notice, ...(p.source === undefined ? {} : { source: p.source }) })),
+    };
+  }
+
+  /** Put back a notice an admission carried that no model heard, with the source it was raised
+   * with — `seen` already holds it, so a raise would drop it. Nothing changes when a notice with
+   * that source is pending already. Answers whether anything changed. */
+  restore(notice: Notice, to: string, source?: string): boolean {
+    if (source === undefined) return this.raise(notice, to);
+    if (this.#pending.some((p) => p.source === source && p.to === to)) return false;
+    this.#seen.add(source);
+    this.#pending.push({ id: this.#newId(), notice, to, source });
+    return true;
+  }
+
+  /** The admission that carried them was ledgered: they are delivered. */
+  delivered(ids: readonly string[]): void {
+    for (const id of ids) {
+      this.#reserved.delete(id);
+      const at = this.#pending.findIndex((p) => p.id === id);
+      if (at !== -1) this.#pending.splice(at, 1);
+    }
+  }
+
+  /** The admission that carried them failed: they are pending again, for the next one. */
+  release(ids: readonly string[]): void {
+    for (const id of ids) this.#reserved.delete(id);
+  }
+
+  /** The persisted form — reserved notices included, because reserved is not delivered. */
+  state(): NoticeLedgerState {
+    return { pending: [...this.#pending], seen: [...this.#seen] };
+  }
+}