@jr2/orchestrator 0.5.1 → 0.6.0

package/src/custodian.ts

@@ -21,14 +21,17 @@
 //                             so the two pod shapes cannot drift
 //
 // The Custodian is a separate container from the Harness, and that is the point: the Agent
-// executes code in the Harness container and nothing here (ADR-0005). What it holds — the
-// Sandbox token and every held secret its pod claims — is mounted into this container alone, and
-// `shareProcessNamespace` stays off, so the Agent cannot read its env, its files or its `/proc`.
+// executes code in the Harness container and nothing here (ADR-0005). What it holds — the pod's
+// control and fetch tokens and every held secret its pod claims — is mounted into this container
+// alone, and `shareProcessNamespace` stays off, so the Agent cannot read its env, its files or its
+// `/proc`. The Harness container gets the Stand-ins, every one but the public fetch Stand-in
+// secret, as files under `/run/jr2/` that no child the Harness confines can read (ADR-0076).
 
 import { readFileSync } from "node:fs";
 import type { HarnessEnvVar } from "./config.ts";
 import type { ResourceRequirements } from "./size.ts";
 import {
+  CONTROL_TOKEN_NAME,
   CREDENTIAL_HEADERS,
   SANDBOX_TOKEN_NAME,
   standIn,
@@ -37,10 +40,12 @@ import {
 } from "./held-secrets.ts";
 import {
   CA_CONFIGMAP,
-  CUSTODIAN_CONTROL_PORT,
+  CUSTODIAN_CONTROL_SOCKET,
+  CUSTODIAN_FETCH_PORT,
   CUSTODIAN_HEALTH_PORT,
   CUSTODIAN_PORT,
   CUSTODIAN_PROGRAM_KEY,
+  CUSTODIAN_SOCKET_DIR,
   HELD_CONFIGMAP,
   HELD_TLS_SECRET,
   heldSecretsSecret,
@@ -96,8 +101,60 @@ export const CUSTODIAN_ARGS: readonly string[] = [
   "warning",
 ];
 
-/** The address the Harness reaches the Custodian's control listener at: its Menu and the ask. */
-export const CUSTODIAN_URL = `http://127.0.0.1:${CUSTODIAN_CONTROL_PORT}`;
+/** The address of the Custodian's fetch listener: the ask alone (ADR-0053), which
+ * `jr2-upload-pack` makes from the domain. The Harness container gets it as `JR2_CUSTODIAN_URL`,
+ * the one `JR2_*` name that a confined process keeps (ADR-0076). The agent routes are not here. */
+export const CUSTODIAN_URL = `http://127.0.0.1:${CUSTODIAN_FETCH_PORT}`;
+
+/** The Harness env that names the Custodian's control socket ({@link CUSTODIAN_CONTROL_SOCKET}):
+ * where the Harness sends each control request — the surface read, a pick, a delivery's poll and a
+ * notice's acknowledgment (ADR-0076). A path, never a value; the domain's env does not keep it. */
+export const CUSTODIAN_SOCKET_ENV = "JR2_CUSTODIAN_SOCKET";
+/** The volume of the control socket's folder ({@link CUSTODIAN_SOCKET_DIR}): an emptyDir in the
+ * Harness container and the Custodian container, and in no other container of the pod. */
+export const CUSTODIAN_SOCKET_VOLUME = "custodian-socket";
+
+/** Where the Harness container holds its Stand-ins (ADR-0059, ADR-0076): a read-only mount that no
+ * child the Harness confines can read — the confiner denies all of `/run/jr2`. Never env. */
+export const HARNESS_CREDENTIALS = "/run/jr2";
+/** The secret control Stand-in, as the Harness reads it once at start (C1). */
+export const CONTROL_STANDIN_FILE = `${HARNESS_CREDENTIALS}/control/standin`;
+/** The directory of the held secrets' Stand-ins, one file per name: `<dir>/<NAME>`. */
+export const STANDINS_DIR = `${HARNESS_CREDENTIALS}/standins`;
+/** The Harness env that names the control Stand-in's file; its default is {@link CONTROL_STANDIN_FILE}. */
+export const CONTROL_STANDIN_FILE_ENV = "JR2_CONTROL_STANDIN_FILE";
+/** The Harness env that names the held secrets the `workspace()` grants a confined child (its
+ * `secrets` list, ADR-0076), comma-separated: names, never a value. Absent → none is granted. */
+export const GRANTED_SECRETS_ENV = "JR2_GRANTED_SECRETS";
+
+/**
+ * The keys of a pod's credentials Secret (a Sandbox's `<sandbox>-token`): the fetch token, the
+ * control token, the secret control Stand-in, and one secret Stand-in per held secret
+ * ({@link heldStandInKey}). The pod's maker mints them all. The tokens are projected into the
+ * Custodian alone; each Stand-in into the Custodian, for its swap, and the Harness container.
+ */
+export const CREDENTIAL_KEYS = {
+  fetchToken: "token",
+  controlToken: "control-token",
+  controlStandIn: "control-standin",
+} as const;
+
+/** The key of one held secret's secret Stand-in in its pod's credentials Secret. */
+export function heldStandInKey(name: string): string {
+  return `standin-${name}`;
+}
+
+/** The file of a Stand-in among the Custodian's values: beside its value, `<NAME>.standin`. A held
+ * name is an env var's, so it holds no `.` and never meets another value's file. */
+export function standInValueFile(name: string): string {
+  return `${name}.standin`;
+}
+
+/** The path prefixes each control credential may ride, after the control listener's rewrite
+ * (ADR-0076, C3): the control token on the agent routes alone, the fetch token on the fetch route
+ * alone. The program's path guard refuses either one elsewhere, before any swap. */
+export const CONTROL_PATHS = "/agents/";
+export const FETCH_PATHS = "/sandboxes/";
 
 /** Where the Orchestrator's Service is, from inside a Harness pod. */
 export type OrchestratorAddress = { host: string; port: number };
@@ -409,9 +466,14 @@ function isIpLiteral(host: string): boolean {
  * The Custodian's static bootstrap (ADR-0059): Envoy's whole configuration, rendered once per
  * converge by `jr2 up`, identical for every Harness pod of the Instance.
  *
- *   control   127.0.0.1:8081   the Menu, a pick's answer and the ask, plain HTTP, to the Orchestrator's Service —
- *                              four routes and nothing else, each swapping the Sandbox token's
- *                              Stand-in for the token (ADR-0013, ADR-0053)
+ *   control   /run/jr2/custodian/control.sock
+ *                              the four agent routes — the Menu, a pick, a delivery's poll and a
+ *                              notice's acknowledgment — plain HTTP, to the Orchestrator's Service.
+ *                              They swap the control Stand-in for the control token. A Unix socket
+ *                              in a folder that no confined process can write, so no process in
+ *                              the domain can take this listener's place (ADR-0013, ADR-0076)
+ *   fetch     127.0.0.1:8081   the ask alone, plain HTTP, to the same Service: it swaps the public
+ *                              fetch Stand-in for the fetch token (ADR-0053, ADR-0076)
  *   health    0.0.0.0:15021    GET /healthz, for the kubelet, which cannot reach loopback
  *   egress    127.0.0.1:15001  CONNECT only — present when a held secret exists; a bound target
  *                              goes to its intercept listener, every other one is tunneled
@@ -428,55 +490,76 @@ export function custodianBootstrap(manifest: HeldManifest, orchestrator: Orchest
     metadata: meta({ role: "control", route: name }),
   });
 
+  // One listener toward the Orchestrator, with its routes and the deny route after them: a route
+  // of the other listener gets the deny route's 404 here.
+  const toOrchestrator = (name: string, address: Json, routes: Json[]): Json => ({
+    name,
+    address,
+    filter_chains: [
+      {
+        filters: [
+          hcm(name, {
+            target: orchestratorTarget,
+            idleSeconds: 3600,
+            lua: true,
+            local: ORCHESTRATOR_UNREACHABLE,
+            routes: {
+              virtual_hosts: [
+                {
+                  name: "orchestrator",
+                  domains: ["*"],
+                  routes: [
+                    ...routes,
+                    {
+                      name: "deny",
+                      match: { prefix: "/" },
+                      direct_response: { status: 404 },
+                      metadata: meta({ role: "deny" }),
+                    },
+                  ],
+                },
+              ],
+            },
+          }),
+        ],
+      },
+    ],
+  });
+
   const listeners: Json[] = [
-    {
-      name: "control",
-      address: { socket_address: { address: "127.0.0.1", port_value: CUSTODIAN_CONTROL_PORT } },
-      filter_chains: [
-        {
-          filters: [
-            hcm("control", {
-              target: orchestratorTarget,
-              idleSeconds: 3600,
-              lua: true,
-              local: ORCHESTRATOR_UNREACHABLE,
-              routes: {
-                virtual_hosts: [
-                  {
-                    name: "orchestrator",
-                    domains: ["*"],
-                    routes: [
-                      // A read retries any reset. A pick or an ask retries only a reset before
-                      // it was sent: one the Orchestrator may have read is not sent twice.
-                      route("surface", "GET", "/agents/[^/]+/surface", {
-                        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
-                      }),
-                      route("events", "POST", "/agents/[^/]+/events", {
-                        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
-                      }),
-                      // An outstanding pick's answer, long-polled (ADR-0024): a read, so any reset
-                      // is retried — an Orchestrator restart mid-poll costs a retry, not the pick.
-                      route("deliveries", "GET", "/agents/[^/]+/deliveries/[^/]+", {
-                        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
-                      }),
-                      route("fetch", "POST", "/fetch", {
-                        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
-                      }),
-                      {
-                        name: "deny",
-                        match: { prefix: "/" },
-                        direct_response: { status: 404 },
-                        metadata: meta({ role: "deny" }),
-                      },
-                    ],
-                  },
-                ],
-              },
-            }),
-          ],
-        },
-      ],
-    },
+    // The agent routes, on the control socket (ADR-0076). A Unix socket, not a loopback port: a
+    // confined process can bind a free loopback port while the Custodian restarts, and it then gets
+    // the control Stand-in on the Harness's next request. It cannot make a socket under `/run/jr2`.
+    // Envoy removes a socket that a stopped Envoy left, before it binds. Mode 0666, because the
+    // Harness runs as a uid that is not Envoy's: the folder, not the mode, keeps the domain out.
+    toOrchestrator("control", { pipe: { path: CUSTODIAN_CONTROL_SOCKET, mode: 0o666 } }, [
+      // A read retries any reset. A pick retries only a reset before it was sent: one the
+      // Orchestrator may have read is not sent twice.
+      route("surface", "GET", "/agents/[^/]+/surface", {
+        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
+      }),
+      route("events", "POST", "/agents/[^/]+/events", {
+        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
+      }),
+      // An outstanding pick's answer, long-polled (ADR-0024): a read, so any reset is retried — an
+      // Orchestrator restart mid-poll costs a retry, not the pick.
+      route("deliveries", "GET", "/agents/[^/]+/deliveries/[^/]+", {
+        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
+      }),
+      // The acknowledgment of the notices a step boundary appended (ADR-0062, ADR-0076): marking
+      // them heard twice changes nothing, so any reset is retried.
+      route("notices", "POST", "/agents/[^/]+/notices", {
+        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
+      }),
+    ]),
+    // The ask (ADR-0053), on loopback: `jr2-upload-pack` runs in the domain, and the fetch Stand-in
+    // is public, so a process that takes this port gets nothing secret. Like a pick, it retries only
+    // a reset before it was sent.
+    toOrchestrator("fetch", { socket_address: { address: "127.0.0.1", port_value: CUSTODIAN_FETCH_PORT } }, [
+      route("fetch", "POST", "/fetch", {
+        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
+      }),
+    ]),
     {
       name: "health",
       address: { socket_address: { address: "0.0.0.0", port_value: CUSTODIAN_HEALTH_PORT } },
@@ -792,24 +875,40 @@ function luaList(values: readonly string[]): string {
 /**
  * The script the Custodian runs: a generated `HELD` table, then `dofile` of the fixed program
  * (`CUSTODIAN_PROGRAM`, mounted beside it from `jr2-held`). The table names every secret this pod
- * holds — the Sandbox token first, then the manifest's — with the headers and paths each may ride
- * and the targets each is bound to. It never holds a value: the program reads those from the
- * mounted files at start.
+ * holds — the control credentials first, then the manifest's — with the headers and paths each may
+ * ride and the targets each is bound to. It never holds a value, and never a secret Stand-in: the
+ * program reads both from the mounted files at start (ADR-0059).
+ *
+ * The control credentials (ADR-0076, C3): the control token, path-restricted to the agent routes,
+ * whose secret Stand-in the program reads from its values; and, on a pod that serves a Sandbox
+ * (`fetch`), the fetch token, path-restricted to the fetch route, whose Stand-in is the one public
+ * one and so rides the table. The Instance Harness and a check pod serve no fetch, and hold the
+ * control token alone.
  */
-export function custodianScript(manifest: HeldManifest): string {
+export function custodianScript(manifest: HeldManifest, opts: { fetch: boolean }): string {
+  const control = [
+    `{ name = ${lua(CONTROL_TOKEN_NAME)}, headers = { "authorization" }, paths = ${luaList([CONTROL_PATHS])} }`,
+    ...(opts.fetch
+      ? [
+          `{ name = ${lua(SANDBOX_TOKEN_NAME)}, headers = { "authorization" }, standIn = ${lua(standIn(SANDBOX_TOKEN_NAME))}, ` +
+            `paths = ${luaList([FETCH_PATHS])} }`,
+        ]
+      : []),
+  ];
   const lines = [
     "-- Generated by `jr2 up` from its pod's held manifest (ADR-0059). Names, headers, paths, targets; never a value.",
     `HELD = { secrets = {}, targets = {}, hosts = ${targetsOf(manifest).length} }`,
     `HELD.credential = ${luaList(CREDENTIAL_HEADERS)}`,
-    `HELD.secrets[1] = { name = ${lua(SANDBOX_TOKEN_NAME)}, headers = { "authorization" } }`,
-    "HELD.control = { HELD.secrets[1] }",
+    ...control.map((entry, i) => `HELD.secrets[${i + 1}] = ${entry}`),
+    `HELD.control = { ${control.map((_, i) => `HELD.secrets[${i + 1}]`).join(", ")} }`,
   ];
+  const offset = control.length + 1;
   manifest.secrets.forEach((s, i) => {
     const paths = s.paths ? `, paths = ${luaList(s.paths)}` : "";
-    lines.push(`HELD.secrets[${i + 2}] = { name = ${lua(s.name)}, headers = ${luaList(s.headers)}${paths} }`);
+    lines.push(`HELD.secrets[${i + offset}] = { name = ${lua(s.name)}, headers = ${luaList(s.headers)}${paths} }`);
   });
   for (const t of targetsOf(manifest)) {
-    const refs = t.secrets.map((s) => `HELD.secrets[${manifest.secrets.indexOf(s) + 2}]`);
+    const refs = t.secrets.map((s) => `HELD.secrets[${manifest.secrets.indexOf(s) + offset}]`);
     lines.push(`HELD.targets[${lua(t.key)}] = { ${refs.join(", ")} }`);
   }
   // `dofile`, not a copy: Envoy's Lua opens the standard libraries (the program already reads its
@@ -830,12 +929,26 @@ export type CustodianCompositionOptions = {
    * makes the pod: the Orchestrator at provision (`sandboxCustodianConfigMap`, owned by the CR),
    * `jr2 up` for the Instance Harness (`INSTANCE_CUSTODIAN_CONFIGMAP`). */
   config: string;
-  /** Where the Sandbox token lives: a Sandbox's `<name>-token` Secret, or the Instance Harness's key
-   * of `jr2-instance`. Mounted into the Custodian alone (ADR-0013). */
-  token: { secret: string; key: string };
-  /** This pod's Sandbox — the name the ask is addressed by (ADR-0053). Absent on the Instance
-   * Harness, which mounts no Repo and answers an ask by saying so. */
+  /**
+   * The pod's credentials Secret (ADR-0076): its control token, its secret control Stand-in, its
+   * fetch token (a Sandbox alone) and one secret Stand-in per held secret, under
+   * {@link CREDENTIAL_KEYS} and {@link heldStandInKey} — a key may be renamed here. The pod's maker
+   * mints them: the Orchestrator a Sandbox's (`<sandbox>-token`), `jr2 up` the Instance Harness's
+   * and a check pod's. The tokens are mounted into the Custodian alone (ADR-0013); each Stand-in
+   * into the Custodian and the Harness container, as files.
+   */
+  credentials: {
+    secret: string;
+    keys?: Partial<Record<keyof typeof CREDENTIAL_KEYS, string>>;
+  };
+  /** This pod's Sandbox — the name the ask is addressed by (ADR-0053), and the reason the pod holds
+   * a fetch token. Absent on the Instance Harness and a check pod, which mount no Repo and answer an
+   * ask by saying so. */
   sandbox?: string;
+  /** The held secrets the `workspace()` grants its confined children (its `secrets` list, ADR-0076):
+   * the Harness puts their Stand-ins, and only theirs, in a child's env. Names the manifest does not
+   * hold are left out. Absent → none. */
+  granted?: readonly string[];
   /** The names of the Instance objects that this Custodian reads in place of the defaults. The
    * defaults are the Instance's own: `pod`'s literal values (`heldSecretsSecret(pod)`),
    * `jr2-held-tls`, `jr2-ca`, and the program in `jr2-held`.
@@ -850,15 +963,24 @@ export type CustodianCompositionOptions = {
 };
 
 type Container = Record<string, unknown>;
+
+/** The Harness container's credentials volume: its Stand-ins, mounted at {@link HARNESS_CREDENTIALS}. */
+export const HARNESS_CREDENTIALS_VOLUME = "harness-credentials";
 type Volume = Record<string, unknown>;
 type VolumeMount = { name: string; mountPath: string; readOnly?: boolean };
 
 /** What one Harness pod gains from the Custodian. */
 export type CustodianComposition = {
-  /** The Harness container's env — in `env`, after `harness.env`, before the wire's gate (§5.1). In
-   * Kubernetes `env` wins over `envFrom`, so a Stand-in overrides a same-named key of any `envFrom`
-   * Secret, even one that changes after the converge. */
+  /** The Harness container's env — in `env`, after `harness.env`, before the wire's gate (§5.1):
+   * the Custodian's fetch address and control socket, the control Stand-in's file, the granted
+   * names, the proxy and the
+   * trust. Never a Stand-in: those are files ({@link HARNESS_CREDENTIALS}), so no `envFrom` key is
+   * hidden by one, and `jr2 up` refuses a held name that is a key of an `envFrom` Secret (R14). */
   harnessEnv: HarnessEnvVar[];
+  /** The Harness container's mounts: the trust bundles, its Stand-ins at {@link HARNESS_CREDENTIALS},
+   * and the control socket's folder below it. Each is read-only. A placement mounts the
+   * conversations' volume at `/run/jr2/conversations`, below the Stand-ins too: the kubelet makes
+   * the mount point of a volume that is below a projected volume (ADR-0076). */
   harnessMounts: VolumeMount[];
   custodianContainer: Container;
   volumes: Volume[];
@@ -892,15 +1014,22 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
     program = HELD_CONFIGMAP,
   } = opts.reads ?? {};
 
+  const keys = { ...CREDENTIAL_KEYS, ...opts.credentials.keys };
+  const fetch = opts.sandbox !== undefined;
+  const heldNames = new Set(manifest.secrets.map((s) => s.name));
+  const granted = (opts.granted ?? []).filter((n) => heldNames.has(n));
+
+  // No Stand-in rides env (ADR-0059, ADR-0076): each is a file under `/run/jr2/`, below.
   const harnessEnv: HarnessEnvVar[] = [
     { name: "JR2_CUSTODIAN_URL", value: CUSTODIAN_URL },
-    { name: SANDBOX_TOKEN_NAME, value: standIn(SANDBOX_TOKEN_NAME) },
+    { name: CUSTODIAN_SOCKET_ENV, value: CUSTODIAN_CONTROL_SOCKET },
+    { name: CONTROL_STANDIN_FILE_ENV, value: CONTROL_STANDIN_FILE },
+    ...(granted.length ? [{ name: GRANTED_SECRETS_ENV, value: granted.join(",") }] : []),
   ];
   if (held) {
     const proxy = `http://127.0.0.1:${CUSTODIAN_PORT}`;
     const noProxy = "localhost,127.0.0.1,::1";
     harnessEnv.push(
-      ...manifest.secrets.map((s) => ({ name: s.name, value: standIn(s.name) })),
       { name: "HTTPS_PROXY", value: proxy },
       { name: "https_proxy", value: proxy },
       { name: "NO_PROXY", value: noProxy },
@@ -923,7 +1052,20 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
         // Group-readable, for the pod's fsGroup: the Custodian runs as Envoy's own uid.
         defaultMode: 0o440,
         sources: [
-          { secret: { name: opts.token.secret, items: [{ key: opts.token.key, path: SANDBOX_TOKEN_NAME }] } },
+          // The control credentials (ADR-0076): the control token beside its secret Stand-in, and
+          // on a Sandbox the fetch token, whose Stand-in is public and rides the script. Then each
+          // held secret's secret Stand-in, beside the value the Custodian swaps it for.
+          {
+            secret: {
+              name: opts.credentials.secret,
+              items: [
+                { key: keys.controlToken, path: CONTROL_TOKEN_NAME },
+                { key: keys.controlStandIn, path: standInValueFile(CONTROL_TOKEN_NAME) },
+                ...(fetch ? [{ key: keys.fetchToken, path: SANDBOX_TOKEN_NAME }] : []),
+                ...manifest.secrets.map((s) => ({ key: heldStandInKey(s.name), path: standInValueFile(s.name) })),
+              ],
+            },
+          },
           ...(literal.length ? [{ secret: { name: literals, items: literal.map((n) => ({ key: n, path: n })) } }] : []),
           ...manifest.secrets.flatMap((s) =>
             s.source.kind === "secret"
@@ -962,6 +1104,31 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
         ]
       : []),
     ...(trust ? [{ name: "ca", configMap: { name: trustMap } }] : []),
+    // The control socket's folder (ADR-0076): the Custodian makes the socket, and the Harness
+    // connects to it. It goes with the pod, and it outlives a restart of either container, so the
+    // socket's path never changes.
+    { name: CUSTODIAN_SOCKET_VOLUME, emptyDir: {} },
+    // The Harness container's Stand-ins (ADR-0076): the secret control Stand-in and each held
+    // secret's, as files under `/run/jr2/`, which the confiner denies to every child the Harness
+    // starts. Group-readable for the pod's fsGroup — the Harness runs as no fixed uid, and the
+    // kubelet writes the files as root — so 0440 is the least mode the Harness can read.
+    {
+      name: HARNESS_CREDENTIALS_VOLUME,
+      projected: {
+        defaultMode: 0o440,
+        sources: [
+          {
+            secret: {
+              name: opts.credentials.secret,
+              items: [
+                { key: keys.controlStandIn, path: "control/standin" },
+                ...manifest.secrets.map((s) => ({ key: heldStandInKey(s.name), path: `standins/${s.name}` })),
+              ],
+            },
+          },
+        ],
+      },
+    },
   ];
 
   const custodianContainer: Container = {
@@ -974,6 +1141,8 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
     volumeMounts: [
       { name: "custodian-values", mountPath: CUSTODIAN_VALUES, readOnly: true },
       { name: "custodian-config", mountPath: CUSTODIAN_CONFIG, readOnly: true },
+      // The one folder that the Custodian writes: where it makes its control socket.
+      { name: CUSTODIAN_SOCKET_VOLUME, mountPath: CUSTODIAN_SOCKET_DIR },
       ...(held
         ? [
             { name: "custodian-tls", mountPath: CUSTODIAN_TLS, readOnly: true },
@@ -996,7 +1165,12 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
 
   return {
     harnessEnv,
-    harnessMounts: trust ? [{ name: "ca", mountPath: CA_MOUNT, readOnly: true }] : [],
+    harnessMounts: [
+      ...(trust ? [{ name: "ca", mountPath: CA_MOUNT, readOnly: true }] : []),
+      { name: HARNESS_CREDENTIALS_VOLUME, mountPath: HARNESS_CREDENTIALS, readOnly: true },
+      // Read-only: the Harness connects to the socket, and nothing in its container writes here.
+      { name: CUSTODIAN_SOCKET_VOLUME, mountPath: CUSTODIAN_SOCKET_DIR, readOnly: true },
+    ],
     custodianContainer,
     volumes,
   };

package/src/customize.ts

@@ -45,6 +45,8 @@
 // its slot MAP Open (`repos: open`, ADR-0051) declared exactly this: every slot is the composer's
 // to name, so the map they write is the declaration, not an addition to one.
 
+import type { CallbackActorLogic } from "xstate";
+import type { AgentRunReceiveEvent } from "./actor.ts";
 import { StateMachine, type AnyStateMachine, type InputFrom, type ProvidedActor, type UnknownActorLogic } from "xstate";
 import type { AgentLogic } from "./actor.ts";
 import { isAgent, type AgentDefinition } from "./agent.ts";
@@ -128,8 +130,10 @@ type LogicAt<M extends AnyStateMachine, K extends string> = Extract<SlotsOf<M>,
  *
  * @internal
  */
-type AgentSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AgentLogic }>["src"];
-
+type AgentSlots<M extends AnyStateMachine> = Extract<
+  SlotsOf<M>,
+  { logic: CallbackActorLogic<AgentRunReceiveEvent, any> }
+>["src"];
 /** The Effect slots with an Open part — told by the phantom `OpenEffect` their constructor's
  * overload states for an `open` url or argv, or a `secret(open)` (open-effect.ts).
  *
@@ -311,7 +315,11 @@ export type Customize<M extends AnyStateMachine> = {
    * the Machine does not declare does not compile. Some Machines, such as `task`, leave their
    * whole slot map Open. Then you name every slot, and at least one. The keys are your names for
    * the Repos, and the Machine says what their order means. */
-  repos?: [RepoSlotsOf<M>] extends [never] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>> };
+  // A Workspace with only optional fields can start with no input, but the wrapper gives a mapper `{}`,
+  // so its `input` is never `undefined`.
+  repos?: [RepoSlotsOf<M>] extends [never]
+    ? never
+    : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>> };
 };
 
 /** The same shape with the types erased — what the implementation walks. */

package/src/effect-checks.ts

@@ -27,6 +27,11 @@
 //     Agent reads the Effect's output, not the answer. Everywhere else a settled child with no
 //     `onDone` is Rest, and the one-line form is correct — silent on purpose.
 //
+//   - AN onDone WITH NO LAST ARM (ADR-0075, `refuseUnroutedOutcome`). Each Effect outcome is open,
+//     so an `onDone` that an output can miss holds the run in the state and shows no fault. A type
+//     cannot see the missing arm, so the walk refuses it. No `onDone` at all is Rest, as above: the
+//     author routes nothing, so no outcome can miss a route.
+//
 // The probe reads, it never runs work: a mapper is called with a Proxy event whose reads are
 // recorded, and a context and self that survive any read. A guard and an assign are pure by
 // contract, and only they are probed; any other action may do work, and is never run.
@@ -34,12 +39,43 @@
 import type { AnyStateMachine, UnknownActorLogic } from "xstate";
 import type { EventDef } from "@jr2/agent-protocol";
 import { isAgent } from "./agent.ts";
-import { inputKeysOf, isEffect } from "./effect.ts";
+import { inputKeysOf, inputShapeOf, isEffect } from "./effect.ts";
 import { mayTake, partiesAt } from "./party.ts";
 import { isAnswer, isPickMapper } from "./pick.ts";
 
 type Node = AnyStateMachine["root"];
 
+/**
+ * Refuse a Machine with a state that invokes an Effect when the last arm of that `onDone` has a
+ * guard (ADR-0075). The slots are the Machine's own `actors`. Thrown at build by
+ * `jr2Setup.createMachine`, so also at a Chart's door, and at load by `partsOf`, so a Machine built
+ * with xstate's own `createMachine` is refused where `jr2 check`, `jr2 up` and the Orchestrator read
+ * it. Throws one line that names each state and the arm to write.
+ */
+export function refuseUnroutedOutcome(machine: AnyStateMachine): void {
+  const actors = (machine.implementations.actors ?? {}) as Record<string, unknown>;
+  const unrouted: string[] = [];
+  const visit = (node: Node): void => {
+    for (const inv of node.invoke) {
+      if (typeof inv.src !== "string" || !isEffect(actors[inv.src])) continue;
+      const arms = node.transitions.get(`xstate.done.actor.${inv.id}`);
+      if (arms !== undefined && (arms.length === 0 || arms.at(-1)!.guard !== undefined)) {
+        unrouted.push(`"${node.id}" (Effect "${inv.src}")`);
+      }
+    }
+    for (const child of Object.values(node.states)) visit(child);
+  };
+  visit(machine.root);
+  if (!unrouted.length) return;
+  const many = unrouted.length > 1;
+  throw new Error(
+    `machine "${machine.id}": ${many ? "states" : "state"} ${unrouted.join(", ")} ${many ? "have" : "has"} an ` +
+      `onDone with no unguarded last arm — an Effect's outcomes are open, and an output that no arm matches holds ` +
+      `the run in that state with no fault: add a last arm with no guard, as onDone: [..., { target: "<the state ` +
+      `that handles the rest>" }] (ADR-0075)`,
+  );
+}
+
 /** What the walk found: refusals, and warnings. */
 export type EffectFindings = { errors: string[]; warnings: string[] };
 
@@ -47,6 +83,7 @@ export function effectChecks(
   machine: AnyStateMachine,
   actors: Record<string, UnknownActorLogic>,
   defs: Map<string, EventDef>,
+  chart = false,
 ): EffectFindings {
   const errors: string[] = [];
   const warnings: string[] = [];
@@ -220,6 +257,15 @@ export function effectChecks(
       };
     });
     const effects = invokes.filter((inv) => inv.effect !== undefined);
+    // xstate's `input` is optional for an actor: a kit Effect that takes a key refuses an invoke
+    // with no input when `jr2Setup` or `customize()` builds the Machine.
+    for (const inv of effects) {
+      const shape = inputShapeOf(inv.effect!);
+      const needs = [...(shape?.required ?? []), ...(shape?.oneOf ?? [])];
+      if (inv.mapper === undefined && needs.length > 0) {
+        errors.push(`state "${n.id}": Effect "${inv.slot}" has no \`input\`, and it takes ${needs.join(", ")}`);
+      }
+    }
     if (!effects.length) continue;
     const at = `state "${n.id}" (Effect${effects.length > 1 ? "s" : ""} ${effects.map((e) => `"${e.slot}"`).join(", ")})`;
     for (const [event, { pick, ...reads }] of entering.get(n) ?? []) {
@@ -276,7 +322,8 @@ export function effectChecks(
             });
           } catch (err) {
             probed = false;
-            warnings.push(`${own}: could not probe the input mapper (${messageOf(err)}); its params are unchecked`);
+            if (!chart)
+              warnings.push(`${own}: could not probe the input mapper (${messageOf(err)}); its params are unchecked`);
           }
         }
       }
@@ -289,7 +336,7 @@ export function effectChecks(
       const picked = effects.filter((e) => isPickMapper(e.mapper));
       if (probed && lost.length && probe.unrun.length) {
         // Any other action may do work, so the probe never runs one; it may read the param.
-        warnings.push(unrunWarning(where, lost, probe.unrun));
+        if (!chart) warnings.push(unrunWarning(where, lost, probe.unrun));
       } else if (probed && lost.length && picked.length) {
         const inputs =
           picked.length === 1