@namzu/sandbox 14.0.0 → 15.0.0

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

@@ -62,20 +62,64 @@
  * the pod — so the call would hang until a connect timeout with nothing in
  * the failure naming the suspend.
  *
+ * Both patches also stamp
+ * {@link OPERATING_MODE_CHANGED_AT_ANNOTATION_KEY}. Nothing in this module
+ * reads it back; it exists so that an inventory can say when a workspace was
+ * last put to sleep without waking it up to ask, which the controller's own
+ * lingering `Suspended` condition cannot answer. See
+ * {@link listKubernetesWorkspaces}.
+ *
+ * ## Three verbs that never open a workspace, and one that notices
+ *
+ * {@link createKubernetesWorkspace} adopts AND resumes, which is right for a
+ * host about to USE a workspace and wrong for everything else. Deleting a
+ * month-old suspended workspace through it means starting a pod, probing it
+ * and deleting it again; taking an inventory means waking every suspended
+ * object in the namespace. So the three operations that are about the OBJECT
+ * are reachable without a handle — {@link listKubernetesWorkspaces},
+ * {@link deleteKubernetesWorkspace} and {@link suspendKubernetesWorkspace} —
+ * and none of them creates a pod, dials an agent or resumes anything.
+ *
+ * The other half of the same problem is the handle that was already open when
+ * somebody else did one of those. A workspace id is a name, not a lock, so a
+ * second process can suspend the workspace this one is holding, and this
+ * handle's `state` is a record of what THIS process did. Two things fix that,
+ * and both re-read the object rather than guessing:
+ * {@link KubernetesWorkspace.refresh} when the caller asks, and the re-read
+ * after a call that FAILED at the transport — which is how it would otherwise
+ * be found out, as a connect refusal or a flat `unauthorized` naming nothing.
+ * Either one records the suspension as UNCONFIRMED (`suspending`, not
+ * `suspended`): what was observed is the object's mode, not the pod stopping,
+ * and only a wait this process performed can promise the disk is quiesced.
+ *
  * ## Adoption is checked against the object, not against the caller
  *
  * A create that collides with an existing object of the same name ADOPTS it,
  * because the deterministic name is only worth having if coming back is the
  * normal path. What is adopted is then checked against the configuration: the
- * block disk, the `sandbox.namzu.ai/template` pod label (the label an egress
- * NetworkPolicy selects by) and `runtimeClassName` (the VM boundary). A
- * standing object that disagrees with any of them is refused by name rather
- * than driven — see {@link KubernetesWorkspaceMismatchError}. What is NOT
+ * block disk, the `sandbox.namzu.ai/template` pod label (the label the
+ * ingress and egress policies select by) and `runtimeClassName` (the VM
+ * boundary). A standing object that disagrees with any of them is refused by
+ * name rather than driven — see {@link KubernetesWorkspaceMismatchError}. What is NOT
  * checked, and cannot be from here, is whether somebody else is already using
  * it: two host processes can hold handles to one running workspace, and the
  * `destroy()` of either suspends the pod the other is executing in. A
  * workspace id is a name, not a lock.
  *
+ * An adopt also has to survive walking in ON a transition, which is the
+ * normal way a workspace is found rather than an edge: a suspend that ended
+ * in {@link KubernetesWorkspaceSuspendTimeoutError}, a second host coming up
+ * during a rollout, a host restarting inside the previous pod's
+ * `terminationGracePeriodSeconds`. In all three the pod under the name is
+ * draining or already gone, and the replacement has not been created yet. So
+ * an adopt that finds the object `Suspended`, or finds its pod carrying a
+ * `deletionTimestamp`, WAITS for the replacement under the same readiness
+ * budget the resume path waits under, instead of failing on the first read
+ * that finds no live pod. What it came by is then reported as `origin`:
+ * `created`, `adopted-running` or `resumed` — a host that adopted a pod
+ * another process left running needs to know that none of that process's
+ * terminals survived it.
+ *
  * ## There is no delete-compute-keep-disk verb
  *
  * The API has `operatingMode` and it has DELETE. Nothing in between. So
@@ -91,9 +135,10 @@
  * {@link createKubernetesWorkspace}), and a pod that stops being able to say
  * what happened to a command — the shared execution controller's unconfirmed
  * cancellation, which retires a task sandbox by DELETING it — is retired here
- * by that same suspend patch (see {@link retireSession}). Exactly one DELETE
- * is reachable from this module, and it is the one `deleteDisk: true` asks
- * for.
+ * by that same suspend patch (see {@link retireSession}). Exactly two DELETEs
+ * are reachable from this module and both are ASKED FOR by name — the one
+ * `deleteDisk: true` sends and the one {@link deleteKubernetesWorkspace} is;
+ * no failure path, no `finally`, and no default reaches either.
  *
  * ## A state is committed when the cluster confirms it, never before
  *
@@ -112,9 +157,12 @@
  * arriving mid-transition awaits the one in progress instead of sending a
  * second request into the gap the deferred mark opens.
  */
-import type { OpenTerminalOptions, Sandbox, SandboxDestroyOptions, SandboxTcpConnectOptions, SandboxTcpConnection, TerminalSession } from '@namzu/sdk';
+import type { Sandbox, SandboxDestroyOptions, SandboxExecResult, SandboxFileEntry, SandboxReadFileOptions, SandboxTcpConnectOptions, SandboxTcpConnection, SandboxWalkFilesOptions } from '@namzu/sdk';
+import { type EgressProfileLabel } from './egress-policy.js';
+import { type KubernetesGuestEvidence, type KubernetesGuestRestart, type KubernetesWorkspaceIdentity } from './identity.js';
 import { type KubernetesBackendInternalConfig } from './index.js';
 import { type SandboxPodTemplate, type SandboxVolumeClaimTemplate } from './objects.js';
+import { type KubernetesAttachExecutionOptions, type KubernetesAttachTerminalOptions, type KubernetesDetachedExecOptions, type KubernetesFlushReport, KubernetesFlushUnreachableError, KubernetesFlushUnsupportedError, type KubernetesOpenTerminalOptions, type KubernetesQuiesceReport, KubernetesQuiesceUnsupportedError, type KubernetesReadSessionOptions, type KubernetesSessionOutput, type KubernetesSessionSummary, type KubernetesSessionTerminal, type KubernetesStartDetachedOptions, type KubernetesWorkspaceTerminal } from './transport.js';
 /**
  * Thrown when a workspace's `SandboxTemplate` does not describe a block disk
  * this backend is willing to build a workspace on.
@@ -149,6 +197,14 @@ export declare class KubernetesWorkspaceDiskError extends Error {
  *    egress `NetworkPolicy`'s `podSelector` matches. A pod carrying another
  *    value — or none — is not selected by the policy this call just verified,
  *    so the boundary would report verified while covering nothing.
+ *  - the egress PROFILE label, when `config.egress.profile` is set, for
+ *    exactly the same reason: it is the selector's second half. A standing
+ *    object built before the profile existed, or under a different one,
+ *    carries a pod the per-profile policy does not select — and once each
+ *    profile has its own policy object, as it must, a pod carrying neither
+ *    key is selected by no egress policy at all. This one is checked only
+ *    when a profile is configured: with none, the policy this call verified
+ *    selects the template label alone, which the object does carry.
  *  - `runtimeClassName`, which is the VM boundary. The privilege probe cannot
  *    stand in for it: `/proc/self/status` reads the same inside a VM guest as
  *    it does inside an ordinary shared-kernel container.
@@ -161,8 +217,12 @@ export declare class KubernetesWorkspaceMismatchError extends Error {
     /** The Sandbox found standing under this workspace's name. */
     readonly sandboxName: string;
     /** Which configured field the standing object disagrees with. */
-    readonly field: 'sandboxTemplateName' | 'runtimeClassName';
-    /** What the configuration asked for. */
+    readonly field: 'sandboxTemplateName' | 'egressProfile' | 'runtimeClassName';
+    /**
+     * What the configuration asked for. `key=value` for `egressProfile`,
+     * because the KEY is configurable too and the value alone would not
+     * say which label was compared.
+     */
     readonly expected: string;
     /** What the object carries — absent when it carries nothing at all. */
     readonly actual: string | undefined;
