@namzu/sandbox 14.0.0 → 16.0.0

package/src/index.ts

@@ -9,11 +9,29 @@
  *
  * Two tiers, each a trust boundary:
  *
- *  • `container` — one OCI container per task, seccomp on, tmpfs
- *    workdir, no network unless asked. The same path on a laptop and
- *    on a Linux replica anywhere. The tier for trusted prompts and
- *    contained workloads. Boundary: kernel namespaces, or a
- *    userspace-kernel runtime where one is installed.
+ *  • `container` — one OCI container per task, with the container itself
+ *    as the boundary: kernel namespaces, or a userspace-kernel runtime
+ *    where one is installed. The same path on a laptop and on a Linux
+ *    replica anywhere. The tier for trusted prompts and contained
+ *    workloads. What confines the workload INSIDE the container is
+ *    applied by each backend and documented where it is applied, not
+ *    promised here: `container:docker` drops every capability, sets
+ *    no-new-privileges, gives the container an IPC namespace nothing else can
+ *    join and mounts its root filesystem read-only over a named writable set
+ *    (see `backends/docker/index.ts`), while the ACI standby pool takes
+ *    its controls from the container-group profile its pool was built
+ *    from. This line used to claim "seccomp on, tmpfs workdir, no
+ *    network unless asked" on both their behalf, and none of the three
+ *    is a property this package establishes: nothing here passes a
+ *    seccomp flag, so what filters a container's syscalls is the daemon's
+ *    own profile rather than a default this package sets; the directory
+ *    the agent works in is the layout's `outputs` bind mount — a host
+ *    directory the run is collected from — rather than a tmpfs that would
+ *    lose it when the container exits; and the network a container is
+ *    attached to is a fact about
+ *    the backend's own configuration — a daemon network whose internals
+ *    the egress policy is checked against, or the container group's
+ *    subnet or public address.
  *
  *  • `microvm` — one hardware-virtualized guest per task. The boundary
  *    to reach for when the prompt itself is adversarial, at the cost
@@ -46,14 +64,27 @@ import { buildDockerBackend, resolveLayout } from './backends/docker/index.js'
 import { buildFirecrackerBackend } from './backends/firecracker/index.js'
 import type { KubernetesEgressConfig } from './backends/kubernetes/egress-policy.js'
 import {
+	type KubernetesAgentAddressMode,
 	type KubernetesBackendInternalConfig,
 	type KubernetesClusterAccess,
+	type KubernetesReadTaskCapacityOptions,
+	type KubernetesReleaseTaskSandboxesOptions,
+	type KubernetesTaskCapacity,
 	buildKubernetesBackend,
+	readKubernetesTaskCapacity as readTaskCapacityOnCluster,
+	releaseKubernetesTaskSandboxes as releaseTaskSandboxesOnCluster,
 } from './backends/kubernetes/index.js'
+import type { KubernetesIngressConfig } from './backends/kubernetes/ingress-policy.js'
 import {
 	type KubernetesWorkspace,
 	type KubernetesWorkspaceOptions,
+	type KubernetesWorkspaceSummary,
+	type KubernetesWorkspaceSuspendOptions,
+	type KubernetesWorkspaceTransitionOptions,
 	createKubernetesWorkspace as buildKubernetesWorkspace,
+	deleteKubernetesWorkspace as deleteWorkspaceOnCluster,
+	listKubernetesWorkspaces as listWorkspacesOnCluster,
+	suspendKubernetesWorkspace as suspendWorkspaceOnCluster,
 } from './backends/kubernetes/workspace.js'
 
 // Re-export the layout types so consumers of `@namzu/sandbox` can
@@ -89,24 +120,152 @@ export type {
 	OrchestratorTokenProvider,
 } from './backends/firecracker/index.js'
 export {
+	AgentDialFailedError,
 	AgentPreauthFrameTooLargeError,
+	AgentReadFileStreamUnsupportedError,
+	AgentWriteFileTooLargeError,
+	DEFAULT_MAX_WRITE_FILE_BYTES,
 	FIRECRACKER_AGENT_PROTOCOL_VERSION,
+	GUEST_FRAME_LIMIT_BYTES,
 	type SandboxAgentHandle,
 	TCP_PREAUTH_FRAME_LIMIT_BYTES,
 	type VsockTransportOptions,
 	VsockAgentTransport,
 } from './backends/firecracker/transport.js'
+// The `write-file` part protocol: the healthz feature string a guest
+// advertises when it can take a body larger than one frame, and the shape
+// of one part. Exported so a host writing its own guest, or asserting what
+// this one advertises, names them rather than repeating the literal.
+export {
+	WRITE_FILE_PARTS_FEATURE,
+	type WriteFilePart,
+} from './backends/firecracker/protocol.js'
+// The per-stream liveness heartbeat: the feature string a guest advertises
+// when it understands one, the frame both sides send, and how many missed
+// intervals end a stream. Same reason as above — a host asserting what this
+// guest advertises should name the string rather than repeat the literal.
+export {
+	MIN_STREAM_HEARTBEAT_MS,
+	STREAM_HEARTBEAT_FEATURE,
+	STREAM_HEARTBEAT_MAX_ECHO_FACTOR,
+	STREAM_HEARTBEAT_MISS_LIMIT,
+	type StreamHeartbeat,
+} from './backends/firecracker/protocol.js'
+// The read side of the same arrangement: one healthz feature string for
+// both the ranged `read-file` and the `read-file-stream` op, and the
+// request/event shapes they speak. Exported for the same reason — a host
+// writing its own guest, or asserting what this one advertises, names them
+// rather than repeating the literal.
+export {
+	READ_FILE_STREAM_FEATURE,
+	type ReadFileStreamEvent,
+	type ReadFileStreamRequest,
+} from './backends/firecracker/protocol.js'
 
 // Kubernetes (agent-sandbox on any cluster) public surface. The access union
 // is named by `KubernetesBackendConfig.access`, so a host that builds its own
