@namzu/sandbox 13.0.0 → 14.0.0

package/src/backends/kubernetes/objects.ts

@@ -0,0 +1,363 @@
+/**
+ * Wire shapes and paths for the agent-sandbox CRDs this backend touches.
+ *
+ * Every field name here was read off the CRDs a real cluster serves —
+ * `kubectl get crd -o json` against agent-sandbox v1.0.2 on a kind cluster —
+ * and cross-checked against the upstream `sandbox_types.go` /
+ * `sandboxclaim_types.go` doc comments. Where the two disagree the served CRD
+ * wins, because it is what the API server validates against: the Go source on
+ * upstream main has already moved `Sandbox`'s `shutdownTime` /
+ * `shutdownPolicy` under a `lifecycle` block, and v1beta1 as served still
+ * carries them at the top of `spec`.
+ *
+ * The shapes are deliberately partial. This backend reads four fields out of a
+ * Sandbox status and writes three into a claim spec; typing the rest of a
+ * PodSpec would be a vendored copy of the core API that goes stale on its own
+ * schedule. A pod template read from a SandboxTemplate is carried through as
+ * an opaque record for exactly that reason — it is copied, never interpreted.
+ *
+ * Two groups, both `v1beta1` and both singular-versioned today:
+ *   - `agents.x-k8s.io`            → sandboxes
+ *   - `extensions.agents.x-k8s.io` → sandboxtemplates, sandboxwarmpools,
+ *                                    sandboxclaims
+ */
+
+/** Group serving the `Sandbox` kind. */
+export const SANDBOX_API_GROUP = 'agents.x-k8s.io'
+/** Group serving `SandboxTemplate`, `SandboxWarmPool` and `SandboxClaim`. */
+export const SANDBOX_EXTENSIONS_API_GROUP = 'extensions.agents.x-k8s.io'
+/** The only version either group serves in agent-sandbox v1.0.2. */
+export const SANDBOX_API_VERSION = 'v1beta1'
+
+/** `status.conditions[].type` both kinds report readiness under. */
+export const READY_CONDITION = 'Ready'
+
+// The controller also reports a `Suspended` condition, and this backend
+// deliberately does NOT model or read it. Upstream's own `sandbox_types.go`
+// says why: "the controller does not currently remove this condition when the
+// Sandbox is resumed, so a stale Suspended condition may linger after
+// operatingMode returns to Running. Consumers should treat Ready as the
+// authoritative signal and not infer the live operating state from the mere
+// presence of this condition." A suspend that waited on it would return on the
+// True left behind by the previous suspend, while the guest was still running
+// and still writing. `workspace.ts` waits on the pod instead — see
+// `isPodStopped` below.
+
+export interface KubernetesObjectMeta {
+	readonly name?: string
+	readonly namespace?: string
+	readonly uid?: string
+	/**
+	 * Set the moment a DELETE is accepted, long before the object goes away.
+	 * A pod that carries one is on its way out and must never be bound to —
+	 * see {@link isPodLive}.
+	 */
+	readonly deletionTimestamp?: string
+	readonly labels?: Readonly<Record<string, string>>
+	readonly annotations?: Readonly<Record<string, string>>
+}
+
+/** `metav1.Condition`, as both CRDs embed it. */
+export interface KubernetesCondition {
+	readonly type: string
+	readonly status: 'True' | 'False' | 'Unknown'
+	readonly reason?: string
+	readonly message?: string
+	readonly lastTransitionTime?: string
+}
+
+/**
+ * True only for an explicit `status: 'True'`. An absent condition, an
+ * `Unknown` and a `False` are all "not yet", never "assume so" — the
+ * controller writes `Unknown` while it is still deciding.
+ */
+export function isConditionTrue(
+	conditions: readonly KubernetesCondition[] | undefined,
+	type: string,
+): boolean {
+	return conditions?.some((c) => c.type === type && c.status === 'True') === true
+}
+
+/**
+ * `SandboxClaim.spec.lifecycle`.
+ *
+ * `shutdownTime` is the only one of the three that bounds a claim whose owner
+ * disappeared: the controller deletes the claim's resources once the wall
+ * clock reaches it, whatever the claim is doing. `ttlSecondsAfterFinished`
+ * reads like the leak guard and is not one — upstream's own comment says "the
+ * timer starts from the mirrored Finished condition's LastTransitionTime", so
+ * a claim whose host crashed before finishing never starts that clock.
+ */
+export interface SandboxClaimLifecycle {
+	/** RFC 3339. Absolute expiry; the claim never expires without it. */
+	readonly shutdownTime?: string
+	/**
+	 * What happens to the claim OBJECT at expiry. `Retain` (the CRD default)
+	 * deletes the Sandbox, Pod and Service but leaves the claim behind, so a
+	 * host that crashes daily accumulates claims forever.
+	 */
+	readonly shutdownPolicy?: 'Delete' | 'DeleteForeground' | 'Retain'
+	readonly ttlSecondsAfterFinished?: number
+}
+
+/**
+ * `SandboxClaim.spec`. `warmPoolRef` is REQUIRED by the CRD, which is why
+ * there is no such thing as a pool-less claim and the no-pool path has to
+ * create a Sandbox directly.
+ *
+ * `env` and `volumeClaimTemplates` exist on this spec and are deliberately
+ * absent from this type: setting either forces the claim to cold-start rather
+ * than adopt a warm pool sandbox, which is the one thing the warm path exists
+ * to avoid. A field that cannot be named cannot be set by accident.
+ */
+export interface SandboxClaimResourceSpec {
+	readonly warmPoolRef: { readonly name: string }
+	readonly lifecycle?: SandboxClaimLifecycle
+}
+
+/**
+ * `SandboxClaim.status`. `sandbox` is the whole reason the claim path reads
+ * status back: an adopted pool sandbox keeps the generated name the pool gave
+ * it, so the bound object is routinely NOT named after the claim.
+ */
+export interface SandboxClaimResourceStatus {
+	readonly conditions?: readonly KubernetesCondition[]
+	readonly sandbox?: {
+		readonly name?: string
+		readonly podIPs?: readonly string[]
+		readonly serviceFQDN?: string
+	}
+}
+
+export interface SandboxClaimResource {
+	readonly apiVersion?: string
+	readonly kind?: string
+	readonly metadata?: KubernetesObjectMeta
+	readonly spec?: SandboxClaimResourceSpec
+	readonly status?: SandboxClaimResourceStatus
+}
+
+/**
+ * `podTemplate` on a Sandbox or a SandboxTemplate. `spec` is a core `PodSpec`,
+ * carried opaquely: this backend copies one from a template into a Sandbox and
+ * overlays at most `runtimeClassName`.
+ */
+export interface SandboxPodTemplate {
+	readonly metadata?: KubernetesObjectMeta
+	readonly spec: Readonly<Record<string, unknown>>
+}
+
+/**
+ * One `spec.volumeClaimTemplates` entry.
+ *
+ * Partial in the same way every other shape here is: a workspace's disk is
+ * COPIED verbatim from the `SandboxTemplate` that declares it, and only the
+ * two fields this backend has to reason about are named — the entry's own
+ * `metadata.name`, which is how the controller wires the mount (StatefulSet
+ * style: the PVC is created as `<entry name>-<sandbox name>` and no explicit
+ * `volumes:` entry is needed in the podTemplate), and `spec.volumeMode`,
+ * which decides whether the guest gets a raw block device or a filesystem
+ * passthrough. The index signatures carry everything else across untouched.
+ */
+export interface SandboxVolumeClaimTemplate {
+	readonly metadata?: KubernetesObjectMeta
+	readonly spec?: {
+		readonly volumeMode?: string
+		readonly [field: string]: unknown
+	}
+	readonly [field: string]: unknown
+}
+
+export interface SandboxResourceSpec {
+	readonly operatingMode?: 'Running' | 'Suspended'
+	readonly podTemplate: SandboxPodTemplate
+	/** Create a headless Service, and with it a `status.serviceFQDN`. */
+	readonly service?: boolean
+	readonly shutdownPolicy?: 'Delete' | 'Retain'
+	/** RFC 3339, top-level on v1beta1 Sandbox (NOT under `lifecycle`). */
+	readonly shutdownTime?: string
+	/**
+	 * CEL-immutable on the served CRD ("volumeClaimTemplates is immutable"),
+	 * which is why a workspace's disk has to be in the spec from creation and
+	 * cannot be attached to a sandbox that is already running.
+	 */
+	readonly volumeClaimTemplates?: readonly SandboxVolumeClaimTemplate[]
+}
+
+/**
+ * `Sandbox.status`. Note what is NOT here: a pod name. The backing pod is
+ * named after the Sandbox itself in v1.0.2, and `selector` — a serialised
+ * label selector, e.g. `agents.x-k8s.io/sandbox-name-hash=<hash>` — is the
+ * only thing in the API that finds the pod without relying on that.
+ */
+export interface SandboxResourceStatus {
+	readonly conditions?: readonly KubernetesCondition[]
+	readonly nodeName?: string
+	readonly podIPs?: readonly string[]
+	readonly selector?: string
+	readonly service?: string
+	readonly serviceFQDN?: string
+}
+
+export interface SandboxResource {
+	readonly apiVersion?: string
+	readonly kind?: string
+	readonly metadata?: KubernetesObjectMeta
+	readonly spec?: SandboxResourceSpec
+	readonly status?: SandboxResourceStatus
+}
+
+export interface SandboxTemplateResource {
+	readonly metadata?: KubernetesObjectMeta
+	readonly spec?: {
+		readonly podTemplate?: SandboxPodTemplate
+		readonly service?: boolean
+		readonly volumeClaimTemplates?: readonly SandboxVolumeClaimTemplate[]
+	}
+}
+
+/**
+ * `metadata.uid` is the per-instance agent bind token; the other two fields
+ * exist only to answer "is this the pod that uid belongs to, or the one being
+ * deleted?" — see {@link isPodLive}.
+ */
+export interface PodResource {
+	readonly metadata?: KubernetesObjectMeta
+	readonly status?: { readonly phase?: string }
+}
+
+export interface PodListResource {
+	readonly items?: readonly PodResource[]
+}
+
+/**
+ * A pod whose uid is still worth binding to: not being deleted, and not in a
+ * phase it cannot leave.
+ *
+ * The case this exists for is resume. A resumed sandbox's pod keeps the
+ * SAME NAME and gets a new uid and a new IP, so while the outgoing pod is
+ * terminating a `GET` by that name answers with the pod on its way out, and a
+ * list by the sandbox's selector returns every pod still carrying its labels,
+ * that one included. Binding to the terminating pod's uid produces a token the
+ * new agent refuses, and the failure arrives as a flat `unauthorized` with
+ * nothing pointing at the race that caused it.
+ */
+export function isPodLive(pod: PodResource | undefined): boolean {
+	if (!pod?.metadata) return false
+	// `!= null`, not `!== undefined`: an explicit JSON null would otherwise
+	// read as "terminating" and make a perfectly healthy pod unbindable. The
+	// API server omits the field rather than nulling it, so this never fires
+	// against a real cluster — it costs nothing not to depend on that.
+	if (pod.metadata.deletionTimestamp != null) return false
+	const phase = pod.status?.phase
+	return phase !== 'Succeeded' && phase !== 'Failed'
+}
+
+/**
+ * A pod whose containers have stopped: it is still an object, and nothing in
+ * it is executing any more.
+ *
+ * NOT the negation of {@link isPodLive}, and the gap between the two is the
+ * whole point. A terminating pod — `deletionTimestamp` set, phase still
+ * `Running` — is not live (never bind to it: its uid is about to stop being
+ * a valid token) and not stopped either (its process is still running, and on
+ * a workspace it is still writing to the caller's block device until it exits
+ * or `terminationGracePeriodSeconds` runs out). A suspend that treated the
+ * timestamp as "gone" would resolve mid-drain and promise a quiesced disk it
+ * had not waited for.
+ */
+export function isPodStopped(pod: PodResource | undefined): boolean {
+	const phase = pod?.status?.phase
+	return phase === 'Succeeded' || phase === 'Failed'
+}
+
+/**
+ * Backend-owned pod label naming which `SandboxTemplate` a Sandbox's pod was
+ * built from.
+ *
+ * agent-sandbox's OWN template-adoption controller selects pods by a
+ * controller-owned label, `agents.x-k8s.io/sandbox-template-ref-hash` — but
+ * that label is written only onto a Sandbox ADOPTED out of a
+ * `SandboxWarmPool` (the controller re-parents ownership and re-labels on
+ * bind). A Sandbox this backend POSTs directly (the pool-less path in
+ * `index.ts`'s `buildSandboxBody`) is never adopted, so it never gets that
+ * label — a direct Sandbox's pod would carry nothing a `NetworkPolicy`
+ * could reliably select it by. This backend writes its own label instead, on
+ * every Sandbox it creates, pooled or direct, so `egress-policy.ts`'s
+ * translated `NetworkPolicy` has one selector that always matches.
+ *
+ * `namzu.ai` matches the published domain (`packages/cli/package.json`'s
+ * `homepage`); there is no pre-existing Kubernetes label or annotation
+ * prefix anywhere in this repo to follow instead — the closest existing
+ * convention, `NAMZU_AGENT_*` / `NAMZU_SANDBOX_*` env vars, is not a
+ * label-safe shape.
+ *
+ * W8's `SandboxTemplate` manifests MUST set this same label (value = the
+ * template's own name) on their `podTemplate.metadata.labels`, so a POOLED
+ * sandbox's pod carries it too — the pool's pods are built from that
+ * template's `podTemplate` directly, not through `buildSandboxBody`, so
+ * nothing here can put it there for them. Skipping that step means a
+ * translated `NetworkPolicy`'s `podSelector` matches only sandboxes this
+ * backend created directly and none of the pooled ones — see
+ * `docs/sdk/kubernetes-sandbox.md`'s egress section.
+ */
+export const SANDBOX_TEMPLATE_LABEL_KEY = 'sandbox.namzu.ai/template'
+
+/** `{ [SANDBOX_TEMPLATE_LABEL_KEY]: sandboxTemplateName }`, as a matchLabels-ready object. */
+export function sandboxTemplateLabel(
+	sandboxTemplateName: string,
+): Readonly<Record<string, string>> {
+	return { [SANDBOX_TEMPLATE_LABEL_KEY]: sandboxTemplateName }
+}
+
+/** Core `NetworkPolicy` — a stock resource, no CRD. */
+export const CORE_NETWORK_POLICY_API_GROUP = 'networking.k8s.io'
+export const CORE_NETWORK_POLICY_API_VERSION = 'v1'
+
+/**
+ * Cilium's FQDN-capable policy CRD. Only reached when
+ * `KubernetesEgressConfig.engine` is explicitly `'cilium'` — see
+ * `egress-policy.ts`.
+ */
+export const CILIUM_NETWORK_POLICY_API_GROUP = 'cilium.io'
+export const CILIUM_NETWORK_POLICY_API_VERSION = 'v2'
+
+function segment(value: string): string {
+	return encodeURIComponent(value)
+}
+
+export function claimCollectionPath(namespace: string): string {
+	return `/apis/${SANDBOX_EXTENSIONS_API_GROUP}/${SANDBOX_API_VERSION}/namespaces/${segment(namespace)}/sandboxclaims`
+}
+
+export function claimPath(namespace: string, name: string): string {
+	return `${claimCollectionPath(namespace)}/${segment(name)}`
+}
+
+export function sandboxCollectionPath(namespace: string): string {
+	return `/apis/${SANDBOX_API_GROUP}/${SANDBOX_API_VERSION}/namespaces/${segment(namespace)}/sandboxes`
+}
+
+export function sandboxPath(namespace: string, name: string): string {
+	return `${sandboxCollectionPath(namespace)}/${segment(name)}`
+}
+
+export function sandboxTemplatePath(namespace: string, name: string): string {
+	return `/apis/${SANDBOX_EXTENSIONS_API_GROUP}/${SANDBOX_API_VERSION}/namespaces/${segment(namespace)}/sandboxtemplates/${segment(name)}`
+}
+
+export function podPath(namespace: string, name: string): string {
+	return `/api/v1/namespaces/${segment(namespace)}/pods/${segment(name)}`
+}
+
+export function podListPath(namespace: string, labelSelector: string): string {
+	return `/api/v1/namespaces/${segment(namespace)}/pods?labelSelector=${encodeURIComponent(labelSelector)}`
+}
+
+export function networkPolicyPath(namespace: string, name: string): string {
+	return `/apis/${CORE_NETWORK_POLICY_API_GROUP}/${CORE_NETWORK_POLICY_API_VERSION}/namespaces/${segment(namespace)}/networkpolicies/${segment(name)}`
+}
+
+export function ciliumNetworkPolicyPath(namespace: string, name: string): string {
+	return `/apis/${CILIUM_NETWORK_POLICY_API_GROUP}/${CILIUM_NETWORK_POLICY_API_VERSION}/namespaces/${segment(namespace)}/ciliumnetworkpolicies/${segment(name)}`
+}

