@jr2/cli 0.2.1 → 0.4.1

package/src/effector-image.ts

@@ -0,0 +1,133 @@
+// What a push owes the author's Effector image (ADR-0068). The Sandbox Effector runs in the
+// author's image — the Sandbox Image by default — and runs jr2's own programs from one fixed PATH
+// (`/usr/local/bin:/usr/bin:/bin`, never the image's own). So, per push form the Workspace holds,
+// `jr2 up` reads the image it built — or, for the stock Harness image, which the kit builds, knows
+// what it holds — and refuses, with the fix, an image that lacks what that form needs:
+//
+//   - ssh transport (`ssh://`, `git@`): `ssh`, and a passwd entry for the uid the Effector runs as —
+//     OpenSSH's client calls `getpwuid(getuid())` before any option, and exits "No user exists for
+//     uid N" without one;
+//   - ssh signing (`sign: { sshKey }`): `ssh-keygen` (`-Y sign` does no passwd lookup);
+//   - GPG signing (`sign: { gpgKey }`): `gpg` and `gpg-agent`;
+//   - a token over https: nothing beyond `git`, the Sandbox Image floor (the helper is jr2's binary).
+//
+// The uid is the image's: its `USER` line by name or number, else 1000 (ADR-0037's fallback).
+// `http` (a Worktree file body included) and the credentialed command owe nothing: the first is
+// Go, the last is the author's argv.
+
+/** Where the Effector looks for jr2's own programs: effector/internal/gitclean's Path. */
+export const EFFECTOR_TOOL_DIRS = ["/usr/local/bin", "/usr/bin", "/bin"] as const;
+
+/** One form a push of a Workspace takes, by what it owes its image. */
+export type PushForm = "ssh-transport" | "ssh-sign" | "gpg-sign";
+
+/** The programs each form needs, by name. */
+const TOOLS: Record<PushForm, readonly string[]> = {
+  "ssh-transport": ["ssh"],
+  "ssh-sign": ["ssh-keygen"],
+  "gpg-sign": ["gpg", "gpg-agent"],
+};
+
+/** What to install, by program: the package name on Debian and on Alpine, where they differ. */
+const PACKAGES: Record<string, string> = {
+  ssh: "openssh-client",
+  "ssh-keygen": "openssh-client (Alpine: openssh-keygen)",
+  gpg: "gnupg",
+  "gpg-agent": "gnupg",
+};
+
+/**
+ * What the stock Harness image holds of the forms' programs, and its /etc/passwd: the fallback
+ * Sandbox Image, which the Sandbox Effector runs in when the Workspace names no image and the
+ * instance has no `images/default`. The kit builds it (deploy/harness/Dockerfile, its last stage:
+ * `node:24-slim` with `git` and `ca-certificates`, `USER 1000`, node's uid), so `jr2 up` knows it in both worlds
+ * without reading it — a published one is never pulled to the host for this. A test holds the
+ * Dockerfile to it.
+ */
+export const STOCK_HARNESS_IMAGE = {
+  present: ["/usr/bin/git"],
+  passwd: "root:x:0:0:root:/root:/bin/bash\nnode:x:1000:1000::/home/node:/bin/bash\n",
+  user: "1000",
+} as const;
+
+/** Every path the forms' programs may be at: each program in each of the Effector's tool dirs. */
+export function effectorImagePaths(forms: readonly PushForm[]): string[] {
+  const out: string[] = [];
+  for (const form of new Set(forms)) {
+    for (const tool of TOOLS[form]) for (const dir of EFFECTOR_TOOL_DIRS) out.push(`${dir}/${tool}`);
+  }
+  return out;
+}
+
+/** The uid the Effector runs as, from the image's recorded `USER`: a name, a number, or — none
+ * declared — ADR-0037's 1000. A `user:group` line decides by its user half. */
+export function effectorSeat(user: string): { name: string } | { uid: number } {
+  const head = user.split(":")[0]!.trim();
+  if (head === "") return { uid: 1000 };
+  if (/^\d+$/.test(head)) return { uid: Number(head) };
+  return { name: head };
+}
+
+/** Whether /etc/passwd's text holds an entry for the seat. */
+export function passwdHolds(passwd: string, seat: { name: string } | { uid: number }): boolean {
+  for (const line of passwd.split("\n")) {
+    const fields = line.split(":");
+    if (fields.length < 3) continue;
+    if ("name" in seat ? fields[0] === seat.name : fields[2] === String(seat.uid)) return true;
+  }
+  return false;
+}
+
+/**
+ * Why the image cannot run the forms, with the fix, or undefined. `present` is which of
+ * {@link effectorImagePaths} the image holds (links followed); `passwd` its `/etc/passwd`, "" when
+ * it has none; `user` its recorded `USER`.
+ */
+export function effectorImageRefusal(input: {
+  /** For the message: `Workspace of workflow "w"`. */
+  label: string;
+  ref: string;
+  user: string;
+  /** Each form, and the push it is for: `the push of Repo Slot "app"`. */
+  forms: ReadonlyArray<{ form: PushForm; push: string }>;
+  present: ReadonlySet<string>;
+  passwd: string;
+  /** The image is the stock Harness image: the fix is an image of the author's, not an install. */
+  stock?: boolean;
+}): string | undefined {
+  const { label, ref } = input;
+  for (const { form, push } of input.forms) {
+    for (const tool of TOOLS[form]) {
+      if (EFFECTOR_TOOL_DIRS.some((dir) => input.present.has(`${dir}/${tool}`))) continue;
+      const why =
+        form === "ssh-transport" ? "over ssh" : form === "ssh-sign" ? "signed with an ssh key" : "signed with GPG";
+      if (input.stock) {
+        return (
+          `${label}: ${push} ${why} needs ${tool}, and its Sandbox Effector runs in the stock Harness image ${ref}, ` +
+          `which holds git alone — the Workspace names no image and the instance has no images/default; give it an ` +
+          `image that holds ${tool} (${PACKAGES[tool]}): an images/default Sandbox Image, the workspace()'s image, ` +
+          `or its effector: { image } (ADR-0068)`
+        );
+      }
+      return (
+        `${label}: ${push} ${why} needs ${tool}, and its Sandbox Effector's image ${ref} holds none in ` +
+        `${EFFECTOR_TOOL_DIRS.join(", ")} — the Effector runs jr2's programs from there alone; install it in the ` +
+        `image (${PACKAGES[tool]}) (ADR-0068)`
+      );
+    }
+    if (form !== "ssh-transport") continue;
+    const seat = effectorSeat(input.user);
+    if (passwdHolds(input.passwd, seat)) continue;
+    const who = "name" in seat ? `user ${seat.name}` : `uid ${seat.uid}`;
+    const fix =
+      "name" in seat
+        ? `a USER line naming a user the image's /etc/passwd holds`
+        : `RUN adduser -D -u ${seat.uid} <name> in the image` +
+          (input.user === "" ? " (the image declares no USER, so the Effector runs as uid 1000)" : "");
+    return (
+      `${label}: ${push} over ssh needs a passwd entry for the ${who} the Sandbox Effector runs as, and its image ` +
+      `${ref} has none — ssh exits "No user exists for uid" before it connects; add ${fix} (ADR-0068)`
+    );
+  }
+  return undefined;
+}