-// credential callback can name what it is passing.
-export type { KubernetesClusterAccess } from './backends/kubernetes/index.js'
+// credential callback can name what it is passing; the address mode is named
+// by `KubernetesBackendConfig.agentAddress` and decides whether the agent is
+// dialed at its Service FQDN (in-cluster host) or at its pod IP (a host
+// outside the cluster, on a routable pod network).
+export type {
+	KubernetesAgentAddressMode,
+	KubernetesClusterAccess,
+} from './backends/kubernetes/index.js'
 // Egress translation types named by `KubernetesBackendConfig.egress` — see
-// `backends/kubernetes/egress-policy.ts` for what each engine can express.
+// `backends/kubernetes/egress-policy.ts` for what each engine can express,
+// and what the two Kubernetes-only kinds (`no-network`, `public-internet`)
+// mean that the shared `EgressPolicy` union has no word for.
 export type {
+	EgressProfileLabel,
+	KubernetesCiliumDnsNarrowing,
+	KubernetesCiliumEgressNarrowing,
 	KubernetesEgressConfig,
 	KubernetesEgressEngine,
+	KubernetesEgressPolicy,
+	KubernetesEgressVerification,
+	KubernetesOnlyEgressPolicy,
+	KubernetesPerSandboxEgressConfig,
+} from './backends/kubernetes/egress-policy.js'
+// Per-sandbox egress — `config.egress.perSandbox`, which makes
+// `Sandbox.setNetworkPolicy` PRESENT on a kubernetes TASK handle instead of
+// omitted. Everything a host needs to configure it and to catch its two
+// refusals by class: a capability declared in a way this backend cannot
+// honour (wiring time), and a write refused because the operator-applied
+// admission fence that bounds it is not there — or cannot be read, which is
+// a different file to fix (call time, nothing written in either case).
+// `KubernetesNetworkPolicyHostError` is the third: an `allowedHosts` entry
+// that is not a hostname, or one the configured narrowing cannot express.
+// `KubernetesOwnerUidMissingError` is the fourth, and the only one raised
+// from an ACQUIRE — the object this backend created reported no uid, so a
+// policy written for it would be an orphan.
+// `KubernetesWorkspacePerSandboxEgressConfigError` is the fifth: the same
+// option reaching `createKubernetesWorkspace`, whose handle never carries
+// `setNetworkPolicy` — refused there rather than accepted and ignored.
+// See `backends/kubernetes/per-sandbox-policy.ts` — and, for
+// `KubernetesNetworkPolicyHostError`, which the config-level translation
+// refuses the same entries with, `backends/kubernetes/egress-policy.ts`.
+export { KubernetesPerSandboxEgressConfigError } from './backends/kubernetes/egress-policy.js'
+export { KubernetesWorkspacePerSandboxEgressConfigError } from './backends/kubernetes/egress-policy.js'
+export { DEFAULT_PER_SANDBOX_EGRESS_LABEL_KEY } from './backends/kubernetes/egress-policy.js'
+export {
+	KubernetesAdmissionFenceMissingError,
+	KubernetesAdmissionFenceUnreadableError,
+	KubernetesNetworkPolicyHostError,
+	KubernetesOwnerUidMissingError,
+	PER_SANDBOX_POLICY_NAME_PREFIX,
+} from './backends/kubernetes/per-sandbox-policy.js'
+// The default label key `KubernetesEgressConfig.profile` is written under.
+// Exported because an operator has to name that key's DOMAIN in the
+// controller's `allowed-label-domains` allowlist before a profiled claim is
+// accepted, and reading it off the package beats copying a string out of a
+// document.
+export { DEFAULT_EGRESS_PROFILE_LABEL_KEY } from './backends/kubernetes/egress-policy.js'
+// The egress union check's refusal and the shapes it reports, so a host can
+// catch an over-wide policy by class and print which policy it was. Separate
+// from `KubernetesEgressPolicyMismatchError` (the ONE named object drifting)
+// and from `KubernetesIngressPolicyError` (the agent port being reachable):
+// three refusals on one create path, told apart by class.
+export type {
+	EgressPolicyRefusal,
+	EgressPolicyVerdict,
+	ExaminedEgressPolicy,
+} from './backends/kubernetes/egress-policy.js'
+export {
+	KubernetesEgressNarrowingUnsupportedError,
+	KubernetesEgressPolicyConfigError,
+	KubernetesEgressPolicyUnionError,
 } from './backends/kubernetes/egress-policy.js'