package/src/backends/kubernetes/privilege-probe.ts

@@ -0,0 +1,261 @@
+/**
+ * Acquire-time privilege probe: prove the guest process really was
+ * deprivileged, rather than assume the entrypoint did its job.
+ *
+ * The image's entrypoint mounts the workspace as root and then
+ * `exec setpriv --reuid --regid --clear-groups --inh-caps=-all
+ * --bounding-set=-all --no-new-privs -- tini -- node agent.cjs` (`tini` is
+ * the container's pid 1 so it can reap an orphan `agent.cjs` itself never
+ * spawned — see `k8s/entrypoint.sh` and the Dockerfile). Nothing in
+ * `agent.cjs` knows about any of that, and nothing on the host can see it
+ * either — an image built from an older entrypoint, a `RuntimeClass` change,
+ * a hand-edited `SandboxTemplate` all produce a sandbox that works perfectly
+ * and is not deprivileged. So the backend asks the guest, once, before it
+ * hands a caller a handle.
+ *
+ * ## Why `execute`, and why not `read-file`
+ *
+ * The guest's `read-file` resolves every path against `READ_ROOTS`
+ * (`WORKSPACE_ROOT` only), so it cannot reach `/proc` at all, and widening
+ * `READ_ROOTS` to make the probe work would hand every caller of `readFile`
+ * a window into the guest's process tree for the sake of one diagnostic.
+ * `handleExecute` jails only `cwd`, so a command whose ARGUMENT is an
+ * absolute path outside the workspace runs fine. The probe therefore spends
+ * one `exec` and touches no jail.
+ *
+ * ## Why all four masks
+ *
+ * Checking `CapEff` alone is a true-looking answer: an ordinary unprivileged
+ * process shows `CapEff: 0000000000000000` whether or not its bounding set
+ * was ever dropped, so a container running as uid 0 with the full bounding
+ * set still passes. `CapBnd` is the one that says a capability can never be
+ * regained; `CapInh` and `CapPrm` close the two ways one could be carried
+ * across an exec. `NoNewPrivs: 1` is what makes a setuid binary inside the
+ * guest unable to raise any of it back.
+ *
+ * ## Why every failure is a refusal
+ *
+ * A probe that could not run, one that never answered at all, output that
+ * could not be parsed and a process that is genuinely privileged are all
+ * reasons NOT to hand back a handle, and they are separated only in the error
+ * TEXT — a distroless image with no `cat` on `PATH` must be diagnosable as
+ * exactly that rather than read as a hardening failure. There is no
+ * configuration that turns this off.
+ *
+ * ## The clock is the caller's, and it lives in `index.ts`
+ *
+ * Nothing here has a timeout: the probe is one `exec`, and the budget it may
+ * spend belongs to the `create()` that ordered it. `admitProbedSandbox` runs
+ * it under an `OperationDeadline` and turns an expiry into
+ * {@link privilegeProbeTimedOut}, so a guest that accepts the connection and
+ * then goes quiet is refused on the caller's clock rather than on the
+ * execution controller's five-minute generic default.
+ */
+
+import type { SandboxExecResult } from '@namzu/sdk'
+
+/**
+ * The probe command. `cat` rather than an absolute `/bin/cat` so a guest
+ * that keeps its coreutils somewhere else still answers, and rather than a
+ * shell so there is no quoting to get wrong. A guest without it fails with
+ * a spawn error the refusal repeats verbatim.
+ */
+export const PRIVILEGE_PROBE_COMMAND = 'cat'
+
+/** `/proc/self/status` — of the process the guest agent spawns, which
+ * inherits exactly the agent's own credentials and capability masks. */
+export const PRIVILEGE_PROBE_ARGS: readonly string[] = ['/proc/self/status']
+
+/** Why a probe refused. The text says the same thing in words. */
+export type PrivilegeProbeFailure =
+	/** The `exec` failed, exited non-zero, or never answered at all. */
+	| 'probe-failed'
+	/** It ran, but its output is not a readable `/proc/<pid>/status`. */
+	| 'unreadable-output'
+	/** It ran, it parsed, and the process has capabilities it should not. */
+	| 'privileged'
+
+/**
+ * Raised by {@link runPrivilegeProbe} and {@link parseProcStatus}. The
+ * `reason` is the machine-readable form of the distinction the message
+ * draws in prose: `'privileged'` means the guest is under-hardened, and the
+ * other two mean the backend could not tell.
+ */
+export class KubernetesPrivilegeProbeError extends Error {
+	override readonly name = 'KubernetesPrivilegeProbeError'
+
+	constructor(
+		readonly reason: PrivilegeProbeFailure,
+		message: string,
+		options?: ErrorOptions,
+	) {
+		super(message, options)
+	}
+}
+
+/**
+ * The five fields the probe reads, parsed. The four capability masks are
+ * `bigint` because a capability mask is 64 bits wide and `Number` stops
+ * being exact at 53 — `000001ffffffffff` is only 41 bits today, but a mask
+ * that silently rounds is precisely the bug this whole module exists to
+ * catch.
+ */
+export interface ProcStatusPrivileges {
+	readonly capInh: bigint
+	readonly capPrm: bigint
+	readonly capEff: bigint
+	readonly capBnd: bigint
+	/** `prctl(PR_GET_NO_NEW_PRIVS)`, 0 or 1 as the kernel prints it. */
+	readonly noNewPrivs: number
+}
+
+const CAPABILITY_FIELDS = ['CapInh', 'CapPrm', 'CapEff', 'CapBnd'] as const
+const NO_NEW_PRIVS_FIELD = 'NoNewPrivs'
+
+/** Clip a value before it goes into an error message. */
+function clip(value: string): string {
+	return value.length > 40 ? `${value.slice(0, 40)}…` : value
+}
+
+function readField(text: string, field: string): string {
+	for (const rawLine of text.split(/\r?\n/)) {
+		const colon = rawLine.indexOf(':')
+		if (colon < 0) continue
+		if (rawLine.slice(0, colon).trim() !== field) continue
+		return rawLine.slice(colon + 1).trim()
+	}
+	throw new KubernetesPrivilegeProbeError(
+		'unreadable-output',
+		`the privilege probe ran but its output carries no ${field} line, so this sandbox's privileges could not be read. The probe is \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` — a guest whose /proc is not mounted, or whose kernel does not publish ${field}, cannot be admitted, because an unreadable answer is not a safe one.`,
+	)
+}
+
+/**
+ * Parse `/proc/<pid>/status` into the five fields that decide admission.
+ *
+ * Pure: no transport, no clock, no I/O. Everything it cannot read is a
+ * throw, never a default — a zero substituted for a missing mask is the one
+ * mistake that would make this function report hardening that is not there.
+ */
+export function parseProcStatus(text: string): ProcStatusPrivileges {
+	const masks = CAPABILITY_FIELDS.map((field) => {
+		const raw = readField(text, field)
+		// The kernel prints a bare, fixed-width hex mask with no `0x`. A
+		// `0x` prefix, a sign, whitespace inside, or anything non-hex means
+		// this is not the file this parser thinks it is.
+		if (!/^[0-9a-fA-F]+$/.test(raw)) {
+			throw new KubernetesPrivilegeProbeError(
+				'unreadable-output',
+				`the privilege probe ran but ${field} is ${JSON.stringify(clip(raw))}, which is not the bare hexadecimal capability mask /proc/<pid>/status publishes, so this sandbox's privileges could not be read.`,
+			)
+		}
+		return BigInt(`0x${raw}`)
+	})
+
+	const noNewPrivsRaw = readField(text, NO_NEW_PRIVS_FIELD)
+	if (!/^\d+$/.test(noNewPrivsRaw)) {
+		throw new KubernetesPrivilegeProbeError(
+			'unreadable-output',
+			`the privilege probe ran but ${NO_NEW_PRIVS_FIELD} is ${JSON.stringify(clip(noNewPrivsRaw))}, which is not the integer /proc/<pid>/status publishes, so this sandbox's privileges could not be read.`,
+		)
+	}
+
+	return {
+		capInh: masks[0] as bigint,
+		capPrm: masks[1] as bigint,
+		capEff: masks[2] as bigint,
+		capBnd: masks[3] as bigint,
+		noNewPrivs: Number(noNewPrivsRaw),
+	}
+}
+
+/**
+ * Admit only an all-zero capability set with `no_new_privs` set. Every
+ * non-zero mask is named in the refusal, because "one of them is set" sends
+ * the reader back to the guest to find out which.
+ */
+export function assertDeprivileged(privileges: ProcStatusPrivileges, sandboxName: string): void {
+	const offenders: string[] = []
+	if (privileges.capInh !== 0n) offenders.push(`CapInh=${privileges.capInh.toString(16)}`)
+	if (privileges.capPrm !== 0n) offenders.push(`CapPrm=${privileges.capPrm.toString(16)}`)
+	if (privileges.capEff !== 0n) offenders.push(`CapEff=${privileges.capEff.toString(16)}`)
+	if (privileges.capBnd !== 0n) offenders.push(`CapBnd=${privileges.capBnd.toString(16)}`)
+	if (privileges.noNewPrivs !== 1) offenders.push(`NoNewPrivs=${privileges.noNewPrivs}`)
+	if (offenders.length === 0) return
+
+	throw new KubernetesPrivilegeProbeError(
+		'privileged',
+		`kubernetes sandbox ${sandboxName} is PRIVILEGED and was refused: ${offenders.join(
+			', ',
+		)} (every capability mask must be 0 and NoNewPrivs must be 1). The probe ran and was read successfully — this is the guest's real state, not a diagnostic failure. The image's entrypoint is expected to end with \`exec setpriv --reuid --regid --clear-groups --inh-caps=-all --bounding-set=-all --no-new-privs -- tini -- node agent.cjs\`; a sandbox that reaches this message is running with capabilities the workload could use.`,
+	)
+}
+
+/**
+ * Run the probe over an already-built sandbox's `exec` and admit or refuse.
+ *
+ * `run` is the sandbox's own `exec`, not the raw transport, so the probe
+ * traverses exactly the path every later call will: reserve, admit, stream,
+ * confirm. A probe that cannot get through this is a sandbox a caller
+ * cannot use either.
+ */
+export async function runPrivilegeProbe(
+	run: (command: string, args: string[]) => Promise<SandboxExecResult>,
+	sandboxName: string,
+): Promise<ProcStatusPrivileges> {
+	let result: SandboxExecResult
+	try {
+		result = await run(PRIVILEGE_PROBE_COMMAND, [...PRIVILEGE_PROBE_ARGS])
+	} catch (error) {
+		throw new KubernetesPrivilegeProbeError(
+			'probe-failed',
+			`the privilege probe could not run in kubernetes sandbox ${sandboxName}: ${
+				error instanceof Error ? error.message : String(error)
+			}. The probe is \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(
+				' ',
+			)}\`; an image without it on PATH cannot be admitted, because a sandbox whose privileges cannot be checked is refused rather than trusted.`,
+			{ cause: error },
+		)
+	}
+	if (result.exitCode !== 0) {
+		throw new KubernetesPrivilegeProbeError(
+			'probe-failed',
+			`the privilege probe could not run in kubernetes sandbox ${sandboxName}: \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(
+				' ',
+			)}\` exited ${result.exitCode}${
+				result.stderr.trim() ? ` (${clip(result.stderr.trim())})` : ''
+			}. This is a diagnostic failure, not a privilege failure — the sandbox is refused because its state is unknown.`,
+		)
+	}
+
+	const privileges = parseProcStatus(result.stdout)
+	assertDeprivileged(privileges, sandboxName)
+	return privileges
+}
+
+/**
+ * The refusal for a probe that never answered.
+ *
+ * A guest that accepts the TCP connection and then goes quiet — an agent
+ * process out of memory, an event loop blocked by the workload, a container
+ * alive with a listener that has stopped reading — cannot be told apart from
+ * a healthy one by the wire alone, so the caller's acquire budget is the only
+ * thing that ends the wait. That expiry is a `'probe-failed'` like any other
+ * way the probe could not run, but it gets its own words: "the deadline
+ * expired" on its own says nothing about WHICH half of the acquire stopped
+ * answering, and a reader who sees `cat` blamed for a hang goes looking for a
+ * missing binary that is not missing.
+ */
+export function privilegeProbeTimedOut(
+	sandboxName: string,
+	timeoutMs: number,
+	cause: unknown,
+): KubernetesPrivilegeProbeError {
+	return new KubernetesPrivilegeProbeError(
+		'probe-failed',
+		`the privilege probe could not run in kubernetes sandbox ${sandboxName}: the guest accepted the connection and did not answer \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(
+			' ',
+		)}\` within ${timeoutMs} ms, so the probe was abandoned. This is a diagnostic failure, not a privilege failure — the sandbox is refused because its state is unknown. A wedged agent (out of memory, an event loop blocked by the workload) looks exactly like this from the host; check the pod's logs before raising the acquire budget.`,
+		{ cause },
+	)
+}