@jr2/cli 0.2.1 → 0.4.1

package/src/deploy.ts

@@ -3,11 +3,31 @@
 // namespace are constants (namespace is the identity); every object carries the instance label so
 // ownership is derivable from the cluster — there is no local target state.
 
+import { createHmac } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import {
   CA_CONFIGMAP,
+  CA_MOUNT,
+  EFFECTOR_PORT,
+  INSTANCE_EFFECTOR,
+  CONVERSATIONS_DIR,
+  CONVERSATIONS_DIR_ENV,
+  CONVERSATIONS_VOLUME,
+  custodianComposition,
+  CUSTODIAN_BOOTSTRAP_KEY,
+  CUSTODIAN_PROGRAM,
+  CUSTODIAN_PROGRAM_KEY,
+  CUSTODIAN_SCRIPT_KEY,
+  INSTANCE_CUSTODIAN_CONFIGMAP,
   GIT_SSH_SECRET,
+  HELD_CA_SECRET,
+  HELD_CONFIGMAP,
+  HELD_MOUNT,
+  HELD_TLS_SECRET,
+  heldManifestKey,
+  heldSecretsSecret,
+  INSTANCE_HARNESS_HELD_POD,
   HARNESS_ENV_SECRET,
   IMAGES_CONFIGMAP,
   IMAGES_KEY,
@@ -18,16 +38,35 @@ import {
   INSTANCE_HARNESS_SERVICE,
   INSTANCE_SECRET,
   KIT_VERSION,
+  NO_DISRUPT_ANNOTATIONS,
   ORCHESTRATOR_PORT,
   ORCHESTRATOR_SERVICE,
   REPO_CACHE,
+  PRIORITY_CLASS_CONTROL,
+  PRIORITY_CLASS_SANDBOX,
   REPO_CACHE_HOSTPATH,
+  SERVICE_ACCOUNT_CA,
   STATE_PVC,
+  type EffectorPlan,
+  type SandboxEffectorPlan,
+  effectorManifestKey,
+  LABEL_EFFECTOR_POD,
+  sandboxEffectorObjectsOf,
+  GIT_PUSH_MANIFEST_KEY,
+  LABEL_GIT_PUSH,
+  GIT_CLONE_MANIFEST_KEY,
+  LABEL_GIT_CLONE,
+  type GitCloneSecret,
+  type GitPushManifest,
   type HarnessConfig,
+  type HeldManifest,
+  type PriorityClasses,
   type SandboxPlacement,
 } from "@jr2/orchestrator";
+import type { Pem } from "./held-pki.ts";
 
 export {
+  INSTANCE_EFFECTOR,
   GIT_SSH_SECRET,
   HARNESS_CONFIGMAP,
   HARNESS_ENV_SECRET,
@@ -39,7 +78,6 @@ export {
 
 export const LABEL_INSTANCE = "jr2.dev/instance";
 export const LABEL_VERSION = "jr2.dev/version";
-export const LABEL_HASH = "jr2.dev/content-hash";
 
 /** The converged name→ref image map, stamped on the Orchestrator Deployment's OWN metadata so the
  * next `jr2 up` can diff it and spend no docker on what has not moved (ADR-0038). An ANNOTATION, not
@@ -48,6 +86,27 @@ export const ANNOTATION_IMAGES = "jr2.dev/images";
 
 export const ORCHESTRATOR_SA = "jr2-orchestrator";
 
+/** The HMAC over the held-secret inputs, on the Instance Harness's pod template (ADR-0059). */
+export const ANNOTATION_HELD_DIGEST = "jr2.dev/held-digest";
+
+/** The Instance Harness pod's `fsGroup` — a Sandbox pod's default work group (ADR-0005), for the
+ * same reason: a group every container is granted, which the Custodian's values are readable by. */
+const INSTANCE_HARNESS_FS_GROUP = 2000;
+
+/** How long the Instance Harness pod is given to stop (ADR-0031's drain): on SIGTERM it stops
+ * admitting and finishes the Turns it holds, so the grace is a Turn's worst case. `jr2 up` waits
+ * out a rollout that long, and no longer. */
+export const INSTANCE_HARNESS_DRAIN_SECONDS = 600;
+
+/** The Instance Harness's conversations volume (ADR-0031): the StatefulSet's one claim, and the
+ * PVC ordinal 0 gets from it — `<claim>-<statefulset>-<ordinal>`. */
+export const INSTANCE_HARNESS_PVC = `${CONVERSATIONS_VOLUME}-${INSTANCE_HARNESS_SERVICE}-0`;
+
+/** The Instance Harness StatefulSet's governing Service (ADR-0031): headless, and dialed by no one
+ * today — it is what gives each ordinal the stable name N > 1 would pin a conversation to. The
+ * Orchestrator dials the ClusterIP Service `INSTANCE_HARNESS_SERVICE`, never this one. */
+export const INSTANCE_HARNESS_PODS_SERVICE = `${INSTANCE_HARNESS_SERVICE}-pods`;
+
 /** The two ingress NetworkPolicies (ADR-0058) — see `harnessIngressPolicies`. */
 export const SANDBOX_INGRESS_POLICY = "jr2-sandbox-ingress";
 export const INSTANCE_HARNESS_INGRESS_POLICY = "jr2-instance-harness-ingress";
@@ -59,13 +118,21 @@ export const OPERATOR_DEPLOYMENT = "jr2-controller-manager";
 export const OPERATOR_SELECTOR = "control-plane=controller-manager";
 
 /** The rendered operator install manifest shipped inside this package (`just operator-manifest`
- * regenerates it from operator/config). The manager image ref is substituted at apply time. */
-export async function operatorManifest(image: string): Promise<string> {
+ * regenerates it from operator/config). The manager image ref is substituted at apply time, and so
+ * is its PriorityClass (ADR-0060): the manifest names `jr2-control`, and an Instance that names its
+ * own control class gets no pod that names one `jr2 up` did not create. */
+export async function operatorManifest(image: string, controlClass = PRIORITY_CLASS_CONTROL): Promise<string> {
   const raw = await readFile(fileURLToPath(new URL("../manifests/operator.yaml", import.meta.url)), "utf8");
   if (!raw.includes("image: controller:latest")) {
     throw new Error("packaged operator.yaml has no `image: controller:latest` placeholder — regenerate it");
   }
-  return raw.replace("image: controller:latest", `image: ${image}`);
+  const classLine = `priorityClassName: ${PRIORITY_CLASS_CONTROL}`;
+  if (!raw.includes(classLine)) {
+    throw new Error(`packaged operator.yaml has no \`${classLine}\` — regenerate it`);
+  }
+  return raw
+    .replace("image: controller:latest", `image: ${image}`)
+    .replace(classLine, `priorityClassName: ${controlClass}`);
 }
 
 /** Compare dotted versions: negative when a < b, 0 when equal, positive when a > b. */
@@ -81,22 +148,140 @@ export function compareVersions(a: string, b: string): number {
 
 type KubeManifest = Record<string, unknown>;
 
+/**
+ * jr2's own pods are kit-sized, with no config key (ADR-0060): memory request = limit, a CPU request
+ * and NO CPU limit — a provisioning burst needs CPU, and no Agent Substrate move applies to them.
+ * The Repo cache agent is the one exception to request = limit: `git index-pack` spikes, and its OOM
+ * costs only a refetch. The operator's own size rides its manifest (operator/config).
+ */
+export const KIT_POD_SIZES = {
+  orchestrator: { requests: { cpu: "500m", memory: "1Gi" }, limits: { memory: "1Gi" } },
+  /** It holds the conversations its live runs hold, and frees the rest on the live set (ADR-0031). */
+  instanceHarness: { requests: { cpu: "250m", memory: "1Gi" }, limits: { memory: "1Gi" } },
+  /** The Instance Harness pod's Custodian: the same 64Mi/50m slice a Sandbox's takes, kit-sized. */
+  instanceCustodian: { requests: { cpu: "50m", memory: "64Mi" }, limits: { memory: "64Mi" } },
+  repoCache: { requests: { cpu: "50m", memory: "128Mi" }, limits: { memory: "1Gi" } },
+  /** The Instance Effector (ADR-0068): one http call at a time per Effect, its text body bounded. */
+  instanceEffector: { requests: { cpu: "50m", memory: "128Mi" }, limits: { memory: "128Mi" } },
+} as const;
+
+/** A fresh copy, so no manifest shares an object with another (or with the constant). */
+const sized = (r: { requests: Record<string, string>; limits: Record<string, string> }) => ({
+  requests: { ...r.requests },
+  limits: { ...r.limits },
+});
+
+/** The PriorityClass each of jr2's two tiers runs under (ADR-0060): the Instance's own when
+ * `priorityClasses` names one, else the one `jr2 up` creates. */
+export function priorityClassNames(classes: PriorityClasses | undefined): { control: string; sandbox: string } {
+  return {
+    control: classes?.control ?? PRIORITY_CLASS_CONTROL,
+    sandbox: classes?.sandbox ?? PRIORITY_CLASS_SANDBOX,
+  };
+}
+
+/**
+ * The PriorityClasses `jr2 up` creates, cluster-scoped, beside the CRDs (ADR-0060) — one manifest
+ * each, and none for a key `priorityClasses` names, since the cluster then has its own scheme.
+ * `jr2-control` preempts lower priorities: the Orchestrator, the operator, the Repo cache agent and the
+ * Instance Effector are small and fixed, and the first three are needed by every Sandbox.
+ * `jr2-sandbox` never preempts: a waiting Sandbox evicts nobody, and an ordinary pod (priority 0)
+ * cannot preempt a live one. Both stay far below the
+ * system classes (2000000000+). Shared by every Instance on the cluster, like the operator, so they
+ * carry no instance label; a class's value and policy are immutable, and these never change.
+ */
+export function priorityClassObjects(classes: PriorityClasses | undefined): string[] {
+  const managed = { "app.kubernetes.io/managed-by": "jr2" };
+  const pc = (name: string, value: number, preemptionPolicy: string, description: string): string =>
+    JSON.stringify({
+      apiVersion: "scheduling.k8s.io/v1",
+      kind: "PriorityClass",
+      metadata: { name, labels: managed },
+      value,
+      preemptionPolicy,
+      globalDefault: false,
+      description,
+    });
+  return [
+    ...(classes?.control === undefined
+      ? [
+          pc(
+            PRIORITY_CLASS_CONTROL,
+            100000,
+            "PreemptLowerPriority",
+            "jr2 control: the Orchestrator, the operator and the Repo cache agent (ADR-0060)",
+          ),
+        ]
+      : []),
+    ...(classes?.sandbox === undefined
+      ? [
+          pc(
+            PRIORITY_CLASS_SANDBOX,
+            1000,
+            "Never",
+            "jr2 Sandboxes and the Instance Harness: never preempted by ordinary pods, never preempting (ADR-0060)",
+          ),
+        ]
+      : []),
+  ];
+}
+
+/**
+ * One Harness pod's held objects (ADR-0059): what `jr2 up` placed in it, ready to become objects.
+ * A Workspace's, or the Instance Harness's.
+ */
+export type HeldPodObjects = {
+  /** The pod key (`INSTANCE_HARNESS_HELD_POD`, `workspaceHeldPod`). */
+  pod: string;
+  manifest: HeldManifest;
+  /** Its literal values, by name — for its `jr2-held-secrets-<pod>` Secret; never in the manifest,
+   * never in a ConfigMap. */
+  values: Record<string, string>;
+};
+
+/** A Custodian's two rendered files: Envoy's bootstrap (JSON) and the `HELD` table script. */
+export type CustodianFiles = { bootstrap: string; script: string };
+
+/**
+ * What `jr2 up` resolved about held secrets (ADR-0059), ready to become objects. Values appear in
+ * two places only: each pod's `values` (the literals, for its own `jr2-held-secrets-<pod>` Secret)
+ * and the CA's and the leaves' keys — each lands in a Secret no Harness container mounts.
+ */
+export type HeldObjects = {
+  /** Every Harness pod the walk found, each with what its Custodian holds. */
+  pods: HeldPodObjects[];
+  /** The Instance Harness's Custodian files, when the walk placed it — the one pod `jr2 up` makes,
+   * so the one it renders for; a Sandbox's are rendered by the Orchestrator at provision
+   * (`kubeSandbox`). */
+  instance?: CustodianFiles;
+  /** The per-Instance CA — kept across converges; present whenever a secret is held. */
+  ca?: Pem;
+  /** One leaf per bound target of any pod, by file stem (`leafStem`). */
+  leaves: Record<string, Pem>;
+};
+
+/** Does any pod hold a secret? */
+export const holdsAny = (held: HeldObjects): boolean => held.pods.some((p) => p.manifest.secrets.length > 0);
+
 /** Everything `jr2 up` converges inside the instance's namespace, as one apply-able List. */
 export function instanceObjects(opts: {
   name: string;
   namespace: string;
+  /** The Orchestrator Kit image's ref (ADR-0069). The Deployment carries no content hash: the
+   * Assembly's hash is an Orchestrator fact, read from `GET /assembly`. */
   image: string;
-  hash: string;
-  /** Secret data (token, signing key, harness env literals) — written stringData, kube encodes. */
+  /** Secret data (the Instance token, the publish token, the signing key) — written stringData,
+   * kube encodes. The Orchestrator reads it through `envFrom`. */
   secretData: Record<string, string>;
-  /** The HARNESS containers' env values (creds, provider key) — a SEPARATE Secret from
-   * `secretData` by doctrine (ADR-0013): Agent code executes where this lands, so the Instance
-   * token and signing key must never share a Secret with it. */
+  /** The HARNESS containers' literal `harness.env` values — a SEPARATE Secret from `secretData` by
+   * doctrine (ADR-0013): Agent code executes where this lands, so the Instance token and signing
+   * key must never share a Secret with it, and no model key rides it either (ADR-0059). */
   harnessEnvData: Record<string, string>;
   harness?: HarnessConfig;
-  /** The private-CA PEM bundle (`harness.caBundle` file contents, read by `up` — ADR-0020). */
-  caBundle?: string;
-  /** Every image ref THIS converge resolved (ADR-0037/0038/0049): `{ harness, adapter, operator?,
+  /** Held secrets (ADR-0059): the Custodian's objects. The `jr2-held` ConfigMap is applied always —
+   * every Harness pod runs a Custodian — and the rest only while a secret is held. */
+  held: HeldObjects;
+  /** Every image ref THIS converge resolved (ADR-0037/0038/0049): `{ harness, custodian, operator?,
    * sandbox: { <key>: ref }, sandboxUser: { <key>: user } }`, where a key is a build context's
    * content digest or the reserved `default`. It lands twice, deliberately as one JSON so the
    * record `up` diffs and the map pods read can never disagree: as the `jr2-images` ConfigMap the
@@ -108,8 +293,20 @@ export function instanceObjects(opts: {
    * resolved operator ref — the same binary is the cache agent (`/manager repo-cache`). Absent, no
    * DaemonSet and none of its RBAC is applied; `up` deletes a stale one. */
   repoCache?: { image: string; placement?: SandboxPlacement };
+  /** `priorityClasses` from jr2.config.ts (ADR-0060): the classes to name instead of jr2's own. */
+  priorityClasses?: PriorityClasses;
+  /** Each Workspace's Sandbox Effector (ADR-0068): its manifest rides `jr2-held`, its
+   * `jr2-effector-<pod>` Secret holds its literals and `effector.json`. */
+  sandboxEffectors?: readonly SandboxEffectorPlan[];
+  /** Each `git.credentials` entry's push Secret and the manifest the provision reads (ADR-0051). */
+  gitPush?: { secrets: ReadonlyArray<{ name: string; data: Record<string, string> }>; manifest: GitPushManifest };
+  /** Each `git.credentials` entry's clone Secret (ADR-0068): the token the cache agent spends. The
+   * Orchestrator names it from `git-clone.json` and never holds it. */
+  gitClone?: readonly GitCloneSecret[];
 }): string {
   const labels = { [LABEL_INSTANCE]: opts.name, "app.kubernetes.io/managed-by": "jr2" };
+  const priority = priorityClassNames(opts.priorityClasses);
+  const effectors = (opts.sandboxEffectors ?? []).map((plan) => ({ plan, ...sandboxEffectorObjectsOf(plan) }));
   const meta = (name: string, extra: Record<string, string> = {}): KubeManifest => ({
     name,
     namespace: opts.namespace,
@@ -130,21 +327,27 @@ export function instanceObjects(opts: {
     { apiVersion: "v1", kind: "ServiceAccount", metadata: meta(ORCHESTRATOR_SA) },
     {
       // The orchestrator drives Sandbox CRs (+ their token Secrets) in its own namespace
-      // (ADR-0012/0013) and creates the Repo CRs the cache agent reconciles (ADR-0051); pod
-      // exec/port-forward are the attach path (ADR-0004).
+      // (ADR-0012/0013), watches them (ADR-0063), and creates the Repo CRs the cache agent
+      // reconciles (ADR-0051). Nothing on Pods: it never reads one — the operator publishes the pod
+      // facts on the Sandbox's status — and the attach is the Harness's own `POST /attach`, so no
+      // `pods/exec` stream crosses the API server (ADR-0063).
       apiVersion: "rbac.authorization.k8s.io/v1",
       kind: "Role",
       metadata: meta(ORCHESTRATOR_SA),
       rules: [
         { apiGroups: ["core.jr2.dev"], resources: ["sandboxes", "repos"], verbs: ["*"] },
-        // patch/update: the token Secret is `kubectl apply`d idempotently and later ownerRef-patched.
-        {
-          apiGroups: [""],
-          resources: ["secrets"],
-          verbs: ["get", "list", "create", "delete", "patch", "update"],
-        },
-        { apiGroups: [""], resources: ["pods", "pods/log"], verbs: ["get", "list", "watch"] },
-        { apiGroups: [""], resources: ["pods/exec", "pods/portforward"], verbs: ["create"] },
+        // Secrets: create and patch, nothing else (ADR-0068). The Orchestrator server-side
+        // applies its own per-Sandbox `<sandbox>-token` and `<sandbox>-effector`, owned by the CR,
+        // and holds no git credential and no Effect secret (ADR-0068): no get, no list, so it cannot read or enumerate the Effect
+        // secrets, the clone and push Secrets, or a user's Secret through the API. RBAC cannot
+        // pin `create` to a name, and `resourceNames` has no prefix form.
+        { apiGroups: [""], resources: ["secrets"], verbs: ["create", "patch"] },
+        // A Sandbox's Custodian files, rendered at provision and server-side applied (ADR-0059);
+        // owned by the CR, so the garbage collector deletes them with the pod.
+        { apiGroups: [""], resources: ["configmaps"], verbs: ["create", "patch"] },
+        // A Sandbox Effector's headless Service, written at provision beside its key (ADR-0068): how
+        // this process reaches the pod's own address. Owned by the CR, like the ConfigMap.
+        { apiGroups: [""], resources: ["services"], verbs: ["create", "patch"] },
       ],
     },
     {
@@ -165,9 +368,8 @@ export function instanceObjects(opts: {
       data: {
         [HARNESS_CONFIG_KEY]: JSON.stringify(
           {
-            // apiKey is deliberately dropped: it materializes into the Secret as
-            // JR2_PROVIDER_API_KEY (`up`), and the Harness reads it from env — a ConfigMap is not
-            // a place for a credential.
+            // apiKey is deliberately dropped: it is a held secret (ADR-0059) — the Custodian holds
+            // it, the Harness's env holds its Stand-in, and a ConfigMap is no place for either.
             provider: opts.harness?.provider
               ? {
                   id: opts.harness.provider.id,
@@ -180,6 +382,8 @@ export function instanceObjects(opts: {
                   models: opts.harness.provider.models,
                 }
               : undefined,
+            // Where pi's catalog providers send their calls (ADR-0059): endpoints, not keys.
+            catalog: opts.harness?.catalog,
           },
           null,
           2,
@@ -197,18 +401,77 @@ export function instanceObjects(opts: {
       metadata: meta(IMAGES_CONFIGMAP),
       data: { [IMAGES_KEY]: imagesJson },
     },
-    // The private-CA bundle (ADR-0020) — a ConfigMap, not a Secret: CA certs are public data.
-    // kubectlSandbox mounts it into the Harness container and points NODE_EXTRA_CA_CERTS at it.
-    ...(opts.caBundle
-      ? [
-          {
-            apiVersion: "v1",
-            kind: "ConfigMap",
-            metadata: meta(CA_CONFIGMAP),
-            data: { "ca.crt": opts.caBundle },
-          },
-        ]
-      : []),
+    // Held secrets (ADR-0059): what `jr2 up` DECLARES. A pod's `held-<pod>.json` is what its
+    // composition reads — the Orchestrator per provision from the mount below, `jr2 up` for the
+    // Instance Harness — and the Custodian's program is here once. Envoy's per-pod files are
+    // rendered by whoever makes the pod, never collected here: a shared object stops at 1 MiB.
+    // Names, hosts, headers: never a value.
+    {
+      apiVersion: "v1",
+      kind: "ConfigMap",
+      metadata: meta(HELD_CONFIGMAP),
+      data: {
+        ...Object.fromEntries(opts.held.pods.map((p) => [heldManifestKey(p.pod), JSON.stringify(p.manifest, null, 2)])),
+        [CUSTODIAN_PROGRAM_KEY]: CUSTODIAN_PROGRAM,
+        // Each Sandbox Effector's manifest (ADR-0068): the sources of its secrets mount, by name.
+        // The provision adds the container only for a pod whose manifest is here.
+        ...Object.fromEntries(
+          effectors.map((e) => [effectorManifestKey(e.plan.pod), JSON.stringify(e.manifest, null, 2)]),
+        ),
+        // The push manifest (ADR-0051): which entries have a push Secret, and what each can spend.
+        // Names only; the provision names the matched entry's Secret on the Sandbox CR.
+        ...(opts.gitPush?.manifest.entries.length
+          ? { [GIT_PUSH_MANIFEST_KEY]: JSON.stringify(opts.gitPush.manifest, null, 2) }
+          : {}),
+        // The clone manifest (ADR-0068): which entries' clone Secrets exist, by name. The Orchestrator
+        // names one as a Repo's `secretRef` only when it is listed here.
+        ...(opts.gitClone?.length
+          ? {
+              [GIT_CLONE_MANIFEST_KEY]: JSON.stringify(
+                { version: 1, secrets: opts.gitClone.map((s) => s.name) },
+                null,
+                2,
+              ),
+            }
+          : {}),
+      },
+    },
+    // Each entry's clone Secret (ADR-0068), in Flux's key names: the operator's cache agent reads the
+    // one a Repo's `secretRef` names. The Orchestrator neither writes nor reads it.
+    ...(opts.gitClone ?? []).map(
+      (s): KubeManifest => ({
+        apiVersion: "v1",
+        kind: "Secret",
+        metadata: meta(s.name, { [LABEL_GIT_CLONE]: "true" }),
+        type: "Opaque",
+        stringData: s.data,
+      }),
+    ),
+    // Each entry's push Secret (ADR-0051): what it pushes and signs with, in Flux's key names where
+    // Flux has them. The operator projects one into the Sandbox Effector of a Sandbox whose push
+    // the entry's match covers; nothing else mounts it.
+    ...(opts.gitPush?.secrets ?? []).map(
+      (s): KubeManifest => ({
+        apiVersion: "v1",
+        kind: "Secret",
+        metadata: meta(s.name, { [LABEL_GIT_PUSH]: "true" }),
+        type: "Opaque",
+        data: s.data,
+      }),
+    ),
+    ...heldSecretObjects(opts.held, meta),
+    // Each Sandbox Effector's own Secret (ADR-0068): the literals its Effects name and
+    // `effector.json`. A `valueFrom` stays in the user's Secret, projected by reference at
+    // provision.
+    ...effectors.map(
+      (e): KubeManifest => ({
+        apiVersion: "v1",
+        kind: "Secret",
+        metadata: meta(e.secret.name, { [LABEL_EFFECTOR_POD]: e.plan.pod }),
+        type: "Opaque",
+        stringData: e.secret.stringData,
+      }),
+    ),
     {
       apiVersion: "v1",
       kind: "Secret",
@@ -230,7 +493,7 @@ export function instanceObjects(opts: {
       apiVersion: "apps/v1",
       kind: "Deployment",
       metadata: {
-        ...meta(ORCHESTRATOR_SERVICE, { [LABEL_HASH]: opts.hash, [LABEL_VERSION]: KIT_VERSION }),
+        ...meta(ORCHESTRATOR_SERVICE, { [LABEL_VERSION]: KIT_VERSION }),
         // The converged image map, on the DEPLOYMENT'S OWN metadata and never on
         // `spec.template.metadata` (ADR-0038). On the pod template it would be part of the pod
         // spec, so every re-resolved ref would roll the Orchestrator — the exact cost the
@@ -239,13 +502,22 @@ export function instanceObjects(opts: {
         annotations: { [ANNOTATION_IMAGES]: imagesJson },
       },
       spec: {
-        replicas: 1, // single WRITER (CONTEXT.md): the snapshot store brooks no split-brain
+        replicas: 1, // single WRITER (GLOSSARY.md): the snapshot store brooks no split-brain
         strategy: { type: "Recreate" }, // two writers may never overlap on the PVC
         selector: { matchLabels: { app: ORCHESTRATOR_SERVICE } },
         template: {
-          metadata: { labels: { ...labels, app: ORCHESTRATOR_SERVICE } },
+          metadata: {
+            labels: { ...labels, app: ORCHESTRATOR_SERVICE },
+            // The Instance Secret reaches the process through `envFrom`, which a running pod reads
+            // once. A minted replacement for a lost Secret (a new publish token above all,
+            // ADR-0069) must roll the pod, or every publish after it is refused with 401.
+            annotations: { [ANNOTATION_SECRET_DIGEST]: instanceSecretDigest(opts.secretData) },
+          },
           spec: {
             serviceAccountName: ORCHESTRATOR_SA,
+            // Control tier (ADR-0060): small, fixed, needed by every Sandbox. No disruption opt-out:
+            // a restarted Orchestrator re-attaches (ADR-0007).
+            priorityClassName: priority.control,
             containers: [
               {
                 name: "orchestrator",
@@ -256,20 +528,26 @@ export function instanceObjects(opts: {
                 env: [
                   // The entrypoint derives its own Service DNS + Sandbox namespace from these.
                   { name: "JR2_NAMESPACE", valueFrom: { fieldRef: { fieldPath: "metadata.namespace" } } },
-                  // What `/healthz` reports as this instance's identity. The same content address
-                  // the image tag carries (ADR-0019), in-process so a CLI can ask over HTTP
-                  // instead of needing kube access to read the Deployment's labels.
-                  { name: "JR2_CONTENT_HASH", value: opts.hash },
+                  // The API server's trust (ADR-0063): the Orchestrator's own Kubernetes client is
+                  // built-in `fetch`, which trusts the ServiceAccount's CA through this and nothing
+                  // else — no TLS code, no dependency.
+                  { name: "NODE_EXTRA_CA_CERTS", value: SERVICE_ACCOUNT_CA },
                 ],
                 // The Orchestrator creates Repo resources and never clones (ADR-0051) — the cache
                 // agent on each node does, reading the credential Secret a Repo's `secretRef`
-                // names — so nothing of git's is mounted here: state and the image map only.
+                // names, which `jr2 up` wrote (ADR-0068) — so nothing of git's is mounted here and no
+                // git token is in this container's env: state, the image map and the manifests.
                 volumeMounts: [
                   { name: "state", mountPath: "/instance/.jr2" },
                   // The image map, read per provision (ADR-0038). A mount, so `jr2 up` rewriting
                   // it costs one kubelet propagation window instead of a rollout.
                   { name: "images", mountPath: IMAGES_MOUNT, readOnly: true },
+                  // What each Workspace's Custodian holds, read per provision the same way
+                  // (ADR-0059): names and hosts, which this process could not derive — its `.env`
+                  // values are absent.
+                  { name: "held", mountPath: HELD_MOUNT, readOnly: true },
                 ],
+                resources: sized(KIT_POD_SIZES.orchestrator),
                 // The period, not the boot, is what `up`'s rollout wait measures. Measured: the
                 // container answers `/healthz` 1.1s after it starts, and the default 10s period
                 // billed that as 11.0s — one probe fired before the server was up, then a whole
@@ -278,7 +556,7 @@ export function instanceObjects(opts: {
                 // `failureThreshold` is then raised to hold the tolerance the default period gave,
                 // because ONE knob sets two unrelated things: how fast a boot is noticed, and how
                 // long a running pod may stall before the kubelet takes it out of service. The
-                // Orchestrator is `replicas: 1` (CONTEXT.md: single writer), so its Service has
+                // Orchestrator is `replicas: 1` (GLOSSARY.md: single writer), so its Service has
                 // exactly one endpoint and losing it is an outage, not a failover — and its store
                 // writes are synchronous, so a GC pause or a node busy with a docker build can
                 // silence `/healthz` for seconds. 15 × 2s keeps the 30s the default 3 × 10s gave.
@@ -288,11 +566,23 @@ export function instanceObjects(opts: {
                   periodSeconds: 2,
                   failureThreshold: 15,
                 },
+                // Liveness restarts, which readiness never does (ADR-0008). A restart of this
+                // `replicas: 1` writer is an outage plus a restore, so it fires only on a process
+                // that has answered nothing for five minutes (30 × 10s): silent that long is dead,
+                // not stalled, and without it the pod sits NotReady until a human deletes it. A
+                // process that EXITS needs no probe — the restart policy already has it. The same
+                // five minutes cover a boot's restore, so there is no initial delay.
+                livenessProbe: {
+                  httpGet: { path: "/healthz", port: ORCHESTRATOR_PORT },
+                  periodSeconds: 10,
+                  failureThreshold: 30,
+                },
               },
             ],
             volumes: [
               { name: "state", persistentVolumeClaim: { claimName: STATE_PVC } },
               { name: "images", configMap: { name: IMAGES_CONFIGMAP } },
+              { name: "held", configMap: { name: HELD_CONFIGMAP } },
             ],
           },
         },
@@ -308,7 +598,15 @@ export function instanceObjects(opts: {
       },
     },
     ...harnessIngressPolicies(opts.name, meta),
-    ...(opts.repoCache ? repoCacheObjects({ ...opts.repoCache, namespace: opts.namespace, labels, meta }) : []),
+    ...(opts.repoCache
+      ? repoCacheObjects({
+          ...opts.repoCache,
+          namespace: opts.namespace,
+          labels,
+          meta,
+          priorityClassName: priority.control,
+        })
+      : []),
   ];
 
   return JSON.stringify({ apiVersion: "v1", kind: "List", items });
@@ -329,8 +627,8 @@ const SANDBOX_POD_LABEL = "sandbox.jr2.dev/name";
  * window. The peer is this instance's Orchestrator and no other — a `podSelector` never crosses the
  * namespace, and the instance label pins it within one. What is NOT here, on purpose:
  *
- * - The Orchestrator is not selected. Every route there is token-gated, and an Adapter in any
- *   Harness pod must reach it; a policy could not tell the Adapter's packets from the Agent's.
+ * - The Orchestrator is not selected. Every route there is token-gated, and a Custodian in any
+ *   Harness pod must reach it; a policy could not tell the Custodian's packets from the Agent's.
  * - No egress. What a Sandbox may reach is its own decision (ADR-0058 records it open).
  * - No port. The Orchestrator speaks only the Harness wire to these pods, and a port here would
  *   have to track the CR's `port`; `kubectl port-forward` (the CLI, a human's shell into the User
@@ -381,8 +679,10 @@ function repoCacheObjects(opts: {
   namespace: string;
   labels: Record<string, string>;
   meta: (name: string, extra?: Record<string, string>) => KubeManifest;
+  /** The control tier's class (ADR-0060): every Sandbox on the node needs this agent. */
+  priorityClassName: string;
 }): KubeManifest[] {
-  const { image, namespace, labels, meta, placement } = opts;
+  const { image, namespace, labels, meta, placement, priorityClassName } = opts;
   return [
     { apiVersion: "v1", kind: "ServiceAccount", metadata: meta(REPO_CACHE) },
     {
@@ -419,6 +719,7 @@ function repoCacheObjects(opts: {
           spec: {
             serviceAccountName: REPO_CACHE,
             automountServiceAccountToken: true,
+            priorityClassName,
             // One agent per Sandbox node (ADR-0052): the pod's own placement, verbatim. A node no
             // Sandbox can reach gets no agent — a cache there is a clone nobody reads, and an
             // affinity term the scheduler cannot honor. (The DaemonSet controller still adds its
@@ -443,7 +744,8 @@ function repoCacheObjects(opts: {
                   { name: "home", mountPath: REPO_CACHE_HOME },
                   { name: "tmp", mountPath: "/tmp" },
                 ],
-                resources: { requests: { cpu: "20m", memory: "64Mi" } },
+                // Kit-sized (ADR-0060): the one request below its limit — `git index-pack` spikes.
+                resources: sized(KIT_POD_SIZES.repoCache),
                 securityContext: {
                   runAsUser: 0,
                   runAsGroup: 0,
@@ -469,23 +771,82 @@ function repoCacheObjects(opts: {
   ];
 }
 
-/** Where the Instance Harness's Harness container sees the CA bundle — the same path
- * `kubectlSandbox` mounts it at in a Sandbox pod (ADR-0020). */
-const CA_MOUNT = "/etc/jr2/ca";
+/** The label on each pod's `jr2-held-secrets-<pod>` Secret: its pod, so `jr2 up` finds and deletes
+ * the one a pod no longer needs. */
+export const LABEL_HELD_POD = "jr2.dev/held-pod";
+
+/**
+ * The held-secret Secrets (ADR-0059), present only while a secret is held: the CA (which NO pod
+ * mounts — `jr2 up` alone reads it back), each pod's literal values (its Custodian's alone) and the
+ * leaves (the Custodians'). `stringData` as written: no trailing newline is added to a value.
+ */
+function heldSecretObjects(held: HeldObjects, meta: (name: string) => KubeManifest): KubeManifest[] {
+  if (!holdsAny(held) || !held.ca) return [];
+  const secret = (name: string, stringData: Record<string, string>, pod?: string): KubeManifest => {
+    const m = meta(name);
+    return {
+      apiVersion: "v1",
+      kind: "Secret",
+      metadata: pod === undefined ? m : { ...m, labels: { ...(m.labels as object), [LABEL_HELD_POD]: pod } },
+      type: "Opaque",
+      stringData,
+    };
+  };
+  const leaves: Record<string, string> = {};
+  for (const [stem, pem] of Object.entries(held.leaves)) {
+    leaves[`${stem}.crt`] = pem.cert;
+    leaves[`${stem}.key`] = pem.key;
+  }
+  return [
+    secret(HELD_CA_SECRET, { "ca.crt": held.ca.cert, "ca.key": held.ca.key }),
+    ...held.pods.flatMap((p) =>
+      Object.keys(p.values).length ? [secret(heldSecretsSecret(p.pod), p.values, p.pod)] : [],
+    ),
+    secret(HELD_TLS_SECRET, leaves),
+  ];
+}
 
-/** The Adapter's port on the pod's loopback — the same default the Sandbox pod uses. */
-const ADAPTER_PORT = 8081;
+/**
+ * The trust ConfigMap (ADR-0020, ADR-0059): the user's `caBundle` as `ca.crt`, and while a secret
+ * is held, the three bundles its path needs. Its own manifest, apart from the List, because the
+ * bundles carry every root certificate — past what client-side apply's annotation can hold — so
+ * `jr2 up` applies it server-side. Undefined when there is nothing to trust.
+ */
+export function trustObject(opts: {
+  name: string;
+  namespace: string;
+  caBundle?: string;
+  bundles?: { extra: string; bundle: string; upstream: string };
+}): string | undefined {
+  if (opts.caBundle === undefined && opts.bundles === undefined) return undefined;
+  return JSON.stringify({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: {
+      name: CA_CONFIGMAP,
+      namespace: opts.namespace,
+      labels: { [LABEL_INSTANCE]: opts.name, "app.kubernetes.io/managed-by": "jr2" },
+    },
+    data: {
+      ...(opts.caBundle !== undefined ? { "ca.crt": opts.caBundle } : {}),
+      ...(opts.bundles
+        ? { "extra.crt": opts.bundles.extra, "bundle.crt": opts.bundles.bundle, "upstream.crt": opts.bundles.upstream }
+        : {}),
+    },
+  });
+}
 
 /**
- * The Instance Harness (ADR-0031): the per-instance Harness Deployment + Service `jr2 up`
+ * The Instance Harness (ADR-0031): the per-instance Harness StatefulSet + Service `jr2 up`
  * converges whenever an Agent a registered Machine CARRIES declares `workspace: "none"`
  * (ADR-0049's walk) — the placement for every Menu-only Agent's Turn, regardless of any enclosing
- * Workspace. The one Harness shape, minus the Workspace: the stock Harness image plus the Adapter
- * sidecar, the same harness-config ConfigMap and env/envFrom/CA wiring a Sandbox's Harness
- * container gets — and NO `/work` volume, no attach step. It runs the STOCK image permanently: `workspace: "none"` withholds the whole
- * Working toolset (ADR-0028), so there are no tools to carry and no Sandbox Image to resolve
- * (ADR-0037). No config key names, sizes, addresses, or enables it: the Machine walk is the
- * entire surface.
+ * Workspace. The one Harness shape, minus the Workspace: the stock Harness image plus the Custodian,
+ * composed by the same function a Sandbox's is (custodian.ts, ADR-0059), the same harness-config
+ * ConfigMap and env/envFrom/trust wiring a Sandbox's Harness container gets — and NO `/work`
+ * volume, no attach step. It runs the STOCK image permanently: `workspace: "none"` withholds the
+ * whole Working toolset (ADR-0028), so there are no tools to carry and no Sandbox Image to resolve
+ * (ADR-0037). No config key names, sizes, addresses, or enables it: the Machine walk is the entire
+ * surface.
  */
 export function instanceHarnessObjects(opts: {
   name: string;
@@ -496,19 +857,31 @@ export function instanceHarnessObjects(opts: {
    *
    * The accepted asymmetry: the Instance Harness names its images HERE, in the pod template, while
    * a Sandbox's refs travel through the `jr2-images` ConfigMap. Both are right for what they are —
-   * this Deployment is supposed to roll when its image moves; the Orchestrator is not. */
+   * this StatefulSet is supposed to roll when its image moves; the Orchestrator is not. */
   harnessImage: string;
-  /** The resolved Adapter ref: the Harness's one menu-delivery path, kept even though a `"none"`
+  /** The resolved Custodian ref: the Harness's one route to its Menu, kept even though a `"none"`
    * Agent cannot execute code — forking the path for one pod buys a divergence ADR-0031 declines. */
-  adapterImage: string;
+  custodianImage: string;
+  /** What this converge placed in the Instance Harness (ADR-0059): its own manifest — the model
+   * keys its `"none"` Agents' providers read, and nothing else. */
+  held: HeldManifest;
+  /** Its Custodian's two files, rendered from `held` — applied here, with the pod they are for
+   * (`INSTANCE_CUSTODIAN_CONFIGMAP`, ADR-0059). */
+  custodian: CustodianFiles;
+  /** An HMAC over this pod's held-secret inputs (its manifest, its leaves, its literal values, its
+   * Custodian's config), keyed with the signing key so it reveals nothing — on the pod template, so
+   * a change to any of them rolls this pod (ADR-0059). */
+  heldDigest: string;
   harness?: HarnessConfig;
-  /** The instance ships a private-CA bundle (ADR-0020): mount `jr2-ca` into the Harness container. */
+  /** The instance ships a private-CA bundle (ADR-0020). */
   caBundle?: boolean;
   /** The digest of this placement's Harness bearer (ADR-0058; `harnessTokenDigest(key,
    * "jr2-instance-harness")`) — the wire's gate. The digest, never the bearer: the same shape
    * every Sandbox Harness container gets, so this pod can verify the Orchestrator and mint
    * nothing. */
   bearerSha256: string;
+  /** `priorityClasses` from jr2.config.ts (ADR-0060): the classes to name instead of jr2's own. */
+  priorityClasses?: PriorityClasses;
 }): string {
   const labels = { [LABEL_INSTANCE]: opts.name, "app.kubernetes.io/managed-by": "jr2" };
   const meta = (): KubeManifest => ({
@@ -526,14 +899,27 @@ export function instanceHarnessObjects(opts: {
     seccompProfile: { type: "RuntimeDefault" },
   });
 
+  // The Custodian (ADR-0013, ADR-0059): the placement's Sandbox token — signed for this
+  // placement's name (`up.ts` mints it into the instance Secret), so it speaks only for the Turns
+  // hosted HERE (tokens.ts) — plus the held secrets placed here. Mounted into the Custodian alone;
+  // the Instance token itself never enters this pod.
+  const custodian = custodianComposition(opts.held, {
+    image: opts.custodianImage,
+    pod: INSTANCE_HARNESS_HELD_POD,
+    config: INSTANCE_CUSTODIAN_CONFIGMAP,
+    token: { secret: INSTANCE_SECRET, key: "JR2_INSTANCE_HARNESS_TOKEN" },
+    caBundle: opts.caBundle === true,
+    resources: sized(KIT_POD_SIZES.instanceCustodian),
+  });
+
   const harnessContainer = {
     name: "harness",
     image: opts.harnessImage,
     imagePullPolicy: "IfNotPresent",
     ports: [{ containerPort: INSTANCE_HARNESS_PORT }],
-    // The same asymmetry the Sandbox pod builds (ADR-0013/0020): the mounted harness config and
-    // the instance's valueFrom entries ride `env` (literal values live in the jr2-harness-env
-    // Secret), the CA trust lands here and nowhere else, and no credential ever does.
+    // The same asymmetry the Sandbox pod builds (ADR-0013/0020/0059): the mounted harness config
+    // and the instance's valueFrom entries ride `env` (literal values live in the jr2-harness-env
+    // Secret), then the Custodian's address and every Stand-in, and no credential ever does.
     env: [
       {
         name: "JR2_HARNESS_JSON",
@@ -545,79 +931,103 @@ export function instanceHarnessObjects(opts: {
       // rather than asserted. The bearer (below) narrows who may try; this decides what.
       { name: "JR2_MENU_ONLY", value: "1" },
       ...(opts.harness?.env ?? []).filter((v) => v.valueFrom !== undefined),
-      { name: "JR2_ADAPTER_URL", value: `http://127.0.0.1:${ADAPTER_PORT}` },
-      ...(opts.caBundle ? [{ name: "NODE_EXTRA_CA_CERTS", value: `${CA_MOUNT}/ca.crt` }] : []),
+      ...custodian.harnessEnv,
+      // Where the conversations persist (ADR-0031): the claim below. Mechanism, as on a Sandbox.
+      { name: CONVERSATIONS_DIR_ENV, value: CONVERSATIONS_DIR },
       // The wire's gate (ADR-0058), last — as on a Sandbox — so no `harness.env` entry chooses it.
       { name: "JR2_HARNESS_TOKEN_SHA256", value: opts.bearerSha256 },
     ],
     envFrom: [{ secretRef: { name: HARNESS_ENV_SECRET } }, ...(opts.harness?.envFrom ?? [])],
-    ...(opts.caBundle ? { volumeMounts: [{ name: "ca", mountPath: CA_MOUNT, readOnly: true }] } : {}),
+    // The Harness container's alone: the Custodian has no business with an Agent's history.
+    volumeMounts: [{ name: CONVERSATIONS_VOLUME, mountPath: CONVERSATIONS_DIR }, ...custodian.harnessMounts],
     // The operator probes a Sandbox's Harness the same way: serving = the socket accepts.
     // Period and threshold as reasoned on the Orchestrator above: the default 10s period is the
     // rollout wait rather than the boot, and the threshold then has to carry the stall tolerance
     // the period used to supply. This pod is single-replica too.
+    // The Harness's own route, not the port (ADR-0063): a socket probe would pass for whatever
+    // listens there. A draining Harness still answers it (ADR-0031).
     readinessProbe: {
-      tcpSocket: { port: INSTANCE_HARNESS_PORT },
+      httpGet: { path: "/healthz", port: INSTANCE_HARNESS_PORT },
       initialDelaySeconds: 1,
       periodSeconds: 2,
       failureThreshold: 15,
     },
+    resources: sized(KIT_POD_SIZES.instanceHarness),
     securityContext: hardenedContainerSecurityContext(),
   };
 
-  const adapterContainer = {
-    name: "adapter",
-    image: opts.adapterImage,
-    imagePullPolicy: "IfNotPresent",
-    securityContext: hardenedContainerSecurityContext(),
-    env: [
-      {
-        name: "JR2_ORCHESTRATOR_URL",
-        value: `http://${ORCHESTRATOR_SERVICE}.${opts.namespace}.svc:${ORCHESTRATOR_PORT}`,
-      },
-      { name: "JR2_ADAPTER_PORT", value: String(ADAPTER_PORT) },
-      // The Adapter's bearer env, carrying a sandbox-style token SIGNED FOR THIS PLACEMENT's
-      // name (`up.ts` mints it into the instance Secret): ADR-0013's delivery doctrine, extended
-      // to the second placement — the token speaks only for registrations that record the
-      // Instance Harness as the pod hosting their Turn (tokens.ts), never a Workspace's, and the
-      // Instance token itself never enters this pod. The credential lives in this container,
-      // where no Agent can read it — and `JR2_MENU_ONLY` above is what keeps that true: only
-      // Menu-only Agents run here, so nothing in this pod executes code (ADR-0031's
-      // defense-in-depth bonus).
-      {
-        name: "JR2_SANDBOX_TOKEN",
-        valueFrom: { secretKeyRef: { name: INSTANCE_SECRET, key: "JR2_INSTANCE_HARNESS_TOKEN" } },
-      },
-    ],
-  };
-
   const items: KubeManifest[] = [
+    // The one pod `jr2 up` makes, so the one whose Custodian files it renders: its bootstrap and
+    // its HELD table, from its own manifest, beside the program its volume projects from `jr2-held`.
+    {
+      apiVersion: "v1",
+      kind: "ConfigMap",
+      metadata: { ...meta(), name: INSTANCE_CUSTODIAN_CONFIGMAP },
+      data: {
+        [CUSTODIAN_BOOTSTRAP_KEY]: opts.custodian.bootstrap,
+        [CUSTODIAN_SCRIPT_KEY]: opts.custodian.script,
+      },
+    },
     {
       apiVersion: "apps/v1",
-      kind: "Deployment",
+      kind: "StatefulSet",
       metadata: { ...meta(), labels: { ...labels, [LABEL_VERSION]: KIT_VERSION } },
       spec: {
-        // ONE replica, Recreate: a conversation is an Instance ID on one Harness PROCESS
-        // (ADR-0031) — two pods behind this Service would route one conversation to two servers,
-        // the exact amnesia definition-wins placement exists to prevent. A restart loses the
-        // conversations (live-only, ADR-0023); the Deployment restores the endpoint, not the
-        // history.
+        // A StatefulSet of ONE (ADR-0031): the value is the stable volume — a restart or a rollout
+        // brings the same conversations back — and the stable name is what N > 1 would pin a
+        // conversation to. Never more than one pod behind this Service for one conversation, and
+        // never an HPA: a scale-down would kill conversations. At N = 1 a rollout has no surge,
+        // so admissions are refused while the new pod starts, which the Orchestrator absorbs
+        // (ADR-0042).
         replicas: 1,
-        strategy: { type: "Recreate" },
+        serviceName: INSTANCE_HARNESS_PODS_SERVICE,
         selector: { matchLabels: { app: INSTANCE_HARNESS_SERVICE } },
+        // The conversations go with the StatefulSet, never with a scale-down: an instance whose
+        // Machines dropped every `"none"` Agent keeps no history for them.
+        persistentVolumeClaimRetentionPolicy: { whenDeleted: "Delete", whenScaled: "Retain" },
+        volumeClaimTemplates: [
+          {
+            metadata: { name: CONVERSATIONS_VOLUME, labels },
+            spec: {
+              accessModes: ["ReadWriteOnce"],
+              resources: { requests: { storage: "1Gi" } },
+            },
+          },
+        ],
         template: {
-          metadata: { labels: { ...labels, app: INSTANCE_HARNESS_SERVICE } },
+          metadata: {
+            labels: { ...labels, app: INSTANCE_HARNESS_SERVICE },
+            // A held-secret edit rolls this pod; a live Sandbox keeps what its Custodian read at
+            // start (ADR-0059, the ADR-0037 stance). A move costs a drain, not the conversations
+            // (the volume keeps them), yet no autoscaler may choose one (ADR-0060) — a drain still
+            // can.
+            annotations: { [ANNOTATION_HELD_DIGEST]: opts.heldDigest, ...NO_DISRUPT_ANNOTATIONS },
+          },
           spec: {
-            containers: [harnessContainer, adapterContainer],
+            // The drain (ADR-0031): on SIGTERM the Harness stops admitting and finishes the Turns
+            // it holds, so the grace is a Turn's worst case — a deploy loses no Turn.
+            terminationGracePeriodSeconds: INSTANCE_HARNESS_DRAIN_SECONDS,
+            // The Sandbox tier's class (ADR-0060): it holds live conversations, as a Sandbox holds
+            // `/work`, and it may wait rather than preempt.
+            priorityClassName: priorityClassNames(opts.priorityClasses).sandbox,
+            // The Custodian is a native sidecar, so it outlives the drain (ADR-0031): the kubelet
+            // stops a pod's sidecars only after its main containers exit, and the draining Harness
+            // needs its Custodian to the end — its one route to the Menu and to the model. As a
+            // plain container Envoy took SIGTERM with the Harness and quit at once.
+            initContainers: [{ ...custodian.custodianContainer, restartPolicy: "Always" }],
+            containers: [harnessContainer],
             // The operator's isolation baseline (sandbox_controller.go), mirrored: same Harness
             // image, same "never reach the Kubernetes API" north star — JR2_MENU_ONLY makes code
-            // execution here unlikely, not unimaginable.
+            // execution here unlikely, not unimaginable. No `shareProcessNamespace`: the Harness
+            // container must not read the Custodian's `/proc`. `fsGroup` makes the Custodian's
+            // group-readable values readable by Envoy's own uid, as a Sandbox pod's does.
             automountServiceAccountToken: false,
             securityContext: {
               runAsNonRoot: true,
               seccompProfile: { type: "RuntimeDefault" },
+              fsGroup: INSTANCE_HARNESS_FS_GROUP,
             },
-            ...(opts.caBundle ? { volumes: [{ name: "ca", configMap: { name: CA_CONFIGMAP } }] } : {}),
+            volumes: custodian.volumes,
           },
         },
       },
@@ -627,11 +1037,272 @@ export function instanceHarnessObjects(opts: {
       kind: "Service",
       metadata: meta(),
       spec: {
+        // The address the Agent actor dials: a ClusterIP Service, deliberately not the headless
+        // one below. A draining pod is terminating, so DNS stops naming it, but kube-proxy still
+        // routes a ClusterIP to a terminating pod that serves while no other is ready — and at
+        // N = 1 none is until it exits. So during the drain reads, waits and aborts keep reaching
+        // it (ADR-0031), and a refused admission meets its 503, not a name that resolves to nothing.
         selector: { app: INSTANCE_HARNESS_SERVICE },
         ports: [{ port: INSTANCE_HARNESS_PORT, targetPort: INSTANCE_HARNESS_PORT }],
       },
     },
+    {
+      apiVersion: "v1",
+      kind: "Service",
+      metadata: { ...meta(), name: INSTANCE_HARNESS_PODS_SERVICE },
+      spec: {
+        // Headless — the StatefulSet's governing Service (`serviceName`), for the per-ordinal names.
+        clusterIP: "None",
+        selector: { app: INSTANCE_HARNESS_SERVICE },
+        ports: [{ port: INSTANCE_HARNESS_PORT, targetPort: INSTANCE_HARNESS_PORT }],
+      },
+    },
+  ];
+
+  return JSON.stringify({ apiVersion: "v1", kind: "List", items });
+}
+
+/** The Orchestrator's pod template digest of the Instance Secret: it rolls the pod when a value
+ * the process reads through `envFrom` changes (ADR-0069). */
+export const ANNOTATION_SECRET_DIGEST = "jr2.dev/secret-digest";
+
+/** A keyed digest of the Instance Secret's data, in key order. Keyed with the signing key it
+ * holds, so the annotation reveals nothing about a token. */
+export function instanceSecretDigest(secretData: Record<string, string>): string {
+  const mac = createHmac("sha256", Buffer.from(secretData.JR2_SIGNING_KEY ?? "", "base64"));
+  mac.update("jr2-instance-secret\n");
+  for (const key of Object.keys(secretData).sort()) {
+    const value = Buffer.from(secretData[key]!, "utf8");
+    mac.update(`${key}\n${value.length}:`).update(value);
+  }
+  return mac.digest("base64url");
+}
+
+/** The Instance Effector's pod template digest (ADR-0068): an HMAC over every secret input, so an
+ * edit to one rolls it, as `jr2.dev/held-digest` rolls the Instance Harness (ADR-0059). */
+export const ANNOTATION_EFFECTOR_DIGEST = "jr2.dev/effector-digest";
+
+/** The Instance Effector pod's `fsGroup`: its Secret files are readable by that group, and the pod
+ * has one container. The group a Sandbox's and the Instance Harness's pods use (ADR-0005). */
+const INSTANCE_EFFECTOR_FS_GROUP = 2000;
+
+/** Where the Effector reads what it holds (ADR-0068): its secrets, one file each; its key and
+ * its config. Its scratch is `$HOME`. */
+const EFFECTOR_SECRETS_DIR = "/run/jr2/secrets";
+const EFFECTOR_OWN_DIR = "/run/jr2/effector";
+const EFFECTOR_SCRATCH = "/run/jr2/scratch";
+
+/** How much more than the longest Effect timeout a stopping replica is given: room for the
+ * Orchestrator's next poll to read the outcome it finished. */
+export const EFFECTOR_READ_MARGIN_SECONDS = 30;
+
+/** The Secret's key of one literal Effect secret: prefixed, so no secret's name is `key` or
+ * `effector.json`. */
+const effectorSecretKey = (name: string): string => `secret.${name}`;
+
+/** The Instance Effector's grace period: the longest timeout among the Effects placed there, plus
+ * the read margin. */
+export const effectorGraceSeconds = (plan: EffectorPlan): number =>
+  Math.ceil(plan.longestTimeoutMs / 1000) + EFFECTOR_READ_MARGIN_SECONDS;
+
+/**
+ * The Instance Effector (ADR-0068): the objects `jr2 up` converges when a registered Machine
+ * places an Effect there — an `http` Effect — and deletes otherwise.
+ *
+ * - A Deployment, not a StatefulSet: a rollout must run the new pod beside the old one (surge), so
+ *   the old one finishes an Effect in flight while the new one takes new Effects. The Kit's
+ *   `jr2-harness` image with `/opt/jr2/bin/effector` as its command; hardened, non-root, a read-only
+ *   root filesystem, an emptyDir scratch as `$HOME`. Its grace period is the longest timeout among
+ *   the Effects placed there, plus a margin for the outcome to be read.
+ * - A headless Service that publishes addresses that are not ready: "ask every replica" is its
+ *   name's addresses, a stopping replica included.
+ * - A NetworkPolicy of `jr2-sandbox-ingress`'s form: ingress from this Instance's Orchestrator only.
+ *   No egress rule: the pod holds real values and calls the hosts its Effects name.
+ * - The Secret `jr2-instance-effector`: the literal Effect secrets placed here, the placement's key,
+ *   and `effector.json` (the targets). A secret from the user's own Secret is projected from there
+ *   by reference, never copied.
+ */
+export function instanceEffectorObjects(opts: {
+  name: string;
+  namespace: string;
+  /** The resolved `jr2-harness` ref — it carries the binary (ADR-0037). */
+  harnessImage: string;
+  plan: EffectorPlan;
+  /** `effectorKey(signingKey, "instance")`. */
+  key: string;
+  /** The HMAC over every secret input (`effectorDigest`). */
+  digest: string;
+  /** The instance ships a private-CA bundle (ADR-0020): it is mounted and trusted. */
+  caBundle?: boolean;
+  priorityClasses?: PriorityClasses;
+}): string {
+  const labels = { [LABEL_INSTANCE]: opts.name, "app.kubernetes.io/managed-by": "jr2" };
+  const meta = (): KubeManifest => ({ name: INSTANCE_EFFECTOR, namespace: opts.namespace, labels });
+  const grace = effectorGraceSeconds(opts.plan);
+
+  const literal = opts.plan.secrets.filter((s) => s.source.kind === "literal");
+  const sources: KubeManifest[] = [
+    ...(literal.length
+      ? [
+          {
+            secret: {
+              name: INSTANCE_EFFECTOR,
+              items: literal.map((s) => ({ key: effectorSecretKey(s.name), path: s.name })),
+            },
+          },
+        ]
+      : []),
+    ...opts.plan.secrets.flatMap((s) =>
+      s.source.kind === "secret"
+        ? [{ secret: { name: s.source.secret, items: [{ key: s.source.key, path: s.name }] } }]
+        : [],
+    ),
   ];
+  const config = { version: 1, placement: opts.plan.placement, targets: opts.plan.targets };
+
+  const container = {
+    name: "effector",
+    image: opts.harnessImage,
+    imagePullPolicy: "IfNotPresent",
+    command: ["/opt/jr2/bin/effector"],
+    ports: [{ containerPort: EFFECTOR_PORT }],
+    env: [
+      { name: "POD_NAME", valueFrom: { fieldRef: { fieldPath: "metadata.name" } } },
+      { name: "POD_IP", valueFrom: { fieldRef: { fieldPath: "status.podIP" } } },
+      { name: "JR2_EFFECTOR_PORT", value: String(EFFECTOR_PORT) },
+      { name: "JR2_EFFECTOR_KEY", value: `${EFFECTOR_OWN_DIR}/key` },
+      { name: "JR2_EFFECTOR_CONFIG", value: `${EFFECTOR_OWN_DIR}/effector.json` },
+      { name: "JR2_EFFECTOR_SECRETS", value: EFFECTOR_SECRETS_DIR },
+      // The drain ends a few seconds before the kubelet's kill, so the replica exits on its own.
+      { name: "JR2_EFFECTOR_DRAIN_SECONDS", value: String(Math.max(grace - 5, 1)) },
+      { name: "HOME", value: EFFECTOR_SCRATCH },
+      ...(opts.caBundle ? [{ name: "JR2_CA_FILE", value: `${CA_MOUNT}/ca.crt` }] : []),
+    ],
+    volumeMounts: [
+      { name: "secrets", mountPath: EFFECTOR_SECRETS_DIR, readOnly: true },
+      { name: "effector", mountPath: EFFECTOR_OWN_DIR, readOnly: true },
+      { name: "scratch", mountPath: EFFECTOR_SCRATCH },
+      ...(opts.caBundle ? [{ name: "ca", mountPath: CA_MOUNT, readOnly: true }] : []),
+    ],
+    readinessProbe: { httpGet: { path: "/healthz", port: EFFECTOR_PORT }, periodSeconds: 2, failureThreshold: 3 },
+    resources: sized(KIT_POD_SIZES.instanceEffector),
+    securityContext: {
+      runAsNonRoot: true,
+      allowPrivilegeEscalation: false,
+      readOnlyRootFilesystem: true,
+      capabilities: { drop: ["ALL"] },
+      seccompProfile: { type: "RuntimeDefault" },
+    },
+  };
 
+  const items: KubeManifest[] = [
+    {
+      apiVersion: "v1",
+      kind: "Secret",
+      metadata: meta(),
+      type: "Opaque",
+      stringData: {
+        key: opts.key,
+        "effector.json": JSON.stringify(config, null, 2),
+        ...Object.fromEntries(literal.map((s) => [effectorSecretKey(s.name), opts.plan.values[s.name] ?? ""])),
+      },
+    },
+    {
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      metadata: { ...meta(), labels: { ...labels, [LABEL_VERSION]: KIT_VERSION } },
+      spec: {
+        replicas: 1,
+        selector: { matchLabels: { app: INSTANCE_EFFECTOR } },
+        // Surge, never a gap: the new replica starts before the old one stops.
+        strategy: { type: "RollingUpdate", rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } },
+        template: {
+          metadata: {
+            labels: { ...labels, app: INSTANCE_EFFECTOR },
+            annotations: { [ANNOTATION_EFFECTOR_DIGEST]: opts.digest },
+          },
+          spec: {
+            terminationGracePeriodSeconds: grace,
+            priorityClassName: priorityClassNames(opts.priorityClasses).control,
+            automountServiceAccountToken: false,
+            enableServiceLinks: false,
+            securityContext: {
+              runAsNonRoot: true,
+              seccompProfile: { type: "RuntimeDefault" },
+              fsGroup: INSTANCE_EFFECTOR_FS_GROUP,
+            },
+            containers: [container],
+            volumes: [
+              { name: "secrets", projected: { defaultMode: 0o400, sources } },
+              {
+                name: "effector",
+                secret: {
+                  secretName: INSTANCE_EFFECTOR,
+                  defaultMode: 0o400,
+                  items: [
+                    { key: "key", path: "key" },
+                    { key: "effector.json", path: "effector.json" },
+                  ],
+                },
+              },
+              { name: "scratch", emptyDir: {} },
+              ...(opts.caBundle ? [{ name: "ca", configMap: { name: CA_CONFIGMAP } }] : []),
+            ],
+          },
+        },
+      },
+    },
+    {
+      apiVersion: "v1",
+      kind: "Service",
+      metadata: meta(),
+      spec: {
+        clusterIP: "None",
+        // A stopping replica still answers for the Effects it finishes: its address stays listed.
+        publishNotReadyAddresses: true,
+        selector: { app: INSTANCE_EFFECTOR },
+        ports: [{ port: EFFECTOR_PORT, targetPort: EFFECTOR_PORT }],
+      },
+    },
+    {
+      apiVersion: "networking.k8s.io/v1",
+      kind: "NetworkPolicy",
+      metadata: meta(),
+      spec: {
+        podSelector: { matchLabels: { app: INSTANCE_EFFECTOR } },
+        policyTypes: ["Ingress"],
+        ingress: [
+          { from: [{ podSelector: { matchLabels: { app: ORCHESTRATOR_SERVICE, [LABEL_INSTANCE]: opts.name } } }] },
+        ],
+      },
+    },
+  ];
   return JSON.stringify({ apiVersion: "v1", kind: "List", items });
 }
+
+/** A keyed digest of one key's value in the user's Secret, as the API returns it (base64): what a
+ * template digest holds for a `valueFrom`, so an edit of the value rolls the pod and the annotation
+ * reveals nothing about it. `jr2 up` keeps the digest, never the value. */
+export function storedValueDigest(signingKey: Buffer, secret: string, key: string, base64: string): string {
+  return createHmac("sha256", signingKey)
+    .update(`jr2-secret-value\n${secret}\n${key}\n`)
+    .update(Buffer.from(base64, "base64"))
+    .digest("base64url");
+}
+
+/** The digest of each `valueFrom` value, by the user's Secret and key; undefined when not read. */
+export type ValueDigest = (secret: string, key: string) => string | undefined;
+
+/** The Instance Effector's template digest: an HMAC over every secret input — a literal's value, a
+ * `valueFrom`'s reference and the digest of its value — keyed with the signing key so the
+ * annotation reveals nothing about a value. */
+export function effectorDigest(signingKey: Buffer, plan: EffectorPlan, key: string, valueDigest: ValueDigest): string {
+  const mac = createHmac("sha256", signingKey);
+  mac.update(JSON.stringify({ secrets: plan.secrets, targets: plan.targets, longest: plan.longestTimeoutMs }));
+  for (const name of Object.keys(plan.values).sort()) mac.update(`${name}=${plan.values[name]}`);
+  for (const s of plan.secrets) {
+    if (s.source.kind === "secret") mac.update(`${s.name}<-${valueDigest(s.source.secret, s.source.key) ?? ""}`);
+  }
+  mac.update(key);
+  return mac.digest("base64url").slice(0, 32);
+}