+// What an egress PROFILE adds to the refusals above. Two are thrown: a
+// profile this backend will not emit (while the host is still being wired),
+// and a bound pod that never carried the label this backend asked the
+// controller for — refused rather than admitted, because admitting it would
+// run the sandbox under whatever policy DOES select it. The third is never
+// thrown on its own: a claim the controller refused because a label key's
+// domain is not on its allowlist still comes out as
+// `KubernetesAcquireError { reason: 'claim-rejected' }`, and
+// `KubernetesPodLabelsRejectedError` is that error's `cause`, naming the map
+// that was sent and the config key that moves it.
+export {
+	KubernetesEgressProfileConfigError,
+	KubernetesPodLabelNotObservedError,
+	KubernetesPodLabelsRejectedError,
+} from './backends/kubernetes/egress-policy.js'
+// Ingress verification types named by `KubernetesBackendConfig.ingress`, plus
+// the refusal a create raises when no applied policy closes the agent port —
+// catchable by class, and distinct from every other refusal on that path. See
+// `backends/kubernetes/ingress-policy.ts`.
+export type {
+	ExaminedIngressPolicy,
+	IngressPolicyRefusal,
+	IngressPolicyVerdict,
+	KubernetesIngressConfig,
+	KubernetesIngressEngine,
+	/** @deprecated Renamed to `UnreadPolicySource`; both checks report it. */
+	UnreadIngressPolicySource,
+	UnreadPolicySource,
+} from './backends/kubernetes/ingress-policy.js'
+export { KubernetesIngressPolicyError } from './backends/kubernetes/ingress-policy.js'
 // The errors a caller of a kubernetes sandbox has to be able to catch BY
 // CLASS rather than by matching a message: an acquire refused because the
 // guest is not deprivileged, a call after the handle ended (this host
@@ -120,22 +279,246 @@ export {
 	KubernetesSandboxDestroyedError,
 	KubernetesSandboxGoneError,
 } from './backends/kubernetes/sandbox.js'