@@ -171,25 +231,53 @@ export declare class KubernetesWorkspaceMismatchError extends Error {
     /** The Sandbox found standing under this workspace's name. */
     sandboxName: string, 
     /** Which configured field the standing object disagrees with. */
-    field: 'sandboxTemplateName' | 'runtimeClassName', 
-    /** What the configuration asked for. */
+    field: 'sandboxTemplateName' | 'egressProfile' | 'runtimeClassName', 
+    /**
+     * What the configuration asked for. `key=value` for `egressProfile`,
+     * because the KEY is configurable too and the value alone would not
+     * say which label was compared.
+     */
     expected: string, 
     /** What the object carries — absent when it carries nothing at all. */
     actual: string | undefined, message: string);
 }
+/**
+ * How a caller came to be told a workspace is suspended.
+ *
+ *  - `admission` — the handle knew before the call, so nothing was dialed.
+ *    Every suspend this handle performed, and every one it has already
+ *    noticed, lands here.
+ *  - `transport` — the call went out and failed, and the re-read that
+ *    followed found the object `Suspended`. Somebody ELSE suspended this
+ *    workspace while this handle was holding it; the failure that prompted
+ *    the re-read is on `cause`.
+ */
+export type KubernetesWorkspaceSuspensionNotice = 'admission' | 'transport';
 /**
  * Thrown by every operation on a workspace that is currently suspended.
  *
  * Distinct from {@link KubernetesSandboxDestroyedError} because the state is
- * RECOVERABLE and the advice is one word: call `resume()`. Nothing is dialed
- * before it is thrown.
+ * RECOVERABLE and the advice is one word: call `resume()`.
+ *
+ * `noticedBy` says which of the two ways the caller got here, and the message
+ * changes with it, because "nothing was dialed" is a promise the first one
+ * keeps and the second one cannot. A workspace another process suspended is
+ * discovered by a call FAILING — the pod is gone, so the dial is refused, or
+ * the replacement pod's agent refuses this handle's token — and the reason
+ * that is worth converting into this error rather than passing on is that the
+ * raw failure names nothing: a flat `unauthorized`, or a connect error against
+ * an address that still resolves because the Service outlives the pod.
  */
 export declare class KubernetesWorkspaceSuspendedError extends Error {
     readonly operation: string;
     readonly workspaceId: string;
     readonly sandboxName: string;
+    /** See {@link KubernetesWorkspaceSuspensionNotice}. Defaults to `admission`. */
+    readonly noticedBy: KubernetesWorkspaceSuspensionNotice;
     readonly name = "KubernetesWorkspaceSuspendedError";
-    constructor(operation: string, workspaceId: string, sandboxName: string);
+    constructor(operation: string, workspaceId: string, sandboxName: string, 
+    /** See {@link KubernetesWorkspaceSuspensionNotice}. Defaults to `admission`. */
+    noticedBy?: KubernetesWorkspaceSuspensionNotice, options?: ErrorOptions);
 }
 /**
  * Thrown when a suspend's `operatingMode: Suspended` patch was accepted and
@@ -218,9 +306,337 @@ export declare class KubernetesWorkspaceSuspendTimeoutError extends Error {
     /** The readiness budget the wait was given, in milliseconds. */
     timeoutMs: number);
 }
