@jr2/cli 0.2.1 → 0.3.0

package/manifests/operator.yaml

@@ -6181,7 +6181,7 @@ spec:
                   Repos is the standing report on the caches this Sandbox mounts
                   (ADR-0053), one entry per key in spec.repos, in that order, computed on
                   every reconcile once the Pod has a node. It is what a fetch inside the
-                  pod waits on: the program asks the Adapter, the Orchestrator marks the
+                  pod waits on: the program asks the Custodian, the Orchestrator marks the
                   ask on this CR, and the entry for that key says whether the node fetched
                   since. `Ready` is untouched by it — that stays the gate it was, sticky
                   and taken once per Pod life; this is the standing answer the gate's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -39,13 +39,14 @@
     "ts-blank-space": "^0.9.0"
   },
   "peerDependencies": {
-    "@jr2/orchestrator": "0.2.1"
+    "@jr2/orchestrator": "0.3.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "0.91.1",
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.2.1"
+    "@jr2/orchestrator": "0.3.0"
   },
   "files": [
     "bin",
@@ -54,6 +55,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --test"
+    "test": "node --test 'test/**/*.test.ts'",
+    "test:custodian": "node --test --test-concurrency=1 test/custodian.docker.ts"
   }
 }

package/src/build.ts

@@ -2,9 +2,10 @@
 // kinds — the instance's own (engine + this instance's workflows baked, ADR-0008), the instance's
 // Sandbox Images (the `file:` docker contexts its Machines carry, ADR-0037/0049), and — only when the
 // CLI is running out of
-// a kit CHECKOUT — the Harness, Adapter, and operator images. Installed from npm those kit sources
-// do not resolve, so a real instance takes the published-`<kitversion>` path and never needs docker
-// for them. The checkout IS the signal: no flag, no config key, no env.
+// a kit CHECKOUT — the Harness and operator images. Installed from npm those kit sources do not
+// resolve, so a real instance takes the published-`<kitversion>` path and never needs docker for
+// them. The checkout IS the signal: no flag, no config key, no env. One image is deployed and never
+// built, in either world: the Custodian's, upstream Envoy pinned by digest (ADR-0038, ADR-0059).
 //
 // Every tag is a content address of its own inputs. That is what makes `imagePullPolicy:
 // IfNotPresent` correct rather than lucky (a unique tag per content means "present" implies
