@jr2/cli 0.4.1 → 0.6.0

package/src/commands/version.ts

@@ -13,17 +13,17 @@
 // A REPORT verb, not a result verb: the human table goes to stdout, `--json` swaps in the one object.
 
 import { basename } from "node:path";
-import { parseArgs } from "node:util";
-import { IMAGES_CONFIGMAP, IMAGES_KEY, INSTANCE_SECRET, loadConfig, type ImageRefs } from "@jr2/orchestrator";
+import { IMAGES_CONFIGMAP, IMAGES_KEY, INSTANCE_SECRET, loadConfig, type ImageRefs } from "@jr2/orchestrator/internal";
 import { detectKitCheckout, KIT_IMAGE_HOME } from "../build.ts";
 import type { InstanceIdentity } from "../client.ts";
 import { compareVersions, LABEL_VERSION, OPERATOR_DEPLOYMENT, OPERATOR_NAMESPACE } from "../deploy.ts";
 import { handedOffFrom } from "../handoff.ts";
-import { TARGET_ARGS, targetOptions, type TargetOptions } from "../instance.ts";
+import { targetOptions, type TargetOptions } from "../instance.ts";
 import { checkKitVersion, CLI_ROOT, CLI_VERSION } from "../kit-version.ts";
 import { kubectlAdmin, kubectlKube, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE, type KubeObject } from "../kube.ts";
 import { activity, result, type Io } from "../output.ts";
 import { findRoot } from "../root.ts";
+import { parseCommand } from "../command-table.ts";
 
 /** A package as the report names it: the number and the real path, so the path says WHICH copy. */
 export type Copy = { version: string; path: string };
@@ -79,12 +79,7 @@ export type VersionReport = {
 type Orchestrator = { version?: string; hash?: string; image?: string } | { error: string };
 
 export async function version(args: string[], io: Io): Promise<number> {
-  const { values } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: { ...TARGET_ARGS, local: { type: "boolean" }, json: { type: "boolean" } },
-  });
+  const { values } = parseCommand("version", args);
   const opts = targetOptions(values);
   const report = await versionReport(io, opts, { local: values.local === true });
   if (values.json === true) result(io, report);
@@ -258,7 +253,7 @@ const copy = (c: Copy): string => `${c.version.padEnd(8)} ${c.path}`;
 export function render(r: VersionReport): string {
   const rows: Row[] = [["cli", copy(r.cli)]];
   if (r.global) rows.push(["global", copy(r.global)]);
-  if (r.kit) rows.push(["kit", renderKit(r.kit)]);
+  if (r.kit) rows.push(["kit", renderKit(r.kit, r.cli)]);
   if (r.instance) {
     const i = r.instance;
     const mode = i.mode === "checkout" ? `kit checkout at ${i.kitCheckout}` : `installed kit → ${i.kitRegistry}`;
@@ -273,14 +268,15 @@ export function render(r: VersionReport): string {
   return rows.map(([label, value]) => (label ? `${`${label}:`.padEnd(width)}${value}` : "")).join("\n") + "\n";
 }
 
-function renderKit(k: NonNullable<VersionReport["kit"]>): string {
+function renderKit(k: NonNullable<VersionReport["kit"]>, cli: Copy): string {
   const pinned = k.pinned !== undefined ? `; package.json pins ${k.pinned} — reinstall` : "";
   if (k.check === "unresolved") return `not installed${pinned}`;
   const head = copy({ version: k.version!, path: k.path! });
   if (k.check === "ok") return `${head}  ok${pinned}`;
+  // The CLI's own number is named: one copy at another version is a mismatch too (ADR-0056).
   const against = k.against
-    ? `this jr2 runs against ${k.against.version} (${k.against.path})`
-    : "this jr2 has no @jr2/orchestrator beside it";
+    ? `this jr2 (${cli.version}) runs against ${k.against.version} (${k.against.path})`
+    : `this jr2 (${cli.version}) has no @jr2/orchestrator beside it`;
   return `${head}  MISMATCH — ${against}${pinned}`;
 }
 

package/src/deploy.ts

@@ -3,7 +3,7 @@
 // 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 { createHmac, randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import {
@@ -19,6 +19,11 @@ import {
   CUSTODIAN_PROGRAM,
   CUSTODIAN_PROGRAM_KEY,
   CUSTODIAN_SCRIPT_KEY,
+  CREDENTIAL_KEYS,
+  controlStandIn,
+  controlToken,
+  heldStandIn,
+  heldStandInKey,
   INSTANCE_CUSTODIAN_CONFIGMAP,
   GIT_SSH_SECRET,
   HELD_CA_SECRET,
@@ -60,9 +65,10 @@ import {
   type GitPushManifest,
   type HarnessConfig,
   type HeldManifest,
+  markHarnessEnv,
   type PriorityClasses,
   type SandboxPlacement,
-} from "@jr2/orchestrator";
+} from "@jr2/orchestrator/internal";
 import type { Pem } from "./held-pki.ts";
 
 export {
@@ -93,6 +99,39 @@ 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;
 
+/**
+ * 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 +149,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";
@@ -163,6 +244,8 @@ export const KIT_POD_SIZES = {
   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). */
@@ -366,28 +449,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),
       },
     },
     {
@@ -598,6 +660,7 @@ export function instanceObjects(opts: {
       },
     },
     ...harnessIngressPolicies(opts.name, meta),
+    ...harnessEgressPolicies(meta),
     ...(opts.repoCache
       ? repoCacheObjects({
           ...opts.repoCache,
@@ -629,7 +692,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.
@@ -650,6 +713,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. */
@@ -670,6 +753,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;
@@ -732,6 +819,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`).
@@ -872,6 +964,9 @@ 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 instance ships a private-CA bundle (ADR-0020). */
   caBundle?: boolean;
@@ -899,15 +994,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),
   });
@@ -920,24 +1016,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.
@@ -957,6 +1057,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`.
     {
@@ -1062,6 +1170,244 @@ 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: "networkpolicy", 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 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.
+ *
+ * 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.
+ *
+ * - `<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
+ * 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;
+  /** 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 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,
+    credentials: { secret: o },
+    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. 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,
+          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, { ...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 });
+}
+
 /** 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";

package/src/index.ts

@@ -14,3 +14,29 @@ export type { KubePort } from "./kube.ts";
 // test can issue its own fixtures the same way (the @kind tier's HTTPS model provider).
 export { issueCa, issueLeaf } from "./held-pki.ts";
 export type { Pem } from "./held-pki.ts";
+// The command table (ADR-0072): every verb as data, and the renderers `--help` prints with — what the
+// docs' CLI Reference is generated from, so the help and the site cannot disagree.
+export {
+  COMMANDS,
+  GLOBAL,
+  GLOBAL_OPTIONS,
+  HELP_FLAG,
+  SECTIONS,
+  EXIT_CODES,
+  nameOf,
+  synopsis,
+  renderHelp,
+  renderCommand,
+} from "./command-table.ts";
+export type {
+  Command,
+  CommandName,
+  Flag,
+  Arg,
+  EnvVar,
+  Form,
+  Output,
+  OutputKind,
+  GlobalOption,
+  Section,
+} from "./command-table.ts";