@jr2/cli 0.5.1 → 0.7.0

package/src/deploy.ts

@@ -3,10 +3,15 @@
 // 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 { createHash, createHmac, randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import {
+  CALLER_DIGESTS_KEY,
+  CALLER_DIGESTS_MOUNT,
+  CALLER_DIGESTS_SECRET,
+  callerTokenDigest,
+  callerTokenSecret,
   CA_CONFIGMAP,
   CA_MOUNT,
   EFFECTOR_PORT,
@@ -19,6 +24,14 @@ import {
   CUSTODIAN_PROGRAM,
   CUSTODIAN_PROGRAM_KEY,
   CUSTODIAN_SCRIPT_KEY,
+  CREDENTIAL_KEYS,
+  controlStandIn,
+  controlToken,
+  heldStandIn,
+  heldStandInKey,
+  HOOK_DIGESTS_KEY,
+  HOOK_DIGESTS_MOUNT,
+  HOOK_DIGESTS_SECRET,
   INSTANCE_CUSTODIAN_CONFIGMAP,
   GIT_SSH_SECRET,
   HELD_CA_SECRET,
@@ -47,6 +60,8 @@ import {
   REPO_CACHE_HOSTPATH,
   SERVICE_ACCOUNT_CA,
   STATE_PVC,
+  STATE_VOLUME_DEFAULT,
+  memoryBytes,
   type EffectorPlan,
   type SandboxEffectorPlan,
   effectorManifestKey,
@@ -59,7 +74,11 @@ import {
   type GitCloneSecret,
   type GitPushManifest,
   type HarnessConfig,
+  type JR2Config,
+  isStdioServer,
+  mcpTimeoutMs,
   type HeldManifest,
+  markHarnessEnv,
   type PriorityClasses,
   type SandboxPlacement,
 } from "@jr2/orchestrator/internal";
@@ -86,13 +105,122 @@ export const ANNOTATION_IMAGES = "jr2.dev/images";
 
 export const ORCHESTRATOR_SA = "jr2-orchestrator";
 
+/** The label on each named Caller token's Secret (ADR-0078), with the token's name as its value.
+ * `jr2 up` finds the Secrets of the names that the config no longer declares by it, and
+ * `jr2 caller rotate` finds every value whose digest the Orchestrator reads. */
+export const LABEL_CALLER_TOKEN = "jr2.dev/caller-token";
+
+/** The key of a named Caller token's value in its Secret (`callerTokenSecret`). */
+export const CALLER_TOKEN_KEY = "token";
+
+/**
+ * The `jr2-caller-digests` file (ADR-0078): one JSON object from each named Caller token's name to
+ * the sha-256 of its value, in hex, names in order. The Orchestrator reads it through a mount, and
+ * never a value.
+ */
+export function callerDigestsJson(values: Readonly<Record<string, string>>): string {
+  const names = Object.keys(values).sort();
+  return JSON.stringify(Object.fromEntries(names.map((n) => [n, callerTokenDigest(values[n]!)])));
+}
+
+/**
+ * The Secrets of the named Caller tokens (ADR-0078): one per name, which holds its value and which
+ * no pod mounts (`jr2 caller token` reads it over the kube API), and `jr2-caller-digests`, which
+ * the Orchestrator mounts. The digests Secret is applied always, empty with no token, so the
+ * mount always has its Secret.
+ */
+export function callerTokenObjects(
+  values: Readonly<Record<string, string>>,
+  meta: (name: string, extra?: Record<string, string>) => KubeManifest,
+): KubeManifest[] {
+  return [
+    ...Object.keys(values)
+      .sort()
+      .map(
+        (name): KubeManifest => ({
+          apiVersion: "v1",
+          kind: "Secret",
+          metadata: meta(callerTokenSecret(name), { [LABEL_CALLER_TOKEN]: name }),
+          type: "Opaque",
+          stringData: { [CALLER_TOKEN_KEY]: values[name]! },
+        }),
+      ),
+    {
+      apiVersion: "v1",
+      kind: "Secret",
+      metadata: meta(CALLER_DIGESTS_SECRET),
+      type: "Opaque",
+      stringData: { [CALLER_DIGESTS_KEY]: callerDigestsJson(values) },
+    },
+  ];
+}
+
+/**
+ * `jr2-hook-digests` (ADR-0078): one JSON object from the secret name of each Hook whose verifier is
+ * `token` to the sha-256 of its value, in hex, names in order. The Orchestrator mounts it, reads it
+ * again when it changes, and never holds a value. Applied always, empty with no `token` Hook, so the
+ * mount always has its Secret.
+ */
+export function hookDigestsObject(
+  digests: Readonly<Record<string, string>>,
+  meta: (name: string) => KubeManifest,
+): KubeManifest {
+  const names = Object.keys(digests).sort();
+  return {
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: meta(HOOK_DIGESTS_SECRET),
+    type: "Opaque",
+    stringData: { [HOOK_DIGESTS_KEY]: JSON.stringify(Object.fromEntries(names.map((n) => [n, digests[n]!]))) },
+  };
+}
+
 /** 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 digest of the `jr2-harness` ConfigMap's text (`harnessConfigJson`), on the Instance
+ * Harness's pod template: the Harness reads the text once, at start, so an edit to the custom
+ * provider, a gateway or an MCP server (ADR-0079) rolls the pod. The text holds no value, so the
+ * digest is not keyed. */
+export const ANNOTATION_HARNESS_CONFIG_DIGEST = "jr2.dev/harness-config-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;
 
+/**
+ * The Instance Harness's credentials Secret (ADR-0076, ADR-0059): what a Sandbox's `<sandbox>-token`
+ * is to a Sandbox. It holds the pod's control token (`controlToken`, for the placement's name), its
+ * secret control Stand-in and one secret Stand-in per held secret of the pod, under
+ * `CREDENTIAL_KEYS` and `heldStandInKey`. `jr2 up` mints it, as the pod's maker. The Custodian
+ * mounts the token and the Stand-ins; the Harness container mounts the Stand-ins alone, as files
+ * under `/run/jr2/` (`custodianComposition`). A Secret of its own, never `jr2-instance`: the
+ * Instance token and the signing key share no Secret with anything the Harness container mounts.
+ */
+export const INSTANCE_HARNESS_CREDENTIALS = `${INSTANCE_HARNESS_SERVICE}-token`;
+
+/**
+ * One pod's credentials Secret data (ADR-0076, ADR-0059), minted by `jr2 up` as that pod's maker:
+ * the control token, the secret control Stand-in, and one secret Stand-in per held secret of
+ * `manifest` (`heldStandIn`, under the pod key `heldPod`). The Instance Harness's control token is
+ * signed for the placement's name, so it speaks only for the Turns hosted there; a check pod's
+ * (`controlToken: "unsigned"`) is a value the Orchestrator never signed — it reads no Menu
+ * (ADR-0019). No pod here serves a fetch, so neither holds a fetch token. Never logged: the values
+ * reach a Secret and nothing else.
+ */
+export function podCredentials(
+  key: Buffer,
+  opts: { placement: string; heldPod: string; manifest: HeldManifest; controlToken?: "signed" | "unsigned" },
+): Record<string, string> {
+  const data: Record<string, string> = {
+    [CREDENTIAL_KEYS.controlToken]:
+      opts.controlToken === "unsigned" ? randomBytes(24).toString("hex") : controlToken(key, opts.placement),
+    [CREDENTIAL_KEYS.controlStandIn]: controlStandIn(key, opts.placement),
+  };
+  for (const s of opts.manifest.secrets) data[heldStandInKey(s.name)] = heldStandIn(key, opts.heldPod, s.name);
+  return data;
+}
+
 /** 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. */
@@ -110,6 +238,48 @@ 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";
+/** The two egress NetworkPolicies (ADR-0076) — see `metadataEgress`. */
+export const SANDBOX_EGRESS_POLICY = "jr2-sandbox-egress";
+export const INSTANCE_HARNESS_EGRESS_POLICY = "jr2-instance-harness-egress";
+
+/**
+ * The cloud metadata addresses that a Harness pod does not reach (ADR-0076): where a node's
+ * metadata service answers pods, it gives the node's own cloud credential, which no `workspace()`
+ * grants. AWS's IMDS (IPv4 and IPv6), ECS's and EKS Pod Identity's credential agents, the
+ * metadata service of GCP and Azure (the same 169.254.169.254), and Alibaba's. Each is a single
+ * address: all of 169.254.0.0/16 would cut NodeLocal DNSCache (169.254.20.10). The list is not
+ * complete for every provider, so the shared-cluster guide tells the admin to check theirs.
+ */
+export const METADATA_ADDRESSES_V4 = [
+  "169.254.169.254/32",
+  "169.254.170.2/32",
+  "169.254.170.23/32",
+  "100.100.100.200/32",
+] as const;
+export const METADATA_ADDRESSES_V6 = ["fd00:ec2::254/128"] as const;
+
+/**
+ * The egress of a Harness pod (ADR-0076): everything, except the cloud metadata addresses.
+ * NetworkPolicy has no deny rule, so the rule allows every address but those, and every pod of the
+ * cluster as a peer of its own. A CNI that matches an `ipBlock` against a pod's address too (Cilium)
+ * would otherwise cut DNS, the Orchestrator and each Service. The policy needs a CNI that enforces
+ * NetworkPolicy; on one that does not, nothing is blocked.
+ */
+export function metadataEgress(podSelector: Record<string, unknown>): Record<string, unknown> {
+  return {
+    podSelector,
+    policyTypes: ["Egress"],
+    egress: [
+      {
+        to: [
+          { ipBlock: { cidr: "0.0.0.0/0", except: [...METADATA_ADDRESSES_V4] } },
+          { ipBlock: { cidr: "::/0", except: [...METADATA_ADDRESSES_V6] } },
+          { namespaceSelector: {} },
+        ],
+      },
+    ],
+  };
+}
 
 /** The operator's install location — per-cluster, shared by every instance (ADR-0019). */
 export const OPERATOR_NAMESPACE = "jr2-system";
@@ -265,21 +435,77 @@ export type HeldObjects = {
 /** Does any pod hold a secret? */
 export const holdsAny = (held: HeldObjects): boolean => held.pods.some((p) => p.manifest.secrets.length > 0);
 
+/** What `jr2 up` does with the state volume claim (ADR-0065): the size to apply and the one line
+ * that says what changed, or the refusal's text. */
+export type StateVolumePlan = { size: string; line?: string } | { refused: string };
+
+/**
+ * The size of the Orchestrator's state volume claim (ADR-0065). `configured` is `runs.volume`;
+ * `claim` the claim that exists, with its StorageClass and whether the class allows expansion
+ * (`undefined` when `jr2 up` did not read it). A new claim takes `runs.volume` or the default. A
+ * claim that exists keeps its size when the config sets none, grows when the config sets a larger
+ * size on a class that expands, and refuses a smaller size, or a larger one on a class that does
+ * not expand: Kubernetes never makes a claim smaller, and grows it only where the class allows.
+ */
+export function stateVolumePlan(
+  configured: string | undefined,
+  claim?: { size: string; storageClass?: string; expandable?: boolean },
+): StateVolumePlan {
+  if (!claim) return { size: configured ?? STATE_VOLUME_DEFAULT };
+  if (configured === undefined) {
+    if (memoryBytes(claim.size) === memoryBytes(STATE_VOLUME_DEFAULT)) return { size: claim.size };
+    return {
+      size: claim.size,
+      line: `state volume: keeping the claim ${STATE_PVC} at ${claim.size} — runs.volume is not set, and the default ${STATE_VOLUME_DEFAULT} is for a new claim`,
+    };
+  }
+  const want = memoryBytes(configured);
+  const have = memoryBytes(claim.size);
+  if (want === have) return { size: claim.size };
+  if (want < have) {
+    return {
+      refused:
+        `runs.volume is ${configured}, smaller than the state volume claim ${STATE_PVC} (${claim.size}) — Kubernetes never ` +
+        `makes a claim smaller. Set runs.volume to ${claim.size} or more (ADR-0065)`,
+    };
+  }
+  const named = claim.storageClass ? `StorageClass "${claim.storageClass}"` : "claim's StorageClass";
+  if (claim.expandable !== true) {
+    return {
+      refused:
+        `runs.volume is ${configured}, larger than the state volume claim ${STATE_PVC} (${claim.size}), and its ${named} ` +
+        `does not allow expansion (allowVolumeExpansion is not true). Keep runs.volume at ${claim.size}, or use a ` +
+        `StorageClass that allows expansion (ADR-0065)`,
+    };
+  }
+  return { size: configured, line: `state volume: growing the claim ${STATE_PVC} from ${claim.size} to ${configured}` };
+}
+
 /** Everything `jr2 up` converges inside the instance's namespace, as one apply-able List. */
 export function instanceObjects(opts: {
   name: string;
   namespace: string;
+  /** The size of the state volume claim (`stateVolumePlan`, ADR-0065). Default: `5Gi`. */
+  stateVolume?: 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;
   /** 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 values of the named Caller tokens, by name (ADR-0078): each goes into a Secret of its own,
+   * and the Orchestrator mounts only their digests (`callerTokenObjects`). Absent: none. */
+  callerTokens?: Readonly<Record<string, string>>;
+  /** The sha-256 digests of the `token` Hooks' secrets, by secret name (ADR-0078): the Orchestrator
+   * mounts them in `jr2-hook-digests` (`hookDigestsObject`). Absent: none. */
+  hookDigests?: Readonly<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
    * key must never share a Secret with it, and no model key rides it either (ADR-0059). */
   harnessEnvData: Record<string, string>;
   harness?: HarnessConfig;
+  /** The config's `mcp` block (ADR-0079), for the `jr2-harness` ConfigMap. */
+  mcp?: JR2Config["mcp"];
   /** 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;
@@ -323,7 +549,7 @@ export function instanceObjects(opts: {
       metadata: meta(STATE_PVC),
       spec: {
         accessModes: ["ReadWriteOnce"],
-        resources: { requests: { storage: "1Gi" } },
+        resources: { requests: { storage: opts.stateVolume ?? STATE_VOLUME_DEFAULT } },
       },
     },
     { apiVersion: "v1", kind: "ServiceAccount", metadata: meta(ORCHESTRATOR_SA) },
@@ -368,7 +594,7 @@ export function instanceObjects(opts: {
       kind: "ConfigMap",
       metadata: meta(HARNESS_CONFIGMAP),
       data: {
-        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness),
+        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness, opts.mcp),
       },
     },
     {
@@ -460,6 +686,13 @@ export function instanceObjects(opts: {
       type: "Opaque",
       stringData: opts.secretData,
     },
+    // The named Caller tokens (ADR-0078): a value in a Secret of its own, and the digests in the
+    // one Secret the Orchestrator mounts below. Not in `jr2-instance`: that one is `envFrom`, which
+    // a running pod reads once, and a new token or a rotation must roll no pod.
+    ...callerTokenObjects(opts.callerTokens ?? {}, meta),
+    // The `token` Hooks' digests (ADR-0078): a Secret of their own, as the door reads them, and
+    // never `jr2-caller-digests`, which `jr2 caller rotate` writes whole. Never a value.
+    hookDigestsObject(opts.hookDigests ?? {}, meta),
     {
       // What the HARNESS containers envFrom (see `harnessEnvData` above): Agent creds, never the
       // Instance token. Always applied (possibly empty) so the Sandbox spec can reference it
@@ -513,6 +746,9 @@ export function instanceObjects(opts: {
                   // 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 claim's size as this converge applied it (ADR-0065): the space guard
+                  // measures against it, because a hostPath class's `statfs` gives the node's disk.
+                  { name: "JR2_STATE_VOLUME", value: opts.stateVolume ?? STATE_VOLUME_DEFAULT },
                 ],
                 // 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`
@@ -527,6 +763,13 @@ export function instanceObjects(opts: {
                   // (ADR-0059): names and hosts, which this process could not derive — its `.env`
                   // values are absent.
                   { name: "held", mountPath: HELD_MOUNT, readOnly: true },
+                  // The digests of the named Caller tokens (ADR-0078), read again when they
+                  // change: a new token or a rotation costs one kubelet propagation window, about
+                  // a minute, and no rollout. Never a value.
+                  { name: "callers", mountPath: CALLER_DIGESTS_MOUNT, readOnly: true },
+                  // The digests of the `token` Hooks' secrets (ADR-0078), read again in the same
+                  // way: a new or changed secret costs one kubelet propagation window. Never a value.
+                  { name: "hooks", mountPath: HOOK_DIGESTS_MOUNT, readOnly: true },
                 ],
                 resources: sized(KIT_POD_SIZES.orchestrator),
                 // The period, not the boot, is what `up`'s rollout wait measures. Measured: the
@@ -564,6 +807,8 @@ export function instanceObjects(opts: {
               { name: "state", persistentVolumeClaim: { claimName: STATE_PVC } },
               { name: "images", configMap: { name: IMAGES_CONFIGMAP } },
               { name: "held", configMap: { name: HELD_CONFIGMAP } },
+              { name: "callers", secret: { secretName: CALLER_DIGESTS_SECRET } },
+              { name: "hooks", secret: { secretName: HOOK_DIGESTS_SECRET } },
             ],
           },
         },
@@ -579,6 +824,7 @@ export function instanceObjects(opts: {
       },
     },
     ...harnessIngressPolicies(opts.name, meta),
+    ...harnessEgressPolicies(meta),
     ...(opts.repoCache
       ? repoCacheObjects({
           ...opts.repoCache,
@@ -610,7 +856,7 @@ const SANDBOX_POD_LABEL = "sandbox.jr2.dev/name";
  *
  * - 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 egress. That is `harnessEgressPolicies`: open, except the cloud metadata addresses (ADR-0076).
  * - 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
  *   Container — ADR-0005) and kubelet probes never cross a policy at all.
@@ -631,6 +877,26 @@ function harnessIngressPolicies(instance: string, meta: (name: string) => KubeMa
   ];
 }
 
+/**
+ * No Harness pod reaches a cloud metadata address (ADR-0076, `metadataEgress`). A Sandbox runs
+ * Workspace code, and the node's credential is one that no `workspace()` grants. The Instance
+ * Harness runs no Workspace code, but it gets the same rule: a check pod of the provider preflight
+ * stands for every Harness pod (ADR-0019), so a model that only the node's credential reaches must
+ * fail the check, not a Turn. Converged unconditionally, for the reason the ingress policies are.
+ */
+function harnessEgressPolicies(meta: (name: string) => KubeManifest): KubeManifest[] {
+  const policy = (name: string, podSelector: Record<string, unknown>): KubeManifest => ({
+    apiVersion: "networking.k8s.io/v1",
+    kind: "NetworkPolicy",
+    metadata: meta(name),
+    spec: metadataEgress(podSelector),
+  });
+  return [
+    policy(SANDBOX_EGRESS_POLICY, { matchExpressions: [{ key: SANDBOX_POD_LABEL, operator: "Exists" }] }),
+    policy(INSTANCE_HARNESS_EGRESS_POLICY, { matchLabels: { app: INSTANCE_HARNESS_SERVICE } }),
+  ];
+}
+
 /** Where the cache agent's pod sees the node's directory: `--cache-dir`'s default. */
 const REPO_CACHE_MOUNT = "/cache";
 /** The agent's `$HOME` — an emptyDir, where it writes a deploy key for the life of the pod. */
@@ -651,6 +917,10 @@ const REPO_CACHE_HOME = "/home/jr2";
  * (ADR-0052), so an agent lands on exactly the nodes a Sandbox can be placed on. The ServiceAccount token IS mounted: the agent is a client of the Repo resources and
  * of the pods on its node (never of Sandboxes — demand is a pod's mount), unlike a Sandbox, whose
  * north star is never reaching the API.
+ *
+ * Because it lands on exactly the Sandbox nodes, it is also the Landlock detector (ADR-0077): it
+ * probes at start and, on a node without Landlock, exits with the reason, and `jr2 up` refuses to
+ * converge (`landlock.ts`).
  */
 function repoCacheObjects(opts: {
   image: string;
@@ -713,6 +983,11 @@ function repoCacheObjects(opts: {
                 image,
                 imagePullPolicy: "IfNotPresent",
                 command: ["/manager", "repo-cache"],
+                // On a node without Landlock the agent exits at start with a message that names
+                // Landlock, the node and the reason (ADR-0077). The kubelet keeps it in the
+                // container's status, where `jr2 up` reads it; the log line serves if the file
+                // write fails.
+                terminationMessagePolicy: "FallbackToLogsOnError",
                 env: [
                   // The downward API names the node this pod is the writer for, and the namespace
                   // whose Repos and pods it watches (the agent's `--node` / `--namespace`).
@@ -844,7 +1119,8 @@ export function instanceHarnessObjects(opts: {
    * Agent cannot execute code — forking the path for one pod buys a divergence ADR-0031 declines. */
   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. */
+   * keys its `"none"` Agents' providers read and the secrets of the remote MCP servers they name
+   * (ADR-0079), 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). */
@@ -853,7 +1129,13 @@ export function instanceHarnessObjects(opts: {
    * 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;
+  /** The pod's credentials Secret data (`podCredentials`): its control token and its secret
+   * Stand-ins, applied here as {@link INSTANCE_HARNESS_CREDENTIALS} with the pod they are for. */
+  credentials: Record<string, string>;
   harness?: HarnessConfig;
+  /** The config's `mcp` block (ADR-0079): with `harness`, the text of the `jr2-harness` ConfigMap,
+   * whose digest is on the pod template. */
+  mcp?: JR2Config["mcp"];
   /** The instance ships a private-CA bundle (ADR-0020). */
   caBundle?: boolean;
   /** The digest of this placement's Harness bearer (ADR-0058; `harnessTokenDigest(key,
@@ -880,15 +1162,16 @@ 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.
+  // The Custodian (ADR-0013, ADR-0059, ADR-0076): the placement's control token — signed for this
+  // placement's name, so it speaks only for the Turns hosted HERE (tokens.ts) — and the held secrets
+  // placed here, from the pod's own credentials Secret (`podCredentials`). The tokens are mounted
+  // into the Custodian alone, the Stand-ins into the Custodian and, as files, the Harness; the
+  // Instance token itself never enters this pod. The pod serves no fetch: no Repo is mounted here.
   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" },
+    credentials: { secret: INSTANCE_HARNESS_CREDENTIALS },
     caBundle: opts.caBundle === true,
     resources: sized(KIT_POD_SIZES.instanceCustodian),
   });
@@ -901,24 +1184,28 @@ export function instanceHarnessObjects(opts: {
     // 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",
-        valueFrom: { configMapKeyRef: { name: HARNESS_CONFIGMAP, key: HARNESS_CONFIG_KEY } },
-      },
-      // The placement gate (ADR-0031): every admission carries its own definition (ADR-0049), so
-      // the Harness itself refuses any admission whose definition declares Workspace access —
-      // Menu-only Agents alone run here, which is what makes "no code execution in this pod" true
-      // 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),
-      ...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 ?? [])],
+    // Marked (ADR-0076, `harness-env.ts`): the stock image's command starts the Harness with
+    // `effector nocore --harness-env`, which gives the Harness process jr2's names alone.
+    ...markHarnessEnv(
+      [
+        {
+          name: "JR2_HARNESS_JSON",
+          valueFrom: { configMapKeyRef: { name: HARNESS_CONFIGMAP, key: HARNESS_CONFIG_KEY } },
+        },
+        // The placement gate (ADR-0031): every admission carries its own definition (ADR-0049), so
+        // the Harness itself refuses any admission whose definition declares Workspace access —
+        // Menu-only Agents alone run here, which is what makes "no code execution in this pod" true
+        // 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),
+        ...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 },
+      ],
+      [{ secretRef: { name: HARNESS_ENV_SECRET } }, ...(opts.harness?.envFrom ?? [])],
+    ),
     // 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.
@@ -938,6 +1225,14 @@ export function instanceHarnessObjects(opts: {
   };
 
   const items: KubeManifest[] = [
+    // The pod's credentials (ADR-0076): a Secret, never a ConfigMap, env or the pod template.
+    {
+      apiVersion: "v1",
+      kind: "Secret",
+      metadata: { ...meta(), name: INSTANCE_HARNESS_CREDENTIALS },
+      type: "Opaque",
+      stringData: opts.credentials,
+    },
     // 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`.
     {
@@ -982,7 +1277,16 @@ export function instanceHarnessObjects(opts: {
             // 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 },
+            // The same for the `jr2-harness` text, which the Harness reads once at start: a server
+            // added to `mcp`, or a url, an argv or a timeout changed, reaches the pod (ADR-0079).
+            annotations: {
+              [ANNOTATION_HELD_DIGEST]: opts.heldDigest,
+              [ANNOTATION_HARNESS_CONFIG_DIGEST]: createHash("sha256")
+                .update(harnessConfigJson(opts.harness, opts.mcp))
+                .digest("base64url")
+                .slice(0, 32),
+              ...NO_DISRUPT_ANNOTATIONS,
+            },
           },
           spec: {
             // The drain (ADR-0031): on SIGTERM the Harness stops admitting and finishes the Turns
@@ -1044,9 +1348,10 @@ export function instanceHarnessObjects(opts: {
 }
 
 /** 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 {
+ * Harness container: the custom provider without its key, the catalog gateways, and the MCP servers
+ * (ADR-0079) — a remote one's url and the NAME of its secret, never a value. The check pod carries
+ * the same text in its own ConfigMap (ADR-0019). */
+export function harnessConfigJson(harness: HarnessConfig | undefined, mcp?: JR2Config["mcp"]): string {
   return JSON.stringify(
     {
       // apiKey is deliberately dropped: it is a held secret (ADR-0059) — the Custodian holds
@@ -1065,12 +1370,35 @@ export function harnessConfigJson(harness: HarnessConfig | undefined): string {
         : undefined,
       // Where pi's catalog providers send their calls (ADR-0059): endpoints, not keys.
       catalog: harness?.catalog,
+      // The MCP servers (ADR-0079), by the config's name: the Harness joins each Agent's `mcp` list
+      // to them. In-cluster the config has no `.env`, so the url rides from here, as baseUrl does.
+      mcp: mcp === undefined ? undefined : mcpSpecOf(mcp),
     },
     null,
     2,
   );
 }
 
+/** The `mcp` block as the Harness reads it (`McpServerSpec` in `@jr2/harness`): the timeout in
+ * milliseconds, and a stdio server's `args` always a list. */
+function mcpSpecOf(mcp: NonNullable<JR2Config["mcp"]>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(mcp).map(([name, server]) => {
+      const timeoutMs = mcpTimeoutMs(server.timeout);
+      return [
+        name,
+        isStdioServer(server)
+          ? { command: server.command, args: [...(server.args ?? [])], timeoutMs }
+          : { url: server.url, ...(server.secret !== undefined ? { secret: server.secret } : {}), timeoutMs },
+      ];
+    }),
+  );
+}
+
+/** The argv word of `provider-preflight.ts` before the MCP servers to list (`PREFLIGHT_MCP_ARG` in
+ * `@jr2/harness`'s `preflight-line.ts`, which a test holds this to). */
+export const PREFLIGHT_MCP_ARG = "--mcp";
+
 /** 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";
@@ -1084,6 +1412,7 @@ export const CHECK_CONTAINER = "check";
 export function checkPodObjectNames(object: string): Array<{ kind: string; name: string }> {
   return [
     { kind: "pod", name: object },
+    { kind: "networkpolicy", name: object },
     { kind: "configmap", name: object },
     { kind: "configmap", name: `${object}-ca` },
     { kind: "secret", name: object },
@@ -1100,8 +1429,9 @@ export function checkPodObjectNames(object: string): Array<{ kind: string; name:
  * - `<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
+ * - `<object>` (Secret): the Custodian's control token, a value the Orchestrator never signed (the
+ *   check pod reads no Menu), the check pod's own secret Stand-ins (`podCredentials`, ADR-0059), 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.
@@ -1112,6 +1442,9 @@ export function checkPodObjectNames(object: string): Array<{ kind: string; name:
  * 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.
  *
+ * - `<object>` (NetworkPolicy): the egress of a Harness pod (`metadataEgress`, ADR-0076), so the
+ *   check reaches a provider only as a Turn does. It is in the List before the pod.
+ *
  * 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
@@ -1136,11 +1469,18 @@ export function checkPodObjects(opts: {
   trust: Record<string, string>;
   /** The Custodian's two files, rendered from `held`. */
   custodian: CustodianFiles;
-  token: string;
+  /** The check pod's credentials (`podCredentials`, ADR-0076): a control token the Orchestrator
+   * never signed, and its own secret Stand-ins, minted for this pod alone. */
+  credentials: Record<string, string>;
   /** The literal `harness.env` values. */
   harnessEnvData: Record<string, string>;
   /** The `<provider>/<model>` specifiers to check, in order. */
   models: readonly string[];
+  /** The remote MCP servers whose tools to list, by the config's name, in order (ADR-0079). */
+  servers?: readonly string[];
+  /** The config's `mcp` block: the check pod's harness config carries it, as the Harness pods'
+   * does, so the check reads each server's url and secret name where a Turn reads them. */
+  mcp?: JR2Config["mcp"];
   /** The node predicate of the Harness pods this check pod stands for. */
   placement?: SandboxPlacement;
   priorityClassName: string;
@@ -1161,7 +1501,7 @@ export function checkPodObjects(opts: {
     pod: o,
     reads: { literals: o, tls: `${o}-tls`, trust: `${o}-ca`, program: o },
     config: o,
-    token: { secret: o, key: "token" },
+    credentials: { secret: o },
     caBundle: opts.caBundle === true,
     resources: sized(KIT_POD_SIZES.instanceCustodian),
   });
@@ -1203,12 +1543,19 @@ export function checkPodObjects(opts: {
             "/opt/jr2/bin/node",
             "/opt/jr2/src/provider-preflight.ts",
             ...opts.models,
+            ...(opts.servers?.length ? [PREFLIGHT_MCP_ARG, ...opts.servers] : []),
           ],
-          // The Harness container's env, in its order (`instanceHarnessObjects`): no credential.
+          // The Harness container's env, in its order (`instanceHarnessObjects`): no credential. And
+          // the check pod's own Stand-ins (ADR-0019): it runs no Workspace code, so it may hold them
+          // in env, where pi reads a provider's key; each is a `secretKeyRef`, never a value here.
           env: [
             { name: "JR2_HARNESS_JSON", valueFrom: { configMapKeyRef: { name: o, key: HARNESS_CONFIG_KEY } } },
             ...(opts.harness?.env ?? []).filter((v) => v.valueFrom !== undefined),
             ...custodian.harnessEnv,
+            ...opts.held.secrets.map((s) => ({
+              name: s.name,
+              valueFrom: { secretKeyRef: { name: o, key: heldStandInKey(s.name) } },
+            })),
           ],
           envFrom: [{ secretRef: { name: `${o}-env` } }, ...(opts.harness?.envFrom ?? [])],
           volumeMounts: custodian.harnessMounts,
@@ -1250,13 +1597,19 @@ export function checkPodObjects(opts: {
         [CUSTODIAN_BOOTSTRAP_KEY]: opts.custodian.bootstrap,
         [CUSTODIAN_SCRIPT_KEY]: opts.custodian.script,
         [CUSTODIAN_PROGRAM_KEY]: CUSTODIAN_PROGRAM,
-        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness),
+        [HARNESS_CONFIG_KEY]: harnessConfigJson(opts.harness, opts.mcp),
       },
     },
     { apiVersion: "v1", kind: "ConfigMap", metadata: meta(`${o}-ca`), data: opts.trust },
-    secret(o, { token: opts.token, ...literals }),
+    secret(o, { ...opts.credentials, ...literals }),
     secret(`${o}-tls`, leaves),
     secret(`${o}-env`, opts.harnessEnvData),
+    {
+      apiVersion: "networking.k8s.io/v1",
+      kind: "NetworkPolicy",
+      metadata: meta(o),
+      spec: metadataEgress({ matchLabels: { app: PROVIDER_PREFLIGHT, [LABEL_PROVIDER_PREFLIGHT]: opts.run } }),
+    },
     pod,
   ];
   return JSON.stringify({ apiVersion: "v1", kind: "List", items });
@@ -1307,7 +1660,8 @@ export const effectorGraceSeconds = (plan: EffectorPlan): number =>
 
 /**
  * The Instance Effector (ADR-0068): the objects `jr2 up` converges when a registered Machine
- * places an Effect there — an `http` Effect — and deletes otherwise.
+ * places an Effect there — an `http` Effect — or a Hook needs it (a `mac` verifier, or a kind that
+ * declares `posts`), 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
@@ -1358,7 +1712,13 @@ export function instanceEffectorObjects(opts: {
         : [],
     ),
   ];
-  const config = { version: 1, placement: opts.plan.placement, targets: opts.plan.targets };
+  // The servers its `mcp` Effects call (ADR-0079): each one's url, its secret's name, its timeout.
+  const config = {
+    version: 1,
+    placement: opts.plan.placement,
+    targets: opts.plan.targets,
+    ...(Object.keys(opts.plan.mcp).length ? { mcp: opts.plan.mcp } : {}),
+  };
 
   const container = {
     name: "effector",
@@ -1498,7 +1858,14 @@ export type ValueDigest = (secret: string, key: string) => string | undefined;
  * 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 }));
+  mac.update(
+    JSON.stringify({
+      secrets: plan.secrets,
+      targets: plan.targets,
+      longest: plan.longestTimeoutMs,
+      ...(Object.keys(plan.mcp).length ? { mcp: plan.mcp } : {}),
+    }),
+  );
   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) ?? ""}`);