@@ -34,7 +35,7 @@ import { createHash } from "node:crypto";
 import { execFile, spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, readdir, readFile, readlink, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { KIT_VERSION } from "@jr2/orchestrator";
@@ -144,7 +145,7 @@ export type BuildPort = {
  * context and carries no `.dockerignore`, so docker copies `dist/` and `node_modules/` straight in.
  */
 
-/** For walks under `packages/*` (harness, adapter): their context is the KIT ROOT, so the root
+/** For walks under `packages/*` (the Harness): its context is the KIT ROOT, so the root
  * `.dockerignore` governs, and the only entries it drops at any depth are `**\/node_modules` and
  * `**\/dist` (plus `*.log`/`.env` globs `contentHash`'s name-set cannot express — hashing a stray
  * one of those over-hashes, which is allowed). A `packages/harness/bin/` would be context-VISIBLE,
@@ -226,7 +227,7 @@ export const LABEL_IMAGE_KIND = "jr2.dev/kind";
 /** The three kinds ADR-0038 builds, and the whole value domain of {@link LABEL_IMAGE_KIND}. */
 export type ImageKind = "instance" | "sandbox" | "kit";
 
-/** The kit's own images (Harness, Adapter, operator). No instance label: every instance on the
+/** The kit's own images (Harness, operator). No instance label: every instance on the
  * cluster shares one copy, and "kit images are never swept" is not a rule any more — a kit ref is
  * kept because some instance's map or pod names it, and collects with everything else when the
  * last instance leaves (ADR-0039). */
@@ -258,8 +259,8 @@ export function sandboxImageLabels(instance: string): Record<string, string> {
  * script's default and fails the gate when they drift.
  *
  * An arch outside this set is never built for. An instance image for `s390x` is dead weight: no Kit
- * image could sit beside it in the pod, so the Sandbox would fail at the Adapter or the Harness
- * instead of at the image nobody published.
+ * image could sit beside it in the pod, so the Sandbox would fail at the Harness instead of at
+ * the image nobody published.
  */
 export const SUPPORTED_PLATFORMS: readonly string[] = ["linux/amd64", "linux/arm64"];
 
@@ -365,8 +366,8 @@ export async function assertEmulation(port: BuildPort, platforms: readonly strin
 
 // --- the kit images (ADR-0038) --------------------------------------------------------------
 
-/** The three images the KIT owns. An instance deploys them but never authors them. */
-export type KitImageName = "harness" | "adapter" | "operator";
+/** The two images the KIT owns and builds. An instance deploys them but never authors them. */
+export type KitImageName = "harness" | "operator";
 export type KitImageRefs = Record<KitImageName, string>;
 
 type KitImage = {
@@ -415,13 +416,6 @@ export const KIT_IMAGES: Record<KitImageName, KitImage> = {
     ],
     exclude: KIT_PACKAGE_EXCLUDE,
   },
-  adapter: {
-    repo: "jr2-adapter",
-    dockerfile: "deploy/adapter/Dockerfile",
-    context: ".",
-    sources: ["packages/adapter", "deploy/adapter/Dockerfile"],
-    exclude: KIT_PACKAGE_EXCLUDE,
-  },
   operator: {
     repo: "jr2-operator",
     dockerfile: "operator/Dockerfile",
@@ -451,14 +445,13 @@ export const KIT_IMAGE_HOME = "ghcr.io/snapwich";
  * home rather than nesting under it: a mirror holds the same tags under its own name, seeded
  * deliberately (`jr2 kit push`) and never by a converge. It is NOT `config.registry`: that key says
  * where images this converge BUILDS go, and prefixing both with one key would make every
- * private-registry user mirror three images they could have pulled from the home. The version is
+ * private-registry user mirror the Kit images they could have pulled from the home. The version is
  * still the CLI's own — re-homing says where the tags live, never which ones.
  */
 export function publishedKitRefs(kitRegistry?: string): KitImageRefs {
   const home = kitRegistry ?? KIT_IMAGE_HOME;
   return {
     harness: `${home}/jr2-harness:${KIT_VERSION}`,
-    adapter: `${home}/jr2-adapter:${KIT_VERSION}`,
     operator: `${home}/jr2-operator:${KIT_VERSION}`,
   };
 }
@@ -468,12 +461,18 @@ export function publishedKitRefs(kitRegistry?: string): KitImageRefs {
  * requiring BOTH `deploy/harness/Dockerfile` and a `packages/harness/package.json` that names
  * `@jr2/harness`. Either marker alone matches an unrelated tree — someone else's `deploy/harness`,
  * or a vendored copy of one package — and a false positive means `jr2 up` tries to docker-build a
- * kit that is not there. Installed from npm neither resolves and the answer is `undefined`.
+ * kit that is not there. Installed from npm the answer is `undefined`.
+ *
+ * A module under `node_modules` came from a registry, so the walk stops there: an instance that
+ * lives INSIDE a checkout but installs `@jr2/*` from npm would otherwise reach the checkout root and
+ * build a Harness at HEAD beside an Orchestrator at the pinned version. The checkout's own instances
+ * link the workspace packages, and node resolves those links, so their CLI loads from `packages/`.
  */
 export async function detectKitCheckout(
   fromDir: string = fileURLToPath(new URL(".", import.meta.url)),
 ): Promise<string | undefined> {
   let dir = resolve(fromDir);
+  if (dir.split(sep).includes("node_modules")) return undefined;
   for (;;) {
     if (await isKitRoot(dir)) return dir;
     const parent = dirname(dir);
@@ -737,7 +736,7 @@ const emptySweep = (): SweepResult => ({ removed: [], kept: [], failed: [], byte
  * One report out of several — the host's and every node's, or several converges' (`mergeSweeps` is
  * associative, so a caller can fold as it goes). Refs are de-duplicated AFTER {@link normalizeRef},
  * because that is the only way the promise holds: the two stores spell one image differently
- * (`jr2-adapter:33a4` on the host, `docker.io/library/jr2-adapter:33a4` on a node), so a raw-string
+ * (`jr2-harness:33a4` on the host, `docker.io/library/jr2-harness:33a4` on a node), so a raw-string
  * set reports one image twice. The merged refs are the normalized spelling — the one the roots, and
  * the user, name an image by.
  *

package/src/commands/kit.ts

@@ -2,16 +2,18 @@
 //
 // Kit images live at a canonical public home (`ghcr.io/snapwich`, baked into `publishedKitRefs()`).
 // A cluster that cannot reach it — air-gapped, mirror-only, or simply policy-bound to one registry —
-// needs the three refs at its own address, which is what `kitRegistry` names in the config. This
-// command is how the bytes get there.
+// needs those refs at its own address, which is what `kitRegistry` names in the config. This
+// command is how the bytes get there. It moves one more image the same way: the Custodian's, the
+// pinned upstream Envoy every Harness pod runs (ADR-0059), which jr2 deploys and never builds — a
+// mirror-only cluster needs it just as much, and `kitRegistry` re-homes it the same way.
 //
 // It is deliberately INSTANCE-LESS: no `jr2.config.ts`, no kube context, no namespace. Kit images are
 // shared by every instance on a cluster (and possibly by every instance in an org), so moving them
 // is its own deliberate act rather than a side effect of converging one instance — which is exactly
 // why ADR-0044 keeps this out of `jr2 up`.
 //
-// It is a MIRROR and nothing else. There is no build arm here: the npm packages carry no Harness or
-// Adapter source, and an installed CLI that could build Kit images would be the patched-Harness
+// It is a MIRROR and nothing else. There is no build arm here: the npm packages carry no Harness
+// source, and an installed CLI that could build Kit images would be the patched-Harness
 // eject hatch ADR-0027/ADR-0038 welded shut. The kit developer's arm is `just kit-push`, in the
 // checkout, where the sources actually are.
 //
@@ -23,7 +25,7 @@
 
 import { execFile } from "node:child_process";
 import { parseArgs, promisify } from "node:util";
-import { KIT_VERSION } from "@jr2/orchestrator";
+import { custodianRef, KIT_VERSION } from "@jr2/orchestrator";
 import { KIT_IMAGES, publishedKitRefs, type KitImageName } from "../build.ts";
 import { activity, result, type Io } from "../output.ts";
 
@@ -31,8 +33,9 @@ const exec = promisify(execFile);
 
 const USAGE = `usage: jr2 kit push <registry>
 
-  mirror the v${KIT_VERSION} kit images (harness, adapter, operator) from their canonical
-  home into <registry>, for a cluster whose \`kitRegistry\` names it (ADR-0044)`;
+  mirror the v${KIT_VERSION} kit images (harness, operator) from their canonical home, and the
+  Custodian's pinned Envoy from its own, into <registry>, for a cluster whose \`kitRegistry\`
+  names it (ADR-0044, ADR-0059)`;
 
 /** Run one `docker` invocation, rejecting on a non-zero exit. The seam this command is tested
  * through: the claims are which argv each ref produces and what a failure means, and both are
@@ -45,7 +48,7 @@ const dockerCli: RunDocker = async (args) => {
 };
 
 /** What one image's mirror did — the per-image line, and the machine-readable result's rows. */
-type Mirrored = { image: KitImageName; source: string; target: string; copied: boolean };
+type Mirrored = { image: KitImageName | "custodian"; source: string; target: string; copied: boolean };
 
 export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli): Promise<number> {
   const { positionals } = parseArgs({ args, allowPositionals: true, strict: false, options: {} });
@@ -77,6 +80,9 @@ export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli)
   for (const image of Object.keys(KIT_IMAGES) as KitImageName[]) {
     rows.push(await mirror(io, docker, image, sources[image], targets[image]));
   }
+  // The Custodian's: pinned by digest, and a registry-to-registry copy keeps the digest — so the
+  // ref a converge with this `kitRegistry` deploys (`custodianRef`) resolves in the mirror.
+  rows.push(await mirror(io, docker, "custodian", custodianRef(), custodianRef(target)));
 
   const copied = rows.filter((r) => r.copied).length;
   activity(io, `mirrored ${copied} image(s), ${rows.length - copied} already present`);
@@ -97,7 +103,7 @@ export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli)
 async function mirror(
   io: Io,
   docker: RunDocker,
-  image: KitImageName,
+  image: KitImageName | "custodian",
   source: string,
   target: string,
 ): Promise<Mirrored> {
@@ -106,7 +112,8 @@ async function mirror(
     return { image, source, target, copied: false };
   }
   await requireSource(docker, image, source, target);
-  await docker(["buildx", "imagetools", "create", "-t", target, source]);
+  // A digest-pinned target is pushed by its tag; the copy lands at that same digest.
+  await docker(["buildx", "imagetools", "create", "-t", target.replace(/@sha256:[0-9a-f]+$/, ""), source]);
   activity(io, `${image}: copied ${source} → ${target}`);
   return { image, source, target, copied: true };
 }
@@ -130,12 +137,17 @@ async function resolves(docker: RunDocker, ref: string): Promise<boolean> {
  * it points at is the other arm of ADR-0044: `just kit-push`, in the checkout, is what puts images
  * at a published name in the first place; this command only moves what is already there.
  */
-async function requireSource(docker: RunDocker, image: KitImageName, source: string, target: string): Promise<void> {
+async function requireSource(
+  docker: RunDocker,
+  image: KitImageName | "custodian",
+  source: string,
+  target: string,
+): Promise<void> {
   if (await resolves(docker, source)) return;
   throw new Error(
     `${image}: ${source} is not there, so nothing can be mirrored to ${target}\n` +
       `  a kit image reaches ${target} only by being copied from its published home;\n` +
       `  if v${KIT_VERSION} was never published (a dev version never is), seed a registry from a kit\n` +
-      `  checkout with \`just kit-push <registry>\`, which builds the three images from source`,
+      `  checkout with \`just kit-push <registry>\`, which builds the Kit images from source`,
   );
 }

package/src/commands/up.ts

@@ -24,7 +24,7 @@
 // `--platform` passed explicitly on every build. The cluster's schedulable nodes choose that set
 // (`platforms` in the config overrides absolutely), so the daemon default and
 // `DOCKER_DEFAULT_PLATFORM` steer nothing any more. In a kit CHECKOUT the built set includes the
-// Harness, Adapter, and operator; installed from npm those sources do not resolve and the published
+// Harness and the operator; installed from npm those sources do not resolve and the published
 // `<kitversion>` refs are used with no docker at all (they are multi-arch manifest lists, so they
 // take no suffix and never had this hole). There is no `images` config block and no env escape
 // hatch — nobody gets to point a real cluster at a hand-picked Harness (ADR-0027's no-eject-hatch,
@@ -45,14 +45,22 @@
 // labeled objects found → converge silently (it's home); nothing → confirm first-time setup
 // (`--yes` for CI); objects labeled as a DIFFERENT instance → refuse.
 
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, createHmac, randomBytes } from "node:crypto";
 import { open, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { parseArgs } from "node:util";
 import {
+  custodianBootstrap,
+  custodianRef,
+  custodianScript,
   customizeLine,
   defaultImageContext,
+  heldSecretsOf,
+  HELD_CA_SECRET,
+  HELD_SECRETS_SECRET,
+  HELD_TLS_SECRET,
+  ORCHESTRATOR_PORT,
   imageContextDigest,
   isSshUrl,
   loadConfig,
@@ -64,9 +72,11 @@ import {
   type CarriedAgent,
   type CarriedImage,
   type CarriedRepo,
+  type HeldManifest,
   type ImageRefs,
   type JR2Config,
 } from "@jr2/orchestrator";
+import { caFits, fingerprint, issueCa, issueLeaf, leafFits, trustBundles, type Pem } from "../held-pki.ts";
 import {
   assertEmulation,
   buildSandboxImage,
@@ -102,6 +112,8 @@ import {
   OPERATOR_SELECTOR,
   operatorManifest,
   REPO_CACHE,
+  trustObject,
+  type HeldObjects,
 } from "../deploy.ts";
 import { resolveRoot } from "../instance.ts";
 import {
@@ -323,16 +335,20 @@ export async function up(args: string[], io: Io): Promise<number> {
   activity(
     io,
     kitRoot
-      ? `images: kit checkout at ${kitRoot} — building the Harness, Adapter, and operator from source`
-      : `images: installed kit — the published v${KIT_VERSION} Harness, Adapter, and operator, pulled from ` +
+      ? `images: kit checkout at ${kitRoot} — building the Harness and operator from source`
+      : `images: installed kit — the published v${KIT_VERSION} Harness and operator, pulled from ` +
           `${config.kitRegistry ? `${config.kitRegistry} (kitRegistry)` : KIT_IMAGE_HOME}`,
   );
+  // The Custodian's image is deployed and never built, in either world (ADR-0038, ADR-0059): the
+  // pinned upstream Envoy, re-homed onto `kitRegistry` like a Kit image when one is set.
+  const custodianImage = custodianRef(config.kitRegistry);
+  activity(io, `custodian image: ${custodianImage} (pinned, deployed — never built)`);
 
   // Read the Orchestrator Deployment ONCE: it carries both convergence records — the instance
   // image's content hash (a label) and the previous name→ref map (an annotation, ADR-0038).
   const orch = await kube.getJson({ kind: "deployment", name: ORCHESTRATOR_SERVICE, namespace, ...ctx });
   const previous = previousImages(orch);
-  const converged: ConvergedImages = { harness: refs.harness, adapter: refs.adapter, sandbox: {}, sandboxUser: {} };
+  const converged: ConvergedImages = { harness: refs.harness, custodian: custodianImage, sandbox: {}, sandboxUser: {} };
 
   // ONE transport branch for every image (ADR-0038), so instance, kit, and Sandbox Images cannot
   // drift into three delivery stories.
@@ -474,13 +490,11 @@ export async function up(args: string[], io: Io): Promise<number> {
   }
 
   // --- the kit's own runtime images (ADR-0038) ---------------------------------------------------
-  // Built here rather than lazily beside their consumers. The Harness is the injection source
+  // Built here rather than lazily beside its consumers. The Harness is the injection source
   // (ADR-0037): the pod's `runtime` init step copies `/opt/jr2` out of this exact ref onto the
-  // volume the Sandbox Image mounts. The Adapter is deployed into every Sandbox this instance
-  // provisions. Neither is a hash input for a Sandbox Image — the runtime rides the pod's volume,
-  // so a kit edit re-images future pods and re-tags nothing of the user's.
+  // volume the Sandbox Image mounts. It is not a hash input for a Sandbox Image — the runtime rides
+  // the pod's volume, so a kit edit re-images future pods and re-tags nothing of the user's.
   await ensureKitImage("harness");
-  await ensureKitImage("adapter");
 
   // --- instance image (content-addressed by the bundle) ------------------------------------------
   // Stage first, THEN decide: the hash is over the materialized bundle — the actual image inputs,
@@ -613,10 +627,10 @@ export async function up(args: string[], io: Io): Promise<number> {
   const secretData: Record<string, string> = {
     JR2_INSTANCE_TOKEN: instanceToken,
     JR2_SIGNING_KEY: signingKey,
-    // The Instance Harness Adapter's credential (ADR-0013/0031): a sandbox-style token signed
+    // The Instance Harness Custodian's credential (ADR-0013/0031): a sandbox-style token signed
     // for the placement's name — it may deliver only to Turns hosted THERE (tokens.ts), so the
     // Instance token never enters that pod. Derived from the kept key, so re-runs converge to
-    // the same value; live Adapters keep verifying.
+    // the same value; live Custodians keep verifying.
     JR2_INSTANCE_HARNESS_TOKEN: sandboxToken(Buffer.from(signingKey, "base64"), INSTANCE_HARNESS_SERVICE),
   };
   // Git tokens (ADR-0019/0051): every env var a `git.credentials` entry names, materialized from
@@ -629,29 +643,49 @@ export async function up(args: string[], io: Io): Promise<number> {
 
   // The HARNESS containers' env — a separate Secret (ADR-0013): Agent code executes where these
   // land, so the Instance token/signing key above must be unreachable from it. Values declared in
-  // config (usually read off process.env/.env) materialize here (ADR-0019); so does the provider
-  // key — the ConfigMap'd harness config carries the provider MINUS this (ADR-0018).
+  // config (usually read off process.env/.env) materialize here (ADR-0019). The provider key does
+  // NOT: it is a held secret (ADR-0059), and the Agent can read everything in this Secret.
   const harnessEnvData: Record<string, string> = {};
   for (const v of config.harness?.env ?? []) if (v.value !== undefined) harnessEnvData[v.name] = v.value;
-  if (config.harness?.provider?.apiKey) harnessEnvData.JR2_PROVIDER_API_KEY = config.harness.provider.apiKey;
 
   // Preflight referenced-but-unmanaged Secrets: turn the CreateContainerConfigError hang into an
-  // immediate, named error (ADR-0019). Sealed/External Secrets ride this seam untouched.
+  // immediate, named error (ADR-0019). Sealed/External Secrets ride this seam untouched. The read
+  // keeps each one's key NAMES (never a value), which the held-secret rules check for a model key.
+  const envFromKeys = new Map<string, string[]>();
   for (const ref of config.harness?.envFrom ?? []) {
-    const refName = ref.secretRef?.name;
+    const refName = ref.secretRef?.name ?? ref.configMapRef?.name;
     if (!refName) continue;
-    if (!(await kube.getJson({ kind: "secret", name: refName, namespace, ...ctx }))) {
+    const kind = ref.secretRef ? "secret" : "configmap";
+    const found = await kube.getJson<KubeObject & { data?: Record<string, string> }>({
+      kind,
+      name: refName,
+      namespace,
+      ...ctx,
+    });
+    if (!found && kind === "secret") {
       throw new Error(
         `harness.envFrom references Secret "${refName}", which does not exist in namespace "${namespace}" — ` +
           `create it first: kubectl -n ${namespace} create secret generic ${refName} --from-literal=KEY=...`,
       );
     }
+    envFromKeys.set(`${kind}/${refName}`, Object.keys(found?.data ?? {}));
   }
 
   // --- private-CA bundle (ADR-0020): read HERE, host-side — the in-cluster config eval never
   // touches the file (the path may not exist there); consumers get the ConfigMap.
   const caPem = await readCaBundle(root, config);
 
+  // --- held secrets (ADR-0059): resolved HERE, host-side, where `.env` exists ------------------
+  const held = await resolveHeld(io, kube, {
+    config,
+    name,
+    namespace,
+    ctx,
+    envFromKeys,
+    models: agents.map((a) => a.definition.model).filter((m): m is string => typeof m === "string"),
+    caBundle: caPem,
+  });
+
   // --- git over ssh: where the key comes from (ADR-0019, ADR-0047) -------------------------------
   // Runs BEFORE the apply, because a missing key source is a converge that must not start, and the
   // notice it hands back is owed to the END of the converge — a generated key is dead until a human
@@ -662,6 +696,10 @@ export async function up(args: string[], io: Io): Promise<number> {
   await preflightProvider(io, kube, config, agents, namespace, ctx, caPem);
 
   // --- apply + rollout ---------------------------------------------------------------------------
+  // The trust bundles first, and server-side: every pod that mounts them must find them, and they
+  // carry every root certificate — past what client-side apply's annotation can hold.
+  const trust = trustObject({ name, namespace, caBundle: caPem, bundles: held.bundles });
+  if (trust) await kube.apply({ manifest: trust, serverSide: true, ...ctx });
   activity(io, `orchestrator: applying (image ${tag})`);
   await kube.apply({
     manifest: instanceObjects({
@@ -672,12 +710,21 @@ export async function up(args: string[], io: Io): Promise<number> {
       secretData,
       harnessEnvData,
       harness: config.harness,
-      caBundle: caPem,
+      held: held.objects,
       imageRefs: converged,
       repoCache: carried.composesSandbox ? { image: operatorImage!, placement: config.sandbox } : undefined,
     }),
     ...ctx,
   });
+  // No secret held any more: the Custodian's Secrets go with it. The CA stays (`jr2-held-ca`), so a
+  // later converge that holds one again issues leaves under the same CA.
+  if (held.objects.manifest.secrets.length === 0) {
+    for (const secret of [HELD_SECRETS_SECRET, HELD_TLS_SECRET]) {
+      await kube.deleteObject({ kind: "secret", name: secret, namespace, ...ctx });
+    }
+  } else if (Object.keys(held.objects.values).length === 0) {
+    await kube.deleteObject({ kind: "secret", name: HELD_SECRETS_SECRET, namespace, ...ctx });
+  }
   activity(io, "orchestrator: waiting for rollout");
   await awaitRollout(kube, {
     name: ORCHESTRATOR_SERVICE,
@@ -748,7 +795,9 @@ export async function up(args: string[], io: Io): Promise<number> {
         name,
         namespace,
         harnessImage,
-        adapterImage: refs.adapter,
+        custodianImage,
+        held: held.objects.manifest,
+        heldDigest: heldDigest(Buffer.from(signingKey, "base64"), held.objects),
         harness: config.harness,
         caBundle: caPem !== undefined,
         // The wire's gate (ADR-0058): the digest of the bearer the Orchestrator derives for this
@@ -787,7 +836,7 @@ export async function up(args: string[], io: Io): Promise<number> {
 }
 
 /**
- * Every image ref one converge resolved. The Orchestrator reads `harness`/`adapter`/`sandbox` from
+ * Every image ref one converge resolved. The Orchestrator reads `harness`/`custodian`/`sandbox` from
  * the mounted map (`ImageRefs`); `operator` rides the same JSON because the record `jr2 up` diffs
  * must cover every image it builds, and one map is what keeps the record it diffs and the map pods
  * read from ever disagreeing (ADR-0038).
@@ -820,7 +869,7 @@ function previousImages(orch?: KubeObject): Partial<ConvergedImages> | undefined
 
 /** Every ref one image map names, flattened — the kit's own plus each Sandbox Image. */
 function mapRefs(map: Partial<ConvergedImages>): string[] {
-  return [map.harness, map.adapter, map.operator, ...Object.values(map.sandbox ?? {})].filter(
+  return [map.harness, map.custodian, map.operator, ...Object.values(map.sandbox ?? {})].filter(
     (ref): ref is string => typeof ref === "string",
   );
 }
@@ -872,6 +921,97 @@ async function sweepAfterConverge(
   }
 }
 
+/**
+ * Held secrets, resolved (ADR-0059): the rules (`heldSecretsOf`, fed what only the cluster knows),
+ * the per-Instance CA (kept, or minted on first need), one leaf per bound target (reused while it
+ * still fits), the trust bundles, and the Custodian's rendered config. Narrated one line per secret
+ * — its name, its hosts, its source — and never a value.
+ */
+async function resolveHeld(
+  io: Io,
+  kube: KubeAdmin,
+  opts: {
+    config: JR2Config;
+    name: string;
+    namespace: string;
+    ctx: { context?: string };
+    envFromKeys: Map<string, string[]>;
+    models: string[];
+    /** The user's `caBundle` (ADR-0020): trusted upstream, and by the Harness beside the jr2 CA. */
+    caBundle?: string;
+  },
+): Promise<{ objects: HeldObjects; bundles?: { extra: string; bundle: string; upstream: string } }> {
+  const { config, namespace, ctx } = opts;
+  type Data = KubeObject & { data?: Record<string, string> };
+  const decode = (data: Record<string, string> | undefined, key: string): string | undefined =>
+    data?.[key] === undefined ? undefined : Buffer.from(data[key], "base64").toString("utf8");
+
+  // R10: a referenced Secret and key must exist. Read once per Secret — key NAMES, never values.
+  const referenced = new Map<string, string[] | undefined>();
+  for (const s of config.harness?.heldSecrets ?? []) {
+    const ref = s.valueFrom?.secretKeyRef.name;
+    if (ref === undefined || referenced.has(ref)) continue;
+    const found = await kube.getJson<Data>({ kind: "secret", name: ref, namespace, ...ctx });
+    referenced.set(ref, found ? Object.keys(found.data ?? {}) : undefined);
+  }
+  const { manifest, values, warnings } = heldSecretsOf(config, {
+    envFromKeys: opts.envFromKeys,
+    secretKeys: (secret) => referenced.get(secret),
+    models: opts.models,
+  });
+  for (const warning of warnings) activity(io, `warning: ${warning}`);
+  const orchestrator = { host: `${ORCHESTRATOR_SERVICE}.${namespace}.svc`, port: ORCHESTRATOR_PORT };
+  const rendered = {
+    bootstrap: JSON.stringify(custodianBootstrap(manifest, orchestrator)),
+    script: custodianScript(manifest),
+  };
+  if (manifest.secrets.length === 0) {
+    return { objects: { manifest, values, leaves: {}, ...rendered } };
+  }
+  for (const s of manifest.secrets) {
+    const where = s.hosts.map((h) => (h.port === 443 ? h.host : `${h.host}:${h.port}`)).join(", ");
+    const source = s.source.kind === "literal" ? "literal" : `secret ${s.source.secret}/${s.source.key}`;
+    activity(io, `held secret ${s.name} → ${where} (${source})`);
+  }
+
+  // The CA: kept whenever the cluster holds a usable one — a live pod's Harness trusts it from its
+  // start, so a leaf a restarted Custodian reads must still chain to it. A human rotates it by
+  // deleting the Secret.
+  const stored = await kube.getJson<Data>({ kind: "secret", name: HELD_CA_SECRET, namespace, ...ctx });
+  const kept = { cert: decode(stored?.data, "ca.crt") ?? "", key: decode(stored?.data, "ca.key") ?? "" };
+  const ca: Pem = stored && caFits(kept) ? kept : issueCa(opts.name);
+  if (ca !== kept) activity(io, `held secrets: minted the Instance's CA into ${HELD_CA_SECRET}`);
+
+  const tls = await kube.getJson<Data>({ kind: "secret", name: HELD_TLS_SECRET, namespace, ...ctx });
+  const leaves: Record<string, Pem> = {};
+  for (const s of manifest.secrets) {
+    for (const h of s.hosts) {
+      if (leaves[h.leaf]) continue;
+      const existing = {
+        cert: decode(tls?.data, `${h.leaf}.crt`) ?? "",
+        key: decode(tls?.data, `${h.leaf}.key`) ?? "",
+      };
+      leaves[h.leaf] = leafFits(existing, ca, h.host) ? existing : issueLeaf(ca, h.host);
+    }
+  }
+  return {
+    objects: { manifest, values, ca, leaves, ...rendered },
+    bundles: trustBundles(ca.cert, opts.caBundle),
+  };
+}
+
+/** The Instance Harness's `jr2.dev/held-digest` (ADR-0059): an HMAC over every held-secret input,
+ * keyed with the signing key so the annotation reveals nothing about a value. */
+function heldDigest(key: Buffer, held: HeldObjects): string {
+  const mac = createHmac("sha256", key);
+  mac.update(JSON.stringify(held.manifest));
+  for (const stem of Object.keys(held.leaves).sort()) mac.update(`${stem}:${fingerprint(held.leaves[stem]!.cert)}`);
+  for (const name of Object.keys(held.values).sort()) mac.update(`${name}=${held.values[name]}`);
+  mac.update(held.bootstrap);
+  mac.update(held.script);
+  return mac.digest("base64url").slice(0, 32);
+}
+
 /** The one delivery failure that is a configuration error rather than a docker one (ADR-0019). */
 function undeliverable(context: string): Error {
   return new Error(
@@ -955,7 +1095,7 @@ async function verifyRunningImage(
   // thing serving — the question is what the cluster runs now, not what it is done running.
   const live = pods.filter((p) => !p.metadata.deletionTimestamp);
   // `container` narrows a multi-container pod to the one this layer's image claim is about
-  // (the Instance Harness pod also carries the Adapter, which is not this check's business).
+  // (the Instance Harness pod also carries the Custodian, which is not this check's business).
   const stale = live.filter((p) =>
     p.spec.containers.some((c) => (container === undefined || c.name === container) && c.image !== image),
   );

package/src/commands/version.ts

@@ -301,7 +301,7 @@ function deployedRows(d: NonNullable<VersionReport["deployed"]>, r: VersionRepor
   }
   if (d.images) {
     if (d.images.harness) rows.push(["harness", d.images.harness]);
-    if (d.images.adapter) rows.push(["adapter", d.images.adapter]);
+    if (d.images.custodian) rows.push(["custodian", d.images.custodian]);
     for (const [key, ref] of Object.entries(d.images.sandbox ?? {})) rows.push([`sandbox ${key}`, ref]);
   }
   const verdict = skewSentence(r);