@jr2/orchestrator 0.4.1 → 0.6.0

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),
@@ -90,3 +50,27 @@ export const SIGNING_CREDENTIALS: readonly string[] = [
   "AWS_PROFILE",
   "GOOGLE_APPLICATION_CREDENTIALS",
 ];
+
+/**
+ * Names whose value is the path of a credential or trust file that the Harness PROCESS reads (the
+ * AWS SDK, Google's library), when `harness.env` or `harness.envFrom` sets one (ADR-0076). The
+ * Harness runs with the control Stand-in in its memory, so such a file must be one that the Agent's
+ * code cannot write: `~/.aws/config` can name a `credential_process`, which the SDK runs. `jr2 up`
+ * refuses a path that the domain writes for certain (`DOMAIN_WRITABLE_ROOTS`), and warns on any
+ * other, because whether the Sandbox's uid can write a path of the image is the image's, which jr2
+ * cannot read. An image's own `ENV` never reaches the Harness process.
+ */
+export const CREDENTIAL_FILES: readonly string[] = [
+  "AWS_CONFIG_FILE",
+  "AWS_SHARED_CREDENTIALS_FILE",
+  "AWS_WEB_IDENTITY_TOKEN_FILE",
+  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
+  "AWS_CA_BUNDLE",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "GOOGLE_API_CERTIFICATE_CONFIG",
+  "CLOUDSDK_CONFIG",
+];
+
+/** Folders of a Sandbox's Harness container that the domain writes in every pod: the Worktree root,
+ * the temporary folders, `/dev/shm`, and the HOME that jr2 gives an image with no `USER`. */
+export const DOMAIN_WRITABLE_ROOTS: readonly string[] = ["/work", "/tmp", "/var/tmp", "/dev/shm", "/home/jr2"];

package/src/names.ts

@@ -25,8 +25,10 @@ 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";
+ * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. It is under
+ * `/run/jr2`, as each path that the Harness holds alone is, so no process that the Harness confines
+ * can read an Agent's history or write into it (ADR-0076). */
+export const CONVERSATIONS_DIR = "/run/jr2/conversations";
 export const CONVERSATIONS_DIR_ENV = "JR2_CONVERSATIONS_DIR";
 export const CONVERSATIONS_VOLUME = "conversations";
 
@@ -98,12 +100,23 @@ export const sandboxCustodianConfigMap = (sandbox: string): string => `${sandbox
  * (`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
- * to the Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). */
+/** The Custodian's ports (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
+ * HTTPS proxy on loopback, the kubelet's probe, and the fetch listener that the ask rides to the
+ * Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). The agent routes are not
+ * on a port: they are on the control socket ({@link CUSTODIAN_CONTROL_SOCKET}, ADR-0076). */
 export const CUSTODIAN_PORT = 15001;
 export const CUSTODIAN_HEALTH_PORT = 15021;
-export const CUSTODIAN_CONTROL_PORT = 8081;
+export const CUSTODIAN_FETCH_PORT = 8081;
+
+/** The folder of the Custodian's control socket (ADR-0076): an emptyDir that the Harness container
+ * and the Custodian container alone mount, at this path in both. It is under `/run/jr2`, so no
+ * process that the Harness confines can make a socket here, and none can take the control
+ * listener's place while the Custodian restarts. The Custodian writes it; the Harness mounts it
+ * read-only, which still lets it connect to the socket. */
+export const CUSTODIAN_SOCKET_DIR = "/run/jr2/custodian";
+/** The control socket: the Custodian's listener for the four agent routes, which carry the control
+ * Stand-in (ADR-0059, ADR-0076). */
+export const CUSTODIAN_CONTROL_SOCKET = `${CUSTODIAN_SOCKET_DIR}/control.sock`;
 
 /** The scaffold's default deploy-key Secret name (ADR-0047/0051): what `jr2 init`'s wildcard
  * `git.credentials` entry names as its `sshKey`, and what `jr2 up`'s ssh offer generates into when