-export { KubernetesAgentUnauthorizedError } from './backends/kubernetes/transport.js'
+export {
+	KubernetesAgentAddressUnresolvableError,
+	// A guest that has fenced itself refuses one CALL here, not the
+	// workspace: the Firecracker tier's mapping of the same refusal retires
+	// the sandbox, which on a workspace would take the pod away from every
+	// other holder. See `backends/kubernetes/transport.ts`.
+	KubernetesAgentRetiringError,
+	KubernetesAgentUnauthorizedError,
+} from './backends/kubernetes/transport.js'
+// A workspace command that can outlive the connection watching it: the
+// options that ask for one, and the three refusals a caller has to be able
+// to catch BY CLASS — a guest image too old to keep output, an execution
+// that can no longer be attached to (past retention, or in a replaced
+// pod), and an observation this host gave up on WITHOUT cancelling, which
+// names the id and the byte offset another process resumes from.
+export type {
+	KubernetesAttachExecutionOptions,
+	KubernetesAttachRefusal,
+	KubernetesDetachedExecOptions,
+} from './backends/kubernetes/transport.js'
+export {
+	KubernetesExecutionAttachUnsupportedError,
+	KubernetesExecutionDetachedError,
+	KubernetesExecutionNotAttachableError,
+} from './backends/kubernetes/transport.js'
+// Guest sessions: a workspace terminal or background program that outlives
+// the connection — and the host process — that started it. The options that
+// name one, the rows `listSessions()` returns, the `BackgroundJobOutput`
+// shape `readSession()` answers in, and the three refusals a caller catches
+// BY CLASS: a guest image with no session registry, a session the guest
+// answered about and refused (past retention, or in a replaced pod), and an
+// attachment that ended while its program went on running.
+export type {
+	KubernetesAttachTerminalOptions,
+	KubernetesOpenTerminalOptions,
+	KubernetesReadSessionOptions,
+	KubernetesSessionOutput,
+	KubernetesSessionRefusal,
+	KubernetesSessionSummary,
+	KubernetesSessionTerminal,
+	KubernetesStartDetachedOptions,
+	KubernetesWorkspaceTerminal,
+} from './backends/kubernetes/transport.js'
+export {
+	KubernetesSessionRefusedError,
+	KubernetesSessionsUnsupportedError,
+} from './backends/kubernetes/transport.js'
+export { AgentSessionDetachedError } from './backends/firecracker/transport.js'
+// The `sessions` healthz feature string, and the session vocabulary its
+// frames use. Same reason as the two feature strings above: a host asserting
+// what an image can do should name the string rather than repeat the literal.
+export {
+	SESSIONS_FEATURE,
+	type SessionDetachReason,
+	type SessionKind,
+	type SessionState,
+} from './backends/firecracker/protocol.js'
+// Quiesce: stop every process a workspace's guest is running, while the
+// agent goes on serving, so a capture taken next is one nobody is writing
+// under. The report a host reads, the two refusals it catches by class, and
+// — for the same reason as the feature strings above — the `quiesce` string
+// itself and the scope vocabulary its report is written in.
+export type {
+	KubernetesQuiesceOptions,
+	KubernetesWorkspaceQuiesceRequest,
+} from './backends/kubernetes/workspace.js'
+export type { KubernetesQuiesceReport } from './backends/kubernetes/transport.js'
+export {
+	KubernetesQuiesceUnconfirmedError,
+	KubernetesQuiesceUnsupportedError,
+} from './backends/kubernetes/transport.js'
+export {
+	QUIESCE_FEATURE,
+	type QuiesceScope,
+	type QuiescedProcess,
+} from './backends/firecracker/protocol.js'
+// Flush: put a workspace's writes on its device on purpose, rather than
+// leaving them to whatever the guest kernel had written back when the pod
+// stopped. `suspend()` runs it by default; the verb, its options, the report
+// and the three named outcomes are exported for the hosts that flush at a
+// moment of their own — before a snapshot, before a drain — and for the
+// `flush` string itself, for the same reason as the feature strings above.
+// Only ONE of the three is ever thrown at a caller by a suspend
+// (`KubernetesFlushUnconfirmedError`, a guest that answered and could not
+// confirm); the other two are what `onFlushUnsupported` and
+// `onFlushUnreachable` are handed when the suspend goes ahead anyway, and a
+// host that wants to act on either has to be able to name the class.
+export type {
+	KubernetesFlushOptions,
+	KubernetesWorkspaceFlushRequest,
+} from './backends/kubernetes/workspace.js'
+export type { KubernetesFlushReport } from './backends/kubernetes/transport.js'
+export {
+	KubernetesFlushUnconfirmedError,
+	KubernetesFlushUnreachableError,
+	KubernetesFlushUnsupportedError,
+} from './backends/kubernetes/transport.js'
+export { FLUSH_FEATURE } from './backends/firecracker/protocol.js'
+// The API-request bound and the error it raises. Exported because
+// "distinguishable from a caller abort and from every other failure, by
+// type" is only true for a host that can name the class — and because a
+// host that sets `apiRequestTimeoutMs` wants the default and the floor it is
+// choosing against.
+// `KubernetesHttpMethod` rides along because `KubernetesApiTimeoutError.verb`
+// is one: a caller that can catch the class but cannot name the type of the
+// field it is reading is back to inlining the union or reaching for `any`.
+export {
+	DEFAULT_API_REQUEST_TIMEOUT_MS,
+	// Every API failure the four classes below do not name: a connect
+	// failure, and every non-2xx status outside 401/403/404/409/410. It
+	// carries the status and the `Retry-After` the server sent, because a
+	// burst past node capacity (429) and an API server that is down (a
+	// connect failure) were otherwise the same plain `Error`, separable only
+	// by matching a message any release is free to reword. It carries no
+	// retry policy — see `backends/kubernetes/index.ts` for who decides that.
+	KubernetesApiError,
+	type KubernetesApiFailureTransport,
+	KubernetesApiTimeoutError,
+	type KubernetesHttpMethod,
+	// A conditional write the API server would not apply. A host that fences
+	// its workspaces with a holder epoch normally catches
+	// `KubernetesWorkspacePreconditionError` instead — this one survives only
+	// when the object kept changing under the write or the patch body was
+	// wrong, and a caller that cannot name the class cannot tell it from a
+	// cluster failure.
+	KubernetesPatchNotAppliedError,
+	MIN_API_REQUEST_TIMEOUT_MS,
+} from './backends/kubernetes/k8s-client.js'
+// The three statuses the client maps to a class of their own, so a caller can
+// treat "already gone" as the state a teardown was asking for, re-read after a
+// 409, and tell a rejected credential from a cluster failure — by class, which
+// is the only way that survives a reworded message. They have been thrown
+// since the backend existed and were reachable only by importing a deep path.
+export {
+	KubernetesAlreadyGoneError,
+	KubernetesConflictError,
+	KubernetesCredentialError,
+} from './backends/kubernetes/k8s-client.js'
+// Why an acquire was refused, as a field rather than as prose: the seven
+// reasons, the class that carries one, and the measured list of controller
+// `Ready=False` reasons that mean "decided" rather than "not yet". A host
+// deciding whether to retry, to fail the run or to page an operator reads
+// `reason` and `retryable`; `cause` is the original failure, so a host that
+// already catches `ReadinessPollTimeout` or `KubernetesApiTimeoutError` finds
+// it there. See `backends/kubernetes/index.ts`.
+export {
+	KubernetesAcquireError,
+	type KubernetesAcquireFailureReason,
+	// The poll's own give-up, by type. It is the `cause` of a `'not-ready'`
+	// acquire refusal and is raised directly by the workspace lifecycle, which
+	// does not go through acquire.
+	ReadinessPollTimeout,
+	TERMINAL_CLAIM_REASONS,
+} from './backends/kubernetes/index.js'
+// The three ways egress verification refuses: a policy this engine cannot
+// express, no applied object at all, and an applied object that does not
+// match what this configuration translates to. Catchable by class for the
+// same reason the ingress refusal above is — an operator debugging two
+// default-on refusals in one release should not have to read messages to
+// tell them apart.
+export {
+	KubernetesEgressPolicyMismatchError,
+	KubernetesEgressPolicyNotAppliedError,
+	KubernetesUnenforceableEgressPolicyError,
+} from './backends/kubernetes/egress-policy.js'
+/** Default `KubernetesBackendConfig.streamHeartbeatMs` — see there. */
+export { DEFAULT_STREAM_HEARTBEAT_MS } from './backends/kubernetes/index.js'
+// Crash recovery and headroom for the task path: label a claim with a
+// host-supplied identity (`KubernetesBackendConfig.claimLabels`), find and
+// release a predecessor's claims by that label, and read pool headroom
+// before admitting more work. All three are additive — a host that sets no
+// `claimLabels` and calls neither function sees no change at all.
+export type {
+	KubernetesReadTaskCapacityOptions,
+	KubernetesReleaseTaskSandboxesOptions,
+	KubernetesTaskCapacity,
+} from './backends/kubernetes/index.js'
+// What a CLAIM-ONLY host is allowed to do, as data: the verbs the pool-only
+// path issues, each pinned to its call site in `backends/kubernetes/rbac.ts`.
+// `k8s/manifests/rbac-claimant.yaml` grants exactly this and a test parses
+// that file and compares it here, so an operator who has to prove a live
+// `Role` carries no more than this backend needs compares against the same
+// constant rather than against a list copied out of a page.
+export {
+	KUBERNETES_CLAIMANT_RBAC_RULES,
+	type KubernetesRbacRule,
+	type KubernetesRbacVerb,
+} from './backends/kubernetes/rbac.js'
 // The persistent workspace: a `Sandbox` that keeps a block disk across a
