@namzu/sandbox 14.0.0 → 16.0.0

package/dist/backends/kubernetes/index.js

@@ -77,22 +77,79 @@
  * ## Egress
  *
  * `config.egress` is optional and, when set, translated and VERIFIED — never
- * created — by `egress-policy.ts`. Verification happens once, lazily, on the
- * first `create()`, so `buildKubernetesBackend` itself still contacts
- * nothing. Every Sandbox this file creates directly (`buildSandboxBody`)
- * carries {@link sandboxTemplateLabel} on its podTemplate specifically so
- * that translated policy's `podSelector` has something stable to match —
- * see `objects.ts`'s doc comment on that label for why agent-sandbox's own
- * controller-owned label does not cover this path.
+ * created — by `egress-policy.ts`, in two steps. The NAMED object is GETted
+ * and compared to the translation exactly, once, lazily, on the first
+ * `create()`, so `buildKubernetesBackend` itself still contacts nothing.
+ * Then, because the API server UNIONS every policy selecting a pod, every
+ * `NetworkPolicy` in the namespace (and, under `engine: 'cilium'`, every
+ * `CiliumNetworkPolicy`) is enumerated against the pod's real labels and the
+ * create is refused when any of them lets out more than the translation does
+ * — a second policy widens egress however exactly the named one matches, and
+ * a `SandboxTemplate`'s own `networkPolicy` block becomes exactly such a
+ * policy. `egress.verify: 'named-object-only'` is the opt-out and restores
+ * the first step alone. Every Sandbox this file creates directly
+ * (`buildSandboxBody`) carries {@link sandboxTemplateLabel} on its
+ * podTemplate specifically so that translated policy's `podSelector` has
+ * something stable to match — see `objects.ts`'s doc comment on that label
+ * for why agent-sandbox's own controller-owned label does not cover this
+ * path.
+ *
+ * ## Ingress
+ *
+ * `config.ingress` is the opposite default: verification is ON unless a
+ * deployment says `'unverified'`. Before the POST for a direct Sandbox, and
+ * after the bind for a claimed one, `ingress-policy.ts` lists the namespace's
+ * policies and refuses unless one of them actually closes the agent port on
+ * the labels this pod carries. Nothing checked that before, while three
+ * pieces of shipped text said it was covered — see that module's own doc
+ * comment for what was measured.
  */
 import { generateSandboxId } from '@namzu/sdk';
 import { OperationDeadline, OperationDeadlineExpired, resolveReadinessOptions, runFailureCleanup, } from '../readiness.js';
-import { assertEgressPolicyIsEnforceable, defaultEgressPolicyName, translateEgressPolicy, verifyEgressPolicyApplied, } from './egress-policy.js';
-import { KubernetesAlreadyGoneError, createKubernetesClient, } from './k8s-client.js';
-import { READY_CONDITION, SANDBOX_API_GROUP, SANDBOX_API_VERSION, SANDBOX_EXTENSIONS_API_GROUP, claimCollectionPath, claimPath, isConditionTrue, isPodLive, podListPath, podPath, sandboxCollectionPath, sandboxPath, sandboxTemplateLabel, sandboxTemplatePath, } from './objects.js';
+import { KubernetesPodLabelNotObservedError, KubernetesPodLabelsRejectedError, assertEgressPolicyIsEnforceable, assertEgressProfileIsUsable, assertPerSandboxEgressIsUsable, composeAdditionalPodLabels, defaultEgressPolicyName, egressProfileLabel, egressUnionVerificationEnabled, perSandboxEgressLabelKey, translateEgressPolicy, verifyEgressPolicyApplied, verifyEgressPolicyUnion, } from './egress-policy.js';
+import { ingressVerificationEnabled, resolveIngressEngine, verifyIngressPolicyApplied, } from './ingress-policy.js';
+import { KubernetesAlreadyGoneError, KubernetesApiError, KubernetesApiTimeoutError, KubernetesCredentialError, createKubernetesClient, } from './k8s-client.js';
+import { READY_CONDITION, SANDBOX_API_GROUP, SANDBOX_API_VERSION, SANDBOX_EXTENSIONS_API_GROUP, claimCollectionPath, claimListPath, claimPath, isConditionTrue, isPodLive, podCollectionPath, podListPath, podPath, readPodIP, sandboxCollectionPath, sandboxPath, sandboxTemplateLabel, sandboxTemplatePath, warmPoolPath, } from './objects.js';
+import { KubernetesOwnerUidMissingError, buildAdmissionFence, buildPerSandboxPolicySetter, } from './per-sandbox-policy.js';
 import { privilegeProbeTimedOut, runPrivilegeProbe } from './privilege-probe.js';
 import { buildKubernetesSandbox } from './sandbox.js';
 import { KubernetesAgentTransport } from './transport.js';
+/**
+ * Default {@link KubernetesBackendInternalConfig.streamHeartbeatMs} — 15 s,
+ * so a stream whose peer vanished without a FIN or an RST is given up on
+ * within 45 s rather than never.
+ *
+ * The Kubernetes backend opts IN here; `VsockTransportOptions.heartbeatMs`
+ * stays undefined by default, because that transport is shared with the
+ * Firecracker tier and a default there would force-close an existing
+ * consumer's quiet-but-alive terminal.
+ */
+export const DEFAULT_STREAM_HEARTBEAT_MS = 15_000;
+/**
+ * Validate the configured stream-heartbeat interval, or supply the default.
+ *
+ * `0` IS accepted here, unlike `apiRequestTimeoutMs`: the heartbeat is a new
+ * capability that a deployment behind a middlebox with its own idea about
+ * unexpected frames may want off, and turning it off restores exactly the
+ * behaviour every release before this one had. An unanswered API request has
+ * no such prior behaviour worth restoring.
+ */
+export function resolveStreamHeartbeatMs(value) {
+    if (value === undefined)
+        return DEFAULT_STREAM_HEARTBEAT_MS;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`kubernetes: streamHeartbeatMs must be a non-negative integer, got ${JSON.stringify(value)}. Use 0 to send no heartbeats at all, which is how every release before this one behaved; the default is ${DEFAULT_STREAM_HEARTBEAT_MS}ms.`);
+    }
+    return value;
+}
+/**
+ * The client options every `createKubernetesClient` call in this backend is
+ * built with. One function so the five call sites — the provider, and each
+ * of the workspace verbs — cannot drift apart on which bounds they honour.
+ */
+export function clientOptions(config) {
+    return { requestTimeoutMs: config.apiRequestTimeoutMs };
+}
 /**
  * The same number the Firecracker guest agent listens on over vsock
  * (`DEFAULT_AGENT_VSOCK_PORT`), so one agent has one port across both tiers
@@ -209,51 +266,220 @@ export function buildKubernetesBackend(config) {
     // `config.egress.policy.kind` alone, with no API call, so it is refused
     // here, synchronously, the same moment the two checks above are.
     if (config.egress) {
-        assertEgressPolicyIsEnforceable(config.egress.policy, config.egress.engine ?? 'core');
+        assertEgressPolicyIsEnforceable(config.egress.policy, config.egress.engine ?? 'core', config.egress.ciliumNarrowing);
     }
-    const client = createKubernetesClient(clientAccess(config));
+    // And the same for an egress PROFILE that could never be written as a
+    // label — a value the API server would reject leaves either a claim
+    // nothing binds or a policy nobody can apply, and both are decidable
+    // from config alone.
+    assertEgressProfileIsUsable(config.egress);
+    // And the same for per-sandbox egress: an engine that cannot express a
+    // hostname, an unnamed admission fence or a selector key the API server
+    // would refuse are all decidable from config alone, and a host that
+    // learns any of them from its first `setNetworkPolicy` call learns it an
+    // hour into a run that cannot be redone.
+    assertPerSandboxEgressIsUsable(config.egress);
+    // Resolved here as well as at each session, so a configuration this
+    // backend will never honour is refused while `buildKubernetesBackend` is
+    // still on the stack rather than on someone's first `create()`.
+    resolveStreamHeartbeatMs(config.streamHeartbeatMs);
+    const client = createKubernetesClient(clientAccess(config), clientOptions(config));
     // Verify-not-trust runs once, lazily, on the first `create()` — never here,
     // because `buildKubernetesBackend` is documented to contact nothing. A
     // failed attempt is not cached: a transient API error should not wedge
-    // every later create() behind the same stale rejection forever.
-    let egressVerification;
+    // every later create() behind the same stale rejection forever. The
+    // boundary object holds both halves and both memos; it lives as long as
+    // this backend does, which is what makes the named-object check
+    // once-per-backend rather than once-per-create.
+    const egressBoundary = buildEgressBoundary(client, config, config.sandboxTemplateName);
+    // Ingress is cached PER LABEL SET rather than once per backend, because
+    // unlike the egress NAMED-object check it is a question about one pod: a
+    // pooled sandbox's labels come off the pool's template and a pool-less
+    // one's off this config, and a single memo would answer for a pod it never
+    // examined. Same failure handling as the egress memo — a failed attempt is
+    // dropped, so a transient API error does not wedge every later create()
+    // behind it. The egress UNION check is keyed the same way, for the same
+    // reason, and additionally expires: see {@link EGRESS_UNION_CACHE_TTL_MS}.
+    const ingressVerifier = buildIngressVerifier(client, config, new Map());
+    // One fence per backend, so its memo is shared by every sandbox this
+    // backend hands out rather than re-proved per handle. `undefined` when
+    // per-sandbox egress is not configured, which is what makes
+    // `setNetworkPolicy` absent from the handle — presence follows
+    // CONFIGURATION and never a runtime probe, so a caller's capability
+    // detection cannot depend on when it asked.
+    const perSandbox = config.egress?.perSandbox;
+    const fence = perSandbox === undefined ? undefined : buildAdmissionFence(client, perSandbox);
     return {
         tier: 'microvm',
         name: 'kubernetes',
         async create(options) {
-            if (config.egress) {
-                egressVerification ??= verifyEgressPolicyConfigured(client, config.namespace, config.sandboxTemplateName, config.egress, options.signal).catch((err) => {
-                    egressVerification = undefined;
-                    throw err;
-                });
-                await egressVerification;
-            }
-            const acquisition = await acquireKubernetesSandbox(client, config, options, readiness);
-            return await admitProbedSandbox(acquisition, config, options, resolveProbeTimeoutMs(readiness.timeoutMs));
+            await egressBoundary?.verifyNamedObject(options.signal);
+            const acquisition = await acquireKubernetesSandbox(client, config, options, readiness, ingressVerifier, egressBoundary);
+            const egress = config.egress;
+            const setNetworkPolicy = fence !== undefined &&
+                egress?.perSandbox !== undefined &&
+                acquisition.owner !== undefined &&
+                acquisition.perSandboxLabelValue !== undefined
+                ? buildPerSandboxPolicySetter({
+                    client,
+                    fence,
+                    namespace: config.namespace,
+                    egress: { ...egress, perSandbox: egress.perSandbox },
+                    owner: acquisition.owner,
+                    selectorValue: acquisition.perSandboxLabelValue,
+                })
+                : undefined;
+            return await admitProbedSandbox(acquisition, config, options, resolveProbeTimeoutMs(readiness.timeoutMs), setNetworkPolicy);
         },
     };
 }
 /**
- * Translate `egress.policy` and confirm an operator applied a matching
- * object — the whole verify-not-trust step, isolated so `create()` above
- * stays about ONE thing (memoize-once-per-backend) rather than two.
+ * How long a union pass is trusted for one label set.
  *
- * Exported because `workspace.ts` runs the identical step: a workspace does
- * not go through `buildKubernetesBackend`, and a config `egress` honoured on
- * one entry point and ignored on the other would be a silent downgrade of the
- * boundary this backend calls primary. `sandboxTemplateName` is the template
- * the caller is actually building from — it decides both the default policy
- * name and the pod label the policy's selector has to match, and a workspace
- * may be built from a different template than the task path's.
+ * Five minutes rather than the backend's lifetime, which is what the
+ * named-object check alone used to get: an operator who applies a widening
+ * policy at 10:00 should not have it go unnoticed until the host restarts.
+ * It is a cache, not a watch — `k8s-client.ts`'s "no watch, no informers, no
+ * resourceVersion tracking" invariant is untouched, because the only thing
+ * kept across calls is "this exact label set passed at this time".
  */
