@jr2/orchestrator 0.3.0 → 0.4.1

package/src/config.ts

@@ -21,11 +21,12 @@ import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { z } from "zod";
 import { repoIdentity } from "./repo-identity.ts";
+import { assertSize, type Size } from "./size.ts";
 
 // ------------------------------------------------------------------------------------------------
 // `git.credentials` (ADR-0051): how the cluster authenticates to a Repo, and the fence.
 //
-// A Repo is identified by its url and nothing in this file names one (CONTEXT.md "Repo"). What
+// A Repo is identified by its url and nothing in this file names one (GLOSSARY.md "Repo"). What
 // the config declares is CREDENTIALS, matched by prefix on the identity — the Argo and Flux shape.
 // The Orchestrator resolves the entry when it creates a Repo CR and writes a `secretRef`; the
 // cache agent reads only that. The list is also the fence: a per-run url (run input, a ticket
@@ -38,10 +39,25 @@ import { repoIdentity } from "./repo-identity.ts";
 export type GitCredential = {
   /** A prefix on the identity (`github.com/ourorg/`), or `*` for everything. */
   match: string;
-  /** Env var name holding an HTTPS token; `jr2 up` materializes its value into the Instance Secret. */
+  /** Env var name holding an HTTPS token; `jr2 up` writes its value into the entry's clone Secret
+   * (`jr2-git-<hash>`), which the cache agent spends. The Orchestrator never holds it (ADR-0068). */
   token?: string;
   /** A Secret (Flux key names: `identity`, `identity.pub`, `known_hosts`) holding a deploy key. */
   sshKey?: string;
+  /** The credential a `push()` spends (ADR-0051, ADR-0067), when it is not the clone credential: an
+   * ssh key (a Secret of `sshKey`'s shape) or a token (an env var, as `token`). Absent, the clone
+   * credential pushes; an entry with neither admits a clone, never a push. A token goes Basic
+   * through a credential helper only. */
+  push?: { sshKey: string } | { token: string };
+  /** The key a `push({ sign: true })` signs with, and the committer it signs as (ADR-0067): an ssh
+   * key (a Secret with `identity`) by default, or a GPG key (a Secret with `private.asc`, no
+   * passphrase). Explicit: an auth key is never reused as a signing key. The committer's email must
+   * belong to the forge account that holds the key, or the forge shows the signature unverified. */
+  sign?: { sshKey: string; name: string; email: string } | { gpgKey: string; name: string; email: string };
+  /** Who an unsigned `push({ squash: true })` is committed by (ADR-0067): the squashed commit is
+   * new, and without `sign` no signer names its committer. Its date is the Effector's clock; the
+   * author line stays the Agent's. A signed push's committer is the signer's. */
+  committer?: { name: string; email: string };
 };
 
 export type GitConfig = {
@@ -63,7 +79,7 @@ export function matchCredential(identity: string, list: readonly GitCredential[]
 }
 
 /** The Secret a Repo CR's `secretRef` names for `url` under `entry`, picked by the url's scheme:
- * https/http spend a token (a Secret the Orchestrator derives from the env var), ssh spends the
+ * https/http spend a token (the clone Secret `jr2 up` writes from the env var), ssh spends the
  * named deploy-key Secret. `undefined` when no entry, no applicable field, or a scheme that carries
  * no credential (`git://`, a local path) — the clone is anonymous. */
 export function credentialSecretFor(
@@ -166,21 +182,32 @@ export type CatalogReach = {
   baseUrl: string;
 };
 
-/** A credential the Harness uses and never holds (ADR-0059). The Harness container's env carries
- * its Stand-in, `jr2-held-<name>`; the Custodian puts the value into requests toward `hosts` alone. */
-export type HeldSecret = {
-  /** The env var the Harness container sees — `[A-Z_][A-Z0-9_]*`. It holds the Stand-in. */
+/**
+ * One secret of the Instance (ADR-0059's entry shape, ADR-0068's list). Its placement is READ, never
+ * declared, and naming is placement: a pod gets the secrets something in it names. A Held secret is
+ * one a Harness pod names — a `workspace()` lists it under `secrets: [...]`, or it is a known model
+ * key the provider of an Agent whose Turns run there reads — and there the Harness container's env
+ * carries its Stand-in, `jr2-held-<name>`, and that pod's Custodian puts the value into requests
+ * toward `hosts` alone. An entry an Effect names with `secret("name")` is an Effect secret, a file in
+ * that Effect's Effector. Both is both, and `jr2 up` reports it per pod; an entry nothing names goes
+ * nowhere, and `jr2 up` warns. `hosts`, `headers` and `paths` are the binding, never the placement.
+ */
+export type SecretEntry = {
+  /** As a Held secret, the env var the Harness container sees — `[A-Z_][A-Z0-9_]*`, holding the
+   * Stand-in. As an Effect secret, the name `secret("name")` names and the Effector's file. */
   name: string;
   /** The value as a literal, usually read from `process.env`/`.env`. `jr2 up` writes it into the
-   * `jr2-held-secrets` Secret, which only the Custodian mounts. Exactly one of `value`/`valueFrom`. */
+   * Secret of each placement that names it — `jr2-held-secrets-<pod>` (that pod's Custodian's),
+   * `jr2-instance-effector` — and nowhere else. Exactly one of `value`/`valueFrom`. */
   value?: string;
   /** Or a key of a Secret you manage (Sealed Secrets, External Secrets). `jr2 up` checks that the
-   * Secret and key exist; the Custodian mounts that one key as a file, and no other container does. */
+   * Secret and key exist; each placement mounts that one key as a file, and no other container does. */
   valueFrom?: { secretKeyRef: { name: string; key: string } };
-  /** Where the value may go. Each entry is `host`, `host:port`, or an `https://` URL (its host and
-   * port are taken; the path is ignored). Exact DNS names or IP literals; no wildcards. Port
-   * default 443. Optional ONLY for a known model-key name (`MODEL_KEYS`), where it defaults to the
-   * one host that provider's calls go to. */
+  /** Where the value may go as a Held secret — its binding, not its placement. Each entry is `host`,
+   * `host:port`, or an `https://`
+   * URL (its host and port are taken; the path is ignored). Exact DNS names or IP literals; no
+   * wildcards. Port default 443. A known model-key name (`MODEL_KEYS`) may leave it out: it then
+   * goes to the one host that provider's calls go to. */
   hosts?: readonly string[];
   /** Request headers the Stand-in is swapped in, lowercase. Default
    * `["authorization", "x-api-key", "x-goog-api-key", "api-key"]`. */
@@ -208,13 +235,9 @@ export type HarnessConfig = {
   /** pi catalog providers whose calls go somewhere else, keyed by the catalog provider id
    * (`anthropic`, `openai`, ...) — a gateway that serves the provider's own API (ADR-0059). */
   catalog?: Readonly<Record<string, CatalogReach>>;
-  /** Credentials the Harness uses and never holds (ADR-0059): the Harness container sees a
-   * Stand-in, and the Custodian puts the value into requests toward the bound hosts alone. A model
-   * API key belongs here, never in `env`. */
-  heldSecrets?: readonly HeldSecret[];
   /** Env vars for the Harness container. Values read from `process.env`/`.env` are materialized
    * into the instance-owned Secret by `jr2 up`. The Agent can read every one of them, so a known
-   * model key here is refused — it goes in `heldSecrets` (ADR-0059). */
+   * model key here is refused — it goes in the top-level `secrets` list (ADR-0059). */
   env?: readonly HarnessEnvVar[];
   /** Whole-Secret/ConfigMap env for the Harness container — `envFrom` refs to Secrets YOU manage
    * (Sealed Secrets etc.); `jr2 up` preflights that each referenced Secret exists (ADR-0019), and
@@ -254,19 +277,59 @@ export type SandboxPlacement = {
   tolerations?: readonly Toleration[];
 };
 
+/**
+ * The Instance's Sandbox defaults (ADR-0052, ADR-0060): placement, and the Size for a Workspace
+ * that states none.
+ */
+export type SandboxConfig = SandboxPlacement & {
+  /**
+   * The Instance's default Size (ADR-0060) — `{ limits: { memory, cpu } }` and nothing else — for
+   * a Workspace that states no Size at all; the kit fills what it leaves out. NEVER an override of a Size a Machine states: a
+   * Size is a fact of the Machine, and its one override path is `customize(machine, { resources })`.
+   * Absent → the kit default, memory 2Gi and cpu 1. jr2 reserves the whole Size (every request
+   * equals its limit) and enforces the CPU limit.
+   */
+  resources?: Size;
+};
+
+/**
+ * The PriorityClasses jr2's pods run under (ADR-0060). Absent, `jr2 up` creates two, cluster-scoped,
+ * beside the CRDs: `jr2-control` (100000, PreemptLowerPriority) for the Orchestrator, the operator
+ * and the Repo cache agent, and `jr2-sandbox` (1000, preemptionPolicy Never) for Sandboxes and the
+ * Instance Harness — so an ordinary pod cannot preempt a live Workspace, and a waiting Sandbox
+ * evicts nobody. A cluster with its own scheme names existing classes here, and `jr2 up` then
+ * creates none for that key.
+ */
+export type PriorityClasses = {
+  /** An existing PriorityClass for the Orchestrator, the operator and the Repo cache agent. */
+  control?: string;
+  /** An existing PriorityClass for Sandboxes and the Instance Harness. */
+  sandbox?: string;
+};
+
 export type JR2Config = {
   /** The instance's identity (ADR-0019): its kube namespace defaults to this (`-n` overrides),
    * and `jr2 up` labels every object it owns with it. Default: the instance folder's name. */
   name?: string;
+  /** Every secret of the Instance, one list for both sides (ADR-0068). Naming is the placement: a
+   * Held secret where a `workspace()` lists it under `secrets: [...]` or an Agent's provider reads
+   * it — a model API key belongs here, never in `harness.env` (ADR-0059) — and an Effect secret
+   * where an Effect names it with `secret("name")`. `hosts` is a Held secret's binding, never its
+   * placement: an entry nothing names goes nowhere. See `SecretEntry`. */
+  secrets?: readonly SecretEntry[];
   /** How the cluster authenticates to Repos, and the fence a per-run url must pass (ADR-0051).
    * NOT a list of Repos: a Machine names those itself, through its `workspace()`'s Repo Slots, and
    * whether the instance has a data plane at all is read off the registered Machines. */
   git?: GitConfig;
   /** Agent-runtime config for the stock Harness (see `HarnessConfig`). */
   harness?: HarnessConfig;
-  /** Which nodes are this Instance's Sandbox nodes (see `SandboxPlacement`, ADR-0052). Absent →
-   * wherever an ordinary pod lands. */
-  sandbox?: SandboxPlacement;
+  /** Which nodes are this Instance's Sandbox nodes (see `SandboxPlacement`, ADR-0052), and the
+   * Size of a Workspace that states none (see `SandboxConfig`, ADR-0060). Absent → wherever an
+   * ordinary pod lands, at the kit's Size. */
+  sandbox?: SandboxConfig;
+  /** Existing PriorityClasses to use instead of the two `jr2 up` creates (see `PriorityClasses`,
+   * ADR-0060). */
+  priorityClasses?: PriorityClasses;
   /** Image registry prefix (deployment-varying — resolve from env). Absent → images are
    * `kind load`-ed; present → pushed. A non-kind cluster without one fails loudly (ADR-0019). */
   registry?: string;
@@ -308,9 +371,9 @@ export function defineConfig(c: JR2Config): JR2Config {
  * Load an instance's `jr2.config.ts` (default export). Absent file → undefined (an instance
  * can boot configless); a file that fails to IMPORT throws — a broken config must be loud,
  * never silently treated as "no config". The shape checks live here, on the path the host CLI
- * and the in-cluster Orchestrator share: `git.credentials`, `harness.heldSecrets` and
- * `harness.catalog` are checked at runtime, because an instance is zero-build and nothing
- * typechecks this file before Node strips its types and imports it. SHAPE only: a held secret's
+ * and the in-cluster Orchestrator share: `git.credentials`, `secrets` and `harness.catalog` are
+ * checked at runtime, because an instance is zero-build and nothing typechecks this file before
+ * Node strips its types and imports it. SHAPE only: a secret's
  * `value` reads `.env`, which the in-cluster evaluation does not have, so an absent value is not
  * this function's to refuse — `jr2 up` checks presence and every held-secret rule host-side
  * (`heldSecretsOf`, ADR-0059).
@@ -321,12 +384,29 @@ export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
   const mod = (await import(pathToFileURL(file).href)) as { default?: JR2Config };
   if (!mod.default) throw new Error(`${file} has no default export (use \`export default defineConfig({…})\`)`);
   if (mod.default.git !== undefined) checkGit(mod.default.git, file);
-  if (mod.default.harness !== undefined) checkHeld(mod.default.harness, file);
+  if (mod.default.secrets !== undefined) checkSecrets(mod.default.secrets, file);
+  if (mod.default.harness !== undefined) checkHarness(mod.default.harness, file);
+  if (mod.default.sandbox !== undefined) checkSandbox(mod.default.sandbox, file);
+  if (mod.default.priorityClasses !== undefined) checkPriorityClasses(mod.default.priorityClasses, file);
   return mod.default;
 }
 
 const NonEmpty = z.string().min(1);
-const Credential = z.object({ match: NonEmpty, token: NonEmpty.optional(), sshKey: NonEmpty.optional() }).strict();
+const Credential = z
+  .object({
+    match: NonEmpty,
+    token: NonEmpty.optional(),
+    sshKey: NonEmpty.optional(),
+    push: z.union([z.object({ sshKey: NonEmpty }).strict(), z.object({ token: NonEmpty }).strict()]).optional(),
+    sign: z
+      .union([
+        z.object({ sshKey: NonEmpty, name: NonEmpty, email: NonEmpty }).strict(),
+        z.object({ gpgKey: NonEmpty, name: NonEmpty, email: NonEmpty }).strict(),
+      ])
+      .optional(),
+    committer: z.object({ name: NonEmpty, email: NonEmpty }).strict().optional(),
+  })
+  .strict();
 
 /** `git.credentials`' SHAPE, checked at load — by index and field, so a bad entry names itself
  * (`git.credentials[1].token`) rather than surfacing as a Secret that never matches. */
@@ -345,10 +425,12 @@ function checkGit(git: unknown, where: string): void {
   }
 }
 
-const GIT_HINT = "an entry is { match, token?, sshKey? } (ADR-0051)";
+const GIT_HINT =
+  "an entry is { match, token?, sshKey?, push?: { sshKey } | { token }, sign?: { sshKey | gpgKey, name, email }, " +
+  "committer?: { name, email } } (ADR-0051)";
 
 const OptionalText = z.string().optional();
-const HeldSecretShape = z
+const SecretShape = z
   .object({
     name: NonEmpty,
     // `.env` values are absent in-cluster, so `undefined` must pass here — presence is `jr2 up`'s.
@@ -364,25 +446,25 @@ const HeldSecretShape = z
   .strict();
 const CatalogReachShape = z.object({ baseUrl: z.string() }).strict();
 
-/** `harness.heldSecrets` and `harness.catalog`, SHAPE only (ADR-0059) — by index and field, the
- * `checkGit` style, so a bad entry names itself (`harness.heldSecrets[1].hosts`). */
-function checkHeld(harness: unknown, where: string): void {
+/** `secrets`' SHAPE (ADR-0059's entry, ADR-0068's list) — by index and field, the `checkGit` style,
+ * so a bad entry names itself (`secrets[1].hosts`). */
+function checkSecrets(secrets: unknown, where: string): void {
+  if (!Array.isArray(secrets)) throw new Error(`${where} at secrets: expected an array — ${SECRET_HINT}`);
+  for (const [i, entry] of secrets.entries()) {
+    const parsed = SecretShape.safeParse(entry);
+    if (parsed.success) continue;
+    const issue = parsed.error.issues[0];
+    const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+    throw new Error(`${where} at secrets[${i}]${at}: ${issue?.message ?? "invalid"} — ${SECRET_HINT}`);
+  }
+}
+
+/** `harness.catalog`'s SHAPE (ADR-0059) — by provider id and field, the `checkGit` style. */
+function checkHarness(harness: unknown, where: string): void {
   if (typeof harness !== "object" || harness === null || Array.isArray(harness)) {
     throw new Error(`${where} at harness: expected an object`);
   }
-  const { heldSecrets, catalog } = harness as { heldSecrets?: unknown; catalog?: unknown };
-  if (heldSecrets !== undefined) {
-    if (!Array.isArray(heldSecrets)) {
-      throw new Error(`${where} at harness.heldSecrets: expected an array — ${HELD_HINT}`);
-    }
-    for (const [i, entry] of heldSecrets.entries()) {
-      const parsed = HeldSecretShape.safeParse(entry);
-      if (parsed.success) continue;
-      const issue = parsed.error.issues[0];
-      const at = ["", ...(issue?.path ?? [])].map(String).join(".");
-      throw new Error(`${where} at harness.heldSecrets[${i}]${at}: ${issue?.message ?? "invalid"} — ${HELD_HINT}`);
-    }
-  }
+  const { catalog } = harness as { catalog?: unknown };
   if (catalog !== undefined) {
     if (typeof catalog !== "object" || catalog === null || Array.isArray(catalog)) {
       throw new Error(`${where} at harness.catalog: expected an object keyed by catalog provider id — ${CATALOG_HINT}`);
@@ -397,6 +479,30 @@ function checkHeld(harness: unknown, where: string): void {
   }
 }
 
-const HELD_HINT =
-  "an entry is { name, value? | valueFrom?: { secretKeyRef: { name, key } }, hosts?, headers?, paths? } (ADR-0059)";
+const SECRET_HINT =
+  "an entry is { name, value? | valueFrom?: { secretKeyRef: { name, key } }, hosts?, headers?, paths? } (ADR-0059, ADR-0068)";
 const CATALOG_HINT = "an entry is <provider id>: { baseUrl } (ADR-0059)";
+
+/** `sandbox.resources`' SHAPE (ADR-0060), checked at load by field — `requests`, or any key beside
+ * the two limits, is refused naming itself (`sandbox.resources.requests`). */
+function checkSandbox(sandbox: unknown, where: string): void {
+  if (typeof sandbox !== "object" || sandbox === null || Array.isArray(sandbox)) {
+    throw new Error(`${where} at sandbox: expected an object — { nodeSelector?, tolerations?, resources? }`);
+  }
+  const { resources } = sandbox as { resources?: unknown };
+  if (resources !== undefined) assertSize(`${where} at sandbox.resources`, resources);
+}
+
+const PriorityClassesShape = z.object({ control: NonEmpty.optional(), sandbox: NonEmpty.optional() }).strict();
+
+/** `priorityClasses`' SHAPE (ADR-0060): two optional class names, nothing else. */
+function checkPriorityClasses(classes: unknown, where: string): void {
+  const parsed = PriorityClassesShape.safeParse(classes);
+  if (parsed.success) return;
+  const issue = parsed.error.issues[0];
+  const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+  throw new Error(
+    `${where} at priorityClasses${at}: ${issue?.message ?? "invalid"} — { control?, sandbox? }, each the name of ` +
+      "an existing PriorityClass (ADR-0060)",
+  );
+}

package/src/content-hash.ts

@@ -0,0 +1,105 @@
+// The content address jr2 takes of a tree (ADR-0038, ADR-0069). It lives here, not in the CLI,
+// because two ends compute it over one Assembly: `jr2 up` hashes the staged tree, and the door
+// recomputes the hash over the unpacked tree before it accepts a publish. One implementation, so
+// the two ends cannot drift.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile, readlink, stat } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+
+/** The salt of an Assembly's hash (ADR-0069). The host and the door both hash with it. */
+export const ASSEMBLY_HASH_SALT = "assembly";
+
+/**
+ * The name of an Assembly (ADR-0069): a hash over every entry the Assembly's archive carries. The
+ * host names its staged tree with it, and the door recomputes it over the unpacked tree. The door
+ * then trusts "one hash names one Assembly" three times: `jr2 up` skips a publish whose hash is
+ * current, the door answers `unchanged`, and the door reuses an `assemblies/<hash>/` it already
+ * holds. So the hash covers what the archive carries, and nothing can change under one hash:
+ *
+ * - Each directory is a record, so an empty one counts.
+ * - Each symlink is a record with its target. `contentHash` skips links (an image tag must not see
+ *   pnpm's store links twice), but an Assembly's links travel, and a changed target is a changed
+ *   Assembly.
+ * - Each record is framed: a type, then every field as its byte length and its bytes. Without the
+ *   frame, a file `a` that holds `X0:b\nY` hashes as the files `a` = `X` and `b` = `Y`.
+ *
+ * The walk is in byte order (`byteOrder`). Modes are not in the hash: nothing at the door reads
+ * them, and an umask must not move an Assembly's name. Other entry types (a socket, a FIFO) are not
+ * records: the archive refuses them, so they never reach the door. Nothing is excluded: the hash
+ * names every byte the archive carries.
+ */
+export async function assemblyHash(dir: string): Promise<string> {
+  const h = createHash("sha256");
+  h.update(`salt:${ASSEMBLY_HASH_SALT}\n`);
+  const field = (bytes: Buffer): void => {
+    h.update(`${bytes.length}:`);
+    h.update(bytes);
+  };
+  const walk = async (d: string, rel: string): Promise<void> => {
+    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => byteOrder(a.name, b.name));
+    for (const e of entries) {
+      const p = join(d, e.name);
+      const path = Buffer.from(rel === "" ? e.name : `${rel}/${e.name}`, "utf8");
+      if (e.isSymbolicLink()) {
+        h.update("l");
+        field(path);
+        field(Buffer.from(await readlink(p), "utf8"));
+      } else if (e.isDirectory()) {
+        h.update("d");
+        field(path);
+        await walk(p, path.toString("utf8"));
+      } else if (e.isFile()) {
+        h.update("f");
+        field(path);
+        field(await readFile(p));
+      }
+    }
+  };
+  await walk(dir, "");
+  return h.digest("hex").slice(0, 12);
+}
+
+/**
+ * The order a content address walks a directory in: UTF-8 byte order of the entry names, never a
+ * locale's collation. `localeCompare` reads the ICU locale from `LANG`/`LC_ALL`, and the two ends
+ * of a hash run in different locales: in `cs_CZ`, "ch" sorts after "h", so a host there would
+ * hash `node_modules/chalk` after `hono` while the Kit image hashes it first, and every publish
+ * would fail the door's check. The Assembly's tar orders its entries by the same rule.
+ */
+export function byteOrder(a: string, b: string): number {
+  return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+
+/**
+ * A short content hash over `paths` (files and/or directories, sorted walk), salted with `salt`.
+ * Symlinks are skipped rather than followed: in a pnpm bundle `node_modules/<pkg>` links into the
+ * virtual store, whose real files the walk already visits — following would hash the same bytes
+ * twice. Each path contributes its entries under its own index prefix, so two directories that
+ * happen to hold the same relative filenames stay distinguishable.
+ */
+export async function contentHash(paths: string[], salt: string, exclude: Set<string> = new Set()): Promise<string> {
+  const h = createHash("sha256");
+  h.update(`salt:${salt}\n`);
+  const walk = async (root: string, d: string, index: number): Promise<void> => {
+    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => byteOrder(a.name, b.name));
+    for (const e of entries) {
+      if (exclude.has(e.name)) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) await walk(root, p, index);
+      else if (e.isFile()) {
+        h.update(`${index}:${relative(root, p)}\n`);
+        h.update(await readFile(p));
+      }
+    }
+  };
+  for (const [index, p] of paths.entries()) {
+    const st = await stat(p);
+    if (st.isDirectory()) await walk(p, p, index);
+    else {
+      h.update(`${index}:${basename(p)}\n`);
+      h.update(await readFile(p));
+    }
+  }
+  return h.digest("hex").slice(0, 12);
+}

package/src/custodian.lua

@@ -1,11 +1,12 @@
 -- The Custodian's decisions (ADR-0059), run by Envoy's Lua filter on every listener it owns.
 --
 -- Envoy carries the bytes: the CONNECT listener, TLS on both sides, the upstream pools, streaming.
--- This script makes every choice about a credential, and nothing else. `jr2 up` prepends a
--- generated `HELD` table (names, headers, paths, bound targets — never a value) and ships the
--- whole file in the `jr2-held` ConfigMap. Envoy loads it once per Lua state at start, so the
--- top-level code below runs before any listener serves: a value that is missing or cannot ride a
--- header stops the start-up with a line that names the secret, never the value.
+-- This script makes every choice about a credential, and nothing else. It ships once per Instance
+-- in the `jr2-held` ConfigMap (`program.lua`); each pod's own `custodian.lua` is a generated `HELD`
+-- table (names, headers, paths, bound targets — never a value) that ends by loading this file.
+-- Envoy loads that once per Lua state at start, so the top-level code below runs before any
+-- listener serves, with `HELD` already set: a value that is missing or cannot ride a header stops
+-- the start-up with a line that names the secret, never the value.
 --
 -- Four roles, one per route family, read from the route's metadata:
 --

package/src/custodian.ts

@@ -5,22 +5,29 @@
 // Its engine is Envoy, the upstream distroless image pinned by digest: jr2 deploys it and never
 // builds it (ADR-0038). This module is the jr2 half — everything Envoy is told, and where:
 //
-//   custodianBootstrap(...)   the static bootstrap `jr2 up` writes into the `jr2-held` ConfigMap:
+//   custodianBootstrap(...)   the static bootstrap, one per pod, from that pod's manifest:
 //                             no admin listener, no xDS, one internal listener per bound host
-//   custodianScript(...)      the Lua the bootstrap runs: `custodian.lua`, with a generated table
-//                             of names, headers, paths and targets in front — never a value
+//   custodianScript(...)      the Lua the bootstrap runs: a generated table of names, headers,
+//                             paths and targets — never a value — then `dofile` of the program
+//   CUSTODIAN_PROGRAM         `custodian.lua` as written: in `jr2-held` once per Instance
+//
+// Who renders the two per-pod files is who makes the pod: the Orchestrator at provision, into a
+// ConfigMap the Sandbox CR owns; `jr2 up` for the Instance Harness. `jr2 up` DECLARES — each pod's
+// manifest, the program — and nothing rendered per pod lands in a shared object (a ConfigMap
+// stops at 1 MiB; a per-pod copy of Envoy's files reached it at nine Workspaces).
 //   custodianComposition(...) what a Harness pod gains: the Custodian container, its volumes, and
 //                             the Harness container's env and mounts. BOTH placements call it —
-//                             `kubectlSandbox` per provision, `instanceHarnessObjects` at converge —
+//                             `kubeSandbox` per provision, `instanceHarnessObjects` at converge —
 //                             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 — is mounted into this container alone, and
+// 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`.
 
 import { readFileSync } from "node:fs";
 import type { HarnessEnvVar } from "./config.ts";
+import type { ResourceRequirements } from "./size.ts";
 import {
   CREDENTIAL_HEADERS,
   SANDBOX_TOKEN_NAME,
@@ -33,9 +40,10 @@ import {
   CUSTODIAN_CONTROL_PORT,
   CUSTODIAN_HEALTH_PORT,
   CUSTODIAN_PORT,
+  CUSTODIAN_PROGRAM_KEY,
   HELD_CONFIGMAP,
-  HELD_SECRETS_SECRET,
   HELD_TLS_SECRET,
+  heldSecretsSecret,
 } from "./names.ts";
 
 /**
@@ -62,7 +70,10 @@ export function custodianRef(kitRegistry?: string): string {
 export const CUSTODIAN_VALUES = "/etc/jr2/custodian/values";
 export const CUSTODIAN_TLS = "/etc/jr2/custodian/tls";
 export const CUSTODIAN_CONFIG = "/etc/jr2/custodian/config";
-/** The two keys of the `jr2-held` ConfigMap the Custodian reads (beside `held.json`). */
+/** The files the Custodian reads under its config mount: its own pod's rendered bootstrap and
+ * script (the two keys of the pod's Custodian ConfigMap — `sandboxCustodianConfigMap`,
+ * `INSTANCE_CUSTODIAN_CONFIGMAP`), and the fixed program the script loads, projected from
+ * `jr2-held` (`CUSTODIAN_PROGRAM_KEY`). */
 export const CUSTODIAN_BOOTSTRAP_KEY = "envoy.json";
 export const CUSTODIAN_SCRIPT_KEY = "custodian.lua";
 
@@ -356,8 +367,8 @@ 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 and the ask, plain HTTP, to the Orchestrator's Service —
- *                              three routes and nothing else, each swapping the Sandbox token's
+ *   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)
  *   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
@@ -401,6 +412,11 @@ export function custodianBootstrap(manifest: HeldManifest, orchestrator: Orchest
                       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 },
                       }),
@@ -715,8 +731,11 @@ export function custodianBootstrap(manifest: HeldManifest, orchestrator: Orchest
 
 // ---- the script ---------------------------------------------------------------------------------
 
-/** `custodian.lua` beside this module — the fixed half of the script. */
-const SCRIPT = readFileSync(new URL("./custodian.lua", import.meta.url), "utf8");
+/** `custodian.lua` beside this module — the fixed half of the script, as written. `jr2 up` puts it
+ * in `jr2-held` once (`CUSTODIAN_PROGRAM_KEY`); every pod's own script loads it from the config
+ * mount. The per-pod half is the table alone, so a pod's rendered files stay small and nothing
+ * fixed is copied per Workspace. */
+export const CUSTODIAN_PROGRAM: string = readFileSync(new URL("./custodian.lua", import.meta.url), "utf8");
 
 /** A Lua string literal. Every string that reaches here passed `heldSecretsOf`'s rules (names,
  * header tokens, printable paths), so escaping the two characters Lua gives meaning to is enough. */
@@ -729,14 +748,15 @@ function luaList(values: readonly string[]): string {
 }
 
 /**
- * The script the Custodian runs: a generated `HELD` table in front of `custodian.lua`. 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
- * script reads those from the mounted files at start.
+ * 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.
  */
 export function custodianScript(manifest: HeldManifest): string {
   const lines = [
-    "-- Generated by `jr2 up` from held.json (ADR-0059). Names, headers, paths, targets; never a value.",
+    "-- 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" } }`,
@@ -750,7 +770,10 @@ export function custodianScript(manifest: HeldManifest): string {
     const refs = t.secrets.map((s) => `HELD.secrets[${manifest.secrets.indexOf(s) + 2}]`);
     lines.push(`HELD.targets[${lua(t.key)}] = { ${refs.join(", ")} }`);
   }
-  return `${lines.join("\n")}\n\n${SCRIPT}`;
+  // `dofile`, not a copy: Envoy's Lua opens the standard libraries (the program already reads its
+  // values with `io`), and the program's top-level code runs here, after the table it reads.
+  lines.push(`dofile(${lua(`${CUSTODIAN_CONFIG}/${CUSTODIAN_PROGRAM_KEY}`)})`);
+  return `${lines.join("\n")}\n`;
 }
 
 // ---- the composition ----------------------------------------------------------------------------
@@ -758,6 +781,13 @@ export function custodianScript(manifest: HeldManifest): string {
 export type CustodianCompositionOptions = {
   /** The Custodian's resolved ref (`custodianRef`, from the image map). */
   image: string;
+  /** The pod whose held objects these are (ADR-0059): `INSTANCE_HARNESS_HELD_POD`, or a Workspace's
+   * `workspaceHeldPod` — its manifest and its literal values' Secret. */
+  pod: string;
+  /** The ConfigMap with THIS pod's rendered `envoy.json` and `custodian.lua` — written by whoever
+   * 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 };
@@ -766,6 +796,9 @@ export type CustodianCompositionOptions = {
   sandbox?: string;
   /** The Instance ships a `harness.caBundle` (ADR-0020). */
   caBundle: boolean;
+  /** The Custodian container's resources (ADR-0060) — the placement's to choose: a Sandbox's fixed
+   * slice of its Size (requests = limits), the Instance Harness's kit-sized request. */
+  resources?: ResourceRequirements;
 };
 
 type Container = Record<string, unknown>;
@@ -838,7 +871,7 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
         sources: [
           { secret: { name: opts.token.secret, items: [{ key: opts.token.key, path: SANDBOX_TOKEN_NAME }] } },
           ...(literal.length
-            ? [{ secret: { name: HELD_SECRETS_SECRET, items: literal.map((n) => ({ key: n, path: n })) } }]
+            ? [{ secret: { name: heldSecretsSecret(opts.pod), items: literal.map((n) => ({ key: n, path: n })) } }]
             : []),
           ...manifest.secrets.flatMap((s) =>
             s.source.kind === "secret"
@@ -848,7 +881,25 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
         ],
       },
     },
-    { name: "custodian-config", configMap: { name: HELD_CONFIGMAP } },
+    // This pod's own bootstrap and script, under the names Envoy is started with, beside the fixed
+    // program the script loads — the one thing every pod shares, from `jr2-held`.
+    {
+      name: "custodian-config",
+      projected: {
+        sources: [
+          {
+            configMap: {
+              name: opts.config,
+              items: [
+                { key: CUSTODIAN_BOOTSTRAP_KEY, path: CUSTODIAN_BOOTSTRAP_KEY },
+                { key: CUSTODIAN_SCRIPT_KEY, path: CUSTODIAN_SCRIPT_KEY },
+              ],
+            },
+          },
+          { configMap: { name: HELD_CONFIGMAP, items: [{ key: CUSTODIAN_PROGRAM_KEY, path: CUSTODIAN_PROGRAM_KEY }] } },
+        ],
+      },
+    },
     ...(held
       ? [
           { name: "custodian-tls", secret: { secretName: HELD_TLS_SECRET, defaultMode: 0o440 } },
@@ -887,6 +938,7 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
       periodSeconds: 2,
       failureThreshold: 15,
     },
+    ...(opts.resources !== undefined ? { resources: opts.resources } : {}),
     securityContext: CUSTODIAN_SECURITY,
   };