-// suspend, plus the four errors its lifecycle can refuse with — a template
-// that cannot carry a disk, a standing object that does not match this
-// configuration, a call on a suspended workspace, and a suspend whose pod
-// outlived the wait. Declared in `@namzu/sandbox` rather than on the SDK's
-// `Sandbox` — see `backends/kubernetes/workspace.ts`.
+// suspend, the union naming how a handle came by its object, plus the four
+// errors its lifecycle can refuse with — a template that cannot carry a disk,
+// a standing object that does not match this configuration, a call on a
+// suspended workspace, and a suspend whose pod outlived the wait. Declared in
+// `@namzu/sandbox` rather than on the SDK's `Sandbox` — see
+// `backends/kubernetes/workspace.ts`.
 export type {
+	KubernetesKillSessionOptions,
 	KubernetesWorkspace,
+	KubernetesWorkspaceAgentState,
+	KubernetesWorkspaceCancellationNotice,
 	KubernetesWorkspaceDestroyOptions,
 	KubernetesWorkspaceOptions,
+	KubernetesWorkspaceOrigin,
+	KubernetesWorkspaceStartFailurePolicy,
+	KubernetesWorkspaceSummary,
+	KubernetesWorkspaceSuspendOptions,
+	KubernetesWorkspaceSuspensionNotice,
 	KubernetesWorkspaceTransitionOptions,
 } from './backends/kubernetes/workspace.js'
+// What a workspace handle is bound to, what it says when the guest behind it
+// is replaced, and the two errors that identity produces. A host that keeps
+// per-workspace state — which processes it started, what is on the disk —
+// subscribes to `onGuestRestart` and compares `identity`; both are useless to
+// a host that cannot name their types.
+export type {
+	KubernetesGuestEvidence,
+	KubernetesGuestRestart,
+	KubernetesGuestRestartReason,
+	KubernetesWorkspaceIdentity,
+} from './backends/kubernetes/identity.js'
+export {
+	// The command's outcome is unknown AND the guest it ran in is gone. A
+	// subclass of `RemoteCancellationUnknownError`, so a host catching the
+	// base class keeps catching it; what it adds is which guest the command
+	// started on and which one is there now.
+	KubernetesWorkspaceGuestGoneError,
+	// A different Sandbox now stands under the workspace's deterministic
+	// name, or none does. The handle refuses rather than following it — the
+	// disk behind the name is not the disk it was opened on.
+	KubernetesWorkspaceReplacedError,
+} from './backends/kubernetes/identity.js'
 export {
 	KubernetesWorkspaceDiskError,
 	KubernetesWorkspaceMismatchError,
+	// A lifecycle write refused because this caller's holder epoch has been
+	// overtaken: the workspace belongs to another process now, nothing on the
+	// cluster changed and nothing about the handle changed. A host that fences
+	// its workspaces has to be able to tell this from a cluster failure, which
+	// is the whole reason the write is conditional.
+	KubernetesWorkspacePreconditionError,
 	KubernetesWorkspaceSuspendTimeoutError,
 	KubernetesWorkspaceSuspendedError,
 } from './backends/kubernetes/workspace.js'
@@ -320,6 +703,46 @@ export interface ContainerBackendConfig {
 	 * collisions with Docker / orchestrator labels.
 	 */
 	readonly labels?: Readonly<Record<string, string>>
+	/**
+	 * CPU cores the container may use, rendered as `--cpus`. Unset by
+	 * default, like `memoryLimitMb` and `maxProcesses`, and for the same
+	 * reason: the value that is right is a property of the host's machine
+	 * and of the workload, and a number chosen here would silently throttle
+	 * runs that finish inside their timeout today.
+	 *
+	 * It is set at provider construction rather than per `create()` call,
+	 * because the documented deployment builds one provider per task — and
+	 * because the ACI and kubernetes backends cannot apply a per-sandbox CPU
+	 * limit, so a per-call field would be a control they would have to
+	 * refuse. See `backends/docker/index.ts` for what it renders.
+	 */
+	readonly cpuLimit?: number
+	/**
+	 * Mount the container's root filesystem read-only. Default `true`.
+	 *
+	 * On by default with the paths that stay writable named in
+	 * `backends/docker/index.ts` (`writableRootfsPaths` extends them). Set it
+	 * to `false` to make the whole container filesystem writable again, which a
+	 * host whose image writes somewhere the writable set cannot describe needs,
+	 * and which is why the switch exists rather than the baseline being
+	 * unconditional. It gives up that one control: the capability drop,
+	 * `no-new-privileges` and `--ipc private` are applied to every container
+	 * whatever this says, so it is not a way back to the previous argv.
+	 */
+	readonly readOnlyRootfs?: boolean
+	/**
+	 * Extra paths to keep writable under `--read-only`, each mounted
+	 * `--tmpfs`.
+	 *
+	 * The default set is the reference image's needs, read off its Dockerfile.
+	 * A host that points `image` at its own build says what that image needs
+	 * here, because the backend cannot read an image's writable set and the
+	 * alternative to asking is guessing. Setting this beside
+	 * `readOnlyRootfs: false` is refused: with a writable root filesystem the
+	 * mounts would add nothing, and accepting a control that is not applied is
+	 * the failure this package refuses everywhere else.
+	 */
+	readonly writableRootfsPaths?: readonly string[]
 }
 
 /**
@@ -480,6 +903,24 @@ export interface KubernetesBackendConfig {
 	readonly warmPoolName?: string
 	/** TCP port the in-pod guest agent listens on. Default 1024. */
 	readonly agentPort?: number