-export async function verifyEgressPolicyConfigured(client, namespace, sandboxTemplateName, egress, signal) {
+export const EGRESS_UNION_CACHE_TTL_MS = 5 * 60 * 1_000;
+/**
+ * Build the egress boundary this config asks for, or nothing at all.
+ *
+ * `sandboxTemplateName` is the template the caller is actually building from
+ * — it decides both the default policy name and the pod label the policy's
+ * selector has to match, and a workspace may be built from a different
+ * template than the task path's.
+ *
+ * `now` is injected only so the TTL above can be tested without waiting five
+ * minutes; nothing else passes it.
+ */
+export function buildEgressBoundary(client, config, sandboxTemplateName, now = Date.now) {
+    const egress = config.egress;
+    if (egress === undefined)
+        return undefined;
     const engine = egress.engine ?? 'core';
-    const translated = await translateEgressPolicy(egress.policy, engine, {
-        namespace,
-        name: egress.networkPolicyName ?? defaultEgressPolicyName(sandboxTemplateName),
+    // One resolution of the profile, shared by the policy NAME and the policy
+    // SELECTOR: under a profile the default name gains the profile segment
+    // (one template under two profiles is two policy objects) and the
+    // selector gains the label, and the two must not be able to disagree.
+    const profile = egressProfileLabel(egress);
+    const target = {
+        namespace: config.namespace,
+        name: egress.networkPolicyName ?? defaultEgressPolicyName(sandboxTemplateName, profile?.value),
         sandboxTemplateName,
-    });
-    await verifyEgressPolicyApplied(client, translated, signal);
+        ...(profile !== undefined ? { profile } : {}),
+    };
+    // Translated ONCE per boundary, not once per check: a `resolver` policy's
+    // `resolve()` is the host's own closure and may cost a network call, and
+    // running the two checks against two independently resolved allowlists
+    // would compare each against a different translation.
+    let translation;
+    const translate = () => {
+        translation ??= translateEgressPolicy(egress.policy, engine, target, egress.ciliumNarrowing).catch((err) => {
+            translation = undefined;
+            throw err;
+        });
+        return translation;
+    };
+    let namedObject;
+    const passes = new Map();
+    // The per-sandbox selector label carries a once-ever value, so it is
+    // excluded from the memo key — see {@link policyCacheKey}. Resolved once
+    // here rather than per check, because the resolver validates as it
+    // resolves and a per-check throw would surface from a cache lookup.
+    const perSandboxKey = perSandboxEgressLabelKey(egress);
+    return {
+        async verifyNamedObject(signal) {
+            namedObject ??= (async () => {
+                await verifyEgressPolicyApplied(client, await translate(), signal);
+            })().catch((err) => {
+                namedObject = undefined;
+                throw err;
+            });
+            await namedObject;
+        },
+        async verifyUnion(podLabels, subject, signal) {
+            if (!egressUnionVerificationEnabled(egress))
+                return;
+            const translated = await translate();
+            const key = policyCacheKey(podLabels, perSandboxKey);
+            const cached = passes.get(key);
+            if (cached !== undefined && now() - cached.at < EGRESS_UNION_CACHE_TTL_MS) {
+                await cached.pending;
+                return;
+            }
+            const pending = verifyEgressPolicyUnion(client, translated, { namespace: config.namespace, podLabels, engine, subject }, signal).catch((err) => {
+                // A failed attempt is never cached — same rule the named-object
+                // memo has always had.
+                passes.delete(key);
+                throw err;
+            });
+            passes.set(key, { at: now(), pending });
+            await pending;
+        },
+    };
+}
+/**
+ * Canonical key for one label set — order-independent, so two spellings of
+ * the same pod share a memo.
+ *
+ * `excludeKey` drops the PER-SANDBOX egress label, whose value is unique per
+ * acquire. Both memos exist to amortise a namespace-wide policy enumeration
+ * across every sandbox a backend produces, and a key that carried a
+ * once-ever value would give every acquire a miss and leave an entry behind
+ * that nothing ever looks up again — a full enumeration per sandbox, and a
+ * Map that grows for the host's whole life.
+ *
+ * Dropping it is sound at the moment these checks run: the only policy that
+ * could select a pod BY that key and value is that sandbox's own, whose name
+ * is generated in the same call and which does not exist yet. Every other
+ * policy selecting the pod — the operator's baseline, a per-profile one,
+ * anything hand-written — selects on the labels that remain, so two pods
+ * differing only in this label are the same question. The label itself is
+ * still PRESENT in the label set each check is run against; only the memo's
+ * key ignores it.
+ */
+function policyCacheKey(podLabels, excludeKey) {
+    return JSON.stringify(Object.entries(podLabels)
+        .filter(([k]) => k !== excludeKey)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+/**
+ * Build the ingress check this config asks for, or nothing at all.
+ *
+ * `cache` is the provider path's per-label-set memo; a workspace passes none,
+ * and re-checks on every call for the same reason its egress check does —
+ * creating a workspace is a rare, explicit act with nothing to amortise, and
+ * a policy deleted since the last call must be noticed.
+ */
+export function buildIngressVerifier(client, config, cache) {
+    if (!ingressVerificationEnabled(config.ingress))
+        return undefined;
+    const engine = resolveIngressEngine(config.ingress, config.egress?.engine);
+    const agentPort = config.agentPort ?? DEFAULT_AGENT_PORT;
+    // Same exclusion, same reason, as the egress union memo above: a
+    // once-ever label value in the key would make this memo a per-acquire
+    // miss and an unbounded Map. See {@link policyCacheKey}.
+    const perSandboxKey = perSandboxEgressLabelKey(config.egress);
+    return async (podLabels, subject, signal) => {
+        const target = { namespace: config.namespace, podLabels, agentPort, engine, subject };
+        if (cache === undefined) {
+            await verifyIngressPolicyApplied(client, target, signal);
+            return;
+        }
+        const key = policyCacheKey(podLabels, perSandboxKey);
+        let pending = cache.get(key);
+        if (pending === undefined) {
+            pending = verifyIngressPolicyApplied(client, target, signal).catch((err) => {
+                cache.delete(key);
+                throw err;
+            });
+            cache.set(key, pending);
+        }
+        await pending;
+    };
 }
 /** Config → the client's own access shape. Shared with `workspace.ts`. */
 export function clientAccess(config) {
@@ -267,6 +493,359 @@ export function clientAccess(config) {
         ...(access.ca !== undefined ? { ca: access.ca } : {}),
     };
 }
+/**
+ * An acquire that was refused, carrying WHY in a field rather than in prose.
+ *
+ * Before this class a burst past node capacity and an API outage were the
+ * same plain `Error`, and a host could only tell them apart by matching
+ * message text that any release is free to reword. `reason` is the diagnosis,
+ * `retryable` is the advice that follows from it, and `cause` is the original
+ * failure — unmodified, so a host that already catches
+ * {@link ReadinessPollTimeout}, {@link KubernetesApiTimeoutError} or
+ * `KubernetesCredentialError` finds it there.
+ *
+ * `retryable` is about THIS acquire being worth attempting again, not about
+ * anything having been retried. Transient API failures are already retried
+ * inside the readiness budget, so a `retryable: true` that reaches a caller
+ * means the whole budget was spent on them.
+ *
+ * Not every acquire failure becomes one of these, and that is deliberate: a
+ * refusal this class cannot honestly diagnose — a malformed template, a 400
+ * from an admission webhook, a controller that reported Ready and named no
+ * sandbox — travels out as itself rather than being filed under whichever of
+ * the seven reasons is least wrong. `KubernetesApiError` carries the status
+ * for those.
+ */
+export class KubernetesAcquireError extends Error {
+    name = 'KubernetesAcquireError';
+    reason;
+    /** Whether attempting the same acquire again could plausibly succeed. */
+    retryable;
+    /**
+     * `status.conditions[Ready].reason`, verbatim, when the controller
+     * refused the claim — `WarmPoolNotFound`, `TemplateNotFound`,
+     * `InvalidMetadata`, `EnvVarsInjectionRejected`. Present only for
+     * `'claim-rejected'`.
+     */
+    controllerReason;
+    /** The controller's own message for the same condition. */
+    controllerMessage;
+    constructor(details) {
+        super(details.message, details.cause !== undefined ? { cause: details.cause } : undefined);
+        this.reason = details.reason;
+        this.retryable = details.retryable;
+        if (details.controllerReason !== undefined)
+            this.controllerReason = details.controllerReason;
+        if (details.controllerMessage !== undefined)
+            this.controllerMessage = details.controllerMessage;
+    }
+}
+/**
+ * The `status.conditions[Ready].reason` values that mean the controller has
+ * DECIDED, so waiting is pointless.
+ *
+ * ## Where these strings came from
+ *
+ * Not from the issue that asked for this, and not from upstream source: this
+ * repo vendors none of agent-sandbox's Go, so a literal copied out of a
+ * changelog is a literal nobody here can check. Each of the four was produced
+ * against the deployed controller (kind v1.37.0, agent-sandbox v1.0.2,
+ * 2026-09-17) by making the claim it describes and reading the condition
+ * back:
+ *
+ * | reason | how it was produced | the controller's message |
+ * |---|---|---|
+ * | `WarmPoolNotFound` | claim at a pool that does not exist | `SandboxWarmPool "…" not found` |
+ * | `TemplateNotFound` | claim at a pool whose template does not exist | `SandboxTemplate "…" not found` |
+ * | `InvalidMetadata` | claim with an `additionalPodMetadata` label outside the allowed domains | `invalid additionalPodMetadata: …` |
+ * | `EnvVarsInjectionRejected` | claim with `spec.env` against a template that forbids injection | `environment variable injection rejected: …` |
+ *
+ * The transient reasons seen on the SAME cluster, which must NOT be in this
+ * set, were `DependenciesNotReady` (pod exists, still Pending) and
+ * `DependenciesReady` (the Ready=True reason).
+ *
+ * ## Why an unknown reason is not terminal
+ *
+ * A wrong literal here fails in one of two ways, and only one of them is
+ * recoverable. Too few entries: a rejected claim waits out the readiness
+ * budget, which is exactly the behaviour every release before this one had.
+ * Too many: an acquire that would have succeeded is refused on a guess. So
+ * the set is a closed list of measured strings and everything else falls
+ * through to the deadline.
+ */
+// Frozen because it is exported from the package root: an array handed to
+// every consumer is one a cast can push onto, and an entry added there would
+// change fail-fast for the whole process. The `readonly string[]` annotation
+// is deliberate rather than `as const` — `includes` on a literal tuple only
+// accepts the literals, and the whole point is to ask it about a reason no
+// one here has seen.
+export const TERMINAL_CLAIM_REASONS = Object.freeze([
+    'WarmPoolNotFound',
+    'TemplateNotFound',
+    'InvalidMetadata',
+    'EnvVarsInjectionRejected',
+]);
+/**
+ * The `Ready` condition a claim reports, whatever its status — the one
+ * {@link isConditionTrue} deliberately cannot return, because it answers a
+ * boolean question and this one needs the reason.
+ */
+function readyCondition(conditions) {
+    return conditions?.find((c) => c.type === READY_CONDITION);
+}
+/**
+ * A claim the controller has refused, or `undefined` for one it is still
+ * working on.
+ *
+ * `status: 'False'` alone is not a refusal — it is also what a claim looks
+ * like for the whole of a cold start — so the REASON decides, against
+ * {@link TERMINAL_CLAIM_REASONS}.
+ *
+ * ONE class comes out of here whatever the reason, and that is deliberate:
+ * `InvalidMetadata` is how the controller refuses a pod label whose domain is
+ * not on its allowlist — the profile's, today — and a host's `catch` must not
+ * have to be written differently depending on whether a profile happens to be
+ * configured. `metadata` only decides what rides along as the `cause`: a
+ * {@link KubernetesPodLabelsRejectedError} naming the map that was sent
+ * and the `config.egress.profileLabelKey` that moves it, which the
+ * controller's own message cannot know about.
+ */
+export function classifyClaimRejection(claim, claimName, metadata) {
+    const condition = readyCondition(claim?.status?.conditions);
+    if (condition === undefined || condition.status !== 'False')
+        return undefined;
+    const reason = condition.reason;
+    if (reason === undefined || !TERMINAL_CLAIM_REASONS.includes(reason))
+        return undefined;
+    // Only for the reason the pod metadata can actually cause, and only when
+    // this backend sent any: a `WarmPoolNotFound` carrying a labels-and-
+    // allowlist explanation would send an operator after the wrong thing.
+    const cause = reason === 'InvalidMetadata' &&
+        metadata !== undefined &&
+        Object.keys(metadata.requestedPodLabels).length > 0
+        ? new KubernetesPodLabelsRejectedError(metadata.requestedPodLabels, claimName, metadata.namespace, reason, condition.message ?? '(the controller reported no message)', metadata.profile)
+        : undefined;
+    return new KubernetesAcquireError({
+        reason: 'claim-rejected',
+        retryable: false,
+        controllerReason: reason,
+        ...(condition.message !== undefined ? { controllerMessage: condition.message } : {}),
+        ...(cause !== undefined ? { cause } : {}),
+        message: `kubernetes: the agent-sandbox controller refused SandboxClaim ${claimName} with reason ${reason}${condition.message !== undefined ? `: ${condition.message}` : ''}. That is a decision, not a delay, so the readiness budget was not waited out.${cause !== undefined ? ` ${cause.message}` : ''}`,
+    });
+}
+/**
+ * How long to wait before repeating a failed readiness read, or `undefined`
+ * when the failure is not worth repeating.
+ *
+ * Retryable: a connect failure (the socket, not the answer), a request the
+ * `apiRequestTimeoutMs` bound gave up on, a 429 (the API server's own
+ * priority-and-fairness queue shedding load) and any 5xx. Not retryable: 401
+ * and 403, which are a decision; 404 and 410, which are an answer; 409, which
+ * a caller resolves by re-reading; and everything this backend threw itself.
+ *
+ * The wait is the poll's own cadence unless the server named one — then its
+ * `Retry-After`, because the server knows when its queue drains and this code
+ * does not. Nothing here consults a clock: the caller's deadline owns the
+ * sleep, so a long `Retry-After` spends the readiness budget rather than
+ * extending it.
+ */
+/**
+ * The largest delay a timer can hold — `2^31 - 1` ms, Node's own ceiling.
+ * Above it `setTimeout` warns and fires immediately, which is the opposite of
+ * what a long `Retry-After` asked for.
+ */
+const MAX_RETRY_DELAY_MS = 2_147_483_647;
+export function retryDelayForApiFailure(err, pollIntervalMs) {
+    if (err instanceof KubernetesApiTimeoutError)
+        return pollIntervalMs;
+    if (!(err instanceof KubernetesApiError))
+        return undefined;
+    if (err.transport === 'connect')
+        return pollIntervalMs;
+    const status = err.status;
+    if (status === undefined)
+        return undefined;
+    // `Retry-After` may only ever SLOW the poll down, and only within what a
+    // timer can express. A header of `0`, or one naming a moment already past,
+    // would otherwise turn the retry into a hot loop against a server that is
+    // already shedding load — the caller's own cadence is the rate this loop
+    // runs at when nothing is wrong. And a header naming a moment years away
+    // overflows `setTimeout`, which then fires at once rather than never,
+    // producing the same hot loop from the opposite direction. The readiness
+    // deadline ends the wait either way; the clamp only stops the wait from
+    // silently becoming no wait at all.
+    if (status === 429 || status >= 500) {
+        const asked = err.retryAfterMs ?? pollIntervalMs;
+        return Math.min(Math.max(asked, pollIntervalMs), MAX_RETRY_DELAY_MS);
+    }
+    return undefined;
+}
+/**
+ * How long the one diagnostic pod read after a failed acquire may take.
+ *
+ * Same shape and the same argument as `runFailureCleanup`'s grace: the
+ * readiness clock has already expired, so this cannot share it, and a
+ * diagnosis that could hang would keep `create()` pending past the budget the
+ * caller chose — for a nicer error message. One second, and a diagnosis that
+ * does not arrive is simply not made.
+ */
+const ACQUIRE_DIAGNOSIS_GRACE_MS = 1_000;
+/**
+ * The image-pull `status.containerStatuses[].state.waiting.reason` values the
+ * kubelet reports. Measured on kind v1.37.0 (2026-09-17): a container whose
+ * image does not exist waits as `ErrImagePull` for the first attempts and
+ * settles into `ImagePullBackOff`. The other two are the kubelet's names for
+ * a pull that resolved and then failed, and for a registry that cannot be
+ * reached at all.
+ */
+const IMAGE_PULL_WAITING_REASONS = [
+    'ErrImagePull',
+    'ImagePullBackOff',
+    'ImageInspectError',
+    'RegistryUnavailable',
+];
+/**
+ * Ask the pod why it is not ready, once, after the budget has already gone.
+ *
+ * Nothing on the healthy path calls this and nothing waits on it: it runs
+ * exactly when an acquire has already failed, and its whole output is a
+ * better {@link KubernetesAcquireFailureReason} than `'not-ready'`. A read
+ * that fails, a pod that is not there and a pod with nothing to say all
+ * produce `undefined`, which leaves the reason where it was.
+ *
+ * It must run BEFORE the cleanup DELETE, because the pod goes away with the
+ * object it belongs to.
+ *
+ * It takes the CALLER's signal where `runFailureCleanup` deliberately does
+ * not: cleanup must finish or the cluster keeps the object, while a diagnosis
+ * is only a better sentence for an error a caller who aborted will never
+ * read.
+ */
+async function diagnoseUnreadyPod(client, namespace, podName, callerSignal) {
+    let pod;
+    try {
+        const deadline = new OperationDeadline(ACQUIRE_DIAGNOSIS_GRACE_MS, 'kubernetes acquire diagnosis', callerSignal);
+        pod = await deadline.run((signal) => client.request('GET', podPath(namespace, podName), undefined, signal));
+    }
+    catch {
+        // The acquire failure is the primary one and keeps its reason. A
+        // diagnosis that cannot be made is not a second failure to report.
+        return undefined;
+    }
+    const scheduled = pod?.status?.conditions?.find((c) => c.type === 'PodScheduled');
+    if (scheduled?.status === 'False' && scheduled.reason === 'Unschedulable')
+        return 'capacity';
+    for (const container of pod?.status?.containerStatuses ?? []) {
+        const reason = container.state?.waiting?.reason;
+        if (reason !== undefined && IMAGE_PULL_WAITING_REASONS.includes(reason))
+            return 'image-pull';
+    }
+    return undefined;
+}
+/**
+ * The refusal a caller sees, given the failure that actually happened and
+ * whatever the pod had to say about it.
+ *
+ * Returns `undefined` for a failure none of the seven reasons describes —
+ * see {@link KubernetesAcquireError} for why that is a deliberate hole rather
+ * than a missing case. A {@link KubernetesAcquireError} that arrived from
+ * deeper in (the claim rejection) is returned unchanged: it is already the
+ * diagnosis.
+ */
+export function classifyAcquireFailure(err, podDiagnosis) {
+    if (err instanceof KubernetesAcquireError)
+        return err;
+    if (err instanceof KubernetesApiTimeoutError) {
+        return new KubernetesAcquireError({
+            reason: 'api-timeout',
+            retryable: true,
+            message: `kubernetes: the acquire was refused because the API server did not answer in time — ${err.message}`,
+            cause: err,
+        });
+    }
+    if (err instanceof KubernetesCredentialError) {
+        return new KubernetesAcquireError({
+            reason: 'forbidden',
+            retryable: false,
+            message: `kubernetes: the acquire was refused because the API server rejected this host's credential — ${err.message}. Check the host ServiceAccount's Role against the RBAC section of the Kubernetes sandbox documentation.`,
+            cause: err,
+        });
+    }
+    if (err instanceof KubernetesApiError) {
+        // The same predicate the poll retries on, so "worth trying again" has
+        // one definition and a caller cannot be told a failure is retryable
+        // that the poll would have declined to retry. The interval is
+        // irrelevant here — only whether an answer comes back at all.
+        if (retryDelayForApiFailure(err, 1) === undefined)
+            return undefined;
+        return new KubernetesAcquireError({
+            reason: 'api-unreachable',
+            retryable: true,
+            message: `kubernetes: the acquire was refused because the API server could not serve it — ${err.message}`,
+            cause: err,
+        });
+    }
+    if (err instanceof ReadinessPollTimeout) {
+        // ORDER MATTERS, and this is the order: what the cluster SAID beats
+        // what the failures suggest. A pod diagnosis is a condition the API
+        // server published about this pod, read after the budget had already
+        // gone; `err.cause` is at best the failure the poll was still meeting
+        // at that moment. On a saturated cluster both are present at once — a
+        // pod nothing can schedule AND an API server shedding load — and
+        // reporting `api-unreachable` there would hide the very reason this
+        // function exists to produce, and would turn `image-pull`'s
+        // `retryable: false` into a `true` that has a host retrying forever
+        // against an image reference that will never resolve. A diagnosis also
+        // cannot be stale in the way a cause can: it only exists because the
+        // API server answered one more read, moments ago.
+        if (podDiagnosis === 'capacity') {
+            return new KubernetesAcquireError({
+                reason: 'capacity',
+                retryable: true,
+                message: `kubernetes: the acquire was refused because its pod could not be scheduled — the cluster reports PodScheduled=False/Unschedulable. ${err.message}`,
+                cause: err,
+            });
+        }
+        if (podDiagnosis === 'image-pull') {
+            return new KubernetesAcquireError({
+                reason: 'image-pull',
+                retryable: false,
+                message: `kubernetes: the acquire was refused because its pod's container image will not pull. ${err.message}`,
+                cause: err,
+            });
+        }
+        // Nothing measured, so the failures the poll kept meeting decide: a
+        // poll that spent its budget retrying API failures did not fail
+        // because the sandbox was slow; it failed because the control plane
+        // was. `pollForBinding` carries the failure it was STILL meeting onto
+        // the timeout, and the reason follows it rather than the timeout.
+        const underlying = classifyAcquireFailure(err.cause, undefined);
+        if (underlying !== undefined) {
+            return new KubernetesAcquireError({
+                reason: underlying.reason,
+                retryable: underlying.retryable,
+                message: underlying.message,
+                cause: err,
+            });
+        }
+        return new KubernetesAcquireError({
+            reason: 'not-ready',
+            retryable: true,
+            message: err.message,
+            cause: err,
+        });
+    }
+    if (err instanceof OperationDeadlineExpired) {
+        return new KubernetesAcquireError({
+            reason: 'not-ready',
+            retryable: true,
+            message: `kubernetes: the acquire ran out of readiness budget — ${err.message}`,
+            cause: err,
+        });
+    }
+    return undefined;
+}
 /**
  * Claim or create, wait for Ready, read the bound identity back, resolve the
  * address and learn the pod's uid — or leave nothing behind trying.
@@ -274,8 +853,29 @@ export function clientAccess(config) {
  * Exported because the sandbox surface is built on top of this record rather
  * than beside it: one acquire path, one cleanup path, whatever ends up
  * wrapping them.
+ *
+ * ## What it refuses with
+ *
+ * Every refusal this function can diagnose arrives as a
+ * {@link KubernetesAcquireError} naming one of seven reasons, with the
+ * original failure as its `cause`. Three things stay outside that:
+ * configuration refused before anything is created
+ * ({@link assertEnforceable}, {@link assertRuntimeClassIsApplicable}), a
+ * caller's own abort, and a failure none of the seven reasons honestly
+ * describes — see {@link KubernetesAcquireError} for why the last one is a
+ * hole on purpose.
+ *
+ * ## What it retries, and what it will not
+ *
+ * A readiness GET that fails transiently — a connect failure, a request the
+ * API bound gave up on, a 429, a 5xx — is repeated INSIDE the readiness
+ * deadline, honouring `Retry-After`. One clock, so a retry spends the budget
+ * rather than extending it, and a `create()` cannot outlive the timeout its
+ * caller chose. The create POST is never retried: it is not idempotent, and a
+ * POST whose answer never arrived may already have committed — which is why
+ * cleanup deletes the client-owned name whatever happened.
  */
-export async function acquireKubernetesSandbox(client, config, options, readiness) {
+export async function acquireKubernetesSandbox(client, config, options, readiness, verifyIngress = buildIngressVerifier(client, config), egressBoundary = buildEgressBoundary(client, config, config.sandboxTemplateName)) {
     options.signal?.throwIfAborted();
     assertEnforceable(options);
     assertRuntimeClassIsApplicable(config);
@@ -324,36 +924,183 @@ export async function acquireKubernetesSandbox(client, config, options, readines
     const createPath = config.warmPoolName !== undefined
         ? claimCollectionPath(namespace)
         : sandboxCollectionPath(namespace);
-    const createBody = config.warmPoolName !== undefined
-        ? buildClaimBody(namespace, objectName, config.warmPoolName, shutdownTime)
-        : buildSandboxBody({
+    // Composed ONCE, here, and handed to whichever body builder runs below:
+    // the claim's `additionalPodMetadata.labels` and a direct Sandbox's pod
+    // template metadata are the same map, and the translated policy's selector
+    // is built from the same resolution. See `composeAdditionalPodLabels`.
+    // Empty — the only case before a profile is configured — means every body
+    // below is byte for byte what it was.
+    // The per-sandbox selector label rides in the SAME map, through the same
+    // composer, as a second key rather than a second construction — the whole
+    // reason `composeAdditionalPodLabels` takes an `extra`. Its value is the
+    // name of the object this acquire is about to create, which is unique per
+    // acquire and known BEFORE the POST: that is what lets the label travel as
+    // claim-time pod metadata (warm-safe, no cold start) instead of as a patch
+    // to a running pod this backend has no verb for.
+    const perSandboxLabelKey = perSandboxEgressLabelKey(config.egress);
+    const podLabels = composeAdditionalPodLabels(config.egress, perSandboxLabelKey !== undefined ? { [perSandboxLabelKey]: objectName } : undefined);
+    const profile = egressProfileLabel(config.egress);
+    // Read off the create reply, and off the readiness polls if that reply
+    // carried no object — it is the uid a per-sandbox policy's
+    // `ownerReferences` names and the suffix of its name, so the cluster can
+    // garbage-collect the policy with the object this backend owns.
+    let ownerUid;
+    const buildCreateBody = async () => {
+        if (config.warmPoolName !== undefined) {
+            return buildClaimBody({
+                namespace,
+                name: objectName,
+                warmPoolName: config.warmPoolName,
+                shutdownTime,
+                ...(config.claimLabels !== undefined ? { labels: config.claimLabels } : {}),
+                podLabels,
+            });
+        }
+        const template = await deadline.run((signal) => readSandboxTemplate(client, namespace, config.sandboxTemplateName, signal));
+        // A direct Sandbox's pod labels are decided HERE, by the body below,
+        // so both network boundaries are checked against the real labels before
+        // anything is created — a refusal leaves no Sandbox and no PVC behind
+        // rather than one of each to clean up. This is EARLIER than the plan
+        // for the egress union check asked for (it said "after binding", for
+        // the bound pod's labels); a pool-less Sandbox's labels are knowable
+        // before the POST, and refusing with nothing created is strictly
+        // better than refusing with an object to clean up.
+        const directPodLabels = sandboxPodLabels(template, config.sandboxTemplateName, podLabels);
+        const directSubject = `to create Sandbox ${objectName} in namespace ${namespace}`;
+        if (verifyIngress !== undefined) {
+            await deadline.run((signal) => verifyIngress(directPodLabels, directSubject, signal));
+        }
+        if (egressBoundary !== undefined) {
+            await deadline.run((signal) => egressBoundary.verifyUnion(directPodLabels, directSubject, signal));
+        }
+        return buildSandboxBody({
             namespace,
             name: objectName,
-            template: await deadline.run((signal) => readSandboxTemplate(client, namespace, config.sandboxTemplateName, signal)),
+            template,
             sandboxTemplateName: config.sandboxTemplateName,
             shutdownTime,
+            podLabels,
             ...(config.runtimeClassName !== undefined
                 ? { runtimeClassName: config.runtimeClassName }
                 : {}),
         });
+    };
+    let createBody;
+    try {
+        createBody = await buildCreateBody();
+    }
+    catch (err) {
+        // Nothing exists yet, so there is nothing to clean up and no pod to
+        // ask — but a 403 on the template read is still a `forbidden` acquire,
+        // and a caller should not have to tell that apart by where it
+        // happened.
+        throw classifyAcquireFailure(err, undefined) ?? err;
+    }
+    // The pod the diagnosis below asks, when there is one. A directly created
+    // Sandbox is backed by a pod of its own name; a CLAIM's pod is not knowable
+    // until the controller has named a sandbox in `status.sandbox`, which it
+    // does before Ready on a cold start and never on a rejected claim.
+    let diagnosablePodName = config.warmPoolName !== undefined ? undefined : objectName;
+    // One definition of "worth trying again", shared by the poll that retries
+    // and the classification that reports — see {@link retryDelayForApiFailure}.
+    const pollBehaviour = {
+        retryDelayFor: (err) => retryDelayForApiFailure(err, readiness.pollIntervalMs),
+    };
     try {
         // Inside the cleanup block: a POST that fails client-side may still have
         // committed, so the only safe assumption is that the object exists.
-        await deadline.run((signal) => client.request('POST', createPath, createBody, signal));
+        const created = await deadline.run((signal) => client.request('POST', createPath, createBody, signal));
+        ownerUid ??= created?.metadata?.uid;
         const binding = config.warmPoolName !== undefined
-            ? await pollForBinding(async (signal) => bindingFromClaim(await client.request('GET', claimPath(namespace, objectName), undefined, signal), objectName), deadline, readiness, `claim ${objectName}`)
-            : await pollForBinding(async (signal) => bindingFromSandbox(await client.request('GET', sandboxPath(namespace, objectName), undefined, signal)), deadline, readiness, `sandbox ${objectName}`);
-        const token = await deadline.run((signal) => readPodBindToken(client, namespace, binding, signal));
+            ? await pollForBinding(async (signal) => {
+                const claim = await client.request('GET', claimPath(namespace, objectName), undefined, signal);
+                diagnosablePodName = claim?.status?.sandbox?.name ?? diagnosablePodName;
+                ownerUid ??= claim?.metadata?.uid;
+                // The pod labels this backend asked the controller for
+                // travel into the read, not because the fail-fast needs
+                // them — `InvalidMetadata` is already one of
+                // `TERMINAL_CLAIM_REASONS`, and that is the ONE
+                // taxonomy a refused claim is reported under — but so
+                // the refusal can carry what was actually sent and how
+                // to change it. See {@link ClaimPodMetadataContext}.
+                return bindingFromClaim(claim, objectName, {
+                    namespace,
+                    requestedPodLabels: podLabels,
+                    ...(profile !== undefined ? { profile } : {}),
+                });
+            }, deadline, readiness, `claim ${objectName}`, pollBehaviour)
+            : await pollForBinding(async (signal) => {
+                const sandbox = await client.request('GET', sandboxPath(namespace, objectName), undefined, signal);
+                ownerUid ??= sandbox?.metadata?.uid;
+                return bindingFromSandbox(sandbox);
+            }, deadline, readiness, `sandbox ${objectName}`, pollBehaviour);
+        const agentPort = config.agentPort ?? DEFAULT_AGENT_PORT;
+        const mode = config.agentAddress ?? 'service';
+        // One read, two facts: the bind token and — under `'pod-ip'` — the
+        // address, off the same pod. See {@link readAddressedPod}, which under
+        // a configured profile also waits for the label the controller
+        // patches onto the bound pod before anything is admitted.
+        const pod = await readAddressedPod(client, namespace, binding, deadline, readiness, mode, podLabels);
+        // The one refusal this capability must not skip: an unlabelled pod
+        // handed back runs under whatever policy DOES select it while the host
+        // believes it is on a narrower profile. This throws INSIDE the try
+        // block, so the cleanup below releases the claim (or deletes the
+        // Sandbox) exactly as a failed privilege probe does — and the probe
+        // itself, which runs in `admitProbedSandbox` after this function
+        // returns, is therefore never reached with the label unobserved.
+        assertRequestedPodLabelsObserved(pod, podLabels, `Sandbox ${binding.name} in namespace ${namespace}`);
+        // A CLAIMED sandbox's pod was built from the pool's own template, so
+        // its labels are not knowable until the controller has bound one.
+        // Checking here rather than not at all is the trade: a refusal
+        // releases the claim through the cleanup below, which is the same
+        // path a failed privilege probe takes.
+        if (config.warmPoolName !== undefined) {
+            const boundSubject = `the pod bound to Sandbox ${binding.name} in namespace ${namespace}`;
+            if (verifyIngress !== undefined) {
+                await deadline.run((signal) => verifyIngress(pod.labels ?? {}, boundSubject, signal));
+            }
+            // The egress union check asks the same question of the same labels
+            // — which policies select THIS pod — so it runs at the same two
+            // points, and a refusal here releases the claim through the cleanup
+            // below, exactly as a failed privilege probe does.
+            if (egressBoundary !== undefined) {
+                await deadline.run((signal) => egressBoundary.verifyUnion(pod.labels ?? {}, boundSubject, signal));
+            }
+        }
+        // Only when the capability is configured, and only after the pod has
+        // been confirmed to carry the selector label: a policy written for a
+        // pod that never got the label would select nothing while the caller
+        // was told its egress had been narrowed.
+        const owner = perSandboxLabelKey === undefined
+            ? undefined
+            : {
+                kind: (config.warmPoolName !== undefined ? 'SandboxClaim' : 'Sandbox'),
+                name: objectName,
+                uid: assertOwnerUid(ownerUid, objectName, namespace),
+            };
         return {
             binding,
-            agent: resolveAgentAddress(binding, config.agentPort ?? DEFAULT_AGENT_PORT, token),
+            agent: resolveAgentAddress(binding, agentPort, pod.uid, {
+                mode,
+                ...(pod.podIP !== undefined ? { podIP: pod.podIP } : {}),
+            }),
+            // Only the literal-address mode gets one — see the field.
+            ...(mode === 'pod-ip'
+                ? { refreshAgent: buildAgentAddressRefresh(client, namespace, binding, agentPort, mode) }
+                : {}),
             ownedPath,
+            ...(owner !== undefined ? { owner, perSandboxLabelValue: objectName } : {}),
             ttlSeconds,
             release,
             renew,
         };
     }
     catch (err) {
+        // Asked BEFORE cleanup, because the pod goes away with the object, and
+        // only for a timeout — every other failure already knows what it was.
+        const podDiagnosis = err instanceof ReadinessPollTimeout && diagnosablePodName !== undefined
+            ? await diagnoseUnreadyPod(client, namespace, diagnosablePodName, options.signal)
+            : undefined;
         // One cleanup for every way out of the block above, on its own short
         // budget: the readiness clock has already expired in the common case,
         // so spending it again would either skip cleanup or leave `create()`
@@ -361,29 +1108,148 @@ export async function acquireKubernetesSandbox(client, config, options, readines
         await runFailureCleanup(async (signal) => {
             await release(signal);
         });
-        throw err;
+        throw classifyAcquireFailure(err, podDiagnosis) ?? err;
     }
 }
-/**
- * The claim body, in full. Everything absent from it is absent on purpose:
- * no `env`, no `volumeClaimTemplates`, no `additionalPodMetadata`. Either of
- * the first two forces a cold start upstream and takes the warm pool away.
- *
- * `shutdownTime` + `shutdownPolicy: 'Delete'` is the leak guard: it bounds the
- * object by the wall clock whatever the host does, so a host that dies
- * mid-acquire costs the cluster one TTL rather than one leaked sandbox
- * forever. `ttlSecondsAfterFinished` deliberately does NOT appear — its timer
- * starts from the Finished condition, which a crashed host never reaches.
- */
-function buildClaimBody(namespace, name, warmPoolName, shutdownTime) {
+function buildClaimBody(options) {
+    const { labels, podLabels } = options;
     return {
         apiVersion: `${SANDBOX_EXTENSIONS_API_GROUP}/${SANDBOX_API_VERSION}`,
         kind: 'SandboxClaim',
-        metadata: { name, namespace },
+        metadata: {
+            name: options.name,
+            namespace: options.namespace,
+            ...(labels !== undefined && Object.keys(labels).length > 0 ? { labels } : {}),
+        },
         spec: {
-            warmPoolRef: { name: warmPoolName },
-            lifecycle: { shutdownTime, shutdownPolicy: 'Delete' },
+            warmPoolRef: { name: options.warmPoolName },
+            ...(podLabels !== undefined && Object.keys(podLabels).length > 0
+                ? { additionalPodMetadata: { labels: podLabels } }
+                : {}),
+            lifecycle: { shutdownTime: options.shutdownTime, shutdownPolicy: 'Delete' },
+        },
+    };
+}
+/**
+ * Refuse a bound pod that does not carry EVERY label this backend asked the
+ * controller to put on it — the egress profile today, and whatever else
+ * `composeAdditionalPodLabels` later contributes to the same map.
+ *
+ * The same set {@link readAddressedPod} waits for, deliberately: a wait that
+ * covered more than the refusal would burn the readiness budget on a label
+ * nothing then checked, and a refusal that covered more than the wait would
+ * refuse a pod that had simply not been patched yet. An empty map (the
+ * unprofiled path) checks nothing and returns.
+ *
+ * Called after {@link readAddressedPod} has already waited on the readiness
+ * deadline, so reaching a missing label here means it never arrived, not that
+ * it had not arrived yet.
+ */
+function assertRequestedPodLabelsObserved(pod, requested, subject) {
+    for (const [key, value] of Object.entries(requested)) {
+        if (pod.labels?.[key] === value)
+            continue;
+        throw new KubernetesPodLabelNotObservedError({ key, value }, subject, pod.labels ?? {});
+    }
+}
+/**
+ * The uid of the object this acquire created, or a refusal naming what was
+ * missing.
+ *
+ * Only reached when `config.egress.perSandbox` is configured, and only after
+ * a create reply and every readiness poll have been read without one — the
+ * API server assigns `metadata.uid` on admission and returns the object it
+ * created, so an object with no uid is an API server that answered something
+ * other than what it was asked for. Refusing is right: without the uid there
+ * is no owner reference, and a per-sandbox policy with no owner is one the
+ * cluster never collects.
+ */
+function assertOwnerUid(uid, objectName, namespace) {
+    if (uid !== undefined && uid !== '')
+        return uid;
+    throw new KubernetesOwnerUidMissingError(objectName, namespace);
+}
+/**
+ * Recover a crashed host's claims: LIST every `SandboxClaim` carrying
+ * `labelSelector`, `DELETE` each, and report what was removed.
+ *
+ * This deletes CLAIMS only. The controller's own garbage collection —
+ * ownerReferences from claim to the Sandbox it bound, and from Sandbox to
+ * Pod and Service — takes the rest down behind it; nothing here reads or
+ * touches a Sandbox or a Pod directly. A claim already gone (raced by the
+ * controller's own TTL reaper, or a second release call) counts as removed
+ * rather than a failure, the same convention every other DELETE in this
+ * backend follows.
+ *
+ * `labelSelector` is REQUIRED and refused, synchronously, before a single
+ * request goes out, if it is absent or empty: a release that could fall back
+ * to matching every claim (or every claim of the template) would delete a
+ * live fleet's work the first time a caller passed one by mistake. There is
+ * no default selector for exactly this reason.
+ */
+export async function releaseKubernetesTaskSandboxes(config, options) {
+    if (options.labelSelector === '') {
+        throw new Error('kubernetes: releaseKubernetesTaskSandboxes requires a non-empty labelSelector — a release with no selector would delete every SandboxClaim in the namespace, including ones a live host still owns. Pass the selector that names only the claims you mean to recover.');
+    }
+    options.signal?.throwIfAborted();
+    const namespace = config.namespace;
+    const client = createKubernetesClient(clientAccess(config), clientOptions(config));
+    const list = await client.request('GET', claimListPath(namespace, options.labelSelector), undefined, options.signal);
+    const names = (list?.items ?? [])
+        .map((claim) => claim.metadata?.name)
+        .filter((name) => typeof name === 'string' && name !== '');
+    // Concurrent, not one at a time: a crash-recovery release can carry a
+    // whole host's worth of claims, and nothing here needs the ordering a
+    // sequential loop would impose — each DELETE is independent and
+    // idempotent (an already-gone claim is tolerated below). A non-tolerated
+    // failure still rejects the whole call, exactly as a sequential loop
+    // would have on its first such failure.
+    await Promise.all(names.map(async (name) => {
+        try {
+            await client.request('DELETE', claimPath(namespace, name), undefined, options.signal);
+        }
+        catch (err) {
+            if (!(err instanceof KubernetesAlreadyGoneError))
+                throw err;
+        }
+    }));
+    return { deleted: names.length, names };
+}
+/**
+ * Read task-pool headroom before admitting more work: three GETs, no writes.
+ *
+ * `config.warmPoolName` is required — this reads the exact object a claim's
+ * `warmPoolRef` names, so a pool-less backend (every create is a direct
+ * Sandbox) has no pool to report on. `activeClaims` is every claim in the
+ * namespace whose `spec.warmPoolRef.name` matches this pool, counted rather
+ * than trusted from a label, because a claim's `warmPoolRef` is the one
+ * field the API itself guarantees. `pendingPods` is every Pod in the
+ * namespace still in phase `Pending` — a coarse but honest signal of
+ * in-flight scale-up the ready-replica count alone does not carry, on
+ * either the warm or the pool-less path.
+ */
+export async function readKubernetesTaskCapacity(config, options) {
+    options?.signal?.throwIfAborted();
+    if (config.warmPoolName === undefined) {
+        throw new Error('kubernetes: readKubernetesTaskCapacity requires config.warmPoolName — there is no SandboxWarmPool to report on for a backend that creates every sandbox directly.');
+    }
+    const namespace = config.namespace;
+    const warmPoolName = config.warmPoolName;
+    const client = createKubernetesClient(clientAccess(config), clientOptions(config));
+    const [pool, claims, pods] = await Promise.all([
+        client.request('GET', warmPoolPath(namespace, warmPoolName), undefined, options?.signal),
+        client.request('GET', claimCollectionPath(namespace), undefined, options?.signal),
+        client.request('GET', podCollectionPath(namespace), undefined, options?.signal),
+    ]);
+    const activeClaims = (claims?.items ?? []).filter((claim) => claim.spec?.warmPoolRef?.name === warmPoolName).length;
+    const pendingPods = (pods?.items ?? []).filter((pod) => pod.status?.phase === 'Pending').length;
+    return {
+        warmPool: {
+            ready: pool?.status?.readyReplicas ?? 0,
+            desired: pool?.spec?.replicas ?? 0,
         },
+        activeClaims,
+        pendingPods,
     };
 }
 /**
@@ -416,21 +1282,14 @@ function buildClaimBody(namespace, name, warmPoolName, shutdownTime) {
  * label the translated policy is built to match.
  */
 export function buildSandboxBody(options) {
-    const podTemplate = options.template.podTemplate;
-    const spec = options.runtimeClassName !== undefined
-        ? { ...podTemplate.spec, runtimeClassName: options.runtimeClassName }
-        : { ...podTemplate.spec };
-    const metadata = {
-        ...podTemplate.metadata,
-        labels: {
-            ...podTemplate.metadata?.labels,
-            ...sandboxTemplateLabel(options.sandboxTemplateName),
-        },
-    };
     return {
         apiVersion: `${SANDBOX_API_GROUP}/${SANDBOX_API_VERSION}`,
         kind: 'Sandbox',
-        metadata: { name: options.name, namespace: options.namespace },
+        metadata: {
+            name: options.name,
+            namespace: options.namespace,
+            ...(options.annotations !== undefined ? { annotations: options.annotations } : {}),
+        },
         spec: {
             operatingMode: 'Running',
             service: true,
@@ -440,10 +1299,69 @@ export function buildSandboxBody(options) {
             ...(options.template.volumeClaimTemplates !== undefined
                 ? { volumeClaimTemplates: options.template.volumeClaimTemplates }
                 : {}),
-            podTemplate: { ...podTemplate, metadata, spec },
+            podTemplate: sandboxPodTemplate(options.template, options.sandboxTemplateName, options.runtimeClassName, options.podLabels),
         },
     };
 }
+/**
+ * The `spec.podTemplate` a directly created Sandbox carries: the template's,
+ * with this backend's overlays — the template label and whatever
+ * {@link composeAdditionalPodLabels} produced ({@link sandboxPodLabels}), and
+ * the configured `runtimeClassName`.
+ *
+ * Its own function because it is now built twice: once into the create POST
+ * by {@link buildSandboxBody}, and once into the JSON Patch that refreshes a
+ * standing workspace's pod template (`workspace.ts`). Two expressions of the
+ * same overlay would drift, and the one that drifted would report a workspace
+ * as off-template forever — the hash under
+ * `sandbox.namzu.ai/pod-template-hash` is taken over exactly this object, so
+ * a second spelling is a second revision.
+ *
+ * `podLabels` is on this signature rather than only on the create body for
+ * exactly that reason. A refresh rewrites `/spec/podTemplate` WHOLE, so a
+ * refresh built without them would PATCH the egress profile off a pod
+ * template that carries it — the replacement pod would come up selected by no
+ * per-profile policy, on a path where nothing re-checks the label, and the
+ * revision stamped beside it would be taken over a template the POST never
+ * writes, so `templateCurrent` would report drift forever.
+ */
+export function sandboxPodTemplate(template, sandboxTemplateName, runtimeClassName, podLabels) {
+    const podTemplate = template.podTemplate;
+    const spec = runtimeClassName !== undefined
+        ? { ...podTemplate.spec, runtimeClassName }
+        : { ...podTemplate.spec };
+    return {
+        ...podTemplate,
+        metadata: {
+            ...podTemplate.metadata,
+            labels: sandboxPodLabels(template, sandboxTemplateName, podLabels),
+        },
+        spec,
+    };
+}
+/**
+ * The labels a directly created Sandbox's pod will carry: whatever the
+ * template declares, plus this backend's own template label, which always
+ * wins because it is the label a policy selector is built to match.
+ *
+ * Its own function because the ingress check has to reason about EXACTLY the
+ * labels {@link buildSandboxBody} stamps, before the POST that stamps them.
+ * Two expressions of the same rule would be one rename away from a check that
+ * verifies a pod nobody creates.
+ *
+ * `extra` is `composeAdditionalPodLabels`'s map — the egress profile today.
+ * It is applied LAST, and so wins over both, for the same reason the template
+ * label wins over the copied template's own: it is a label the translated
+ * policy's selector is built to match, and a pod that matched the selector
+ * only sometimes would be a boundary that applied only sometimes.
+ */
+export function sandboxPodLabels(template, sandboxTemplateName, extra) {
+    return {
+        ...template.podTemplate.metadata?.labels,
+        ...sandboxTemplateLabel(sandboxTemplateName),
+        ...extra,
+    };
+}
 export async function readSandboxTemplate(client, namespace, sandboxTemplateName, signal) {
     const template = await client.request('GET', sandboxTemplatePath(namespace, sandboxTemplateName), undefined, signal);
     const podTemplate = template?.spec?.podTemplate;
@@ -459,20 +1377,48 @@ export async function readSandboxTemplate(client, namespace, sandboxTemplateName
 /**
  * Where the agent answers.
  *
- * Its own function, and the Service FQDN wins over a pod IP, because the
- * address outlives the pod: a suspended-then-resumed workspace comes back as a
- * new pod with a new IP behind the same name, and the transport re-resolves
- * the name on every dial. A literal IP baked into a long-lived handle is the
- * bug that would produce.
+ * Its own function, and under the default mode the Service FQDN wins over a
+ * pod IP, because that address outlives the pod: a suspended-then-resumed
+ * workspace comes back as a new pod with a new IP behind the same name, and
+ * the transport re-resolves the name on every dial. A literal IP baked into a
+ * long-lived handle is the bug that would produce — and it is exactly the bug
+ * `'pod-ip'` accepts, deliberately, in exchange for an address a host outside
+ * the cluster can resolve at all. That mode pays for it by re-reading the IP
+ * on every resume and once after a failed connect.
+ *
+ * `'pod-ip'` takes the address from `pod`, the record the bind token was just
+ * read out of, and NEVER falls back to `binding.podIPs`. The Sandbox's status
+ * is a second source that can name a different pod — the one a resume is
+ * replacing — and an address from one pod with a token from another is the
+ * mismatch that arrives as a flat `unauthorized`.
  */
-export function resolveAgentAddress(binding, agentPort, token) {
+export function resolveAgentAddress(binding, agentPort, token, options = {}) {
+    if ((options.mode ?? 'service') === 'pod-ip') {
+        const podIP = options.podIP;
+        if (podIP === undefined || podIP === '') {
+            throw new Error(`kubernetes: sandbox ${binding.name} is configured with agentAddress: 'pod-ip', but the live pod its bind token was read from reported no status.podIP (nor a status.podIPs entry), so there is no address to dial. Every path that binds a pod POLLS for that address until the readiness deadline before this is reached — see readAddressedPod — so a pod that still reports none was never given one: a CNI that did not attach it, or a pod that never got past scheduling. Nothing is taken from the Sandbox's own status here on purpose — that IP may belong to a different pod than the token does.`);
+        }
+        return { kind: 'tcp', host: podIP, port: agentPort, token };
+    }
     const host = binding.serviceFQDN ?? binding.podIPs?.[0];
     if (host === undefined || host === '') {
         throw new Error(`kubernetes: sandbox ${binding.name} reported Ready with neither a serviceFQDN nor a pod IP, so its agent has no address to dial. Set 'service: true' on the SandboxTemplate the pool is built from.`);
     }
     return { kind: 'tcp', host, port: agentPort, token };
 }
-function bindingFromClaim(claim, claimName) {
+/**
+ * Ready-or-not-yet, read off a `SandboxClaim`'s own status — plus the one
+ * "not yet" that is really a "no".
+ *
+ * The rejection check runs BEFORE the readiness check rather than after,
+ * because a refused claim is `Ready=False` forever and the readiness check
+ * cannot tell that from a cold start in progress. See
+ * {@link classifyClaimRejection}.
+ */
+function bindingFromClaim(claim, claimName, metadata) {
+    const rejection = classifyClaimRejection(claim, claimName, metadata);
+    if (rejection !== undefined)
+        throw rejection;
     if (!isConditionTrue(claim?.status?.conditions, READY_CONDITION))
         return undefined;
     const bound = claim?.status?.sandbox;
@@ -503,26 +1449,64 @@ export function bindingFromSandbox(sandbox) {
         ...(status?.selector !== undefined ? { podSelector: status.selector } : {}),
     };
 }
+/**
+ * The readiness poll ran out of budget — and nothing else. Every OTHER
+ * failure {@link pollForBinding} meets is rethrown as itself, so this class
+ * is an exact answer to "was it the clock?", which a caller that has to
+ * choose between two timeout messages needs and cannot get from the clock.
+ *
+ * Reading `remainingMs()` after the fact is NOT that answer: the expiry timer
+ * and `performance.now()` are different clocks, and a timer that fires a
+ * fraction of a millisecond early leaves a positive remainder behind an
+ * expiry that has already happened.
+ */
+export class ReadinessPollTimeout extends Error {
+    name = 'ReadinessPollTimeout';
+}
 /**
  * Poll until `read` reports a binding. `read` returns `undefined` for "not
  * yet" and throws for a failure worth surfacing; the deadline owns every wait,
  * including the sleep between attempts, so an expired clock cannot be extended
  * by one more round trip. Shaped after ACI's `pollForRunningIp`.
+ *
+ * The only failure this raises on its own account is
+ * {@link ReadinessPollTimeout}; anything `read` throws travels out unchanged,
+ * unless `behaviour.retryDelayFor` claims it — in which case it is repeated
+ * inside the same budget and, if the budget then runs out, carried onto the
+ * timeout as its `cause`, so a poll that kept failing still says what it kept
+ * seeing.
  */
-export async function pollForBinding(read, deadline, readiness, label) {
+export async function pollForBinding(read, deadline, readiness, label, behaviour = {}) {
+    /**
+     * The last failure that was retried rather than raised, and only while it
+     * is still the truth: a read that succeeds clears it, so the timeout
+     * carries a failure the poll was STILL meeting when the budget ran out
+     * rather than a blip it recovered from twenty polls earlier. The
+     * difference is not cosmetic — the acquire's reason is read off this
+     * cause, so a stale one would report an API outage for a poll whose API
+     * was answering fine.
+     */
+    let lastRetried;
     while (deadline.remainingMs() > 0) {
+        /** Overrides the poll cadence for one round when the server named one. */
+        let nextDelayMs = readiness.pollIntervalMs;
         try {
             const binding = await deadline.run(read);
+            lastRetried = undefined;
             if (binding)
                 return binding;
         }
         catch (err) {
             if (err instanceof OperationDeadlineExpired)
                 break;
-            throw err;
+            const retryDelayMs = behaviour.retryDelayFor?.(err);
+            if (retryDelayMs === undefined)
+                throw err;
+            lastRetried = err;
+            nextDelayMs = retryDelayMs;
         }
         try {
-            await deadline.delay(readiness.pollIntervalMs);
+            await deadline.delay(nextDelayMs);
         }
         catch (err) {
             if (err instanceof OperationDeadlineExpired)
@@ -530,10 +1514,15 @@ export async function pollForBinding(read, deadline, readiness, label) {
             throw err;
         }
     }
-    throw new Error(`kubernetes: ${label} never became Ready (${readiness.timeoutMs}ms)`);
+    throw new ReadinessPollTimeout(`kubernetes: ${label} never became Ready (${readiness.timeoutMs}ms)${lastRetried !== undefined
+        ? `; the last API failure retried inside that budget was: ${lastRetried instanceof Error ? lastRetried.message : String(lastRetried)}`
+        : ''}`, lastRetried !== undefined ? { cause: lastRetried } : undefined);
 }
 /**
- * The per-instance bind token: the backing pod's `metadata.uid`.
+ * Find the pod a sandbox is currently backed by, and read both facts off it.
+ *
+ * `uid` is the per-instance agent bind token; `podIP` is where that agent
+ * listens, and only `agentAddress: 'pod-ip'` reads it.
  *
  * The pod is named after its Sandbox in agent-sandbox v1.0.2 — verified
  * against a running cluster — but that is an observation, not a documented
@@ -542,7 +1531,7 @@ export async function pollForBinding(read, deadline, readiness, label) {
  * changing upstream is a second round trip through `status.selector`, which is
  * exactly what the controller publishes the selector for.
  */
-export async function readPodBindToken(client, namespace, binding, signal) {
+export async function readBoundPod(client, namespace, binding, signal) {
     try {
         const pod = await client.request('GET', podPath(namespace, binding.name), undefined, signal);
         const uid = pod?.metadata?.uid;
@@ -552,7 +1541,7 @@ export async function readPodBindToken(client, namespace, binding, signal) {
         // uid the new agent will refuse. On the acquire path nothing is
         // terminating and the filter never fires.
         if (uid && isPodLive(pod))
-            return uid;
+            return boundPod(uid, pod);
     }
     catch (err) {
         if (!(err instanceof KubernetesAlreadyGoneError))
@@ -564,11 +1553,93 @@ export async function readPodBindToken(client, namespace, binding, signal) {
         for (const pod of list?.items ?? []) {
             const uid = pod.metadata?.uid;
             if (uid && isPodLive(pod))
-                return uid;
+                return boundPod(uid, pod);
         }
     }
     throw new Error(`kubernetes: could not read a pod uid for sandbox ${binding.name} in namespace ${namespace} — no live pod of that name, and its status.selector matched no live pod either (a pod carrying a deletionTimestamp, or in phase Succeeded/Failed, is never bound to). The pod uid is the agent's bind token, so the sandbox is refused rather than returned unauthenticated.`);
 }
+function boundPod(uid, pod) {
+    const podIP = readPodIP(pod);
+    const labels = pod.metadata?.labels;
+    return {
+        uid,
+        ...(podIP !== undefined ? { podIP } : {}),
+        ...(labels !== undefined ? { labels } : {}),
+    };
+}
+/**
+ * {@link readBoundPod}, plus — under `'pod-ip'` only — the wait for an
+ * address to go with the token.
+ *
+ * Under the default mode this is the single read it has always been: one
+ * `GET`, in the same place in the same order, because a Service FQDN is
+ * published with the Sandbox and needs nothing from the pod but its uid.
+ *
+ * `'pod-ip'` has to wait, because a LIVE pod is not yet an ADDRESSED pod. A
+ * pod is created `Pending` and carries no `status.podIP` until the CNI has
+ * finished attaching it, and {@link isPodLive} accepts `Pending` on purpose —
+ * the resume path in `workspace.ts` binds its replacement pod long before that
+ * pod is Ready, because `Ready` stays True across the transition and the uid
+ * is the only transition signal there is. Refusing an address-less pod outright
+ * would therefore fail on the NORMAL path, in milliseconds, with the whole
+ * readiness budget unspent. So "live, no address yet" is polled on the same
+ * deadline as everything else on this path, and
+ * {@link resolveAgentAddress}'s own refusal is left as the post-deadline
+ * backstop for a pod that never gets an address at all.
+ *
+ * A failed READ stays fatal, exactly as it was: this is the acquire path,
+ * where nothing is being replaced and a pod that cannot be read is not a pod
+ * that is about to appear.
+ *
+ * `requiredLabels` is the second thing worth waiting for, and it is waited
+ * for in the SAME loop rather than in a second one: an egress profile is a
+ * label the CONTROLLER patches onto the pod it binds, so a pod read the
+ * instant it was bound can be live, addressed and not yet labelled. Two
+ * loops would be two deadlines and two answers to "is this pod ready to be
+ * admitted". Like the address, an expired clock hands the pod back as it is
+ * — the caller decides whether a missing label is fatal, and on the acquire
+ * path it is: see `assertRequestedPodLabelsObserved`.
+ */
+export async function readAddressedPod(client, namespace, binding, deadline, readiness, mode, requiredLabels) {
+    const required = Object.entries(requiredLabels ?? {});
+    const wanting = (pod) => (mode === 'pod-ip' && pod.podIP === undefined) ||
+        required.some(([key, value]) => pod.labels?.[key] !== value);
+    let pod = await deadline.run((signal) => readBoundPod(client, namespace, binding, signal));
+    while (wanting(pod) && deadline.remainingMs() > 0) {
+        try {
+            await deadline.delay(readiness.pollIntervalMs);
+            pod = await deadline.run((signal) => readBoundPod(client, namespace, binding, signal));
+        }
+        catch (err) {
+            // An expired clock hands the incomplete pod back rather than
+            // replacing it with a bare "deadline expired": the caller's
+            // `resolveAgentAddress` (or `assertRequestedPodLabelsObserved`) then
+            // reports WHICH fact never arrived.
+            if (err instanceof OperationDeadlineExpired)
+                break;
+            throw err;
+        }
+    }
+    return pod;
+}
+/**
+ * The re-read a `'pod-ip'` handle follows a replaced pod with: one live-pod
+ * read, then the same address resolution acquire did.
+ *
+ * Built here rather than inside the transport because finding the pod is a
+ * CONTROL-plane act — the by-name GET, the selector fallback, the
+ * liveness filter — and the transport owns none of that. It is handed over as
+ * a closure so the transport can call it without learning what a Sandbox is.
+ */
+export function buildAgentAddressRefresh(client, namespace, binding, agentPort, mode) {
+    return async (signal) => {
+        const pod = await readBoundPod(client, namespace, binding, signal);
+        return resolveAgentAddress(binding, agentPort, pod.uid, {
+            mode,
+            ...(pod.podIP !== undefined ? { podIP: pod.podIP } : {}),
+        });
+    };
+}
 async function readSandboxSelector(client, namespace, binding, signal) {
     try {
         const sandbox = await client.request('GET', sandboxPath(namespace, binding.name), undefined, signal);
@@ -607,17 +1678,31 @@ async function readSandboxSelector(client, namespace, binding, signal) {
  * whose expiry takes the same cleanup-and-reject path every other refusal
  * does, in words that name the hang rather than blame a missing `cat`.
  */
-async function admitProbedSandbox(acquisition, config, options, probeTimeoutMs) {
+async function admitProbedSandbox(acquisition, config, options, probeTimeoutMs, 
+/**
+ * Present exactly when `config.egress.perSandbox` is configured — which
+ * is what makes `setNetworkPolicy` present on the handle. See
+ * `per-sandbox-policy.ts`.
+ */
+setNetworkPolicy) {
     const sandbox = buildKubernetesSandbox({
         name: acquisition.binding.name,
         rootDir: options.workingDirectory,
-        transport: new KubernetesAgentTransport(acquisition.agent),
+        transport: new KubernetesAgentTransport(acquisition.agent, {
+            // The backend opts in to the stream heartbeat; the transport
+            // option it sets stays undefined for every other tier.
+            heartbeatMs: resolveStreamHeartbeatMs(config.streamHeartbeatMs),
+            ...(acquisition.refreshAgent !== undefined
+                ? { refreshHandle: acquisition.refreshAgent }
+                : {}),
+        }),
         release: acquisition.release,
         renew: acquisition.renew,
         ttlSeconds: acquisition.ttlSeconds,
         ...(config.onLeaseRenewalError !== undefined
             ? { onRenewalError: config.onLeaseRenewalError }
             : {}),
+        ...(setNetworkPolicy !== undefined ? { setNetworkPolicy } : {}),
     });
     try {
         await probeSandboxPrivileges(sandbox, acquisition.binding.name, probeTimeoutMs, options.signal);