@jr2/cli 0.3.0 → 0.5.1

package/src/deploy.ts

@@ -3,20 +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_KEY,
   HELD_MOUNT,
-  HELD_SECRETS_SECRET,
   HELD_TLS_SECRET,
+  heldManifestKey,
+  heldSecretsSecret,
+  INSTANCE_HARNESS_HELD_POD,
   HARNESS_ENV_SECRET,
   IMAGES_CONFIGMAP,
   IMAGES_KEY,
@@ -27,18 +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";
+} from "@jr2/orchestrator/internal";
 import type { Pem } from "./held-pki.ts";
 
 export {
+  INSTANCE_EFFECTOR,
   GIT_SSH_SECRET,
   HARNESS_CONFIGMAP,
   HARNESS_ENV_SECRET,
@@ -50,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
@@ -66,6 +93,20 @@ export const ANNOTATION_HELD_DIGEST = "jr2.dev/held-digest";
  * 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";
@@ -77,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. */
@@ -100,30 +149,131 @@ export function compareVersions(a: string, b: string): number {
 type KubeManifest = Record<string, unknown>;
 
 /**
- * What `jr2 up` resolved about held secrets (ADR-0059), ready to become objects. Values appear in
- * two places only: `values` (the literals, for the `jr2-held-secrets` Secret) and the CA's and the
- * leaves' keys — each lands in a Secret no Harness container mounts.
+ * 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 type HeldObjects = {
+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" } },
+  /** The provider preflight's check container (ADR-0019): one Node.js process, pi-ai, one call at a time. */
+  checkContainer: { requests: { cpu: "100m", memory: "512Mi" }, limits: { memory: "512Mi" } },
+} 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;
-  /** The literal values, by name — never in the manifest, never in a ConfigMap. */
+  /** 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, by file stem (`leafStem`). */
+  /** One leaf per bound target of any pod, by file stem (`leafStem`). */
   leaves: Record<string, Pem>;
-  /** The Custodian's rendered bootstrap (JSON) and script. */
-  bootstrap: string;
-  script: string;
 };
 
+/** 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' 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
@@ -145,8 +295,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,
@@ -167,21 +329,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"] },
       ],
     },
     {
@@ -200,28 +368,7 @@ export function instanceObjects(opts: {
       kind: "ConfigMap",
       metadata: meta(HARNESS_CONFIGMAP),
       data: {
-        [HARNESS_CONFIG_KEY]: JSON.stringify(
-          {
-            // 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,
-                  api: opts.harness.provider.api,
-                  baseUrl: opts.harness.provider.baseUrl,
-                  // Token limits are model properties, not credentials — they ride the ConfigMap
-                  // so the Harness can register the provider with them.
-                  contextWindow: opts.harness.provider.contextWindow,
-                  maxTokens: opts.harness.provider.maxTokens,
-                  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,
-        ),
+        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness),
       },
     },
     {
@@ -235,20 +382,77 @@ export function instanceObjects(opts: {
       metadata: meta(IMAGES_CONFIGMAP),
       data: { [IMAGES_KEY]: imagesJson },
     },
-    // Held secrets (ADR-0059). `held.json` is what every composition reads — the Orchestrator per
-    // provision from the mount below, `jr2 up` for the Instance Harness — beside the Custodian's
-    // bootstrap and script, which Envoy reads at start. Names, hosts, headers: never a value.
+    // 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: {
-        [HELD_KEY]: JSON.stringify(opts.held.manifest, null, 2),
-        [CUSTODIAN_BOOTSTRAP_KEY]: opts.held.bootstrap,
-        [CUSTODIAN_SCRIPT_KEY]: opts.held.script,
+        ...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",
@@ -270,7 +474,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
@@ -279,13 +483,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",
@@ -296,23 +509,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 the Custodian holds, read per provision the same way (ADR-0059): names
-                  // and hosts, which this process could not derive — its `.env` values are absent.
+                  // 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
@@ -321,7 +537,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.
@@ -331,12 +547,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, items: [{ key: HELD_KEY, path: HELD_KEY }] } },
+              { name: "held", configMap: { name: HELD_CONFIGMAP } },
             ],
           },
         },
@@ -352,7 +579,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 });
@@ -425,8 +660,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) },
     {
@@ -463,6 +700,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
@@ -487,7 +725,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,
@@ -513,20 +752,27 @@ function repoCacheObjects(opts: {
   ];
 }
 
+/** 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), the literal values and the leaves (the Custodian's alone).
- * `stringData` as written: no trailing newline is added to a value.
+ * 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 (held.manifest.secrets.length === 0 || !held.ca) return [];
-  const secret = (name: string, stringData: Record<string, string>): KubeManifest => ({
-    apiVersion: "v1",
-    kind: "Secret",
-    metadata: meta(name),
-    type: "Opaque",
-    stringData,
-  });
+  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;
@@ -534,7 +780,9 @@ function heldSecretObjects(held: HeldObjects, meta: (name: string) => KubeManife
   }
   return [
     secret(HELD_CA_SECRET, { "ca.crt": held.ca.cert, "ca.key": held.ca.key }),
-    ...(Object.keys(held.values).length ? [secret(HELD_SECRETS_SECRET, held.values)] : []),
+    ...held.pods.flatMap((p) =>
+      Object.keys(p.values).length ? [secret(heldSecretsSecret(p.pod), p.values, p.pod)] : [],
+    ),
     secret(HELD_TLS_SECRET, leaves),
   ];
 }
@@ -570,7 +818,7 @@ export function trustObject(opts: {
 }
 
 /**
- * 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 Custodian,
@@ -590,15 +838,18 @@ 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 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. */
   custodianImage: string;