package/src/held-pki.ts

@@ -0,0 +1,306 @@
+// The held-secret PKI (ADR-0059): the per-Instance CA and the leaves the Custodian ends TLS with.
+//
+// `jr2 up` issues every leaf BEFORE a pod starts, so the CA's private key never enters a Harness
+// pod: it lives in the `jr2-held-ca` Secret, which no pod mounts, and `jr2 up` alone reads it over
+// the kube API. A Custodian holds leaves and no key that could mint one.
+//
+// jr2 WRITES two fixed certificate shapes and nothing else, so this is a small DER writer over
+// `node:crypto` rather than a dependency: the CLI's one runtime dependency is `ts-blank-space`, and
+// the libraries that write X.509 bring a dozen packages (`@peculiar/x509`) or an ASN.1 parser and
+// pure-JS RSA (`node-forge`) jr2 has no use for. Nor does it shell to `openssl`: that would add a
+// binary to `jr2 up`'s floor, and macOS ships LibreSSL, whose flags differ. Node VERIFIES what this
+// writes — the tests read every certificate back with `crypto.X509Certificate`, and the Custodian
+// suite ends real TLS handshakes with them.
+//
+//   CA    CN=jr2 held-secret CA (<instance>)   CA:true pathLen:0, keyCertSign+cRLSign, SKI   10 years
+//   leaf  CN=<host>                            one DNS or IP SAN, CA:false, digitalSignature,  1 year
+//                                              serverAuth, AKI, SKI
+//
+// Keys are ECDSA P-256. Serials are 16 random bytes, top bit clear. `notBefore` is an hour back,
+// for clock skew between this host and a node.
+
+import {
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign,
+  X509Certificate,
+  type KeyObject,
+} from "node:crypto";
+import { isIP } from "node:net";
+import { rootCertificates } from "node:tls";
+
+/** One certificate and its key, both PEM. */
+export type Pem = { cert: string; key: string };
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+/** A leaf is issued again when fewer than this many days remain on it. */
+const RENEW_BEFORE_DAYS = 30;
+
+// ---- DER ----------------------------------------------------------------------------------------
+
+function length(n: number): Buffer {
+  if (n < 0x80) return Buffer.from([n]);
+  const bytes: number[] = [];
+  for (let v = n; v > 0; v = Math.floor(v / 256)) bytes.unshift(v % 256);
+  return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+function tlv(tag: number, content: Buffer): Buffer {
+  return Buffer.concat([Buffer.from([tag]), length(content.length), content]);
+}
+
+const seq = (...parts: Buffer[]): Buffer => tlv(0x30, Buffer.concat(parts));
+const set = (...parts: Buffer[]): Buffer => tlv(0x31, Buffer.concat(parts));
+const octets = (content: Buffer): Buffer => tlv(0x04, content);
+const bits = (content: Buffer, unused = 0): Buffer => tlv(0x03, Buffer.concat([Buffer.from([unused]), content]));
+const bool = (value: boolean): Buffer => tlv(0x01, Buffer.from([value ? 0xff : 0x00]));
+const utf8 = (value: string): Buffer => tlv(0x0c, Buffer.from(value, "utf8"));
+/** A context-specific tag: constructed and EXPLICIT for `[0]`/`[3]` of the TBS, primitive and
+ * IMPLICIT for a SAN or a key identifier. */
+const context = (n: number, content: Buffer, constructed: boolean): Buffer =>
+  tlv((constructed ? 0xa0 : 0x80) | n, content);
+
+/** A DER INTEGER from its big-endian magnitude: minimal, and positive. */
+function integer(magnitude: Buffer): Buffer {
+  let start = 0;
+  while (start < magnitude.length - 1 && magnitude[start] === 0 && (magnitude[start + 1] as number) < 0x80) start++;
+  const trimmed = magnitude.subarray(start);
+  return tlv(0x02, (trimmed[0] as number) >= 0x80 ? Buffer.concat([Buffer.from([0]), trimmed]) : trimmed);
+}
+
+function oid(dotted: string): Buffer {
+  const [a, b, ...rest] = dotted.split(".").map(Number) as [number, number, ...number[]];
+  const out = [40 * a + b];
+  for (const n of rest) {
+    const chunk: number[] = [n & 0x7f];
+    for (let v = Math.floor(n / 128); v > 0; v = Math.floor(v / 128)) chunk.unshift(0x80 | (v & 0x7f));
+    out.push(...chunk);
+  }
+  return tlv(0x06, Buffer.from(out));
+}
+
+/** UTCTime until 2049, GeneralizedTime from 2050 (RFC 5280 §4.1.2.5). */
+function time(date: Date): Buffer {
+  const iso = date.toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  return date.getUTCFullYear() < 2050 ? tlv(0x17, Buffer.from(`${iso.slice(2)}Z`)) : tlv(0x18, Buffer.from(`${iso}Z`));
+}
+
+const name = (cn: string): Buffer => seq(set(seq(oid("2.5.4.3"), utf8(cn))));
+const ECDSA_SHA256 = seq(oid("1.2.840.10045.4.3.2"));
+
+function extension(id: string, critical: boolean, value: Buffer): Buffer {
+  return seq(oid(id), ...(critical ? [bool(true)] : []), octets(value));
+}
+
+// ---- keys ---------------------------------------------------------------------------------------
+
+/** A P-256 public key's uncompressed point — the subjectPublicKey bits a key identifier hashes. */
+function ecPoint(publicKey: KeyObject): Buffer {
+  const jwk = publicKey.export({ format: "jwk" });
+  return Buffer.concat([
+    Buffer.from([0x04]),
+    Buffer.from(jwk.x as string, "base64url"),
+    Buffer.from(jwk.y as string, "base64url"),
+  ]);
+}
+
+function p256(): { publicKeyDer: Buffer; point: Buffer; keyPem: string } {
+  const pair = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  return {
+    publicKeyDer: pair.publicKey.export({ type: "spki", format: "der" }),
+    point: ecPoint(pair.publicKey),
+    keyPem: pair.privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+  };
+}
+
+/** RFC 5280's key identifier, method 1: the SHA-1 of the subjectPublicKey bits. */
+function keyId(point: Buffer): Buffer {
+  return createHash("sha1").update(point).digest();
+}
+
+function serial(): Buffer {
+  const bytes = randomBytes(16);
+  bytes[0] = (bytes[0] as number) & 0x7f || 0x01;
+  return bytes;
+}
+
+function pem(der: Buffer): string {
+  const b64 = der
+    .toString("base64")
+    .replace(/(.{64})/g, "$1\n")
+    .replace(/\n$/, "");
+  return `-----BEGIN CERTIFICATE-----\n${b64}\n-----END CERTIFICATE-----\n`;
+}
+
+/** Sign a TBSCertificate into a Certificate. */
+function certificate(tbs: Buffer, signerKeyPem: string): Buffer {
+  const signature = sign("sha256", tbs, createPrivateKey(signerKeyPem));
+  return seq(tbs, ECDSA_SHA256, bits(signature));
+}
+
+// ---- the two shapes -----------------------------------------------------------------------------
+
+/** The per-Instance CA: `CN=jr2 held-secret CA (<instance>)`, ten years. */
+export function issueCa(instance: string, now: Date = new Date()): Pem {
+  const key = p256();
+  const subject = name(`jr2 held-secret CA (${instance})`);
+  const tbs = seq(
+    context(0, integer(Buffer.from([2])), true),
+    integer(serial()),
+    ECDSA_SHA256,
+    subject,
+    seq(time(new Date(now.getTime() - HOUR)), time(new Date(now.getTime() + 3650 * DAY))),
+    subject,
+    key.publicKeyDer,
+    context(
+      3,
+      seq(
+        extension("2.5.29.19", true, seq(bool(true), integer(Buffer.from([0])))),
+        // keyCertSign (bit 5) + cRLSign (bit 6): 0b0000_0110, one unused bit.
+        extension("2.5.29.15", true, bits(Buffer.from([0x06]), 1)),
+        extension("2.5.29.14", false, octets(keyId(key.point))),
+      ),
+      true,
+    ),
+  );
+  return { cert: pem(certificate(tbs, key.keyPem)), key: key.keyPem };
+}
+
+/** A leaf for one bound host — a DNS name or an IP literal — signed by `ca`, one year. */
+export function issueLeaf(ca: Pem, host: string, now: Date = new Date()): Pem {
+  const key = p256();
+  const caCert = new X509Certificate(ca.cert);
+  const caKeyId = keyId(ecPoint(caCert.publicKey));
+  const tbs = seq(
+    context(0, integer(Buffer.from([2])), true),
+    integer(serial()),
+    ECDSA_SHA256,
+    issuerName(caCert),
+    seq(time(new Date(now.getTime() - HOUR)), time(new Date(now.getTime() + 365 * DAY))),
+    name(host),
+    key.publicKeyDer,
+    context(
+      3,
+      seq(
+        extension("2.5.29.17", false, seq(subjectAltName(host))),
+        extension("2.5.29.19", false, seq()),
+        // digitalSignature (bit 0): 0b1000_0000, seven unused bits.
+        extension("2.5.29.15", true, bits(Buffer.from([0x80]), 7)),
+        extension("2.5.29.37", false, seq(oid("1.3.6.1.5.5.7.3.1"))),
+        extension("2.5.29.35", false, seq(context(0, caKeyId, false))),
+        extension("2.5.29.14", false, octets(keyId(key.point))),
+      ),
+      true,
+    ),
+  );
+  return { cert: pem(certificate(tbs, ca.key)), key: key.keyPem };
+}
+
+/** The issuer, as the CA's own subject — read off its DER rather than rebuilt from its CN, so a CA
+ * this module did not write still chains. */
+function issuerName(ca: X509Certificate): Buffer {
+  const der = ca.raw;
+  // Certificate → TBSCertificate → [0] version, serial, sigAlg, issuer, validity, SUBJECT.
+  const tbs = children(children(der, 0)[0] as Buffer, 0);
+  return tbs[5] as Buffer;
+}
+
+/** The DER elements inside one constructed element, whole (tag and length included). */
+function children(der: Buffer, offset: number): Buffer[] {
+  const header = (at: number): { start: number; end: number } => {
+    const first = der[at + 1] as number;
+    if (first < 0x80) return { start: at + 2, end: at + 2 + first };
+    const n = first & 0x7f;
+    let len = 0;
+    for (let i = 0; i < n; i++) len = len * 256 + (der[at + 2 + i] as number);
+    return { start: at + 2 + n, end: at + 2 + n + len };
+  };
+  const outer = header(offset);
+  const out: Buffer[] = [];
+  for (let at = outer.start; at < outer.end; ) {
+    const inner = header(at);
+    out.push(der.subarray(at, inner.end));
+    at = inner.end;
+  }
+  return out;
+}
+
+function subjectAltName(host: string): Buffer {
+  const family = isIP(host);
+  if (family === 4) return context(7, Buffer.from(host.split(".").map(Number)), false);
+  if (family === 6) return context(7, ipv6Bytes(host), false);
+  return context(2, Buffer.from(host, "ascii"), false);
+}
+
+function ipv6Bytes(host: string): Buffer {
+  const [head = "", tail] = host.split("::");
+  const groups = (part: string) => (part ? part.split(":") : []);
+  const left = groups(head);
+  const right = tail === undefined ? [] : groups(tail);
+  const all = [...left, ...Array(8 - left.length - right.length).fill("0"), ...right];
+  return Buffer.from(all.flatMap((g) => [parseInt(g, 16) >> 8, parseInt(g, 16) & 0xff]));
+}
+
+// ---- reuse --------------------------------------------------------------------------------------
+
+/**
+ * Does a leaf `jr2 up` already holds still serve this host? Only when its one SAN names exactly
+ * this host, it verifies against the CURRENT CA, its key is its own, and more than 30 days remain.
+ * Anything else — a moved host, a rotated CA, an expiring leaf — issues a new one.
+ */
+export function leafFits(leaf: Pem, ca: Pem, host: string, now: Date = new Date()): boolean {
+  try {
+    const cert = new X509Certificate(leaf.cert);
+    const issuer = new X509Certificate(ca.cert);
+    if (!cert.verify(issuer.publicKey)) return false;
+    if (!cert.checkPrivateKey(createPrivateKey(leaf.key))) return false;
+    const want = isIP(host) === 0 ? `DNS:${host}` : undefined;
+    if (want !== undefined ? cert.subjectAltName !== want : cert.checkIP(host) === undefined) return false;
+    if (isIP(host) !== 0 && (cert.subjectAltName ?? "").split(",").length !== 1) return false;
+    return new Date(cert.validTo).getTime() - now.getTime() > RENEW_BEFORE_DAYS * DAY;
+  } catch {
+    return false;
+  }
+}
+
+/** A CA `jr2 up` found in the cluster is kept when it parses, is a CA, and its key is its own. */
+export function caFits(ca: Pem, now: Date = new Date()): boolean {
+  try {
+    const cert = new X509Certificate(ca.cert);
+    return (
+      cert.ca && cert.checkPrivateKey(createPrivateKey(ca.key)) && new Date(cert.validTo).getTime() > now.getTime()
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** SHA-256 of a certificate's DER — what the Instance Harness's held digest covers per leaf. */
+export function fingerprint(certPem: string): string {
+  return new X509Certificate(certPem).fingerprint256;
+}
+
+// ---- trust --------------------------------------------------------------------------------------
+
+/**
+ * The three bundles a held secret needs, beside the user's own `ca.crt` (ADR-0020, ADR-0059).
+ * "Roots" are the Mozilla roots of the Node that runs `jr2 up` — no file on the host, no dependency,
+ * and one list whatever engine verifies with it.
+ *
+ *   extra.crt      caBundle + the jr2 CA      the Harness's NODE_EXTRA_CA_CERTS (adds to Node's roots)
+ *   bundle.crt     roots + both               SSL_CERT_FILE and friends (these REPLACE a tool's store)
+ *   upstream.crt   roots + caBundle           the Custodian's upstream trust — NEVER the jr2 CA, so
+ *                                            it can never accept one of its own leaves from upstream
+ */
+export function trustBundles(jr2Ca: string, caBundle?: string): { extra: string; bundle: string; upstream: string } {
+  const roots = rootCertificates.map((c) => (c.endsWith("\n") ? c : `${c}\n`)).join("");
+  const user = caBundle ? (caBundle.endsWith("\n") ? caBundle : `${caBundle}\n`) : "";
+  return {
+    extra: `${user}${jr2Ca}`,
+    bundle: `${roots}${user}${jr2Ca}`,
+    upstream: `${roots}${user}`,
+  };
+}

package/src/index.ts

@@ -10,3 +10,7 @@ export { assertKitVersion, checkKitVersion, resolvePackage, CLI_VERSION } from "
 export type { Target, TargetOptions } from "./instance.ts";
 export { kubectlKube } from "./kube.ts";
 export type { KubePort } from "./kube.ts";
+// The held-secret PKI (ADR-0059): what `jr2 up` issues the Custodian's leaves with — exported so a
+// 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";

package/src/kube.ts

@@ -52,8 +52,8 @@ export type KubePort = {
 const ctxArgs = (context?: string): string[] => (context ? ["--context", context] : []);
 
 /** The loosely-typed kube object shape the converge logic inspects: labels carry the instance's
- * identity and the instance image's content hash; annotations carry the converged image map, which
- * is too long for a label value (ADR-0038). */
+ * identity; annotations carry the converged image map, which is too long for a label value
+ * (ADR-0038). */
 export type KubeObject = {
   metadata: {
     name: string;
@@ -98,8 +98,11 @@ export type KubeAdmin = {
     allNamespaces?: boolean;
     context?: string;
   }): Promise<T[]>;
-  /** `kubectl apply -f -` of a multi-doc YAML or JSON manifest string. */
-  apply(opts: { manifest: string; context?: string }): Promise<void>;
+  /** `kubectl apply -f -` of a multi-doc YAML or JSON manifest string. `serverSide` is for an
+   * object too large for client-side apply's `last-applied-configuration` annotation (256 KiB) —
+   * the trust bundles, which carry every root certificate (ADR-0059); jr2 is its only writer, so it
+   * takes the fields it owns (`--force-conflicts`). */
+  apply(opts: { manifest: string; context?: string; serverSide?: boolean }): Promise<void>;
   /** `kubectl label --overwrite`. */
   label(opts: {
     kind: string;
@@ -135,6 +138,13 @@ export type KubeAdmin = {
     previous?: boolean;
     context?: string;
   }): Promise<string>;
+  /** The API server's `gitVersion` (`kubectl get --raw /version`), e.g. `v1.35.0-gke.1200` — what
+   * ADR-0037's Kubernetes floor is judged against. THROWS when the server does not answer, like
+   * `listJson`: a floor check that passed because it could not look is no check at all. */
+  serverVersion(opts: { context?: string }): Promise<string>;
+  /** `kubectl create --dry-run=server -o json -f -`: the object as admission would store it,
+   * stored nowhere. THROWS on a refusal, with kubectl's reason. */
+  dryRunCreate(opts: { manifest: string; context?: string }): Promise<{ spec?: { resources?: unknown } }>;
   /** Run a one-shot node script IN the cluster (`kubectl run --rm`) and return its output — the
    * provider-preflight seam (ADR-0019: reachability must be probed from where pods live).
    * `caPem` makes the probe trust a private CA the same way the Harness does (ADR-0020):
@@ -151,8 +161,8 @@ export type KubeAdmin = {
 
 const nsArgs = (namespace?: string): string[] => (namespace ? ["--namespace", namespace] : []);
 
-/** The two workload kinds `jr2 up` rolls out and waits on. */
-export type RolloutKind = "deployment" | "daemonset";
+/** The workload kinds `jr2 up` rolls out and waits on. */
+export type RolloutKind = "deployment" | "daemonset" | "statefulset";
 
 /** One rollout to wait for: the object, by kind and name, in its namespace. */
 export type RolloutRequest = {
@@ -183,6 +193,28 @@ export function rolloutStatusArgs({
   ];
 }
 
+/** ADR-0037's Kubernetes floor: every Sandbox's `/opt/jr2` is an `image` volume of the harness
+ * image, and image volumes are on by default from 1.35 (GA in 1.36). There is no fallback below it
+ * — a second pod shape kept alive for clusters no Instance runs on — so `jr2 up` refuses there. */
+export const KUBE_FLOOR = { major: 1, minor: 35 } as const;
+
+/**
+ * Why this server version cannot host an Instance, or undefined when it can. Pure, so the floor is
+ * checkable without a cluster. Judged on the leading `v<major>.<minor>` alone: distributions append
+ * their own suffixes (`-gke.1200`, `+k3s1`, `-eks-…`), and none of them moves the feature gate. A
+ * version with no such prefix is refused BY NAME rather than passed — a floor that waves through
+ * what it cannot read is the timeout ADR-0046 exists to replace.
+ */
+export function kubeFloorRefusal(gitVersion: string): string | undefined {
+  const floor = `${KUBE_FLOOR.major}.${KUBE_FLOOR.minor}`;
+  const why = `jr2 needs Kubernetes ${floor} or newer (every Sandbox mounts jr2's runtime as an image volume, ADR-0037)`;
+  const m = /^v?(\d+)\.(\d+)/.exec(gitVersion);
+  if (!m) return `reports version "${gitVersion}", which names no major.minor; ${why}`;
+  const [major, minor] = [Number(m[1]), Number(m[2])];
+  if (major > KUBE_FLOOR.major || (major === KUBE_FLOOR.major && minor >= KUBE_FLOOR.minor)) return undefined;
+  return `runs Kubernetes ${gitVersion}; ${why}`;
+}
+
 /**
  * Did this read fail because the cluster has no such RESOURCE TYPE (`kubectl get sandboxes… ` on a
  * cluster with no jr2 CRD)? kubectl exits 1 with `the server doesn't have a resource type "…"`, and
@@ -238,8 +270,9 @@ export const kubectlAdmin: KubeAdmin = {
     return (JSON.parse(stdout) as { items?: never[] }).items ?? [];
   },
 
-  async apply({ manifest, context }) {
-    await execStdin(["kubectl", ...ctxArgs(context), "apply", "-f", "-"], manifest);
+  async apply({ manifest, context, serverSide }) {
+    const mode = serverSide ? ["--server-side", "--force-conflicts", "--field-manager=jr2"] : [];
+    await execStdin(["kubectl", ...ctxArgs(context), "apply", ...mode, "-f", "-"], manifest);
   },
 
   async label({ kind, name, namespace, labels, context }) {
@@ -284,6 +317,28 @@ export const kubectlAdmin: KubeAdmin = {
     }
   },
 
+  async serverVersion({ context }) {
+    // `get --raw /version`, not `kubectl version`: that one reports the CLIENT too; this asks the
+    // server alone, and answers in the server's own JSON. Bounded like every first contact: it is
+    // the first thing `jr2 up` asks, so a dead context fails here, fast, with kubectl's own reason.
+    try {
+      const { stdout } = await exec("kubectl", [...ctxArgs(context), "get", "--raw", "/version", ...reachArgs], {
+        timeout: REACH_BUDGET_MS,
+      });
+      return (JSON.parse(stdout) as { gitVersion?: string }).gitVersion ?? "";
+    } catch (e) {
+      throw new Error(unreachable(e));
+    }
+  },
+
+  async dryRunCreate({ manifest, context }) {
+    const out = await execStdinOut(
+      ["kubectl", ...ctxArgs(context), "create", "--dry-run=server", "-o", "json", "-f", "-"],
+      manifest,
+    );
+    return JSON.parse(out) as { spec?: { resources?: unknown } };
+  },
+
   async runOneShot({ namespace, name, script, caPem, context }) {
     // With a CA bundle: write the PEM to a file BEFORE node starts, because NODE_EXTRA_CA_CERTS
     // is only honored as process-start env. The PEM rides an env var base64'd (multiline values
@@ -346,6 +401,8 @@ export type RolloutTarget = {
   namespace: string;
   selector: string;
   context?: string;
+  /** Default 180s (see `rolloutStatusArgs`). */
+  timeoutSeconds?: number;
 };
 
 /** One container's state, as the kubelet tells it. `reason`/`message` are its words verbatim — the
@@ -470,7 +527,12 @@ async function gatherRolloutEvidence(kube: KubeAdmin, target: RolloutTarget): Pr
   const live = pods.filter((p) => !p.metadata.deletionTimestamp);
   if (pods.length > 0 && live.length === 0) notes.push(`every pod matching ${selector} is terminating`);
   if (pods.length === 0 && notes.length === 0) {
-    const maker = target.kind === "daemonset" ? "the DaemonSet" : "the ReplicaSet";
+    const maker =
+      target.kind === "daemonset"
+        ? "the DaemonSet"
+        : target.kind === "statefulset"
+          ? "the StatefulSet"
+          : "the ReplicaSet";
     notes.push(`no pod matches ${selector} — ${maker} made none (check quota, node taints, and the selector)`);
   }
 
@@ -728,6 +790,50 @@ function execStdin(cmd: string[], stdin: string): Promise<void> {
   });
 }
 
+/** `execStdin`, keeping stdout. */
+function execStdinOut(cmd: string[], stdin: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd[0]!, cmd.slice(1));
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d: Buffer) => (out += d.toString()));
+    child.stderr.on("data", (d: Buffer) => (err += d.toString()));
+    child.on("error", reject);
+    child.on("close", (code) =>
+      code === 0 ? resolve(out) : reject(new Error(`${cmd.join(" ")} exited (${code}): ${err.trim()}`)),
+    );
+    child.stdin.write(stdin);
+    child.stdin.end();
+  });
+}
+
+/**
+ * The pod ADR-0060's check dry-runs: one that states pod-level resources (KEP-2837). A server
+ * whose PodLevelResources gate is off drops `spec.resources` at admission without a word, and
+ * every Sandbox then runs Burstable — a User Container with no split unbounded, against "jr2
+ * reserves the whole Size". On by default from 1.34, below KUBE_FLOOR, so only an owner who turned
+ * it off trips this. Shaped for the `restricted` Pod Security level, so a namespace that enforces
+ * it does not refuse the probe for another reason. Never scheduled, never pulled.
+ */
+export function podResourcesProbe(namespace: string): object {
+  return {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { name: "jr2-pod-resources-probe", namespace },
+    spec: {
+      resources: { requests: { cpu: "10m", memory: "16Mi" }, limits: { cpu: "10m", memory: "16Mi" } },
+      securityContext: { runAsNonRoot: true, runAsUser: 65532, seccompProfile: { type: "RuntimeDefault" } },
+      containers: [
+        {
+          name: "probe",
+          image: "registry.k8s.io/pause:3.10",
+          securityContext: { allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+        },
+      ],
+    },
+  };
+}
+
 /** The real kube port, over `kubectl` subprocesses. */
 export const kubectlKube: KubePort = {
   async currentContext() {