-/** Authority for one lifecycle transition, owned independently of the run. */
+/**
+ * Thrown when a lifecycle write carried a holder epoch the workspace has
+ * already moved past: the request was NOT sent, or was sent and refused, and
+ * nothing on the cluster changed either way.
+ *
+ * The workspace is somebody else's now. The epoch stored on the Sandbox is
+ * higher than the one this call carried, which is what a host says when it
+ * hands authority over a workspace to another process — see
+ * {@link HOLDER_EPOCH_ANNOTATION_KEY}. A superseded holder that suspends,
+ * resumes or deletes anyway would be taking the pod, or the disk, away from
+ * whoever holds it now.
+ *
+ * Nothing about the handle changes either. A refused `suspend()` leaves the
+ * handle exactly where it was — still `running`, terminals still open,
+ * because the refusal is decided BEFORE they are reaped — so a caller that
+ * catches this and re-reads its own holder record has lost nothing.
+ *
+ * `storedEpoch` is `undefined` in the one case the annotation cannot be read
+ * at all: it is present and is not a decimal integer, which no release of
+ * this backend writes. `storedAnnotation` carries it verbatim so an operator
+ * can see what is actually on the object.
+ */
+export declare class KubernetesWorkspacePreconditionError extends Error {
+    /** The verb that was refused — `suspend`, `resume`, `destroy`, ... */
+    readonly operation: string;
+    readonly workspaceId: string;
+    readonly sandboxName: string;
+    /** The epoch this call carried. */
+    readonly epoch: number;
+    /** The epoch stored on the Sandbox, or `undefined` if unreadable. */
+    readonly storedEpoch: number | undefined;
+    /** The annotation exactly as stored, when there is one. */
+    readonly storedAnnotation?: string | undefined;
+    readonly name = "KubernetesWorkspacePreconditionError";
+    constructor(
+    /** The verb that was refused — `suspend`, `resume`, `destroy`, ... */
+    operation: string, workspaceId: string, sandboxName: string, 
+    /** The epoch this call carried. */
+    epoch: number, 
+    /** The epoch stored on the Sandbox, or `undefined` if unreadable. */
+    storedEpoch: number | undefined, 
+    /** The annotation exactly as stored, when there is one. */
+    storedAnnotation?: string | undefined);
+}
+/**
+ * What a start that FAILED is allowed to do to the workspace it was starting
+ * in.
+ *
+ *  - `suspend-if-woken` (the default) — send the `operatingMode: Suspended`
+ *    patch only when this call is the one that moved the mode: it POSTed the
+ *    object, or its Running patch took the object out of `Suspended`. That
+ *    keeps the case the rule exists for — a workspace this call WOKE and then
+ *    failed to start would otherwise be left Running with a pod nobody is
+ *    using, burning a node until somebody notices — while never taking a pod
+ *    away from a holder who was already using it.
+ *  - `leave` — never patch, on any start failure, without exception. For a
+ *    host that keeps its own holder record and sweeps idle workspaces itself:
+ *    the cost of being wrong is one Running workspace nobody is in, which
+ *    that host can already see and already sweeps.
+ *
+ * Read only by the paths that START a session: {@link
+ * createKubernetesWorkspace} and `resume()`. `suspend()`, `refresh()`,
+ * `destroy()` and the three standalone verbs start nothing and ignore it.
+ */
+export type KubernetesWorkspaceStartFailurePolicy = 'suspend-if-woken' | 'leave';
+/**
+ * What one bounded `healthz` found after a cancellation went unconfirmed —
+ * the fact the host needs and the error cannot carry.
+ *
+ *  - `ok` — the agent answered and is serving normally. The command whose
+ *    cancellation could not be confirmed may still be running in that pod,
+ *    but nothing is wedged; the workspace goes on working.
+ *  - `retiring` — the agent has FENCED itself: it could not confirm that a
+ *    process group was gone, so it refuses every op but `healthz` and
+ *    `cancel-execution` and will until the pod is replaced. This is the one
+ *    case where `suspend()` then `resume()` is the cure.
+ *  - `unreachable` — the probe could not get an answer at all: the pod is
+ *    gone, the network is out, or the address stopped resolving. Nothing can
+ *    be concluded about the command, and nothing should be done about the
+ *    workspace on this alone — the next call finds out, and a foreign suspend
+ *    is reported as one.
+ */
+export type KubernetesWorkspaceAgentState = 'ok' | 'retiring' | 'unreachable';
+/**
+ * What {@link KubernetesWorkspaceOptions.onCancellationUnconfirmed} is told.
+ *
+ * It is a NOTIFICATION, not a decision point: the `exec()` this came from
+ * rejects with `error` whatever the callback does, and nothing the callback
+ * does is awaited by the failing call beyond the moment it returns.
+ */
+export interface KubernetesWorkspaceCancellationNotice {
+    /** The `RemoteCancellationUnknownError` the caller is about to receive. */
+    readonly error: Error;
+    /** See {@link KubernetesWorkspaceAgentState}. */
+    readonly agent: KubernetesWorkspaceAgentState;
+    /**
+     * What a bounded look at the pod and the agent process found — see
+     * {@link KubernetesGuestEvidence}.
+     *
+     * It answers the question `agent` cannot: `healthz` says whether SOME
+     * agent is serving at that address, and this says whether it is the same
+     * one the command was running in. Anything but `same-guest` means the
+     * command cannot still be running, because the process tree it belonged
+     * to is gone — and that a suspend would take a pod nobody's command is in.
+     */
+    readonly guest: KubernetesGuestEvidence;
+    /** The guest the command was started on. */
+    readonly previous: KubernetesWorkspaceIdentity;
+    /** The guest standing under the workspace's name now. */
+    readonly current: KubernetesWorkspaceIdentity;
+}
+/**
+ * Authority for one workspace operation, owned independently of the run.
+ *
+ * Carried by the handle's transitions and by the three verbs that reach a
+ * workspace without opening one ({@link listKubernetesWorkspaces},
+ * {@link deleteKubernetesWorkspace}, {@link suspendKubernetesWorkspace}) —
+ * one shape rather than four, because a cancellation scope is what all of
+ * them take and the one verb among them that starts a session takes one
+ * thing more.
+ */
 export interface KubernetesWorkspaceTransitionOptions {
     readonly signal?: AbortSignal;
+    /**
+     * Override, for this call only, what a failed start may do to the
+     * workspace — see {@link KubernetesWorkspaceStartFailurePolicy}. Defaults
+     * to whatever the handle was opened with, which defaults to
+     * `suspend-if-woken`.
+     *
+     * `resume()` is the only verb on this shape that reads it, because it is
+     * the only one that starts a session. It is declared here rather than on
+     * a resume-only shape so that a host passing one options object to every
+     * transition does not have to know which verb consults which field.
+     */
+    readonly onStartFailure?: KubernetesWorkspaceStartFailurePolicy;
+    /**
+     * The holder epoch this call writes under — see
+     * {@link HOLDER_EPOCH_ANNOTATION_KEY}.
+     *
+     * The write applies when the epoch stored on the Sandbox is `<=` this
+     * one, and stores this one in the same request; a stored epoch above it
+     * refuses the write with {@link KubernetesWorkspacePreconditionError} and
+     * changes nothing. Omitted, every request goes out exactly as it did
+     * before epochs existed, merge-patch content type included — this fences
+     * nothing until a host opts in.
+     *
+     * Read by every verb on this shape that WRITES: `suspend()`, `resume()`,
+     * `destroy()` and the standalone
+     * {@link suspendKubernetesWorkspace} / {@link deleteKubernetesWorkspace}.
+     * `refresh()`, `cancelExecution()` and {@link listKubernetesWorkspaces}
+     * send no write, so there is nothing for an epoch to condition there and
+     * they ignore it — the same way `onStartFailure` above is ignored by
+     * every verb that starts no session. A list REPORTS each workspace's
+     * stored epoch instead, on
+     * {@link KubernetesWorkspaceSummary.holderEpoch}.
+     *
+     * A handle that was opened with one, or last resumed with one, uses it
+     * for every write it sends when the call passes none — including the
+     * patch a failed start's cleanup sends.
+     */
+    readonly epoch?: number;
+    /**
+     * Write the SandboxTemplate's CURRENT `spec.podTemplate` onto the
+     * workspace as it wakes, keeping its disk — see
+     * {@link KubernetesWorkspace.templateRevision}.
+     *
+     * `resume()` is the only verb on this shape that reads it, in the same
+     * way `onStartFailure` above is read only by the verb that starts a
+     * session. It is honoured on exactly one transition — a workspace
+     * observed `Suspended` going back to `Running` — because the controller
+     * does not rewrite a pod that already exists, so a Running workspace
+     * patched this way would carry a spec describing a pod it is not running.
+     * A `resume()` of a workspace that is already awake, and one whose
+     * condition loses to another process's resume, send no pod template and
+     * bind the pod that is there.
+     *
+     * Omitted or `false`, `resume()` sends exactly the single merge patch it
+     * always sent.
+     */
+    readonly refreshPodTemplate?: boolean;
+}
+/**
+ * What a SUSPEND takes, which is every transition option plus the one thing
+ * only a suspend can do with it.
+ *
+ * `quiesce` lives here rather than on
+ * {@link KubernetesWorkspaceTransitionOptions} so that the verbs which
+ * cannot honour it — `resume()`, `refresh()`, {@link listKubernetesWorkspaces}
+ * and {@link deleteKubernetesWorkspace}, none of which sends a patch a
+ * quiesce could precede — do not accept it and then ignore it. A caller who
+ * passed it is about to trust a capture, and a silently dropped flag is the
+ * one way this feature could lie.
+ */
+export interface KubernetesWorkspaceSuspendOptions extends KubernetesWorkspaceTransitionOptions {
+    /**
+     * Stop every process in the guest BEFORE the `Suspended` patch goes out —
+     * see {@link KubernetesWorkspace.quiesce}, which this runs.
+     *
+     * Honoured by the handle's `suspend()` and by the `destroy()` that
+     * suspends. The standalone {@link suspendKubernetesWorkspace} takes this
+     * same shape and REFUSES the flag rather than ignoring it: it reaches the
+     * workspace through the API server alone and never dials the agent, so
+     * there is no connection on which it could stop anything. Off by default,
+     * so a `suspend()` that does not name it is byte-for-byte the suspend it
+     * always was.
+     *
+     * A guest whose image predates the op keeps today's behaviour: the
+     * suspend proceeds and
+     * {@link KubernetesWorkspaceOptions.onQuiesceUnsupported} is told. A
+     * quiesce the guest ANSWERED and could not confirm is different — the
+     * suspend rejects and sends no patch, leaving the workspace running,
+     * because the state that is true is the one this handle records. And a
+     * suspend ALREADY IN FLIGHT without a quiesce is refused rather than
+     * joined — see `suspend()`.
+     */
+    readonly quiesce?: KubernetesWorkspaceQuiesceRequest;
+    /**
+     * Ask the guest to put the workspace's writes on its device before the
+     * `Suspended` patch goes out — see {@link KubernetesWorkspace.flush},
+     * which this runs. **On by default**, which is the one behaviour this
+     * option changes from what `suspend()` used to do.
+     *
+     * It is on by default because the alternative is the failure it exists
+     * to fix: a stopped pod means only that nothing is writing any more, and
+     * the page cache of a guest whose pod was taken away is not a thing
+     * anything here can go back for. The cost is one round trip and one
+     * `syncfs` per suspend.
+     *
+     * `false` sends the patch with no flush, which is exactly what every
+     * release before this one did. Use it when the caller has already
+     * flushed (a `flush()` of its own, or a `sync` it ran through `exec`),
+     * or when the workspace is about to be deleted anyway.
+     *
+     * A guest whose image predates the op keeps the old behaviour: the
+     * suspend proceeds and
+     * {@link KubernetesWorkspaceOptions.onFlushUnsupported} is told. So does
+     * a guest that cannot be REACHED to be asked — a crashed or OOM-killed
+     * agent, a lost network, a fence — through
+     * {@link KubernetesWorkspaceOptions.onFlushUnreachable}: leaving such a
+     * workspace running flushes nothing and costs money, and this is the
+     * verb that replaces its pod. A flush the guest ANSWERED and could not
+     * confirm is the one that is different — the suspend rejects and sends
+     * no patch, leaving the workspace running and the caller holding the
+     * guest's own message, because a patch sent over unwritten pages is how
+     * the data is lost.
+     *
+     * `{ timeoutMs }` raises what the GUEST may spend inside that `syncfs`,
+     * for a workspace that leaves more dirty than the guest's 10000ms
+     * default covers. It is the same number `flush({ timeoutMs })` takes.
+     */
+    readonly flush?: KubernetesWorkspaceFlushRequest;
+}
+/**
+ * `flush()`'s own options.
+ *
+ * `signal` is the `AbortSignal` that cancels the REQUEST, like every other
+ * verb on this handle. `timeoutMs` bounds what the GUEST spends inside the
+ * `syncfs`, which is a different clock: aborting the request leaves the
+ * guest's own syncfs running, and only the guest's timeout ends that.
+ */
+export interface KubernetesFlushOptions {
+    /**
+     * How long the guest may spend flushing before it reports the flush
+     * unconfirmed. The guest defaults to 10000ms
+     * (`NAMZU_AGENT_FLUSH_TIMEOUT_MS`).
+     *
+     * It is NOT the pod's `terminationGracePeriodSeconds`, which has to
+     * cover the flush a stopping pod performs AND the drain beside it.
+     */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * `quiesce()`'s own options.
+ *
+ * `signal` is the `AbortSignal` that cancels the REQUEST, as it is on every
+ * other verb on this handle. There is deliberately no POSIX-signal field to
+ * go with it: the escalation is the guest's and is fixed — `SIGTERM`, then
+ * `SIGKILL` on whatever is left — because a caller-chosen signal that a
+ * process ignores would turn a quiesce into a call that resolves having
+ * stopped nothing.
+ */
+export interface KubernetesQuiesceOptions {
+    /**
+     * How long the guest waits after `SIGTERM` before escalating to
+     * `SIGKILL`, per round. The guest refuses a value at or above its own
+     * cancel-confirmation timeout (5000ms by default) and defaults to
+     * 1000ms.
+     *
+     * It is NOT the pod's `terminationGracePeriodSeconds`, which bounds how
+     * long the kubelet waits after the pod has been asked to stop. This one
+     * bounds a round of an op the host called while the pod is still running
+     * and still serving.
+     */
+    readonly graceMs?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * What `suspend({ quiesce })` and `destroy({ quiesce })` ask for: `true`
+ * for the guest's own default window, or an object naming `graceMs`.
+ */
+export type KubernetesWorkspaceQuiesceRequest = boolean | {
+    readonly graceMs?: number;
+};
+/**
+ * What `suspend({ flush })` and `destroy({ flush })` ask for: `true` (the
+ * default) for the guest's own flush timeout, `false` for no flush at all,
+ * or an object naming `timeoutMs`.
+ *
+ * The object shape exists for the workspace whose flush does not fit in the
+ * guest's default 10000ms (`NAMZU_AGENT_FLUSH_TIMEOUT_MS`). Without it such
+ * a workspace answers `flush_unconfirmed` — the one outcome that STOPS a
+ * suspend — and the only ways past it are `flush({ timeoutMs })` followed
+ * by `suspend({ flush: false })`, or rebuilding the image's environment.
+ * Mirrors {@link KubernetesWorkspaceQuiesceRequest}, which names the
+ * guest-side budget of its own op for the same reason.
+ */
+export type KubernetesWorkspaceFlushRequest = boolean | {
+    readonly timeoutMs?: number;
+};
+/**
+ * `killSession()`'s two signals, which are different things and are named
+ * apart for that reason: `signal` is the POSIX signal the guest sends to the
+ * session, and `abort` is the `AbortSignal` that cancels the REQUEST.
+ * Collapsing them into one field called `signal` is how a caller ends up
+ * sending `SIGKILL` to a shell it only meant to stop asking about.
+ */
+export interface KubernetesKillSessionOptions {
+    /** `SIGTERM`, `SIGKILL`, `SIGINT` or `SIGHUP`. Default `SIGKILL`. */
+    readonly signal?: string;
+    readonly abort?: AbortSignal;
 }
 /**
  * `destroy()` on a workspace, with the one field that decides whether the
@@ -233,7 +649,52 @@ export interface KubernetesWorkspaceDestroyOptions extends SandboxDestroyOptions
      * including the default, suspends and leaves the object standing.
      */
     readonly deleteDisk?: boolean;
+    /**
+     * The holder epoch this destroy writes under — see
+     * {@link KubernetesWorkspaceTransitionOptions.epoch}, which it means
+     * exactly the same thing as.
+     *
+     * It fences both shapes of `destroy()`: the default's suspend patch and
+     * `deleteDisk: true`'s DELETE, the latter through a
+     * `preconditions.resourceVersion` on the version whose epoch was read. A
+     * retention job superseded between its check and its call takes nobody's
+     * disk.
+     */
+    readonly epoch?: number;
+    /**
+     * Stop every process in the guest first — see
+     * {@link KubernetesWorkspaceSuspendOptions.quiesce}, which this means
+     * exactly the same thing as.
+     *
+     * It is read by the `destroy()` that SUSPENDS, which is the default one.
+     * A `destroy({ deleteDisk: true })` ignores it: the disk it would be
+     * quiescing is about to be deleted along with everything on it.
+     */
+    readonly quiesce?: KubernetesWorkspaceQuiesceRequest;
+    /**
+     * Put the workspace's writes on its device first — see
+     * {@link KubernetesWorkspaceSuspendOptions.flush}, which this means
+     * exactly the same thing as, default included.
+     *
+     * Read by the `destroy()` that SUSPENDS, which is the default one and
+     * which keeps the disk. A `destroy({ deleteDisk: true })` ignores it for
+     * the same reason it ignores `quiesce`: the disk is about to be deleted.
+     */
+    readonly flush?: KubernetesWorkspaceFlushRequest;
 }
+/**
+ * How a {@link KubernetesWorkspace} handle came by its workspace.
+ *
+ *  - `created` — this call POSTed the Sandbox. The pod is this process's own
+ *    and the disk is empty.
+ *  - `adopted-running` — an object of that name already stood, already
+ *    Running. The pod predates this handle, and usually predates this
+ *    process.
+ *  - `resumed` — an object of that name stood Suspended and this call patched
+ *    it back to Running. The disk is whatever the last holder left on it; the
+ *    pod is brand new.
+ */
+export type KubernetesWorkspaceOrigin = 'created' | 'adopted-running' | 'resumed';
 /**
  * A {@link Sandbox} that survives having its compute taken away.
  *
@@ -244,6 +705,117 @@ export interface KubernetesWorkspaceDestroyOptions extends SandboxDestroyOptions
  * `deleteDisk` field on the shared `SandboxDestroyOptions`.
  */
 export interface KubernetesWorkspace extends Sandbox {
+    /**
+     * How this handle came by its workspace — see
+     * {@link KubernetesWorkspaceOrigin}.
+     *
+     * Fixed for the handle's life. It answers "what did this call walk into",
+     * not "what state is the workspace in now", which is what `suspended` is
+     * for; a later suspend/resume cycle does not rewrite it.
+     *
+     * It is reported because the two adopted values mean a pod this process
+     * did not start, and a host reattaching to a workspace another process
+     * left behind has to know what of that process's work is still there. On
+     * `resumed` the pod is new, so nothing survived but the disk. On
+     * `adopted-running` the guest's agent is the same process it was and a
+     * detached background command may still be running — but no TERMINAL is:
+     * the agent kills a terminal's process group the moment its connection
+     * closes, and the previous host's connections closed with the host. A
+     * caller that reopens terminals unconditionally on this value is right;
+     * one that assumes it can reattach to them is not.
+     */
+    readonly origin: KubernetesWorkspaceOrigin;
+    /**
+     * The revision of the pod template the BOUND Sandbox carries — the value
+     * of its `sandbox.namzu.ai/pod-template-hash` annotation.
+     *
+     * A Sandbox's `spec.podTemplate` is a copy of the SandboxTemplate's,
+     * taken once, and the controller builds every replacement pod from that
+     * copy — so a workspace kept for weeks runs the pod spec it was created
+     * with. This is what the object recorded it was built from.
+     *
+     * `undefined` for a workspace created before the annotation existed, and
+     * for one an older release last wrote. That is reported as unknown rather
+     * than guessed from the stored spec: a comparison this backend invents
+     * would be a second, weaker copy of the overlay rules.
+     */
+    readonly templateRevision: string | undefined;
+    /**
+     * Whether {@link templateRevision} matched the SandboxTemplate this
+     * handle last read.
+     *
+     * `false` means a suspend and a resume with
+     * {@link KubernetesWorkspaceTransitionOptions.refreshPodTemplate} would
+     * change what this workspace runs — a new image tag, a memory limit, a
+     * grace period, an env entry. A host can schedule that at a moment of its
+     * choosing instead of finding out when a release makes the stored image
+     * fail every start.
+     *
+     * A workspace with no recorded revision reads `false`: unknown is not
+     * current. The template is read when the handle is opened and again on
+     * every refresh, so a `resume()` WITHOUT the option leaves this answering
+     * against the last template this handle read rather than paying a GET for
+     * one nothing is going to be compared to.
+     */
+    readonly templateCurrent: boolean;
+    /**
+     * The four objects this handle is bound to RIGHT NOW — see
+     * {@link KubernetesWorkspaceIdentity}.
+     *
+     * Read fresh on every access rather than snapshotted, because it moves:
+     * `podUid` changes across a suspend/resume and across a pod this handle
+     * rebound to, `guestBootId` changes when the kubelet restarts the
+     * container, and both are `undefined` while this handle holds no pod — a
+     * suspended or destroyed workspace. A resume that has BOUND its pod names
+     * it from that moment, probe included, so a listener reading this from
+     * inside a `pod-replaced` event raised during a resume is answered with
+     * the pod it was just told about rather than with nothing.
+     * `sandboxUid` and `volumeClaimUids` do not move for the life of a handle
+     * — a handle whose object was replaced refuses rather than following it.
+     *
+     * A host that keeps per-workspace state compares this across calls, or
+     * (better) subscribes with {@link onGuestRestart} and is told.
+     */
+    readonly identity: KubernetesWorkspaceIdentity;
+    /**
+     * Be told when the guest behind this handle is replaced, and get back the
+     * function that stops being told.
+     *
+     * This is the honest half of the rebind. A handle that follows a replaced
+     * pod keeps WORKING, which is what a caller wants; what it cannot do is
+     * keep the caller's guest state, because every process that pod was
+     * running died with it. A host that remembers what it started — a dev
+     * server, a watcher, a shell — must subscribe, or it will go on believing
+     * in processes that no longer exist while every call succeeds.
+     *
+     * It fires for a pod the handle rebound to (`pod-replaced`) and for an
+     * agent process that was restarted inside the same pod
+     * (`container-restarted`, recognised only against a guest that reports a
+     * `guestBootId`). It does NOT fire across the caller's own `suspend()`
+     * and `resume()`: that pod change was asked for, and a host that issued
+     * it already knows its processes are gone. The one exception is a pod
+     * replaced by somebody else DURING a resume — between the pod this
+     * handle bound and the privilege probe that follows it — where the probe
+     * is refused, the handle rebinds, and a `pod-replaced` event is
+     * announced. That is a pod change the caller did not ask for, arriving
+     * inside a transition it did; reporting it is the point.
+     *
+     * Every event names both pods, that one included. The payload is built
+     * from the uids the routine announcing the move is holding — not read
+     * back off a handle whose transition has not finished — so there is no
+     * path on which a listener is told its guest moved and not told where
+     * from or where to.
+     *
+     * On a `pod-replaced` event `current.guestBootId` is `undefined`: the
+     * replacement has not answered yet, so there is no process to name.
+     * `current.podUid` is what moved, and `identity` names the process that
+     * answered from there once the call that rebound has returned.
+     *
+     * Listeners are called synchronously, in subscription order, and a
+     * listener that throws is swallowed — the event is a notification and
+     * must not fail the call that discovered it.
+     */
+    onGuestRestart(listener: (event: KubernetesGuestRestart) => void): () => void;
     /**
      * True from the moment `suspend()` starts until `resume()` finishes.
      *
@@ -254,8 +826,198 @@ export interface KubernetesWorkspace extends Sandbox {
      * SDK's union.
      */
     readonly suspended: boolean;
-    openTerminal(options: OpenTerminalOptions): Promise<TerminalSession>;
+    /**
+     * The SDK's `exec`, plus the three Kubernetes-only fields that let a
+     * command outlive the connection watching it — see
+     * {@link KubernetesDetachedExecOptions}.
+     *
+     * Without `executionId` and without `detach` this is the SDK's exec
+     * exactly: the same reserve-before-admission controller, the same wire
+     * request, the same result. The options type only WIDENS what is
+     * accepted, so every `SandboxExecOptions` a caller already passes is
+     * still a valid argument and nothing about `Sandbox` changed.
+     */
+    exec(command: string, argv?: string[], options?: KubernetesDetachedExecOptions): Promise<SandboxExecResult>;
+    /**
+     * Read a command this workspace is running, or has recently run, by the
+     * id it was started with — including one started by a host process that
+     * no longer exists.
+     *
+     * It never signals the command: aborting `signal` stops reading and
+     * leaves it running, and closing the connection changes nothing in the
+     * guest. Every attach inside the retention window returns the same
+     * result. Past it, or in a pod that has since been replaced, it rejects
+     * with `KubernetesExecutionNotAttachableError`.
+     */
+    attachExecution(executionId: string, options?: KubernetesAttachExecutionOptions): Promise<SandboxExecResult>;
+    /**
+     * End a command by id, from any process holding the id. Resolves only
+     * on a CONFIRMED termination and rejects with
+     * `RemoteCancellationUnknownError` otherwise — and rejecting here
+     * retires nothing: the workspace, its pod and its disk are left exactly
+     * as they are. A caller that wants the pod gone asks for that.
+     */
+    cancelExecution(executionId: string, options?: KubernetesWorkspaceTransitionOptions): Promise<void>;
+    /**
+     * A guest PTY. Without `sessionId` and `persistent: true` this is exactly
+     * the terminal it has always been — same wire request, same behaviour —
+     * except that its teardown now reaches the whole session rather than only
+     * `script`'s process group, so a job the shell backgrounded no longer
+     * outlives the terminal that started it.
+     *
+     * With them the PTY belongs to the pod rather than to this connection:
+     * losing the connection DETACHES, and {@link attachTerminal} rejoins the
+     * same shell from another process. `exited` on such a terminal rejects
+     * with `AgentSessionDetachedError` when the attachment ends and the
+     * program does not, because resolving it would claim an exit that never
+     * happened.
+     */
+    openTerminal(options: KubernetesOpenTerminalOptions): Promise<KubernetesWorkspaceTerminal>;
+    /**
+     * Rejoin a terminal session by the id it was opened with — from this
+     * process or from one that replaced it.
+     *
+     * The guest replays from `fromOffset` and then follows live, so a reader
+     * starting at 0 sees what the shell printed while nobody was watching,
+     * and is told how much the ring had to evict. At most one attachment
+     * exists at a time: a second attach ends the first by name rather than
+     * letting two processes interleave keystrokes into one shell.
+     */
+    attachTerminal(sessionId: string, options?: KubernetesAttachTerminalOptions): Promise<KubernetesSessionTerminal>;
+    /**
+     * Start a program with no terminal, in its own kernel session, with
+     * stdin closed and both output streams going into the guest's retained
+     * log.
+     *
+     * This is not the SDK's `spawnDetached` and does not pretend to be: that
+     * hands back a host `ChildProcess`, which cannot cross a process
+     * boundary, and it stays absent here. What this returns is a NAME, and
+     * the name is what another host process comes back with.
+     */
+    startDetached(options: KubernetesStartDetachedOptions): Promise<KubernetesSessionSummary>;
+    /**
+     * Read a session's output from `fromOffset` without attaching to it and
+     * without signalling anything — the chunk, the offset to come back with,
+     * the bytes the ring dropped before it, and the program's status.
+     */
+    readSession(sessionId: string, options?: KubernetesReadSessionOptions): Promise<KubernetesSessionOutput>;
+    /**
+     * Every session this workspace's pod is holding, running and recently
+     * exited. Empty after a suspend and resume: the registry is the pod's
+     * memory, and a resumed workspace is a new pod.
+     */
+    listSessions(options?: KubernetesWorkspaceTransitionOptions): Promise<readonly KubernetesSessionSummary[]>;
+    /**
+     * End one session and everything still in it — the shell, the jobs it
+     * backgrounded, and whatever a detached session started. Idempotent, and
+     * the reply says what the session's state actually is, so a program that
+     * ignored a `SIGTERM` is reported still running rather than reported
+     * dead.
+     *
+     * `options.signal` is the POSIX signal to send (`SIGKILL` by default);
+     * `options.abort` is the `AbortSignal` that cancels the request.
+     */
+    killSession(sessionId: string, options?: KubernetesKillSessionOptions): Promise<KubernetesSessionSummary>;
     openTcpConnection(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection>;
+    /**
+     * Narrowed to present, like the two above: the pod behind a workspace runs
+     * the same guest agent a task sandbox does, so bounded file discovery is
+     * always available here and a caller composing this handle does not have
+     * to re-check for a method the backend always defines. The SDK's `glob`
+     * and `grep` builtins refuse a sandbox that omits it.
+     */
+    walkFiles(rootPath: string, options: SandboxWalkFilesOptions): AsyncIterable<SandboxFileEntry>;
+    /**
+     * Narrowed to PRESENT, like the three above: the pod behind a workspace
+     * runs this repository's agent, so the streamed read is never absent
+     * here and a host draining a large output file before `suspend()` or
+     * `destroy()` — the use a long-lived workspace exists for — does not
+     * have to check for it.
+     */
+    readFileStream(path: string, options?: SandboxReadFileOptions): AsyncIterable<Buffer>;
+    /**
+     * Re-read `spec.operatingMode` and believe it: a workspace ANOTHER
+     * process suspended reports `suspended: true` afterwards, and `resume()`
+     * brings it back on the same disk.
+     *
+     * A workspace id is a name, not a lock — two host processes can hold
+     * handles to one workspace — and everything else on this handle reports
+     * what THIS process did. Without this verb the second process has no way
+     * to ask, and its handle goes on claiming to be running with no pod
+     * behind it until a call fails.
+     *
+     * The foreign suspend is recorded as UNCONFIRMED, not as finished: what
+     * was observed is the object's mode, not the pod stopping, so a later
+     * `suspend()` on this handle still sends its own patch and waits for the
+     * pod rather than returning on what this read saw. Every terminal this
+     * handle handed out is killed, because the pod they live in is being
+     * taken away.
+     *
+     * It notices a suspension and nothing else. A workspace that reads
+     * `Running` while this handle is suspended is NOT taken back — coming
+     * back means binding a new pod, reading its token and probing it, which
+     * is what `resume()` is. A workspace somebody DELETED rejects with the
+     * client's already-gone error and changes nothing here: there is no state
+     * on this handle that means "another process deleted it", and inventing
+     * one to report it is a larger change than this verb.
+     */
+    refresh(options?: KubernetesWorkspaceTransitionOptions): Promise<void>;
+    /**
+     * Stop every process this workspace's pod is running, and go on serving.
+     *
+     * `suspend()` on its own reaches two kinds of process: the terminals THIS
+     * handle returned, and a command somebody cancelled by id. A terminal
+     * another host process opened, a command already in flight, and above all
+     * a program that moved into a session of its own with `setsid` and was
+     * then reparented away from the agent all keep running — and keep writing
+     * to the disk — until the pod stops. By then there is no agent left to
+     * read that disk through.
+     *
+     * So this is the verb for a host that wants the disk still WHILE IT CAN
+     * STILL READ IT: afterwards the guest is quiet and the agent is up, so
+     * `exec`, `readFile`, `readFileStream` and `writeFile` all work and what
+     * they see is a filesystem nobody is writing to. A capture taken here can
+     * be trusted; `destroy({ deleteDisk: true })` or
+     * {@link deleteKubernetesWorkspace} can then run against a workspace
+     * nobody has to wake again to check.
+     *
+     * What it costs is everything running: an open terminal receives its
+     * exit, a running `exec` resolves with a signal in its result, and a
+     * session in the registry is reported `exited` rather than detached. A
+     * second call straight after the first stops nothing and says so, with an
+     * empty list.
+     *
+     * Admitted only while the workspace is running, and serialised with the
+     * lifecycle transitions, so it cannot interleave with a suspend or a
+     * resume. It rejects — changing nothing on the cluster — with
+     * `KubernetesQuiesceUnconfirmedError` when a process would not stop (the
+     * message names its pid), and with `KubernetesQuiesceUnsupportedError`
+     * against an image whose agent predates the op.
+     */
+    quiesce(options?: KubernetesQuiesceOptions): Promise<KubernetesQuiesceReport>;
+    /**
+     * Put everything this workspace has written onto its disk, now.
+     *
+     * `syncfs(2)` over the workspace mount inside the guest: every dirty
+     * page of every file on it, whichever process wrote it. That covers what
+     * a COMMAND wrote, which is the half no per-file fsync can reach —
+     * `writeFile` fsyncs its own bytes before it answers, and a compiler's
+     * output belongs to nobody here.
+     *
+     * `suspend()` runs this by default, so a caller that only suspends never
+     * needs it. It is a verb of its own for the moments that are not a
+     * suspend: before a snapshot somebody else takes, before a node is
+     * drained, or beside a {@link quiesce} when a host wants the disk both
+     * still AND written back while the workspace keeps running.
+     *
+     * Admitted only while the workspace is running, and serialised with the
+     * lifecycle transitions like `quiesce()` is. It rejects — changing
+     * nothing on the cluster — with `KubernetesFlushUnconfirmedError` when
+     * the guest answered and could not confirm, and with
+     * `KubernetesFlushUnsupportedError` against an image whose agent
+     * predates the op.
+     */
+    flush(options?: KubernetesFlushOptions): Promise<KubernetesFlushReport>;
     /**
      * Give the compute back and keep the disk. Idempotent: suspending a
      * workspace whose suspend has been CONFIRMED sends nothing.
@@ -275,12 +1037,52 @@ export interface KubernetesWorkspace extends Sandbox {
      * A call already in flight when this is called is not cancelled: it fails
      * at the transport when the pod goes away, rather than with the named
      * suspended error, which only covers calls admitted from here on.
+     *
+     * It also runs {@link flush} before the patch unless
+     * {@link KubernetesWorkspaceSuspendOptions.flush} says otherwise, so what
+     * the workspace wrote is on the device before the pod is taken away
+     * rather than left to whatever the guest kernel had written back. A flush
+     * the guest ANSWERED and could not confirm rejects and sends NO patch —
+     * the only flush outcome that stops a suspend. An image that cannot
+     * flush at all, and a guest that cannot be reached to be asked, both
+     * keep the old behaviour: the suspend goes ahead and the host is told
+     * through `onFlushUnsupported` or `onFlushUnreachable`, because a
+     * workspace nobody can reach is exactly the one an operator most needs
+     * this verb for.
+     *
+     * `suspend({ quiesce: true })` runs {@link quiesce} first — after this
+     * handle's own terminals are reaped and BEFORE the patch and before that
+     * flush — so the disk is still at the moment the pod is asked to stop
+     * rather than merely by the time it has. A quiesce that cannot be confirmed rejects and sends NO
+     * patch: the workspace stays running and admits calls, which is the rule
+     * this verb already keeps everywhere else — leave the state that is true.
+     *
+     * Sharing a transition has ONE exception, and it is this option. A call
+     * arriving mid-suspend joins the transition in flight rather than
+     * starting one of its own, under the first caller's signal and epoch —
+     * but a `quiesce` the transition in flight is not performing cannot be
+     * joined into: that transition is on its way to patching over a guest
+     * nothing has stopped, and once its state leaves `running` no call is
+     * admitted to stop anything. Such a caller is REJECTED with
+     * {@link KubernetesQuiesceUnconfirmedError} instead of being handed a
+     * resolved suspend it would trust a capture on. A caller whose request
+     * the flight already satisfies still joins it.
      */
-    suspend(options?: KubernetesWorkspaceTransitionOptions): Promise<void>;
+    suspend(options?: KubernetesWorkspaceSuspendOptions): Promise<void>;
     /**
      * Take a new pod, on a new address, with a new agent token, and prove it
      * is deprivileged before handing it back. Idempotent: resuming a running
      * workspace sends nothing.
+     *
+     * With
+     * {@link KubernetesWorkspaceTransitionOptions.refreshPodTemplate}, the
+     * wake-up patch also writes the SandboxTemplate's current
+     * `spec.podTemplate`, so the new pod is built from the template as it
+     * stands rather than as it stood when the workspace was created. The disk
+     * is untouched — `spec.volumeClaimTemplates` is CEL-immutable and is not
+     * in the patch — and a template that no longer claims this workspace's
+     * disk is refused with {@link KubernetesWorkspaceDiskError} before
+     * anything is sent.
      */
     resume(options?: KubernetesWorkspaceTransitionOptions): Promise<void>;
     /**
@@ -315,6 +1117,167 @@ export interface KubernetesWorkspaceOptions {
      */
     readonly sandboxTemplateName?: string;
     readonly signal?: AbortSignal;
+    /**
+     * What a failed start may do to the workspace, for this handle and every
+     * transition on it — see {@link KubernetesWorkspaceStartFailurePolicy}.
+     * Default: `suspend-if-woken`.
+     */
+    readonly onStartFailure?: KubernetesWorkspaceStartFailurePolicy;
+    /**
+     * Told when an execution's cancellation could not be CONFIRMED, with
+     * what a bounded `healthz` found afterwards — see
+     * {@link KubernetesWorkspaceCancellationNotice}.
+     *
+     * Nothing happens to the workspace on this path: the pod keeps running,
+     * no patch is sent, the handle goes on admitting calls, and the failing
+     * `exec()` rejects with `RemoteCancellationUnknownError` carrying
+     * `retirement: { accepted: false, reason: 'workspace-kept' }`. A command
+     * of unknown state is left in that pod, which is a fact the host has to
+     * be able to act on — so it is reported here rather than acted on from
+     * inside a failing call, where the only action available (the Suspended
+     * patch) would delete the pod out from under every other holder.
+     *
+     * A host that wants the old behaviour calls `suspend()` from this
+     * callback. One that wants it only for a genuinely fenced agent calls it
+     * when `agent` is `retiring`.
+     *
+     * Not only from `exec()`. The acquire-time PRIVILEGE PROBE is itself an
+     * execution on the same inner handle, so a create or a resume whose probe
+     * loses its cancellation fires this too — and pays the diagnosis's own
+     * bound before rejecting. A callback that suspends the workspace is
+     * therefore reachable from a failing START as well as from a failing
+     * call, which is worth knowing before it is wired to one.
+     *
+     * In the style of `onLeaseRenewalError`: synchronous, never awaited, and
+     * a callback that throws changes nothing about the error the caller
+     * receives.
+     */
+    readonly onCancellationUnconfirmed?: (notice: KubernetesWorkspaceCancellationNotice) => void;
+    /**
+     * Told when a `suspend({ quiesce: true })` could not quiesce because the
+     * guest's image predates the op, just before the suspend goes ahead
+     * without one.
+     *
+     * This is the one gap that must not be silent. Everything else about a
+     * quiesce is reported by the call that asked for it — `quiesce()` itself
+     * refuses an image that cannot perform one, and a quiesce the guest
+     * answered and could not confirm rejects the suspend — but a host that
+     * passes `quiesce: true` and gets a suspend anyway would otherwise have
+     * no way to learn that its capture was taken over a guest nothing had
+     * stopped. `@namzu/sandbox` owns no logger and reads none from module
+     * scope, so the diagnostic goes to the host that has one.
+     *
+     * In the style of `onLeaseRenewalError`: synchronous, never awaited, and
+     * a callback that throws changes nothing about the suspend.
+     */
+    readonly onQuiesceUnsupported?: (error: KubernetesQuiesceUnsupportedError) => void;
+    /**
+     * Told when a `suspend({ quiesce: true })` DID quiesce, and the guest
+     * narrowed the scan to the kernel sessions its own registries own —
+     * `report.scope === 'owned-sessions'` — just before the patch goes out.
+     *
+     * The sibling of `onQuiesceUnsupported`, and it exists for the same
+     * reason: `quiesce()` hands its caller the report and that caller can
+     * read the scope, but a `suspend({ quiesce: true })` returns `void`, so
+     * the one path that cannot read the report would otherwise be the one
+     * that silently under-delivers. A narrowed scan can miss exactly the
+     * process this feature exists for — a program `setsid` moved out of
+     * every session either registry holds — so a capture taken after one is
+     * weaker than a capture taken after a `pid-namespace` scan.
+     *
+     * A pod built from this repo's image never narrows: `k8s/entrypoint.sh`
+     * makes `tini` PID 1 and the agent its child. A derived image that wraps
+     * the agent in something else, or an embedded agent, can.
+     *
+     * In the style of `onLeaseRenewalError`: synchronous, never awaited, and
+     * a callback that throws changes nothing about the suspend.
+     */
+    readonly onQuiesceNarrowed?: (report: KubernetesQuiesceReport) => void;
+    /**
+     * Told when a `suspend()` could not flush because the guest's image
+     * predates the op, just before the suspend goes ahead without one.
+     *
+     * The exact sibling of {@link onQuiesceUnsupported}, and the one gap on
+     * the flush path that must not be silent for the same reason: a flush is
+     * ON by default here, so a deployment whose images are older than this
+     * release gets a suspend that behaves exactly as it always did, and
+     * nothing would say that the writes it thought were being put on the
+     * device were not. Every other flush failure is reported by the call
+     * itself — an explicit `flush()` refuses an image that cannot do it, and
+     * a flush the guest answered and could not confirm rejects the suspend
+     * before any patch is sent.
+     *
+     * In the style of `onLeaseRenewalError`: synchronous, never awaited, and
+     * a callback that throws changes nothing about the suspend.
+     */
+    readonly onFlushUnsupported?: (error: KubernetesFlushUnsupportedError) => void;
+    /**
+     * Told when a `suspend()` could not ASK for a flush — the guest could
+     * not be reached, or refused to answer — just before the suspend goes
+     * ahead without one.
+     *
+     * The sibling of {@link onFlushUnsupported}, and the reason `suspend()`
+     * is still the verb it always was. A flush is ON by default, so without
+     * this a workspace whose agent has crashed, been OOM-killed, lost its
+     * network or fenced itself could no longer be suspended at all on the
+     * default path: it would keep running, and keep costing, behind a raw
+     * `ECONNREFUSED` that named neither the flush nor a way past it. A guest
+     * nothing can reach does not become flushable by being left alone, and
+     * `suspend()` then `resume()` is precisely what
+     * `KubernetesAgentRetiringError` tells a caller to do about a fenced
+     * one.
+     *
+     * So the suspend proceeds and the gap is REPORTED. What it means for the
+     * disk is in the error's message: the writes that reached it are the
+     * ones the guest kernel had already written back, plus whatever the
+     * pod's `preStop` hook and the agent's own `SIGTERM` handler manage
+     * while the pod stops. A caller that would rather stop can throw from
+     * here — the callback's exception is swallowed like every other
+     * callback's here, so the way to refuse is to suspend under
+     * `{ flush: false }` only after a `flush()` of its own has succeeded.
+     *
+     * A guest that ANSWERS and cannot confirm is the other case and is not
+     * this one: that rejects the suspend with
+     * {@link KubernetesFlushUnconfirmedError} and sends no patch.
+     *
+     * In the style of `onLeaseRenewalError`: synchronous, never awaited, and
+     * a callback that throws changes nothing about the suspend.
+     */
+    readonly onFlushUnreachable?: (error: KubernetesFlushUnreachableError) => void;
+    /**
+     * The holder epoch this call opens the workspace under, and the one the
+     * handle keeps — see {@link HOLDER_EPOCH_ANNOTATION_KEY}.
+     *
+     * On the CREATE path the POST stamps it, so the workspace is fenced from
+     * the moment it exists. On the ADOPT path it is checked against the
+     * stored epoch before anything is patched — an opener the workspace has
+     * moved past is refused with
+     * {@link KubernetesWorkspacePreconditionError} and wakes nothing — and
+     * then written, even when the object was already `Running` and today
+     * nothing would be sent: taking a workspace over is exactly the moment
+     * the fence has to move.
+     *
+     * The handle then uses it for every write it sends when the call passes
+     * none: `suspend()`, `destroy()`, and the cleanup patch a failed start
+     * sends. Omitted, nothing is fenced and every request is what it was.
+     */
+    readonly epoch?: number;
+    /**
+     * On the ADOPT path, write the SandboxTemplate's current
+     * `spec.podTemplate` onto the workspace as it wakes — the same opt-in
+     * {@link KubernetesWorkspaceTransitionOptions.refreshPodTemplate}
+     * describes, reachable from an entry point that needs no handle.
+     *
+     * It exists here because a host that restarted has no handle to call
+     * `resume()` on: the workspace is found again by name, and this call is
+     * the only place the decision can be made. It is honoured on exactly the
+     * transition the handle's is — an object found `Suspended` going back to
+     * `Running` — and is ignored on the CREATE path, where the POST already
+     * carries the template as it stands.
+     *
+     * Omitted or `false`, an adopt behaves exactly as it always did.
+     */
+    readonly refreshPodTemplate?: boolean;
 }
 /** Prefix every workspace Sandbox's name carries. */
 export declare const WORKSPACE_NAME_PREFIX = "namzu-ws-";
@@ -349,9 +1312,32 @@ export declare function assertBlockModeWorkspaceDisk(source: string, podTemplate
  * object whose label says one thing while the caller builds from another is a
  * mix-up worth naming the first time it is seen rather than the first time a
  * policy is switched on. See {@link KubernetesWorkspaceMismatchError}.
+ *
+ * The PROFILE check is conditional, because a profile is what this
+ * configuration asks for rather than something every object has: it runs when
+ * `config.egress.profile` is set, and then the object's own pod template has
+ * to carry that key with that value — unless this call is about to REWRITE
+ * that pod template (`refreshPodTemplate: true` onto a Suspended object),
+ * which writes the configured profile with the rest of the overlays. That is
+ * the same lifting the `runtimeClassName` check gets, for the same reason and
+ * with the same re-application if the patch does not land.
+ *
+ * Both halves of the policy selector are therefore checked against the object
+ * on this path — which matters because neither network check further up can
+ * do it: the ingress verification and the egress union both run against the
+ * labels the POST *would* stamp, and on this path the POST already lost to a
+ * 409. What this does NOT check is a
+ * label the standing object carries that this configuration does not ask for
+ * — an object built under a profile this config has dropped, say. That pod is
+ * still selected by the unprofiled policy this call verified (a selector is a
+ * subset match), so the boundary it reports holds; what a stale label could
+ * do is bring a SECOND policy into the union, and the adopt path cannot
+ * enumerate the standing object's labels without reading them, which is a
+ * wider change than this refusal.
  */
 export declare function assertAdoptedWorkspaceMatchesConfig(sandboxName: string, namespace: string, podTemplate: SandboxPodTemplate | undefined, expected: {
     readonly sandboxTemplateName: string;
+    readonly profile?: EgressProfileLabel;
     readonly runtimeClassName?: string;
 }): void;
 /**
@@ -378,4 +1364,149 @@ export declare function assertAdoptedWorkspaceMatchesConfig(sandboxName: string,
  * name and nothing reaps for them — see the docs page.
  */
 export declare function createKubernetesWorkspace(config: KubernetesBackendInternalConfig, options: KubernetesWorkspaceOptions): Promise<KubernetesWorkspace>;
+/**
+ * One workspace as an INVENTORY reads it: enough to decide what to do with
+ * it, and not one field that required waking it up.
+ *
+ * Everything here comes off the Sandbox object itself. No pod is read, no
+ * agent is dialed, and no transport exists — which is the whole point, since
+ * the caller this exists for is a retention pass over workspaces that have
+ * been asleep for a month and must stay asleep.
+ */
+export interface KubernetesWorkspaceSummary {
+    /** The caller's own id — the Sandbox's name with `namzu-ws-` taken off. */
+    readonly workspaceId: string;
+    /**
+     * `spec.operatingMode`, verbatim. NOT "is a pod running": a `Running`
+     * workspace whose pod is still being created, or has just crashed, reads
+     * `Running` here, because this is the mode the object was last asked to
+     * be in.
+     */
+    readonly operatingMode: 'Running' | 'Suspended';
+    /** The `SandboxTemplate` this workspace was built from — the pod label. */
+    readonly template: string;
+    /**
+     * `metadata.creationTimestamp`, RFC 3339. Optional only because it is
+     * read off an object rather than promised by this type: the API server
+     * always sets it.
+     */
+    readonly createdAt?: string;
+    /**
+     * When this backend last patched `spec.operatingMode`, RFC 3339 — the
+     * {@link OPERATING_MODE_CHANGED_AT_ANNOTATION_KEY} annotation.
+     *
+     * ABSENT on a workspace whose mode has never been changed since it was
+     * created, and on one created before this backend started stamping it.
+     * It is reported absent rather than defaulted to `createdAt`, because a
+     * retention rule that deletes "anything not touched for 30 days" must be
+     * able to tell "never suspended" from "suspended a month ago".
+     */
+    readonly operatingModeChangedAt?: string;
+    /**
+     * The holder epoch stored on the Sandbox — see
+     * {@link HOLDER_EPOCH_ANNOTATION_KEY}.
+     *
+     * `0` on a workspace that carries no such annotation, because that is
+     * what every write compares against: a workspace nobody has fenced is
+     * held at epoch 0 and the next write of any epoch takes it. ABSENT only
+     * when the annotation is present and unreadable — not a decimal integer,
+     * which no release of this backend writes — because reporting that as 0
+     * would tell a retention pass a workspace is free when the next write
+     * against it will be refused.
+     *
+     * Reported rather than conditioned: a list sends no write, so it has
+     * nothing for an epoch to fence, and what an inventory needs is to SEE
+     * the fences it is looking at.
+     */
+    readonly holderEpoch?: number;
+}
+/**
+ * Every workspace this backend owns in the namespace, WITHOUT waking one.
+ *
+ * The verb retention needs. Deleting a workspace nobody has resumed since
+ * last month, or reporting what a namespace is holding, used to require
+ * {@link createKubernetesWorkspace} — which adopts AND resumes: the inventory
+ * pass would start a pod for every suspended workspace it looked at, probe
+ * each one, and then have to put them all back. This issues exactly one GET
+ * of the sandboxes collection and reads the objects.
+ *
+ * ## What counts as a workspace
+ *
+ * Two things together, and both are this backend's own marks:
+ *
+ *  - the `namzu-ws-` name prefix — {@link workspaceSandboxName}'s contract,
+ *    and the only thing that makes a `workspaceId` recoverable from a
+ *    Sandbox at all;
+ *  - {@link SANDBOX_TEMPLATE_LABEL_KEY} on `spec.podTemplate.metadata.labels`,
+ *    which says this object was built by this backend and names the template
+ *    it came from.
+ *
+ * The filtering happens HERE rather than in a `labelSelector` on the request,
+ * and the reason is where that label lives. It is a POD label — the one an
+ * egress `NetworkPolicy`'s `podSelector` matches — written onto
+ * `spec.podTemplate`, while a `labelSelector` on the sandboxes collection
+ * matches the Sandbox's OWN `metadata.labels`, which this backend has never
+ * written. Stamping a second copy up there to make a server-side selector
+ * work would leave every workspace created before that change invisible to
+ * this call, and an inventory that silently omits the oldest objects is worse
+ * than no inventory at all — those are exactly the ones a retention pass is
+ * looking for.
+ *
+ * ## What it never does
+ *
+ * No PATCH, no DELETE, no pod read, no dial. A workspace that was suspended
+ * before this call is suspended after it, and a running one is untouched. The
+ * order is the API server's own (name order); the caller sorts if it cares.
+ */
+export declare function listKubernetesWorkspaces(config: KubernetesBackendInternalConfig, options?: KubernetesWorkspaceTransitionOptions): Promise<readonly KubernetesWorkspaceSummary[]>;
+/**
+ * DELETE a workspace by id, without ever adopting or resuming it.
+ *
+ * The same thing `destroy({ deleteDisk: true })` does to the cluster — one
+ * DELETE of the Sandbox, which cascades to the Pod, the Service and the PVC
+ * through ownerReferences — with the same two guarantees: an object already
+ * gone counts as deleted, that being the state DELETE was asking for, and a
+ * DELETE that FAILS rejects and stays retryable, because nothing here records
+ * a state a retry could early-return on.
+ *
+ * What it does NOT do is the point. Removing a month-old suspended workspace
+ * through a handle meant starting a pod for it first, probing it, and then
+ * deleting the pod again — compute spent, and a guest woken, purely to be
+ * told to go away. The DELETE never needed any of that: the name is
+ * deterministic, so the object can be addressed without being opened.
+ *
+ * It is not gated on the workspace being suspended, and deliberately: a
+ * running workspace's DELETE takes its pod down with it, which is what
+ * deleting a workspace means. A caller that wants the disk quiesced first
+ * calls {@link suspendKubernetesWorkspace} and then this.
+ */
+export declare function deleteKubernetesWorkspace(config: KubernetesBackendInternalConfig, workspaceId: string, options?: KubernetesWorkspaceTransitionOptions): Promise<void>;
+/**
+ * Suspend a workspace by id, without ever adopting it: send the patch, then
+ * wait for the pod to actually stop.
+ *
+ * The handle's own `suspend()` does three things — reap the terminals it
+ * handed out, stop admitting calls, and patch-and-wait. Only the third is
+ * about the CLUSTER, and it is the only one a process holding no handle can
+ * do or needs to. So this is that third thing on its own, for the operator
+ * putting somebody else's workspace to sleep.
+ *
+ * It resolves only once the pod is gone or in a terminal phase, for the same
+ * reason the handle's does: 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
+ * {@link KubernetesWorkspaceSuspendTimeoutError} and the object is left
+ * exactly as the patch left it — the next call patches and waits again.
+ *
+ * A workspace that no longer exists rejects with the client's own
+ * already-gone error rather than resolving. Unlike a DELETE, this asks for a
+ * state that cannot be reached: there is no object to suspend, and nothing
+ * the caller believed about it holds.
+ *
+ * Any HANDLE another process is holding on this workspace is not told. It
+ * finds out on its next call, which fails at the transport and is re-read
+ * into a {@link KubernetesWorkspaceSuspendedError} — or the moment that
+ * process calls `refresh()`. See {@link KubernetesWorkspace.refresh}.
+ */
+export declare function suspendKubernetesWorkspace(config: KubernetesBackendInternalConfig, workspaceId: string, options?: KubernetesWorkspaceSuspendOptions): Promise<void>;
 //# sourceMappingURL=workspace.d.ts.map