-  /** What this converge resolved about held secrets (ADR-0059) — the same manifest the
-   * Orchestrator composes every Sandbox's Custodian from. */
+  /** 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;
-  /** An HMAC over every held-secret input (`held.json`, the leaves, the literal values, the
+  /** 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;
@@ -610,6 +861,8 @@ export function instanceHarnessObjects(opts: {
    * 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 => ({
@@ -629,12 +882,15 @@ export function instanceHarnessObjects(opts: {
 
   // 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 every held secret. Mounted into the Custodian alone; the Instance
-  // token itself never enters this pod.
+  // 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 = {
@@ -657,47 +913,90 @@ export function instanceHarnessObjects(opts: {
       { name: "JR2_MENU_ONLY", value: "1" },
       ...(opts.harness?.env ?? []).filter((v) => v.valueFrom !== undefined),
       ...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 ?? [])],
-    ...(custodian.harnessMounts.length ? { volumeMounts: custodian.harnessMounts } : {}),
+    // 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 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 },
             // A held-secret edit rolls this pod; a live Sandbox keeps what its Custodian read at
-            // start (ADR-0059, the ADR-0037 stance).
-            annotations: { [ANNOTATION_HELD_DIGEST]: opts.heldDigest },
+            // 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, custodian.custodianContainer],
+            // 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. No `shareProcessNamespace`: the Harness
@@ -719,6 +1018,22 @@ 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 }],
       },
@@ -727,3 +1042,467 @@ export function instanceHarnessObjects(opts: {
 
   return JSON.stringify({ apiVersion: "v1", kind: "List", items });
 }
+
+/** What the Instance can REACH (ADR-0018), as the `jr2-harness` ConfigMap carries it to every
+ * Harness container: the custom provider without its key and the catalog gateways. The check pod
+ * carries the same text in its own ConfigMap (ADR-0019). */
+export function harnessConfigJson(harness: HarnessConfig | undefined): string {
+  return JSON.stringify(
+    {
+      // 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: harness?.provider
+        ? {
+            id: harness.provider.id,
+            api: harness.provider.api,
+            baseUrl: harness.provider.baseUrl,
+            // Token limits are model properties, not credentials — they ride the ConfigMap
+            // so the Harness can register the provider with them.
+            contextWindow: harness.provider.contextWindow,
+            maxTokens: harness.provider.maxTokens,
+            models: harness.provider.models,
+          }
+        : undefined,
+      // Where pi's catalog providers send their calls (ADR-0059): endpoints, not keys.
+      catalog: harness?.catalog,
+    },
+    null,
+    2,
+  );
+}
+
+/** The provider preflight's objects (ADR-0019): a check pod and its own copies of what it reads,
+ * each named `jr2-provider-preflight-<run>-<n>` or that name and a suffix, unique to one `jr2 up`. */
+export const PROVIDER_PREFLIGHT = "jr2-provider-preflight";
+/** The label every one of them carries, its value the `jr2 up` run: how a later run finds the
+ * leftovers of a run that did not end, and leaves another run's objects alone. */
+export const LABEL_PROVIDER_PREFLIGHT = "jr2.dev/provider-preflight";
+/** The check container in that pod, whose output `jr2 up` reads. An older `jr2 up` named it `probe`. */
+export const CHECK_CONTAINER = "check";
+
+/** Every object of one check pod (`checkPodObjects`), for its deletion. */
+export function checkPodObjectNames(object: string): Array<{ kind: string; name: string }> {
+  return [
+    { kind: "pod", name: object },
+    { kind: "configmap", name: object },
+    { kind: "configmap", name: `${object}-ca` },
+    { kind: "secret", name: object },
+    { kind: "secret", name: `${object}-tls` },
+    { kind: "secret", name: `${object}-env` },
+  ];
+}
+
+/**
+ * One check pod of the provider preflight (ADR-0019, ADR-0059): a Harness pod with no Harness in
+ * it, and its own copies of every object a Harness pod reads. So a check pod writes nothing that a
+ * running pod of the Instance reads, and a check that fails leaves the Instance as it was.
+ *
+ * - `<object>` (ConfigMap): the Custodian's bootstrap and script, the program and the harness config
+ *   (`harnessConfigJson`).
+ * - `<object>-ca` (ConfigMap): the trust bundles, as `jr2-ca` would carry them.
+ * - `<object>` (Secret): the Custodian's token, a value the Orchestrator never signed (the check pod
+ *   reads no Menu), and the LITERAL values of the keys it holds, from the host. A `valueFrom` key
+ *   stays a reference to the user's Secret. The values are in this Secret for the check pod's life.
+ * - `<object>-tls` (Secret): the leaves of the bound hosts. `<object>-env` (Secret): the literal
+ *   `harness.env` values, which `jr2-harness-env` would carry.
+ *
+ * The Custodian is composed by the function every Harness pod's is (`custodianComposition`). With
+ * no binding, it holds nothing and the check pod's HTTPS goes direct, as in a Harness pod that holds no
+ * secret. The check container runs the stock Harness image's `provider-preflight.ts` with the Harness
+ * container's env, so the call is the one a Turn makes, and the key never enters that container,
+ * its argv or its log. The argv is the model specifiers alone.
+ *
+ * The pod has the placement and the priority class of the Harness pods it stands for (ADR-0052,
+ * ADR-0060). Its labels are its own and match no Harness pod's: the Instance Harness Service
+ * selects by label, and would send Turns to it. The Custodian is a native sidecar with a startup
+ * probe, so the check starts only once Envoy serves and the pod ends when the check does.
+ */
+export function checkPodObjects(opts: {
+  name: string;
+  namespace: string;
+  /** This check pod's object name (`jr2-provider-preflight-<run>-<n>`) and its run, for the label. */
+  object: string;
+  run: string;
+  /** The resolved stock Harness ref: the image a Turn's Harness runs, with pi-ai at the pin. */
+  harnessImage: string;
+  custodianImage: string;
+  /** The bindings of the keys this check pod holds: each a part of a held pod's manifest. */
+  held: HeldManifest;
+  /** The literal values of those keys, by name, from the host. */
+  values: Record<string, string>;
+  /** The leaves of their bound hosts, by file stem. */
+  leaves: Record<string, Pem>;
+  /** The trust bundles (`ca.crt`, `extra.crt`, `bundle.crt`, `upstream.crt`), as `jr2-ca` has them. */
+  trust: Record<string, string>;
+  /** The Custodian's two files, rendered from `held`. */
+  custodian: CustodianFiles;
+  token: string;
+  /** The literal `harness.env` values. */
+  harnessEnvData: Record<string, string>;
+  /** The `<provider>/<model>` specifiers to check, in order. */
+  models: readonly string[];
+  /** The node predicate of the Harness pods this check pod stands for. */
+  placement?: SandboxPlacement;
+  priorityClassName: string;
+  harness?: HarnessConfig;
+  caBundle?: boolean;
+  /** The pod's whole budget: the kubelet ends it at this deadline, even when `jr2 up` is gone. */
+  deadlineSeconds: number;
+}): string {
+  const labels = {
+    [LABEL_INSTANCE]: opts.name,
+    "app.kubernetes.io/managed-by": "jr2",
+    [LABEL_PROVIDER_PREFLIGHT]: opts.run,
+  };
+  const meta = (name: string) => ({ name, namespace: opts.namespace, labels });
+  const o = opts.object;
+  const custodian = custodianComposition(opts.held, {
+    image: opts.custodianImage,
+    pod: o,
+    reads: { literals: o, tls: `${o}-tls`, trust: `${o}-ca`, program: o },
+    config: o,
+    token: { secret: o, key: "token" },
+    caBundle: opts.caBundle === true,
+    resources: sized(KIT_POD_SIZES.instanceCustodian),
+  });
+  const ready = custodian.custodianContainer.readinessProbe as { httpGet: unknown };
+  const pod = {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { ...meta(o), labels: { ...labels, app: PROVIDER_PREFLIGHT } },
+    spec: {
+      restartPolicy: "Never",
+      activeDeadlineSeconds: opts.deadlineSeconds,
+      automountServiceAccountToken: false,
+      priorityClassName: opts.priorityClassName,
+      ...(opts.placement?.nodeSelector ? { nodeSelector: opts.placement.nodeSelector } : {}),
+      ...(opts.placement?.tolerations?.length ? { tolerations: opts.placement.tolerations } : {}),
+      // The Instance Harness pod's baseline, and its `fsGroup` for the same reason: the
+      // Custodian's values are group-readable, and Envoy runs as its own uid.
+      securityContext: {
+        runAsNonRoot: true,
+        seccompProfile: { type: "RuntimeDefault" },
+        fsGroup: INSTANCE_HARNESS_FS_GROUP,
+      },
+      initContainers: [
+        {
+          ...custodian.custodianContainer,
+          restartPolicy: "Always",
+          startupProbe: { httpGet: ready.httpGet, periodSeconds: 1, failureThreshold: 60 },
+        },
+      ],
+      containers: [
+        {
+          name: CHECK_CONTAINER,
+          image: opts.harnessImage,
+          imagePullPolicy: "IfNotPresent",
+          // Under tini, as the Harness runs (ADR-0061): PID 1 reaps, and forwards a stop.
+          command: [
+            "/opt/jr2/bin/tini",
+            "--",
+            "/opt/jr2/bin/node",
+            "/opt/jr2/src/provider-preflight.ts",
+            ...opts.models,
+          ],
+          // The Harness container's env, in its order (`instanceHarnessObjects`): no credential.
+          env: [
+            { name: "JR2_HARNESS_JSON", valueFrom: { configMapKeyRef: { name: o, key: HARNESS_CONFIG_KEY } } },
+            ...(opts.harness?.env ?? []).filter((v) => v.valueFrom !== undefined),
+            ...custodian.harnessEnv,
+          ],
+          envFrom: [{ secretRef: { name: `${o}-env` } }, ...(opts.harness?.envFrom ?? [])],
+          volumeMounts: custodian.harnessMounts,
+          resources: sized(KIT_POD_SIZES.checkContainer),
+          securityContext: {
+            runAsNonRoot: true,
+            allowPrivilegeEscalation: false,
+            capabilities: { drop: ["ALL"] },
+            seccompProfile: { type: "RuntimeDefault" },
+          },
+        },
+      ],
+      volumes: custodian.volumes,
+    },
+  };
+  const secret = (name: string, stringData: Record<string, string>): KubeManifest => ({
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: meta(name),
+    type: "Opaque",
+    stringData,
+  });
+  const leaves: Record<string, string> = {};
+  for (const stem of new Set(opts.held.secrets.flatMap((s) => s.hosts.map((h) => h.leaf)))) {
+    const pem = opts.leaves[stem];
+    if (!pem) throw new Error(`no leaf for a bound host of the provider preflight (${stem}) — a jr2 defect`);
+    leaves[`${stem}.crt`] = pem.cert;
+    leaves[`${stem}.key`] = pem.key;
+  }
+  const literals = Object.fromEntries(
+    opts.held.secrets.filter((s) => s.source.kind === "literal").map((s) => [s.name, opts.values[s.name] ?? ""]),
+  );
+  const items: KubeManifest[] = [
+    {
+      apiVersion: "v1",
+      kind: "ConfigMap",
+      metadata: meta(o),
+      data: {
+        [CUSTODIAN_BOOTSTRAP_KEY]: opts.custodian.bootstrap,
+        [CUSTODIAN_SCRIPT_KEY]: opts.custodian.script,
+        [CUSTODIAN_PROGRAM_KEY]: CUSTODIAN_PROGRAM,
+        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness),
+      },
+    },
+    { apiVersion: "v1", kind: "ConfigMap", metadata: meta(`${o}-ca`), data: opts.trust },
+    secret(o, { token: opts.token, ...literals }),
+    secret(`${o}-tls`, leaves),
+    secret(`${o}-env`, opts.harnessEnvData),
+    pod,
+  ];
+  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);
+}