+	/**
+	 * Which of a sandbox's two addresses the transport dials.
+	 *
+	 * `'service'` (default) is the Sandbox's `status.serviceFQDN`, which
+	 * outlives the pod and is re-resolved on every dial — and which ONLY the
+	 * cluster's own DNS answers. A host running outside the cluster fails
+	 * every call at name resolution, readiness included, so it reads as a
+	 * sandbox that never came up.
+	 *
+	 * `'pod-ip'` dials the bound pod's IP, read from the same `GET` that
+	 * reads its bind token. For a host outside the cluster with a route to
+	 * the pod network. It needs that route and a `NetworkPolicy` admitting
+	 * the host's address range on {@link agentPort}; the IP dies with its
+	 * pod, which the backend covers by re-reading it on every resume and once
+	 * after a connect failure. Nothing else changes: same bind token, same
+	 * privilege probe, same egress verification.
+	 */
+	readonly agentAddress?: KubernetesAgentAddressMode
 	/** Delay between readiness polls. Default 50ms. */
 	readonly readyPollIntervalMs?: number
 	/** Total deadline from create to an addressed, Ready sandbox. Default 60000ms. */
@@ -495,10 +936,12 @@ export interface KubernetesBackendConfig {
 	 *
 	 * The handle renews its own `shutdownTime` every half-TTL for as long as
 	 * it is alive, so a run that outlives `claimTtlSeconds` keeps its pod.
-	 * A failed renewal is retried on the next tick, half a TTL before
-	 * anything expires; this callback is where the diagnostic goes, because
-	 * `@namzu/sandbox` owns no logger and reads none from module scope.
-	 * Setting it changes nothing about behaviour.
+	 * A failed renewal is retried on a short capped backoff — starting at one
+	 * second, not the next half-TTL tick — so a single API blip near a
+	 * scheduled renewal gets several more chances before anything expires;
+	 * this callback is where the diagnostic goes, because `@namzu/sandbox`
+	 * owns no logger and reads none from module scope. Setting it changes
+	 * nothing about behaviour.
 	 */
 	readonly onLeaseRenewalError?: (error: unknown) => void
 	/**
@@ -521,10 +964,89 @@ export interface KubernetesBackendConfig {
 	 * enforcement point is one object attached to the template and cannot be
 	 * rewritten per running sandbox. `static` and `resolver` — hostname
 	 * allowlists — throw a named error at construction unless `engine` is
-	 * `'cilium'`: core `NetworkPolicy` has no FQDN concept at all. See
+	 * `'cilium'`: core `NetworkPolicy` has no FQDN concept at all.
+	 *
+	 * `policy` also takes two kinds that exist only here, because only a
+	 * `NetworkPolicy` can express them: `{ kind: 'no-network' }` (nothing
+	 * leaves the pod, the cluster resolver included — which `'deny-all'` never
+	 * meant, since it allows DNS and a cluster resolver forwards outside
+	 * names) and `{ kind: 'public-internet', exceptCidrs? }` (the internet,
+	 * minus the private ranges, carrier-grade NAT, link-local and one cloud
+	 * platform endpoint). `'deny-all'` and `'allow-all'` emit exactly the
+	 * manifests they always have.
+	 *
+	 * **Setting this now checks the UNION.** Since every policy selecting a
+	 * pod is unioned by the API server, the check reads the named object AND
+	 * enumerates the namespace's policies, refusing when any of them lets out
+	 * more than `policy` does. `verify: 'named-object-only'` restores the
+	 * single-object check exactly. See
 	 * `docs/sdk/kubernetes-sandbox.md`'s egress section.
 	 */
 	readonly egress?: KubernetesEgressConfig
+	/**
+	 * Whether this backend proves, before creating a sandbox, that an applied
+	 * policy actually closes {@link agentPort} on the pod it is about to hand
+	 * back — and against which policy resources.
+	 *
+	 * **Unset means verify.** This is the one field here whose absent value is
+	 * the strict one, because the deployment that needs the check is the one
+	 * that would never have switched it on: the guest agent's own source calls
+	 * the network rule in front of its port the boundary, and until this field
+	 * existed nothing confirmed there was one.
+	 *
+	 * `{ engine: 'cilium' }` also enumerates that CNI's own policy CRD;
+	 * `engine` otherwise defaults to `egress?.engine ?? 'core'`.
+	 *
+	 * `'unverified'` reads no policy and issues no request. It is the
+	 * supported answer for a deployment whose boundary a namespaced Role
+	 * cannot see — a cluster-scoped policy, a service mesh, a cloud security
+	 * group — and it is a claim the deployment makes on purpose rather than a
+	 * default it inherits. See `docs/sdk/kubernetes-sandbox.md`'s ingress
+	 * section.
+	 */
+	readonly ingress?: KubernetesIngressConfig
+	/**
+	 * How long a single Kubernetes API request may take, end to end —
+	 * resolving the token, connecting, and reading the reply. Default
+	 * `30000`; minimum `1000`; there is no value that turns it off.
+	 *
+	 * The caller's `signal` is optional everywhere and several of this
+	 * backend's requests are SHARED flights that run under whichever caller
+	 * arrived first, so a signal-less `destroy()` against an API server that
+	 * accepted a request and never answered used to pin every later caller
+	 * joined to it. Expiry rejects with `KubernetesApiTimeoutError`, which
+	 * says nothing about whether the request was applied — the paths that
+	 * send one already cope with not knowing.
+	 */
+	readonly apiRequestTimeoutMs?: number
+	/**
+	 * Interval of the liveness heartbeat `openTerminal` and
+	 * `openTcpConnection` streams negotiate with the guest. Default `15000`;
+	 * `0` sends none, which is exactly how every release before this one
+	 * behaved.
+	 *
+	 * A quiet shell is healthy, so nothing replaced the read-idle timer the
+	 * transport clears once a stream is ready: a partition that delivered no
+	 * FIN and no RST left `exited`/`closed` unresolved on the host and the
+	 * shell's process group alive in the guest. Three missed intervals end
+	 * the stream on both sides. It is negotiated per stream — the guest
+	 * echoes the interval in its `ready` event and sends nothing new unless
+	 * it did — so an older guest image behaves exactly as it does today.
+	 */
+	readonly streamHeartbeatMs?: number
+	/**
+	 * Extra labels written onto every `SandboxClaim` this backend POSTs —
+	 * `metadata.labels` only, never the pod's own labels. Unset means no
+	 * labels beyond what the controller itself writes, and every claim body
+	 * is byte-for-byte what it was before this option existed.
+	 *
+	 * The intended use is a host-instance identity, so a restarted host can
+	 * find and {@link releaseKubernetesTaskSandboxes} a crashed predecessor's
+	 * claims well before `claimTtlSeconds` reaps them on its own — see
+	 * {@link readKubernetesTaskCapacity} for reading pool headroom
+	 * alongside it.
+	 */
+	readonly claimLabels?: Record<string, string>
 }
 
 /**
@@ -796,6 +1318,11 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 			...(backend.network !== undefined ? { network: backend.network } : {}),
 			...(backend.allowInwardFor !== undefined ? { allowInwardFor: backend.allowInwardFor } : {}),
 			...(backend.labels !== undefined ? { labels: backend.labels } : {}),
+			...(backend.cpuLimit !== undefined ? { cpuLimit: backend.cpuLimit } : {}),
+			...(backend.readOnlyRootfs !== undefined ? { readOnlyRootfs: backend.readOnlyRootfs } : {}),
+			...(backend.writableRootfsPaths !== undefined
+				? { writableRootfsPaths: backend.writableRootfsPaths }
+				: {}),
 		})
 	}
 	if (backend.tier === 'container' && backend.runtime === 'runsc') {
@@ -816,6 +1343,11 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 			...(backend.network !== undefined ? { network: backend.network } : {}),
 			...(backend.allowInwardFor !== undefined ? { allowInwardFor: backend.allowInwardFor } : {}),
 			...(backend.labels !== undefined ? { labels: backend.labels } : {}),
+			...(backend.cpuLimit !== undefined ? { cpuLimit: backend.cpuLimit } : {}),
+			...(backend.readOnlyRootfs !== undefined ? { readOnlyRootfs: backend.readOnlyRootfs } : {}),
+			...(backend.writableRootfsPaths !== undefined
+				? { writableRootfsPaths: backend.writableRootfsPaths }
+				: {}),
 		})
 	}
 	// `microvm:self-hosted` targeting the OWNED Azure Firecracker
@@ -871,6 +1403,7 @@ function kubernetesInternalConfig(
 		sandboxTemplateName: backend.sandboxTemplateName,
 		...(backend.warmPoolName !== undefined ? { warmPoolName: backend.warmPoolName } : {}),
 		...(backend.agentPort !== undefined ? { agentPort: backend.agentPort } : {}),
+		...(backend.agentAddress !== undefined ? { agentAddress: backend.agentAddress } : {}),
 		...(backend.readyPollIntervalMs !== undefined
 			? { readyPollIntervalMs: backend.readyPollIntervalMs }
 			: {}),
@@ -883,6 +1416,14 @@ function kubernetesInternalConfig(
 			? { runtimeClassName: backend.runtimeClassName }
 			: {}),
 		...(backend.egress !== undefined ? { egress: backend.egress } : {}),
+		...(backend.ingress !== undefined ? { ingress: backend.ingress } : {}),
+		...(backend.apiRequestTimeoutMs !== undefined
+			? { apiRequestTimeoutMs: backend.apiRequestTimeoutMs }
+			: {}),
+		...(backend.streamHeartbeatMs !== undefined
+			? { streamHeartbeatMs: backend.streamHeartbeatMs }
+			: {}),
+		...(backend.claimLabels !== undefined ? { claimLabels: backend.claimLabels } : {}),
 	}
 }
 
@@ -913,6 +1454,114 @@ export async function createKubernetesWorkspace(
 	return await buildKubernetesWorkspace(kubernetesInternalConfig(config), options)
 }
 
+/**
+ * Every workspace this backend owns in the namespace, read off the objects
+ * and waking none of them.
+ *
+ * The inventory {@link createKubernetesWorkspace} cannot give you: it adopts
+ * AND resumes, so taking stock through it would start a pod for every
+ * suspended workspace it looked at. This issues one GET of the sandboxes
+ * collection and sends no PATCH and no DELETE — a suspended workspace is
+ * still suspended afterwards.
+ *
+ * Needs `list` on `sandboxes` in the namespace, which is the one RBAC verb
+ * the task path did not already require.
+ */
+export async function listKubernetesWorkspaces(
+	config: KubernetesBackendConfig,
+	options?: KubernetesWorkspaceTransitionOptions,
+): Promise<readonly KubernetesWorkspaceSummary[]> {
+	return await listWorkspacesOnCluster(kubernetesInternalConfig(config), options)
+}
+
+/**
+ * Delete a workspace by id — the Sandbox, and with it the Pod, the Service
+ * and the PVC — without adopting or resuming it first.
+ *
+ * Exactly what `destroy({ deleteDisk: true })` does to the cluster, with the
+ * same guarantees: an object already gone counts as deleted, and a DELETE
+ * that fails rejects and stays retryable. The files are gone and nothing
+ * brings them back.
+ *
+ * It is the retention verb. Removing a month-old suspended workspace through
+ * a handle meant starting its pod and probing it purely to tell it to go
+ * away; the name is deterministic, so the object never needed opening.
+ */
+export async function deleteKubernetesWorkspace(
+	config: KubernetesBackendConfig,
+	workspaceId: string,
+	options?: KubernetesWorkspaceTransitionOptions,
+): Promise<void> {
+	await deleteWorkspaceOnCluster(kubernetesInternalConfig(config), workspaceId, options)
+}
+
+/**
+ * Suspend a workspace by id: send the `operatingMode: Suspended` patch and
+ * wait for the pod to actually stop, without adopting the workspace.
+ *
+ * Resolves only once the pod is gone or in a terminal phase — a suspend is a
+ * promise that the disk is quiesced, and the patch being accepted says only
+ * that the controller has been asked. A pod that outlives `readyTimeoutMs`
+ * rejects with `KubernetesWorkspaceSuspendTimeoutError`, leaving the object
+ * as the patch left it.
+ *
+ * A handle another process is holding is not told. It finds out on its next
+ * call — which fails at the transport and is re-read into a
+ * `KubernetesWorkspaceSuspendedError` — or when that process calls
+ * `refresh()`.
+ *
+ * It takes the suspend options shape and REFUSES `quiesce` rather than
+ * accepting the flag and dropping it: this verb never dials the agent, so
+ * there is no connection here on which anything could be stopped. Quiescing
+ * needs a handle — `createKubernetesWorkspace()`, then
+ * `suspend({ quiesce: true })`.
+ */
+export async function suspendKubernetesWorkspace(
+	config: KubernetesBackendConfig,
+	workspaceId: string,
+	options?: KubernetesWorkspaceSuspendOptions,
+): Promise<void> {
+	await suspendWorkspaceOnCluster(kubernetesInternalConfig(config), workspaceId, options)
+}
+
+/**
+ * Recover a crashed host's task-path claims: LIST every `SandboxClaim`
+ * carrying `options.labelSelector`, `DELETE` each, and report what was
+ * removed.
+ *
+ * Deletes claims only — the controller's own ownerReferences take the bound
+ * Sandbox, its Pod and its Service down behind each one; nothing here reads
+ * or touches those objects directly. `labelSelector` is REQUIRED and refused
+ * before any request goes out if it is empty: falling back to matching every
+ * claim would delete a live fleet's work.
+ *
+ * Pairs with `config.claimLabels`: a host stamps its own identity onto every
+ * claim it creates, and a restarted instance passes that same selector here
+ * to reclaim its predecessor's warm-pool capacity well before
+ * `claimTtlSeconds` would reap it on its own.
+ */
+export async function releaseKubernetesTaskSandboxes(
+	config: KubernetesBackendConfig,
+	options: KubernetesReleaseTaskSandboxesOptions,
+): Promise<{ readonly deleted: number; readonly names: readonly string[] }> {
+	return await releaseTaskSandboxesOnCluster(kubernetesInternalConfig(config), options)
+}
+
+/**
+ * Read task-pool headroom before admitting more work: three GETs
+ * (`SandboxWarmPool`, the claims collection, the pods collection), no
+ * writes.
+ *
+ * Requires `config.warmPoolName` — a pool-less backend (every create is a
+ * direct Sandbox) has no `SandboxWarmPool` to report on.
+ */
+export async function readKubernetesTaskCapacity(
+	config: KubernetesBackendConfig,
+	options?: KubernetesReadTaskCapacityOptions,
+): Promise<KubernetesTaskCapacity> {
+	return await readTaskCapacityOnCluster(kubernetesInternalConfig(config), options)
+}
+
 /**
  * Human-readable backend label for error messages. Returns the
  * tier plus the concrete service / runtime when present, e.g.