@namzu/sandbox 13.0.0 → 15.0.0

package/dist/backends/kubernetes/index.d.ts

@@ -0,0 +1,1019 @@
+/**
+ * Kubernetes / agent-sandbox backend — acquire, readiness and teardown.
+ *
+ * Sibling of `firecracker/` and `aci-standby-pool/`: same
+ * {@link SandboxBackend} surface, same "the host supplies the credential
+ * callback and this package carries no cloud SDK" boundary, a different
+ * control plane. Here the control plane is the Kubernetes API server and the
+ * warm pool is a `SandboxWarmPool` reconciled by the agent-sandbox controller
+ * (kubernetes-sigs/agent-sandbox v1.0.2).
+ *
+ * Registered as `microvm` because {@link SandboxTier} names the strength of
+ * the boundary, not the orchestrator that starts it: a pod scheduled onto a
+ * Kata RuntimeClass runs in a hardware-virtualized guest. The tier also keeps
+ * the backend out of the container tier's mandatory
+ * `ContainerSandboxLayout`, which a remote-copy backend has no use for —
+ * Firecracker took the same exemption.
+ *
+ * ## Two acquire paths, and why they create different kinds
+ *
+ *  - `warmPoolName` set → POST a `SandboxClaim` at the named pool. The
+ *    controller binds an already-running Sandbox out of the pool, which is
+ *    what makes a sub-second acquire possible at all.
+ *  - `warmPoolName` unset → POST a `Sandbox` directly. This is necessitated
+ *    rather than chosen: `SandboxClaimSpec.warmPoolRef` is a REQUIRED field,
+ *    so a pool-less claim does not exist in the API.
+ *
+ * The claim this backend POSTs is PRISTINE: `warmPoolRef` and a lifecycle
+ * bound, nothing else. `spec.env` and `spec.volumeClaimTemplates` are
+ * available on the claim and are never set, because a claim carrying either
+ * is forced to cold-start instead of adopting a pool sandbox — the single
+ * most expensive mistake available on this path, and a silent one, since such
+ * a claim still works and only the latency shows it. Per-sandbox controls
+ * that would need those fields are refused by {@link assertEnforceable}
+ * rather than accepted and dropped.
+ *
+ * ## The bound sandbox is not named after the claim
+ *
+ * A pool sandbox keeps the generated name the pool gave it when the claim
+ * adopts it. The backend therefore reads the bound identity back out of
+ * `status.sandbox` and never derives it from the claim's own name. A test
+ * covers exactly that asymmetry.
+ *
+ * ## Credential
+ *
+ * The per-instance agent bind token is the backing pod's own
+ * `metadata.uid`: the host learns it from the API server after readiness, the
+ * guest learns it through the downward API (`NAMZU_AGENT_BIND_TOKEN`), and
+ * nothing has to be minted, stored or injected at claim time. One GET, no
+ * claim mutation, so the warm path stays pristine. A resumed pod is a new pod
+ * with a new uid, which is correct: it is a new instance.
+ *
+ * ## The lease
+ *
+ * The `shutdownTime` acquire stamps is the leak guard AND, unrenewed, a
+ * deadline on the run. The Sandbox handle owns a renewal loop that PATCHes
+ * it forward every half-TTL for as long as the handle is alive, and
+ * `destroy()` stops it — so a live run keeps its pod and a dead host still
+ * costs the cluster exactly one expiry. See `lease.ts`.
+ *
+ * ## The privilege probe
+ *
+ * `create()` does not resolve until the guest has reported — and this
+ * backend has checked — that it is deprivileged: all four capability masks
+ * zero, `NoNewPrivs: 1`, read out of `/proc/self/status` over the agent's
+ * `execute` op, on a clock of its own so a guest that goes quiet is refused
+ * rather than waited on. A refusal destroys the instance and rejects, so no
+ * handle to an under-hardened sandbox escapes. There is no off switch. See
+ * `privilege-probe.ts`.
+ *
+ * ## Not watch
+ *
+ * Readiness is polled against the shared {@link OperationDeadline}, exactly as
+ * ACI polls `provisioningState`. A watch would buy nothing on a path whose
+ * whole budget is under a second, and would cost resourceVersion tracking,
+ * bookmarks, 410-relist and reconnect backoff.
+ *
+ * ## Egress
+ *
+ * `config.egress` is optional and, when set, translated and VERIFIED — never
+ * 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 type { Sandbox } from '@namzu/sdk';
+import type { SandboxBackend, SandboxBackendOptions } from '../../index.js';
+import { OperationDeadline } from '../readiness.js';
+import { type EgressProfileLabel, type KubernetesEgressConfig } from './egress-policy.js';
+import { type KubernetesIngressConfig } from './ingress-policy.js';
+import { type KubernetesAccess, type KubernetesClient, type KubernetesClientOptions } from './k8s-client.js';
+import { type SandboxClaimResource, type SandboxPodTemplate, type SandboxResource, type SandboxVolumeClaimTemplate } from './objects.js';
+import { type PerSandboxPolicyOwner } from './per-sandbox-policy.js';
+export type { KubernetesEgressConfig, KubernetesEgressEngine, KubernetesEgressPolicy, KubernetesEgressVerification, KubernetesOnlyEgressPolicy, KubernetesPerSandboxEgressConfig, } from './egress-policy.js';
+export type { KubernetesIngressConfig, KubernetesIngressEngine } from './ingress-policy.js';
+/**
+ * How the backend reaches the API server. Two sources, neither needing a YAML
+ * parser — see `k8s-client.ts` for the reasoning.
+ */
+export type KubernetesClusterAccess = {
+    readonly inCluster: true;
+} | {
+    readonly inCluster?: false;
+    readonly server: string;
+    readonly ca?: string | Buffer;
+    readonly getToken: () => Promise<string>;
+};
+export interface KubernetesBackendInternalConfig {
+    readonly access: KubernetesClusterAccess;
+    /** Namespace the claims, sandboxes and pods live in. */
+    readonly namespace: string;
+    /**
+     * SandboxTemplate whose `podTemplate` a POOL-LESS create copies into the
+     * Sandbox it posts. The warm path never reads it — the pool's own
+     * `sandboxTemplateRef` decides there — but an operator reading this config
+     * still learns which template these sandboxes are built from.
+     */
+    readonly sandboxTemplateName: string;
+    /** Named `SandboxWarmPool`. Absent → every create is a direct Sandbox. */
+    readonly warmPoolName?: string;
+    /** TCP port the guest agent listens on. Default {@link DEFAULT_AGENT_PORT}. */
+    readonly agentPort?: number;
+    /**
+     * Which of a sandbox's two addresses the transport dials. Default
+     * `'service'` — see {@link KubernetesAgentAddressMode}, which is where
+     * the choice is explained, because it is a fact about where the HOST
+     * runs rather than about the cluster.
+     */
+    readonly agentAddress?: KubernetesAgentAddressMode;
+    readonly readyPollIntervalMs?: number;
+    readonly readyTimeoutMs?: number;
+    /**
+     * Lifetime bound written into every created object, and the amount each
+     * lease renewal pushes the expiry forward. Default 1 hour.
+     */
+    readonly claimTtlSeconds?: number;
+    /**
+     * Every lease-renewal failure that is not "the object is already gone".
+     * `@namzu/sandbox` owns no logger and reads none from module scope, so a
+     * diagnostic it cannot print is handed to the host that can. Renewal
+     * retries on the next tick either way; nothing here changes behaviour.
+     */
+    readonly onLeaseRenewalError?: (error: unknown) => void;
+    /**
+     * RuntimeClass for a POOL-LESS create. Refused together with
+     * `warmPoolName`: a pooled sandbox's runtime class is fixed by the pool's
+     * SandboxTemplate and cannot be chosen per claim.
+     */
+    readonly runtimeClassName?: string;
+    /**
+     * Egress policy this backend's `NetworkPolicy` (or `CiliumNetworkPolicy`,
+     * under `engine: 'cilium'`) is expected to carry. Unset means this backend
+     * neither computes nor verifies one, and OUTBOUND traffic is then whatever
+     * the cluster's own policies happen to allow.
+     *
+     * Deliberately not described as "covered by the SandboxTemplate's managed
+     * NetworkPolicy", which is what this comment used to claim: that policy
+     * selects `agents.x-k8s.io/sandbox-template-ref-hash`, a label the
+     * controller writes only onto a Sandbox adopted out of a `SandboxWarmPool`
+     * and never onto one this backend POSTs — so for every pool-less sandbox
+     * and every workspace it selects nothing at all. See `ingress-policy.ts`.
+     */
+    readonly egress?: KubernetesEgressConfig;
+    /**
+     * Whether the agent port's INGRESS boundary is verified before a sandbox
+     * is created, and against which policy resources.
+     *
+     * Unset means VERIFY — the one field in this config whose absent value is
+     * the strict one, because the deployment that needs the check is the one
+     * that would never have set it. `'unverified'` reads no policy and issues
+     * no request, for a deployment whose boundary lives somewhere a namespaced
+     * Role cannot see. See `ingress-policy.ts`.
+     */
+    readonly ingress?: KubernetesIngressConfig;
+    /**
+     * Bound on every single Kubernetes API request this backend sends. See
+     * {@link KubernetesClientOptions.requestTimeoutMs} in `k8s-client.ts`,
+     * which owns the default (30 s), the floor (1 s) and the reason there is
+     * no value that disables it.
+     */
+    readonly apiRequestTimeoutMs?: number;
+    /**
+     * Interval of the negotiated liveness heartbeat on `openTerminal` and
+     * `openTcpConnection` streams. Default
+     * {@link DEFAULT_STREAM_HEARTBEAT_MS}; `0` turns it off and restores the
+     * pre-heartbeat behaviour exactly. See {@link resolveStreamHeartbeatMs}.
+     */
+    readonly streamHeartbeatMs?: number;
+    /**
+     * Extra labels written onto every `SandboxClaim` this backend POSTs —
+     * `metadata.labels`, and nowhere else. Never merged into
+     * `additionalPodMetadata`: those are POD labels a running Sandbox and its
+     * `NetworkPolicy` selectors read, and a host's own recovery bookkeeping
+     * has no business changing what a pod is selected by. Absent means no
+     * labels beyond what the controller itself writes, and every claim body
+     * this backend sends is byte-for-byte what it always was.
+     *
+     * The intended use is a host-instance identity — e.g.
+     * `{ 'sandbox.namzu.ai/host-instance': hostId }` — so a restarted host
+     * can find and {@link releaseKubernetesTaskSandboxes} its predecessor's
+     * claims well before `claimTtlSeconds` would reap them on its own.
+     */
+    readonly claimLabels?: Record<string, string>;
+}
+/**
+ * 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 declare const DEFAULT_STREAM_HEARTBEAT_MS = 15000;
+/**
+ * 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 declare function resolveStreamHeartbeatMs(value: number | undefined): number;
+/**
+ * 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 declare function clientOptions(config: KubernetesBackendInternalConfig): KubernetesClientOptions;
+/**
+ * Which address a sandbox's agent is dialed at. A property of where the HOST
+ * runs, not of the cluster.
+ *
+ *  - `'service'` (default) — the Sandbox's `status.serviceFQDN`,
+ *    `<name>.<namespace>.svc.cluster.local`. It outlives the pod: a resumed
+ *    workspace comes back behind the same name, and every dial re-resolves
+ *    it. The catch is that only the cluster's own DNS answers it, so this is
+ *    correct exactly when the host itself runs inside the cluster.
+ *  - `'pod-ip'` — the bound pod's IP, read from the same `GET` that reads
+ *    its uid, so the address and the bind token are always one pod's. For a
+ *    host OUTSIDE the cluster on a routable pod network (a peered VNet, a
+ *    node-local operator, a CI runner with a route): it needs no cluster
+ *    resolver at all. The cost is that a pod IP dies with its pod, which is
+ *    why a resume re-reads it and a connect failure re-reads it once.
+ *
+ * The cluster still decides whether either address is REACHABLE: `'pod-ip'`
+ * additionally needs a NetworkPolicy that admits the host's own address
+ * range on the agent port. Neither mode changes the bind token, the
+ * privilege probe or egress verification.
+ */
+export type KubernetesAgentAddressMode = 'service' | 'pod-ip';
+/**
+ * The address the guest agent answers on, plus the token to present.
+ *
+ * Structurally the `tcp` arm of the transport's `SandboxAgentHandle`. It is
+ * declared here rather than imported so acquire does not depend on the
+ * transport landing first; the two are asserted equal where they meet.
+ */
+export interface KubernetesAgentAddress {
+    readonly kind: 'tcp';
+    readonly host: string;
+    readonly port: number;
+    readonly token: string;
+}
+/** What the controller bound, read back off the object's own status. */
+export interface KubernetesSandboxBinding {
+    /** The Sandbox's own name — NOT the claim's. */
+    readonly name: string;
+    readonly podIPs?: readonly string[];
+    readonly serviceFQDN?: string;
+    /** `Sandbox.status.selector`, when the path that read it had it for free. */
+    readonly podSelector?: string;
+}
+/** One acquired sandbox: what it is, where it answers, how to give it back. */
+export interface KubernetesAcquisition {
+    readonly binding: KubernetesSandboxBinding;
+    readonly agent: KubernetesAgentAddress;
+    /**
+     * Re-read the live pod and recompute {@link agent} from it. Present only
+     * under `agentAddress: 'pod-ip'`, where the address is a literal that
+     * dies with its pod; a Service FQDN needs no such thing, and handing one
+     * over anyway would give the default mode a re-read it never had.
+     */
+    readonly refreshAgent?: (signal?: AbortSignal) => Promise<KubernetesAgentAddress>;
+    /** API path of the object THIS backend created — the claim, or the Sandbox. */
+    readonly ownedPath: string;
+    /**
+     * The object this backend created, identified well enough to be named in
+     * another object's `ownerReferences`: its kind, its name and the uid the
+     * API server assigned it.
+     *
+     * Present only when `config.egress.perSandbox` is configured, because it
+     * is read from the create reply and the readiness polls and nothing else
+     * needs it — a deployment that never writes a per-sandbox policy should
+     * not start carrying a field whose absence would otherwise be a bug.
+     */
+    readonly owner?: PerSandboxPolicyOwner;
+    /**
+     * The VALUE of the per-sandbox selector label on this sandbox's pod —
+     * the created object's name, confirmed on the bound pod before the
+     * sandbox was admitted. Present under the same condition as
+     * {@link owner}.
+     */
+    readonly perSandboxLabelValue?: string;
+    /** The TTL acquire stamped, which every renewal re-stamps. */
+    readonly ttlSeconds: number;
+    /** DELETE that object. An already-gone object counts as released. */
+    release(signal?: AbortSignal): Promise<void>;
+    /**
+     * Merge-PATCH the created object's expiry forward to `shutdownTime`.
+     *
+     * On the acquisition rather than in `lease.ts` because only this path
+     * knows WHICH object it created and therefore where the field lives: a
+     * `SandboxClaim` carries it at `spec.lifecycle.shutdownTime`, a directly
+     * created `Sandbox` at `spec.shutdownTime` (v1beta1 as served keeps it at
+     * the top of `spec`). A merge patch of the nested object leaves
+     * `shutdownPolicy` alone.
+     */
+    renew(shutdownTime: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * The same number the Firecracker guest agent listens on over vsock
+ * (`DEFAULT_AGENT_VSOCK_PORT`), so one agent has one port across both tiers
+ * and a manifest, a NetworkPolicy and a transport can all name it from
+ * memory. Unprivileged, and the sandbox pod is not sharing it with anything.
+ */
+export declare const DEFAULT_AGENT_PORT = 1024;
+/**
+ * How long the privilege probe may take, given the caller's readiness budget.
+ *
+ * `readyTimeoutMs` bounds the CONTROL plane and has usually expired by the
+ * time the probe starts, so the probe cannot share it — but it is still the
+ * number the caller chose to describe how long an acquire may take, so the
+ * probe is allowed exactly that much again and no more, capped. A caller who
+ * asked for a 500 ms acquire gets a 500 ms probe; one who asked for two
+ * minutes of cold start still gets {@link PRIVILEGE_PROBE_TIMEOUT_CAP_MS}.
+ * Deliberately not a separate config key: a knob whose only correct value is
+ * "long enough for one `cat`" is a knob that only ever gets set wrong.
+ */
+export declare function resolveProbeTimeoutMs(readyTimeoutMs: number): number;
+/**
+ * The readiness bounds every path in this backend polls against — acquire,
+ * and `workspace.ts`'s create/suspend/resume. One function so the two cannot
+ * drift apart on defaults.
+ */
+export declare function resolveKubernetesReadiness(config: {
+    readonly readyTimeoutMs?: number;
+    readonly readyPollIntervalMs?: number;
+}): {
+    readonly timeoutMs: number;
+    readonly pollIntervalMs: number;
+};
+export declare function assertEnforceable(options: SandboxBackendOptions): void;
+/**
+ * Refuse a runtime class the pool path cannot honour.
+ *
+ * A pooled sandbox is already running by the time a claim reaches it, under
+ * whatever RuntimeClass its SandboxTemplate named. `runtimeClassName` in this
+ * config would therefore be read, accepted and ignored — and the thing it
+ * selects is the VM boundary, which is the last control to lose quietly.
+ */
+export declare function assertRuntimeClassIsApplicable(config: {
+    warmPoolName?: string;
+    runtimeClassName?: string;
+}): void;
+/**
+ * Build a {@link SandboxBackend} against a cluster running the agent-sandbox
+ * controller. Construction is synchronous and contacts nothing: readiness
+ * bounds and the config refusals are validated here so a misconfiguration
+ * surfaces during host wiring rather than mid-run, and the first API call
+ * happens on the first `create()`.
+ */
+export declare function buildKubernetesBackend(config: KubernetesBackendInternalConfig): SandboxBackend;
+/**
+ * The two egress checks a create path runs, with their memos.
+ *
+ * `undefined` when `config.egress` is unset — the whole boundary is one
+ * absent object rather than a flag every call site re-reads, the same shape
+ * {@link IngressVerifier} uses for its own opt-out.
+ *
+ * Exported because `workspace.ts` runs the identical steps: 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. It builds its own boundary per create,
+ * which is what makes its checks per-call rather than memoized — creating a
+ * workspace is a rare, explicit act with nothing to amortise, and a policy
+ * deleted since the last call must be noticed.
+ */
+export interface KubernetesEgressBoundary {
+    /**
+     * Translate `egress.policy` and confirm an operator applied a matching
+     * object — the original verify-not-trust step, unchanged, including its
+     * exact-match comparison and its once-per-boundary memo.
+     */
+    verifyNamedObject(signal?: AbortSignal): Promise<void>;
+    /**
+     * Enumerate every policy selecting THIS pod and refuse when any of them
+     * allows egress the translation does not. A no-op under
+     * `egress.verify: 'named-object-only'`.
+     */
+    verifyUnion(podLabels: Readonly<Record<string, string>>, subject: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * How long a union pass is trusted for one label set.
+ *
+ * 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 declare const EGRESS_UNION_CACHE_TTL_MS: number;
+/**
+ * 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 declare function buildEgressBoundary(client: KubernetesClient, config: KubernetesBackendInternalConfig, sandboxTemplateName: string, now?: () => number): KubernetesEgressBoundary | undefined;
+/**
+ * What a create path calls to prove the agent port is closed before it hands
+ * a sandbox back. `undefined` when `config.ingress` is `'unverified'`, so the
+ * opt-out is one absent function rather than a flag every call site re-reads.
+ */
+export type IngressVerifier = (podLabels: Readonly<Record<string, string>>, subject: string, signal?: AbortSignal) => Promise<void>;
+/**
+ * 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 declare function buildIngressVerifier(client: KubernetesClient, config: KubernetesBackendInternalConfig, cache?: Map<string, Promise<void>>): IngressVerifier | undefined;
+/** Config → the client's own access shape. Shared with `workspace.ts`. */
+export declare function clientAccess(config: KubernetesBackendInternalConfig): KubernetesAccess;
+/**
+ * Why an acquire was refused, in the terms an operator acts on rather than
+ * the terms the failure happened to arrive in.
+ *
+ *  - `'api-unreachable'` — the API server could not be reached, or kept
+ *    answering with a status that means "not now": a connect failure, a 429,
+ *    a 5xx. Retried inside the readiness budget before it ever reaches a
+ *    caller, so seeing it means the whole budget was spent failing.
+ *  - `'api-timeout'` — requests were accepted and never answered, until
+ *    `apiRequestTimeoutMs` gave up on them. Also retried first.
+ *  - `'forbidden'` — 401 or 403. The host's ServiceAccount cannot do this;
+ *    no amount of waiting changes that. See the RBAC section of
+ *    `docs/sdk/kubernetes-sandbox.md`.
+ *  - `'claim-rejected'` — the controller REFUSED the claim, and said why.
+ *    {@link KubernetesAcquireError.controllerReason} carries its own word for
+ *    it. This is the one that used to burn the entire readiness budget before
+ *    failing.
+ *  - `'capacity'` — the pod exists and cannot be placed: the scheduler
+ *    reports `PodScheduled=False` with reason `Unschedulable`. The cluster is
+ *    full, or nothing matches the template's placement rules.
+ *  - `'image-pull'` — the pod was placed and its container cannot start
+ *    because the image will not pull. Permanent until an operator fixes the
+ *    reference or the pull credential.
+ *  - `'not-ready'` — none of the above: the readiness budget expired with the
+ *    cluster reporting nothing wrong. A slow cold start, a webhook, an
+ *    admission controller, a CNI that never attached the pod.
+ */
+export type KubernetesAcquireFailureReason = 'api-unreachable' | 'api-timeout' | 'forbidden' | 'claim-rejected' | 'capacity' | 'image-pull' | 'not-ready';
+/**
+ * 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 declare class KubernetesAcquireError extends Error {
+    readonly name = "KubernetesAcquireError";
+    readonly reason: KubernetesAcquireFailureReason;
+    /** Whether attempting the same acquire again could plausibly succeed. */
+    readonly retryable: boolean;
+    /**
+     * `status.conditions[Ready].reason`, verbatim, when the controller
+     * refused the claim — `WarmPoolNotFound`, `TemplateNotFound`,
+     * `InvalidMetadata`, `EnvVarsInjectionRejected`. Present only for
+     * `'claim-rejected'`.
+     */
+    readonly controllerReason?: string;
+    /** The controller's own message for the same condition. */
+    readonly controllerMessage?: string;
+    constructor(details: {
+        readonly reason: KubernetesAcquireFailureReason;
+        readonly retryable: boolean;
+        readonly message: string;
+        readonly controllerReason?: string;
+        readonly controllerMessage?: string;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * 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.
+ */
+export declare const TERMINAL_CLAIM_REASONS: readonly string[];
+/**
+ * What this backend asked the controller to put on the claim's pod, carried
+ * into the rejection so an `InvalidMetadata` refusal can say what was sent
+ * and which knob changes it.
+ *
+ * Context, never a second decision: whether a claim is refused at all is
+ * {@link TERMINAL_CLAIM_REASONS}' answer and nobody else's, so an empty map
+ * changes nothing about the class thrown, the reason on it, or when it is
+ * raised.
+ */
+export interface ClaimPodMetadataContext {
+    readonly namespace: string;
+    /** `spec.additionalPodMetadata.labels`, exactly as sent. */
+    readonly requestedPodLabels: Readonly<Record<string, string>>;
+    /** The egress profile among those labels, when one is configured. */
+    readonly profile?: EgressProfileLabel;
+}
+/**
+ * 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 declare function classifyClaimRejection(claim: SandboxClaimResource | undefined, claimName: string, metadata?: ClaimPodMetadataContext): KubernetesAcquireError | undefined;
+export declare function retryDelayForApiFailure(err: unknown, pollIntervalMs: number): number | 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 declare function classifyAcquireFailure(err: unknown, podDiagnosis: 'capacity' | 'image-pull' | undefined): KubernetesAcquireError | 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.
+ *
+ * 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 declare function acquireKubernetesSandbox(client: KubernetesClient, config: KubernetesBackendInternalConfig, options: SandboxBackendOptions, readiness: {
+    readonly timeoutMs: number;
+    readonly pollIntervalMs: number;
+}, verifyIngress?: IngressVerifier | undefined, egressBoundary?: KubernetesEgressBoundary | undefined): Promise<KubernetesAcquisition>;
+/**
+ * Options for {@link releaseKubernetesTaskSandboxes}.
+ */
+export interface KubernetesReleaseTaskSandboxesOptions {
+    /**
+     * Required, and refused if empty — see {@link releaseKubernetesTaskSandboxes}.
+     * The same selector syntax a `kubectl get --selector` takes, e.g.
+     * `sandbox.namzu.ai/host-instance=host-a`.
+     */
+    readonly labelSelector: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * 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 declare function releaseKubernetesTaskSandboxes(config: KubernetesBackendInternalConfig, options: KubernetesReleaseTaskSandboxesOptions): Promise<{
+    readonly deleted: number;
+    readonly names: readonly string[];
+}>;
+/** Result of {@link readKubernetesTaskCapacity}. */
+export interface KubernetesTaskCapacity {
+    /** `config.warmPoolName`'s own replica counts, straight off its `status`/`spec`. */
+    readonly warmPool: {
+        /** `status.readyReplicas`. `0` when the field is absent (a brand-new or empty pool). */
+        readonly ready: number;
+        /** `spec.replicas`. `0` when the field is absent. */
+        readonly desired: number;
+    };
+    /** Every `SandboxClaim` in the namespace bound to `config.warmPoolName`, whatever its state. */
+    readonly activeClaims: number;
+    /** Every Pod in the namespace currently in phase `Pending`. */
+    readonly pendingPods: number;
+}
+/** Options for {@link readKubernetesTaskCapacity}. */
+export interface KubernetesReadTaskCapacityOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * 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 declare function readKubernetesTaskCapacity(config: KubernetesBackendInternalConfig, options?: KubernetesReadTaskCapacityOptions): Promise<KubernetesTaskCapacity>;
+/**
+ * What a directly created Sandbox copies out of a `SandboxTemplate`, and the
+ * two things it decides for itself.
+ */
+export interface SandboxBodyOptions {
+    readonly namespace: string;
+    readonly name: string;
+    readonly template: SandboxTemplateCopy;
+    /** The template the copy came from — the value of {@link sandboxTemplateLabel}. */
+    readonly sandboxTemplateName: string;
+    readonly runtimeClassName?: string;
+    /**
+     * RFC 3339 expiry, paired with `shutdownPolicy: Delete`. ABSENT means the
+     * object carries no expiry at all and nothing reaps it on the wall clock:
+     * that is the persistent workspace (`workspace.ts`), which is explicitly
+     * managed and must survive a host that stops renewing. Every task sandbox
+     * sets it, because an unbounded task sandbox is a leak.
+     */
+    readonly shutdownTime?: string;
+    /**
+     * Annotations to stamp on the Sandbox's OWN metadata at creation.
+     *
+     * One caller, and everything it writes is a fact the object has to carry
+     * from the moment it exists rather than from its first patch: the holder
+     * epoch of a workspace created under one, so there is no window in which
+     * it stands unfenced, and the revision of the pod template it was built
+     * from, so there is no window in which it claims none. Both are
+     * `workspace.ts`'s — see `HOLDER_EPOCH_ANNOTATION_KEY` and
+     * `POD_TEMPLATE_HASH_ANNOTATION_KEY`.
+     *
+     * Absent, the body is byte for byte what it always was, which is what
+     * keeps every task sandbox's create unchanged — a task sandbox is
+     * ephemeral, so it has no revision to drift from and nothing to fence.
+     */
+    readonly annotations?: Readonly<Record<string, string>>;
+    /**
+     * Extra labels stamped onto the POD template's metadata, beside the
+     * template label this body always adds.
+     *
+     * The same map `buildClaimBody` puts on a claim's
+     * `additionalPodMetadata.labels`, from the same
+     * `composeAdditionalPodLabels` call — a direct Sandbox has no controller
+     * to merge them for it, so the create body stamps them itself and the two
+     * paths produce one set of pod labels. Absent or empty, the pod template
+     * is byte for byte what it was.
+     */
+    readonly podLabels?: Readonly<Record<string, string>>;
+}
+/**
+ * The pool-less body. `Sandbox.spec` has no `templateRef` — only a
+ * SandboxWarmPool consumes a SandboxTemplate — so the template's podTemplate
+ * is copied in here by the client.
+ *
+ * `service: true` is forced rather than inherited: a Sandbox without a Service
+ * has no `status.serviceFQDN`, and then the only address left is a pod IP that
+ * changes on every resume.
+ *
+ * `volumeClaimTemplates` is copied VERBATIM when the template declares any.
+ * Dropping it would be silent: the Sandbox would come up healthy with no disk,
+ * the container's `volumeDevices`/`volumeMounts` entry would fail to resolve
+ * (or, worse, resolve to an empty emptyDir on some paths), and the only
+ * symptom of a workspace that lost its disk would be that yesterday's files
+ * are gone. The controller wires the mount by the entry's own NAME,
+ * StatefulSet style, so the copy needs no matching `volumes:` entry and this
+ * function adds none.
+ *
+ * The podTemplate's metadata gains {@link sandboxTemplateLabel}: this Sandbox
+ * is created DIRECTLY, never adopted out of a pool, so it never gets
+ * agent-sandbox's own controller-owned
+ * `agents.x-k8s.io/sandbox-template-ref-hash` label (that is written only on
+ * bind). Without a label of its own a direct Sandbox's pod would carry
+ * nothing `egress-policy.ts`'s translated `NetworkPolicy` could select it
+ * by. Existing labels on the copied template are preserved — this ADDS to
+ * them rather than replacing the object outright — but this backend's own
+ * key always wins if the template happened to set it too, since this is the
+ * label the translated policy is built to match.
+ */
+export declare function buildSandboxBody(options: SandboxBodyOptions): Record<string, unknown>;
+/**
+ * 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 declare function sandboxPodTemplate(template: SandboxTemplateCopy, sandboxTemplateName: string, runtimeClassName?: string, podLabels?: Readonly<Record<string, string>>): SandboxPodTemplate;
+/**
+ * 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 declare function sandboxPodLabels(template: SandboxTemplateCopy, sandboxTemplateName: string, extra?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/** The two halves of a `SandboxTemplate` a directly created Sandbox copies. */
+export interface SandboxTemplateCopy {
+    readonly podTemplate: SandboxPodTemplate;
+    /** Absent when the template declares no disk, which is every task template. */
+    readonly volumeClaimTemplates?: readonly SandboxVolumeClaimTemplate[];
+}
+export declare function readSandboxTemplate(client: KubernetesClient, namespace: string, sandboxTemplateName: string, signal?: AbortSignal): Promise<SandboxTemplateCopy>;
+/**
+ * Where the agent answers.
+ *
+ * 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 declare function resolveAgentAddress(binding: KubernetesSandboxBinding, agentPort: number, token: string, options?: {
+    readonly mode?: KubernetesAgentAddressMode;
+    /** The live pod the token came from. Required by `'pod-ip'`. */
+    readonly podIP?: string;
+}): KubernetesAgentAddress;
+/** Ready-or-not-yet, read off a `Sandbox`'s own status. Shared with `workspace.ts`. */
+export declare function bindingFromSandbox(sandbox: SandboxResource | undefined): KubernetesSandboxBinding | undefined;
+/**
+ * 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 declare class ReadinessPollTimeout extends Error {
+    readonly name = "ReadinessPollTimeout";
+}
+/**
+ * What a failed readiness read is worth, decided by the caller.
+ *
+ * Optional, and absent means exactly the behaviour every caller had before:
+ * the first failure of any kind ends the poll. `workspace.ts` passes nothing
+ * and is unchanged; the acquire path passes
+ * {@link retryDelayForApiFailure} so one 429 on a shared cluster no longer
+ * fails a create that had fifty-nine seconds of budget left.
+ */
+export interface ReadinessPollBehaviour {
+    /**
+     * Milliseconds to wait before reading again, or `undefined` to rethrow.
+     *
+     * The wait is spent on the SAME deadline as everything else in the poll,
+     * so a retry consumes the readiness budget and can never extend it. A hook
+     * that always returns a number therefore still terminates: the clock ends
+     * the loop, not the hook.
+     */
+    readonly retryDelayFor?: (err: unknown) => number | undefined;
+}
+/**
+ * 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 declare function pollForBinding(read: (signal: AbortSignal) => Promise<KubernetesSandboxBinding | undefined>, deadline: OperationDeadline, readiness: {
+    readonly timeoutMs: number;
+    readonly pollIntervalMs: number;
+}, label: string, behaviour?: ReadinessPollBehaviour): Promise<KubernetesSandboxBinding>;
+/**
+ * The live pod behind a bound sandbox: its uid, and — read in the SAME
+ * answer — the IP it can be dialed at.
+ *
+ * One record rather than two reads because the two facts have to describe one
+ * pod. The uid is the agent's bind token and the IP is where that agent
+ * listens; taking them from separate GETs leaves a window in which a resume,
+ * an eviction or a node drain replaces the pod in between, and the handle
+ * then presents pod A's token at pod B's address. The guest answers that with
+ * a flat `unauthorized`, which says nothing about the race that caused it.
+ */
+export interface KubernetesBoundPod {
+    /** `metadata.uid` — the agent's bind token. */
+    readonly uid: string;
+    /** `status.podIP`. Read by `agentAddress: 'pod-ip'`; absent is legal. */
+    readonly podIP?: string;
+    /**
+     * `metadata.labels` — what an ingress policy's `podSelector` actually
+     * matches. Read off the SAME object the uid and the address come from,
+     * for the same reason they are: a policy decision made about one pod and
+     * a connection made to another is the mismatch this record exists to
+     * prevent. The claim path reads it to ask which policies select the bound
+     * pod — a directly created Sandbox's labels are known before its pod
+     * exists — and BOTH paths read it to confirm the pod really carries the
+     * labels this backend asked the controller for, which is the one thing
+     * knowing them in advance cannot establish. See `ingress-policy.ts` and
+     * `assertRequestedPodLabelsObserved`.
+     */
+    readonly labels?: Readonly<Record<string, string>>;
+}
+/**
+ * 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
+ * guarantee, and `Sandbox.status` exposes no pod name to fall back on. So the
+ * fast path is one GET by that name, and the only cost of the name convention
+ * changing upstream is a second round trip through `status.selector`, which is
+ * exactly what the controller publishes the selector for.
+ */
+export declare function readBoundPod(client: KubernetesClient, namespace: string, binding: KubernetesSandboxBinding, signal?: AbortSignal): Promise<KubernetesBoundPod>;
+/**
+ * {@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 declare function readAddressedPod(client: KubernetesClient, namespace: string, binding: KubernetesSandboxBinding, deadline: OperationDeadline, readiness: {
+    readonly pollIntervalMs: number;
+}, mode: KubernetesAgentAddressMode, requiredLabels?: Readonly<Record<string, string>>): Promise<KubernetesBoundPod>;
+/**
+ * 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 declare function buildAgentAddressRefresh(client: KubernetesClient, namespace: string, binding: KubernetesSandboxBinding, agentPort: number, mode: KubernetesAgentAddressMode): (signal?: AbortSignal) => Promise<KubernetesAgentAddress>;
+/**
+ * Run the probe against a built Sandbox, on its own clock, and throw if it
+ * refuses. Cleanup is the CALLER's, and the two callers want opposite things:
+ * a task acquire destroys the instance, while `workspace.ts` suspends it,
+ * because deleting a workspace deletes its disk and a probe refusal is not a
+ * reason to lose a caller's files.
+ */
+export declare function probeSandboxPrivileges(sandbox: Sandbox, sandboxName: string, probeTimeoutMs: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=index.d.ts.map