@namzu/sandbox 14.0.0 → 16.0.0

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

@@ -23,7 +23,8 @@
  * sub-second warm-acquire target this backend is judged against must be
  * measured, not guessed at.
  */
-import type { OpenTerminalOptions, SandboxExecOptions, SandboxExecResult, SandboxTcpConnectOptions, SandboxTcpConnection, TerminalSession } from '@namzu/sdk';
+import type { BackgroundJobStatus, OpenTerminalOptions, SandboxExecOptions, SandboxExecResult, SandboxReadFileOptions, SandboxTcpConnectOptions, SandboxTcpConnection, TerminalSession } from '@namzu/sdk';
+import { type GuestReplyIdentity, type QuiesceScope, type QuiescedProcess, type SessionKind, type SessionState } from '../firecracker/protocol.js';
 import { type SandboxAgentHandle, type VsockTransportOptions } from '../firecracker/transport.js';
 /** The one {@link SandboxAgentHandle} arm this backend ever constructs. */
 export type KubernetesAgentHandle = Extract<SandboxAgentHandle, {
@@ -37,8 +38,73 @@ export type KubernetesAgentHandle = Extract<SandboxAgentHandle, {
  * unexpected".
  */
 export declare class KubernetesAgentUnauthorizedError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the guest agent refuses a request because it has FENCED
+ * ITSELF: an earlier process group's shutdown could not be confirmed, so it
+ * answers every op but `healthz` and `cancel-execution` with `agent_retiring`
+ * and will go on doing so until the pod is replaced.
+ *
+ * Its own class, and deliberately NOT the Firecracker tier's mapping of the
+ * same refusal. There a fenced agent becomes {@link
+ * RemoteCancellationUnknownError}, which is correct for a disposable microVM:
+ * the shared controller's rule is that the sandbox stops being reusable, and
+ * on that tier retiring one means deleting scratch. On a workspace the same
+ * error would retire the handle and take the pod — and with it every other
+ * holder's terminals, dev servers and running commands — away from callers
+ * who did nothing but share a workspace with the command that wedged.
+ *
+ * So this error refuses the ONE call rather than the workspace: the handle is
+ * not retired, nothing is patched, and every other holder's pod stays where it
+ * was. What it does NOT claim is that the next call will work. The fence is
+ * the GUEST's, and `dispatch` gates it ahead of every data-plane branch, so
+ * `readFile`, `writeFile`, `openTerminal` and `openTcpConnection` meet the
+ * same refusal on the wire — under their own paths' error shapes, since only
+ * the two control ops come through `requestChecked`. Only a new pod clears
+ * it, which is why the message names the verbs that REPLACE the pod, on both
+ * tiers that use this transport, and leaves the timing to the host: on a
+ * workspace those are `suspend()` then `resume()`, and they take the live
+ * sessions in that pod down with them.
+ */
+export declare class KubernetesAgentRetiringError extends Error {
+    readonly name = "KubernetesAgentRetiringError";
     constructor(message?: string);
 }
+/**
+ * Thrown when the agent's address could not be RESOLVED — the dial never
+ * reached a socket because the name has no answer here.
+ *
+ * Its own class, and its own message, because this is the one failure whose
+ * cause is the deployment's shape rather than anything the cluster did: a
+ * Service FQDN resolves through cluster DNS and nowhere else, so a host
+ * outside the cluster fails every call at name resolution and reads the
+ * result as a sandbox that never came up. The fix is a configuration field,
+ * so the error names it.
+ */
+export declare class KubernetesAgentAddressUnresolvableError extends Error {
+    /** The host that did not resolve — normally a `*.svc.cluster.local`. */
+    readonly host: string;
+    readonly name = "KubernetesAgentAddressUnresolvableError";
+    constructor(
+    /** The host that did not resolve — normally a `*.svc.cluster.local`. */
+    host: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The pod and process one execution reserved on — see {@link executionGuest}. */
+export interface KubernetesReservedGuest {
+    /** The bind token the attempt presented, which is the pod's uid. */
+    readonly podUid?: string;
+    /** The boot id the `reserve-execution` reply carried, when it carried one. */
+    readonly guestBootId?: string;
+}
+/**
+ * The guest that reserved the execution this error came from — see
+ * {@link executionGuest}. `undefined` when the error is not an execution
+ * failure this transport produced.
+ */
+export declare function guestWhenReserved(error: unknown): KubernetesReservedGuest | undefined;
 /**
  * One `exec()` call's wall-time breakdown. Durations are NOT a partition
  * of a single total — `reserveMs` and `executeMs` each include their OWN
@@ -62,13 +128,339 @@ export interface KubernetesTransportTiming {
      */
     readonly drainMs: number;
 }
-export interface KubernetesTransportOptions extends VsockTransportOptions {
+/**
+ * What one `healthz` reply says about the agent, with the fence kept rather
+ * than collapsed into a boolean.
+ *
+ * {@link VsockAgentTransport.healthz} answers `false` both for an agent that
+ * did not reply and for one that replied "I have fenced myself", and those
+ * are opposite facts for a host deciding what to do next: the first is a pod
+ * that may be perfectly fine a second from now, the second is a pod that will
+ * refuse every call until it is replaced.
+ */
+export interface KubernetesAgentHealth {
+    /** The reply's own `ok` — `true` only for an agent serving normally. */
+    readonly ok: boolean;
+    /**
+     * The agent has fenced itself and only a new pod clears it.
+     *
+     * Read from the reply's own `retiring` flag and from nothing else. A
+     * not-`ok` reply without it is NOT inferred to be a fence: the connection
+     * gate answers a `healthz` that arrived over one unauthenticated
+     * connection too many, or behind an exhausted pre-auth buffer, with a
+     * named `{ ok: false, error }` and no flag — and a caller told `retiring`
+     * there would suspend and resume a perfectly healthy pod. So `ok: false`
+     * with `retiring: false` is its own answer: this reply says nothing about
+     * whether the agent is serving.
+     */
+    readonly retiring: boolean;
+}
+/**
+ * `permanentDialFailure` is deliberately NOT inherited: this transport sets
+ * its own (see the constructor), so advertising the field would be offering a
+ * caller a predicate that is silently overwritten. `onGuestReply` is
+ * re-declared rather than inherited, with the pod the reply came FROM — see
+ * below.
+ */
+export interface KubernetesTransportOptions extends Omit<VsockTransportOptions, 'permanentDialFailure' | 'onGuestReply'> {
     /**
      * Fires once per completed `exec()` call (success or failure) with
      * the four phase durations above. The payload is exactly those four
      * numbers — never the token, never a command, argv, or output.
      */
     readonly onTiming?: (timing: KubernetesTransportTiming) => void;
+    /**
+     * Re-read the live pod behind this sandbox and hand back the address
+     * and token it answers on NOW.
+     *
+     * Set only by the `pod-ip` address mode, where the handle carries a
+     * literal IP that dies with its pod; a Service FQDN needs none of this
+     * because the name outlives the pod and the dial re-resolves it every
+     * call. Consulted at most ONCE per call, and only after a dial that
+     * failed at connect — see {@link KubernetesAgentTransport}.
+     */
+    readonly refreshHandle?: (signal?: AbortSignal) => Promise<KubernetesAgentHandle>;
+    /**
+     * {@link VsockTransportOptions.onGuestReply}, plus the one thing the
+     * shared transport cannot say and this one always can: the bind token of
+     * the WIRE the reply arrived on, which is the uid of the pod that
+     * answered.
+     *
+     * A rebind builds a replacement wire and does not close the wire it
+     * leaves, so a call dispatched to the outgoing pod can still be answered
+     * BY it — a long `write-file`, a `read-file`, a pod inside its
+     * termination grace period — minutes after this transport has followed
+     * the replacement. That reply is a true statement about a pod this
+     * transport is no longer bound to, and a listener that could not tell the
+     * two apart would pair the departed pod's agent process with the
+     * replacement's uid: an identity naming a process that never ran there.
+     *
+     * Bound per wire, so the token is the one the reply's own connection
+     * presented and never the one the transport happens to hold now —
+     * `undefined` on a handle carrying no token at all, which is a wire that
+     * cannot name the pod that answered and so proves nothing about it.
+     */
+    readonly onGuestReply?: (reply: GuestReplyIdentity, podUid: string | undefined) => void;
+}
+/**
+ * Thrown before a command is admitted, when the caller asked for a
+ * detachable execution and the guest does not advertise
+ * {@link EXECUTION_ATTACH_FEATURE}.
+ *
+ * Refused rather than downgraded: a caller that asked for detach is about
+ * to rely on being able to come back for the output, and running the
+ * command anyway would keep nothing and tell nobody.
+ */
+export declare class KubernetesExecutionAttachUnsupportedError extends Error {
+    readonly feature: string;
+    readonly name = "KubernetesExecutionAttachUnsupportedError";
+    constructor(feature: string, message: string);
+}
+/** Why an `attach-execution` could not be served. */
+export type KubernetesAttachRefusal = 'unknown_execution' | 'output_not_retained' | 'invalid_offset' | 'invalid_execution_id' | 'agent_retiring' | 'unknown';
+/**
+ * Thrown when the guest ANSWERED an attach and refused it — the execution
+ * is past its retention, ran in a pod that has since been replaced, never
+ * asked for its output to be kept, or the offset names bytes it does not
+ * have.
+ *
+ * Distinct from a transport failure on purpose: a refusal will not become a
+ * success by being retried, so the reattach loop stops on it instead of
+ * spending its whole window re-asking a question already answered.
+ */
+export declare class KubernetesExecutionNotAttachableError extends Error {
+    readonly executionId: string;
+    readonly reason: KubernetesAttachRefusal;
+    readonly name = "KubernetesExecutionNotAttachableError";
+    /**
+     * The state the guest reported for this execution, when it reported
+     * one. `'reserved'` is the one that changes what a caller should do:
+     * the command was never started, so nothing is running.
+     */
+    readonly executionState: string | undefined;
+    constructor(executionId: string, reason: KubernetesAttachRefusal, message: string, options?: {
+        cause?: unknown;
+        state?: string;
+    });
+}
+/**
+ * Thrown when a detached `exec()` gave up OBSERVING a command that is, as
+ * far as this host knows, still the guest's to run.
+ *
+ * The two fields are what makes it recoverable rather than merely a
+ * failure: `executionId` names the command to a second host process, and
+ * `outputOffset` is the byte the next `attachExecution` should resume from
+ * so nothing is read twice and no gap is invented.
+ *
+ * Nothing on this path cancels to reconcile. That is the whole point of
+ * the feature: a reset connection used to cost the workspace its pod, and
+ * a command the host has stopped watching is not a command that has to
+ * die.
+ */
+export declare class KubernetesExecutionDetachedError extends Error {
+    readonly executionId: string;
+    readonly outputOffset: number;
+    readonly name = "KubernetesExecutionDetachedError";
+    constructor(executionId: string, outputOffset: number, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * What a caller passes to read an execution it did not necessarily start.
+ *
+ * `signal` here is an OBSERVATION signal, not the SDK's command signal:
+ * aborting it stops reading and leaves the command running. That is the
+ * opposite of `SandboxExecOptions.signal`, and it is why this type does not
+ * extend it.
+ */
+export interface KubernetesAttachExecutionOptions {
+    /** Byte offset to resume from. Default 0 — the whole retained log. */
+    readonly fromOffset?: number;
+    readonly onOutput?: SandboxExecOptions['onOutput'];
+    /** Stops OBSERVING. Never cancels; see {@link KubernetesAgentTransport.cancelExecution}. */
+    readonly signal?: AbortSignal;
+    /**
+     * Called when the guest reports that bytes the caller asked for had
+     * already been evicted from the retained log. The result's truncation
+     * flags say the same thing; this says how much.
+     */
+    readonly onGap?: (gap: {
+        readonly executionId: string;
+        readonly fromOffset: number;
+        readonly droppedBytes: number;
+    }) => void;
+}
+/**
+ * An `exec()` whose observation can be lost and taken up again — on this
+ * handle or in another host process — instead of costing the command its
+ * life.
+ *
+ * Deliberately NOT on the SDK's `SandboxExecOptions`: every other backend
+ * would then have to answer for a field it cannot honour, and the SDK's
+ * exec contract stays exactly what it was. This is a Kubernetes workspace
+ * surface, layered over the shared options type rather than widening it.
+ */
+export interface KubernetesDetachedExecOptions extends SandboxExecOptions, Pick<KubernetesAttachExecutionOptions, 'onGap'> {
+    /**
+     * The id this command is known by, to this process and to any other.
+     * Minted here when absent. Reserving an id the guest still holds does
+     * NOT start a second command: the call attaches to the one that exists,
+     * which is what makes a retried start idempotent for as long as the
+     * record lives.
+     */
+    readonly executionId?: string;
+    /**
+     * Ask the guest to retain this command's output so the observation can
+     * be resumed. Setting `executionId` implies it; the flag is what a
+     * caller that does not care about the id passes.
+     */
+    readonly detach?: boolean;
+    /**
+     * Stop observing and leave the command running — for a host that is
+     * shutting down. Rejects with {@link KubernetesExecutionDetachedError},
+     * which names the id and the offset to resume from.
+     *
+     * The opposite of `signal`, which keeps the SDK contract and terminates.
+     */
+    readonly detachSignal?: AbortSignal;
+    /**
+     * How long a lost connection is retried before the call gives up and
+     * reports itself detached. Default 30s.
+     */
+    readonly reattachWindowMs?: number;
+}
+/**
+ * Thrown before anything is started, when the caller asked for a session and
+ * the guest does not advertise {@link SESSIONS_FEATURE}.
+ *
+ * Refused, never downgraded to a connection-bound terminal. A caller that
+ * asked for a session is about to rely on coming back to it after its own
+ * process has been replaced; handing it one that dies with the socket would
+ * look like it worked until the one moment it was needed.
+ */
+export declare class KubernetesSessionsUnsupportedError extends Error {
+    readonly feature: string;
+    readonly name = "KubernetesSessionsUnsupportedError";
+    constructor(feature: string, message: string);
+}
+/** Why the guest refused a session request. */
+export type KubernetesSessionRefusal = 'unknown_session' | 'invalid_session_id' | 'invalid_offset' | 'session_exists' | 'session_capacity' | 'missing_command' | 'spawn_failed' | 'agent_retiring' | 'unknown';
+/**
+ * Thrown when the guest ANSWERED and refused: the session is past its
+ * retention, ran in a pod that has since been replaced, the id is already
+ * taken, or the offset names bytes it does not have.
+ *
+ * Distinct from a transport failure for the same reason
+ * {@link KubernetesExecutionNotAttachableError} is: a refusal does not
+ * become a success by being retried.
+ */
+export declare class KubernetesSessionRefusedError extends Error {
+    readonly sessionId: string;
+    readonly reason: KubernetesSessionRefusal;
+    readonly name = "KubernetesSessionRefusedError";
+    constructor(sessionId: string, reason: KubernetesSessionRefusal, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** One row of {@link KubernetesAgentTransport.listSessions}. */
+export interface KubernetesSessionSummary {
+    readonly sessionId: string;
+    readonly kind: SessionKind;
+    /** The program, as it was asked for. Never the environment it was given. */
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly startedAt: number;
+    readonly lastInputAt?: number;
+    readonly lastOutputAt?: number;
+    /** Pass as `fromOffset` to read everything this session has printed since. */
+    readonly nextOffset: number;
+    /** Bytes the ring has evicted over this session's life. */
+    readonly droppedBytes: number;
+    readonly state: SessionState;
+    /** Whether a host process is attached to it right now. */
+    readonly attached: boolean;
+    readonly exitCode?: number;
+    readonly signal?: number;
+}
+/**
+ * One read of a session's retained output, in the SDK's
+ * `BackgroundJobOutput` shape — deliberately, because it answers the same
+ * question for the same kind of consumer and a second vocabulary for
+ * "here is the next chunk and here is what you missed" helps nobody.
+ */
+export interface KubernetesSessionOutput {
+    readonly chunk: string;
+    readonly nextOffset: number;
+    readonly droppedBytes: number;
+    readonly status: BackgroundJobStatus;
+    readonly exitCode?: number;
+}
+/**
+ * A terminal on a workspace, with the three things only a SESSION's reader
+ * needs. On a connection-bound terminal the two optional members are absent,
+ * which is the honest answer: there is no session to name and nothing to
+ * detach from.
+ */
+export interface KubernetesWorkspaceTerminal extends TerminalSession {
+    /** Present exactly when this terminal belongs to a guest session. */
+    readonly sessionId?: string;
+    /** One past the newest retained byte delivered so far. */
+    nextOffset?(): number | undefined;
+    /**
+     * Stop reading and leave the program running — the opposite of
+     * {@link TerminalSession.kill}. `exited` then rejects with
+     * `AgentSessionDetachedError`, because a resolved `exited` would claim
+     * an exit that did not happen.
+     */
+    detach?(): void;
+}
+/**
+ * What an ATTACH hands back: the same terminal, with the three session
+ * members present rather than optional. `openTerminal` returns the looser
+ * type because it serves both shapes and a connection-bound terminal
+ * genuinely has no session to name.
+ */
+export interface KubernetesSessionTerminal extends KubernetesWorkspaceTerminal {
+    readonly sessionId: string;
+    nextOffset(): number | undefined;
+    detach(): void;
+}
+/** `openTerminal` on a workspace, widened by the two session fields. */
+export interface KubernetesOpenTerminalOptions extends OpenTerminalOptions {
+    /**
+     * Name this terminal so a later host process can find it again.
+     * Requires {@link persistent}; on its own it names nothing.
+     */
+    readonly sessionId?: string;
+    /**
+     * Hand the PTY to the guest's session registry rather than to this
+     * connection. Losing the connection then DETACHES — no signal is sent,
+     * and the program ends when it exits, on `killSession`, or when the pod
+     * stops.
+     */
+    readonly persistent?: boolean;
+}
+/** Rejoin a terminal session that is already running. */
+export interface KubernetesAttachTerminalOptions {
+    /** Byte offset to replay from. Default 0 — everything the ring still holds. */
+    readonly fromOffset?: number;
+    /** Resize the PTY on attach, for a reader whose window is a different shape. */
+    readonly size?: {
+        readonly cols: number;
+        readonly rows: number;
+    };
+}
+/** Start a program with no terminal, which only a kill or the pod ends. */
+export interface KubernetesStartDetachedOptions {
+    readonly sessionId: string;
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+}
+/** Read a session's retained output without attaching to it. */
+export interface KubernetesReadSessionOptions {
+    readonly fromOffset?: number;
 }
 /**
  * The kubernetes backend's dialable transport: a `tcp` handle plus a
@@ -78,17 +470,322 @@ export interface KubernetesTransportOptions extends VsockTransportOptions {
  * remote backend gets, while every network operation is delegated to
  * {@link VsockAgentTransport} for the actual dial/frame/token work.
  */
+/**
+ * Thrown when a quiesce was asked of a guest that cannot perform one:
+ * either its `healthz` does not advertise {@link QUIESCE_FEATURE}, or it
+ * answered `unknown_op: quiesce`.
+ *
+ * Refused rather than treated as "nothing was running". A caller asks for a
+ * quiesce because it is about to read the disk and needs it still; an image
+ * that cannot stop its processes has to say so, not resolve with an empty
+ * list that reads exactly like a guest which had nothing to stop.
+ */
+export declare class KubernetesQuiesceUnsupportedError extends Error {
+    readonly feature: string;
+    readonly name = "KubernetesQuiesceUnsupportedError";
+    constructor(feature: string, message: string);
+}
+/**
+ * Thrown when nothing can promise the guest is quiet.
+ *
+ * Usually because the guest ANSWERED and said so — a process survived
+ * `SIGKILL`, the scan could not be performed, or the op ran out of its own
+ * deadline — and then the guest's own message names the pid. The workspace
+ * handle raises the same class for the one case that never reaches a guest:
+ * a `suspend({ quiesce: true })` arriving while a suspend WITHOUT a quiesce
+ * is already in flight, whose patch has gone over processes nobody stopped
+ * (`reason: 'suspend_already_in_flight'`). Both mean the one thing a caller
+ * has to act on: do not trust a capture taken now.
+ *
+ * Its own class for the same reason {@link KubernetesSessionRefusedError}
+ * is: this is an answer, not a transport failure, and retrying it is a
+ * decision the caller makes with the pid in hand rather than one a wrapper
+ * makes on its behalf.
+ */
+export declare class KubernetesQuiesceUnconfirmedError extends Error {
+    readonly reason: string;
+    readonly name = "KubernetesQuiesceUnconfirmedError";
+    constructor(reason: string, message: string);
+}
+/** What the guest stopped, and how widely it was allowed to look. */
+export interface KubernetesQuiesceReport {
+    /** Every process signalled, with the last signal it was actually sent. */
+    readonly stopped: readonly QuiescedProcess[];
+    /** See {@link QuiesceScope}. `owned-sessions` is the narrowed one. */
+    readonly scope: QuiesceScope;
+    /** The per-round SIGTERM window the guest used, after its own clamp. */
+    readonly graceMs: number;
+    /** Scan-and-signal passes. `0` means nothing was running. */
+    readonly rounds: number;
+}
+/**
+ * Thrown when a flush was asked of a guest that cannot perform one: either
+ * its `healthz` does not advertise {@link FLUSH_FEATURE}, or it answered
+ * `unknown_op: flush`.
+ *
+ * Refused rather than treated as "the disk is already flushed", for the
+ * same reason {@link KubernetesQuiesceUnsupportedError} is not treated as
+ * "nothing was running". The one caller that does NOT pass this on is
+ * `suspend()`, which goes ahead and tells the host through
+ * `onFlushUnsupported`: an image built before this op is a deployment that
+ * has to be able to suspend its workspaces, not one that has to be stopped.
+ */
+export declare class KubernetesFlushUnsupportedError extends Error {
+    readonly feature: string;
+    readonly name = "KubernetesFlushUnsupportedError";
+    constructor(feature: string, message: string);
+}
+/**
+ * Thrown when nothing can promise the workspace's writes are on the device.
+ *
+ * The guest ANSWERED and said so — the `syncfs` failed, or ran past its own
+ * timeout — and its message says which. Its own class for the reason every
+ * other answered refusal here has one: this is a fact about the disk, not a
+ * transport failure, and a caller holding it decides whether to retry,
+ * suspend anyway, or leave the workspace running.
+ */
+export declare class KubernetesFlushUnconfirmedError extends Error {
+    readonly reason: string;
+    readonly name = "KubernetesFlushUnconfirmedError";
+    constructor(reason: string, message: string);
+}
+/**
+ * Carried to {@link KubernetesWorkspaceOptions.onFlushUnreachable} when a
+ * `suspend()` could not ASK for a flush at all — the dial failed, the
+ * connection timed out, the token was refused, or the agent has fenced
+ * itself — and the suspend went ahead without one.
+ *
+ * Never thrown at a caller. The difference between this and
+ * {@link KubernetesFlushUnconfirmedError} is the difference between a guest
+ * that could not be reached and a guest that answered: a guest that
+ * answered is alive, and stopping the suspend gives its caller something to
+ * do about it, while a guest nothing can reach will not become flushable by
+ * leaving its pod running — and refusing to suspend over it would take away
+ * the one verb an operator reaches for when a workspace is wedged, the verb
+ * {@link KubernetesAgentRetiringError} itself names as the way out.
+ *
+ * So the suspend proceeds, the host is told, and the message says what the
+ * disk is resting on instead: whatever the guest kernel had already written
+ * back, plus the pod's own `preStop` hook and the agent's `SIGTERM` handler
+ * if either of them still runs.
+ */
+export declare class KubernetesFlushUnreachableError extends Error {
+    readonly name = "KubernetesFlushUnreachableError";
+}
+/** What a flush did, as the guest measured it. */
+export interface KubernetesFlushReport {
+    /** How long the `syncfs` took inside the guest. */
+    readonly durationMs: number;
+    /** The mount the guest flushed — its workspace root. */
+    readonly workspace: string;
+}
+/**
+ * The refusal a guest that cannot flush earns, built in one place.
+ *
+ * Exported because the WORKSPACE has to be able to hand this exact error to
+ * `onFlushUnsupported` on the one path that does not throw it — a
+ * `suspend()` against an older image — and a second copy of the message
+ * would be a second thing to keep true.
+ */
+export declare function flushUnsupportedError(): KubernetesFlushUnsupportedError;
 export declare class KubernetesAgentTransport {
-    private readonly handle;
+    /**
+     * Mutable: the handle follows a replaced pod — see {@link rebind}.
+     *
+     * Under `'pod-ip'` both the address and the token move, because the
+     * address is a literal that died with its pod. Under the default
+     * `'service'` mode the host is a Service FQDN that outlives the pod and
+     * resolves to the replacement on its own, so what moves is the TOKEN
+     * alone — which is the entire reason a `service` handle needed a rebind
+     * at all: the dial keeps working and the guest refuses every call.
+     */
+    private handle;
+    /** The re-read currently in flight, so concurrent refusals share one. */
+    private rebinding?;
+    /**
+     * How many times this transport has moved to a different pod. Captured
+     * before every attempt and compared after it fails, so a call refused by
+     * the pod it was bound to — arriving after ANOTHER call's rebind already
+     * installed the replacement — retries on the handle that has moved
+     * instead of re-reading to be told nothing changed.
+     */
+    private rebindSeq;
     private readonly transportOptions;
+    /** Bound to each wire's own pod by {@link wireOptions}. */
+    private readonly onGuestReply?;
     private readonly onTiming?;
+    private readonly refreshHandle?;
     /** Simple pass-through operations share one transport instance. */
-    private readonly wire;
+    private wire;
     constructor(handle: KubernetesAgentHandle, options?: KubernetesTransportOptions);
-    /** Readiness probe — never requires a token; see `protocol.ts`. */
+    /**
+     * The shared transport's options for ONE wire, with the reply observer
+     * bound to the pod that wire is talking to.
+     *
+     * Every `VsockAgentTransport` this class builds goes through here — the
+     * first one, the one a rebind installs, and the per-attempt one `exec()`
+     * times — because a wire outlives the moment it was current: the pod it
+     * dials can answer a call after a rebind has already moved
+     * {@link handle} on, and the observer has to be told the pod that
+     * ANSWERED rather than the pod this transport now holds. Capturing the
+     * handle in the closure is what makes the two different values.
+     */
+    private wireOptions;
+    /**
+     * The address this transport is dialing right now. Diagnostics only —
+     * host and port, and deliberately NOT the handle itself: this is read
+     * into a log line or an assertion, and the bind token has no business
+     * travelling with either.
+     */
+    get address(): {
+        readonly host: string;
+        readonly port: number;
+    };
+    /**
+     * Run one operation, and give the handle exactly one chance to follow a
+     * pod that was replaced underneath it.
+     *
+     * TWO failures reach a rebind, and they are the only two, because they
+     * are the only two that prove the operation ran NOTHING in the guest:
+     *
+     *  - **the dial failed.** No socket was ever established, so no byte was
+     *    sent. This is the trigger the `'pod-ip'` mode was built on: the
+     *    address is a literal that dies with its pod.
+     *  - **the guest REFUSED the token** (`unauthorized`, in either of the
+     *    shapes {@link isUnauthorizedRefusal} unifies). The agent checks the
+     *    token before `dispatch`, so a refused request reached the guest and
+     *    was thrown away unread. This is the trigger that matters under the
+     *    DEFAULT `'service'` mode, where the Service FQDN outlives the pod
+     *    and keeps resolving: the dial SUCCEEDS against the replacement and
+     *    the refusal is the only thing that says the pod moved.
+     *
+     * Everything else is the guest's answer to a request it did receive, and
+     * nothing here may reinterpret it — not as a resolver problem, and not as
+     * a reason to repeat work the guest has already begun.
+     *
+     * From there both arms run the SAME routine, which is the whole of this
+     * change to it: {@link rebind} reads the pod once, and a DIFFERENT uid
+     * means the controller replaced it (a resume, an eviction, a node drain),
+     * so the handle takes the new address AND the new token together and the
+     * operation is retried once.
+     *
+     * One branch belongs to the dial arm alone, and is taken before the
+     * re-read: the handle's host is a NAME and the dial gave up at
+     * resolution, so this is a Service FQDN and this host has no resolver for
+     * it. Re-reading the pod would change nothing — the next dial would ask
+     * the same resolver the same question — so the error is replaced with one
+     * that names the FQDN and the configuration field that fixes it. It is
+     * never asked of a refusal, which came back over a connection that
+     * plainly worked, and the name check is not decoration either: a
+     * `pod-ip` handle must keep its one re-read however an unrelated error
+     * happens to be worded.
+     *
+     * Anything else — a re-read that finds the SAME pod, or one that fails —
+     * leaves the original error standing. A pod that is still there and still
+     * refusing is a guest problem, and replacing that error with a second,
+     * later one would hide it. The one exception is a re-read that comes back
+     * with a verdict about the OBJECT rather than a failed diagnosis
+     * ({@link KubernetesWorkspaceReplacedError}): the disk behind the name is
+     * not this handle's disk, which outranks whatever uncovered it.
+     *
+     * `signal` is the caller's own, and it decides one thing only: a call that
+     * has ALREADY been cancelled is not owed a re-read, because the retry it
+     * would buy would abort before it left. It is never handed to the re-read
+     * itself, which is shared and runs under a bound of its own — see
+     * {@link rebind}.
+     *
+     * `dials` is how `exec()` answers the first question at all. Its failure
+     * can arrive as a bare timeout from the execution controller's own bound,
+     * with the dial's error discarded rather than wrapped, so that path
+     * watches its dials instead of reading its error — see {@link DialWatch}.
+     * Every other operation hands back the dial's own error and passes none.
+     *
+     * A refusal that no rebind could fix leaves as {@link
+     * KubernetesAgentUnauthorizedError} whichever shape it arrived in — the
+     * unification the whole recovery hangs off, applied at the one point
+     * where "nothing else can be done about it" is known.
+     */
+    private withRebind;
+    /**
+     * Whether the dial gave up at name resolution.
+     *
+     * Asked of the caller's error first, and of the watched dial's own error
+     * only when nothing ever connected — the case where the error the caller
+     * holds is a bound's timer rather than the failure that caused it. A
+     * watched attempt that DID connect is never consulted: its error is the
+     * guest's answer, however it happens to be worded.
+     */
+    private failedToResolve;
+    /**
+     * The one connect failure waiting cannot cure — see the constructor.
+     * A method rather than a closure because the watched `exec()` dials wrap
+     * it, and a caller-visible answer must not depend on which wire asked.
+     */
+    private dialFailureIsPermanent;
+    /**
+     * One re-read, shared by every call that needs one at the same moment.
+     * True when the handle now points at a DIFFERENT pod than the one the
+     * caller's attempt was dispatched on — whether this call's own re-read
+     * moved it or another call's already had.
+     *
+     * Single-flight, and that is not an optimisation. A pod replaced
+     * underneath a busy handle refuses EVERY call in flight at once, and one
+     * re-read per refused call would be a burst of Sandbox and pod GETs, each
+     * one racing the others to install a handle — with the last to finish
+     * winning, which is not necessarily the last to read. Sharing the promise
+     * makes the burst one round trip and one installation, in the order the
+     * API answered.
+     *
+     * The slot is cleared inside the shared run, before the promise settles,
+     * so a caller that awaits it and is refused AGAIN gets a fresh re-read
+     * rather than the answer to the previous question.
+     *
+     * Because it is shared it runs under {@link REBIND_READ_TIMEOUT_MS} and
+     * under NO caller's signal. A caller that aborts while the shared read is
+     * in flight would otherwise abort it for everyone, and every call the
+     * replacement refused would fail with its original refusal although the
+     * handle could have followed the pod. Its own bound is what the aborting
+     * caller was owed — nobody waits on a re-read for longer than that — and
+     * the read is two GETs nobody is billed for twice.
+     */
+    private rebind;
+    private runRebind;
+    /** Whether the current handle's host goes through a resolver at all. */
+    private dialsAName;
+    /** The DNS-shaped failure, in words that name the way out of it. */
+    private unresolvable;
+    /**
+     * Readiness probe — never requires a token; see `protocol.ts`.
+     *
+     * Deliberately NOT wrapped in {@link withRebind}: `healthz` answers a
+     * failed dial with `false` rather than by throwing, so there is no error
+     * to classify and nothing for a re-read to be triggered by. A caller that
+     * wants the reason asks for it by making a real call.
+     */
     healthz(signal?: AbortSignal): Promise<boolean>;
-    /** Poll until `healthz` succeeds or the timeout elapses. */
+    /**
+     * Poll until `healthz` succeeds or the timeout elapses. Unwrapped for the
+     * same reason, and for one more: it already owns a retry loop, so a
+     * connect failure here is not a single failed dial but a whole budget of
+     * them.
+     */
     waitForReady(timeoutMs: number, pollIntervalMs: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Ask the agent how it is, and keep the two "not ok" answers apart —
+     * see {@link KubernetesAgentHealth}.
+     *
+     * Deliberately NOT wrapped in {@link withRebind}: this is a diagnostic
+     * about the pod this handle is bound to RIGHT NOW, and a rebind would
+     * silently answer it about a different pod. A caller that wants to know
+     * whether the agent it was talking to has fenced itself would then be
+     * told about the replacement, which is a different question with a
+     * different answer.
+     *
+     * It throws whatever the dial or the read threw. An agent that cannot be
+     * reached has no health to report, and inventing one here would turn
+     * "unreachable" into "fine".
+     */
+    agentHealth(signal?: AbortSignal): Promise<KubernetesAgentHealth>;
     /**
      * The raw `reserve-execution` primitive, exposed directly (rather than
      * only reachable as a side effect of `exec()`) so the reservation
@@ -103,9 +800,166 @@ export declare class KubernetesAgentTransport {
      * driving a whole cancelled `exec()` to reach it.
      */
     cancel(executionId: string, signal?: AbortSignal): Promise<unknown>;
-    writeFile(path: string, content: Buffer): Promise<void>;
-    readFile(path: string): Promise<Buffer>;
-    openTerminal(options: OpenTerminalOptions): Promise<TerminalSession>;
+    /**
+     * Delegated, `signal` included: a body larger than one pre-auth frame
+     * is written as a sequence of parts by {@link VsockAgentTransport}
+     * itself, and a cancelled sequence has to be able to stop mid-way and
+     * take its temp file with it.
+     *
+     * One transport instance, deliberately — {@link wire} is shared by
+     * every simple pass-through op — so the one `healthz` probe that asks
+     * the guest whether it can take parts is asked once for this sandbox,
+     * not once per large write.
+     *
+     * Wrapped in {@link withRebind} like every other guest-dialling op,
+     * the multi-part route included, and for both of its triggers: a retry
+     * starts a fresh sequence under a new temp name
+     * (`writeFilePartTempPath` mints a UUID per call), so a sequence
+     * abandoned mid-way on the replaced pod — because the dial failed, or
+     * because the replacement refused this handle's token before reading a
+     * byte — cannot collide with the retry's offsets and never touched the
+     * target. At worst it leaves one orphan temp file behind on the
+     * workspace volume.
+     */
+    writeFile(path: string, content: Buffer, signal?: AbortSignal): Promise<void>;
+    readFile(path: string, options?: SandboxReadFileOptions): Promise<Buffer>;
+    /**
+     * Delegated, and rebound exactly once — but only around the FIRST
+     * chunk.
+     *
+     * That is the whole of what {@link withRebind} can honestly cover here.
+     * Its retry is safe because nothing reached the guest, and once a chunk
+     * has been yielded that is no longer true: re-dialing a replaced pod
+     * mid-stream would restart the file from its beginning, and the
+     * consumer — which has already taken the bytes and cannot give them
+     * back — would silently concatenate a duplicate prefix. So the first
+     * pull carries the dial, the rebind and the retry; everything after it
+     * fails as itself.
+     */
+    readFileStream(path: string, options?: SandboxReadFileOptions): AsyncGenerator<Buffer, void, undefined>;
+    /**
+     * A guest PTY. Without `sessionId`/`persistent` this is exactly the
+     * terminal it has always been, down to the wire request.
+     *
+     * With them the PTY belongs to the guest's session registry: losing this
+     * connection detaches rather than killing, a later process rejoins it
+     * with {@link attachSession}, and the capability is verified against the
+     * guest's `healthz` features BEFORE the shell is started — never
+     * downgraded to a connection-bound terminal, which would look like it
+     * worked until the rollout it exists for.
+     */
+    openTerminal(options: KubernetesOpenTerminalOptions): Promise<KubernetesWorkspaceTerminal>;
+    /**
+     * One open of a session stream, with the guest's refusal mapped to
+     * {@link KubernetesSessionRefusedError} — see {@link sessionStreamFailure}.
+     */
+    private sessionStream;
+    /**
+     * Rejoin a terminal session, replaying from `fromOffset` and then
+     * following it live.
+     *
+     * The guest allows one attachment per session and ends the previous one
+     * by name, so two host processes cannot interleave keystrokes into one
+     * shell. Losing this connection detaches; ending the program is
+     * {@link killSession} and nothing else.
+     */
+    attachSession(sessionId: string, options?: KubernetesAttachTerminalOptions): Promise<KubernetesSessionTerminal>;
+    /**
+     * Start a program with no terminal at all, in its own kernel session,
+     * with stdin closed and both output streams going into the guest's
+     * retained log.
+     *
+     * It is not the SDK's `spawnDetached` and deliberately does not pretend
+     * to be: that one hands back a host `ChildProcess`, which cannot cross a
+     * process boundary. This returns a NAME, and the name is what a
+     * redeployed host comes back with.
+     */
+    startDetached(options: KubernetesStartDetachedOptions, signal?: AbortSignal): Promise<KubernetesSessionSummary>;
+    /** Every session this pod's agent is holding, running and recently exited. */
+    listSessions(signal?: AbortSignal): Promise<readonly KubernetesSessionSummary[]>;
+    /**
+     * End one session and everything still in it — the shell, its
+     * backgrounded jobs, and the program a detached session started.
+     *
+     * Idempotent: a session that has already exited answers with what it
+     * exited with. The reply carries the session's state, so a program that
+     * ignored a `SIGTERM` and outlived the guest's confirm window is
+     * reported still running rather than reported dead.
+     */
+    killSession(sessionId: string, options?: {
+        readonly signal?: string;
+        readonly abort?: AbortSignal;
+    }): Promise<KubernetesSessionSummary>;
+    /**
+     * Read what a session has printed since `fromOffset`, without attaching
+     * to it and without signalling anything.
+     *
+     * One request, one answer, in the SDK's `BackgroundJobOutput` shape: the
+     * chunk, the offset to come back with, the bytes the ring dropped before
+     * it, and the program's status. A caller polling in a loop can neither
+     * re-read nor skip, because the offset is the guest's own.
+     */
+    readSession(sessionId: string, options?: KubernetesReadSessionOptions, signal?: AbortSignal): Promise<KubernetesSessionOutput>;
+    /**
+     * Stop every process this pod's guest is running, and keep the agent.
+     *
+     * The point is the pair. Stopping the POD stops its processes too, but
+     * leaves nothing to read the disk through, so a host that wants a capture
+     * it can trust has to wake the workspace again and check. After this the
+     * guest is quiet and still serving: `exec`, `readFile` and `writeFile`
+     * all work, and what they see is a filesystem nobody is writing to.
+     *
+     * Open terminals and running commands end as a side effect and report it
+     * through their own exit and result paths — a terminal receives its exit,
+     * an `exec` resolves with a signal in its result. Rejecting with
+     * {@link KubernetesQuiesceUnconfirmedError} is the honest failure: a
+     * process would not stop, and the reply names its pid.
+     */
+    quiesce(options?: {
+        readonly graceMs?: number;
+    }, signal?: AbortSignal): Promise<KubernetesQuiesceReport>;
+    /**
+     * Put everything this workspace has written onto its device.
+     *
+     * The disk a workspace keeps is whatever the guest kernel happened to
+     * write back. Nothing in this backend ever asked for more than that: a
+     * `suspend()` patched the pod away and waited for it to stop, and a
+     * stopped pod means only that nothing is writing any more — not that
+     * what was written arrived. This is the call that closes the difference,
+     * and it is `syncfs(2)` over the whole workspace mount, so it covers
+     * what a COMMAND wrote as well as what `writeFile` did (`writeFile`
+     * fsyncs its own bytes before it answers; a compiler's output is nobody's
+     * to fsync).
+     *
+     * Rejecting with {@link KubernetesFlushUnconfirmedError} is the honest
+     * failure, exactly as an unconfirmed quiesce is: the caller is usually
+     * about to take the pod away, and "the flush did not run" has to be
+     * distinguishable from "the flush ran".
+     */
+    flush(options?: {
+        readonly timeoutMs?: number;
+    }, signal?: AbortSignal): Promise<KubernetesFlushReport>;
+    /**
+     * Whether this guest can flush at all — asked, rather than assumed,
+     * because a `suspend()` against an older image keeps today's behaviour
+     * and reports the gap instead of refusing to suspend.
+     */
+    supportsFlush(signal?: AbortSignal): Promise<boolean>;
+    private assertFlushSupported;
+    private flushUnsupported;
+    /**
+     * Whether this guest can quiesce at all — asked, rather than assumed,
+     * because `suspend({ quiesce: true })` against an older image keeps
+     * today's behaviour and reports the gap instead of refusing to suspend.
+     */
+    supportsQuiesce(signal?: AbortSignal): Promise<boolean>;
+    private assertQuiesceSupported;
+    private quiesceUnsupported;
+    /**
+     * Whether this guest keeps a session registry at all, asked once per
+     * transport and only when a caller wants one.
+     */
+    private assertSessionsSupported;
     openTcpConnection(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection>;
     /**
      * Run one command through a fresh, call-scoped adapter + controller.
@@ -118,5 +972,77 @@ export declare class KubernetesAgentTransport {
      * mutable field for two in-flight calls to race on.
      */
     exec(command: string, argv?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>;
+    /**
+     * Whether this guest implements the detach/attach ops at all, asked once
+     * per transport and only when a caller wants them.
+     */
+    private assertExecutionAttachSupported;
+    /** `reserve-execution` for a caller-named id, with its reported state. */
+    private reserveDetached;
+    /**
+     * The `cancel-execution` control path, retried for its whole confirm
+     * window and reported UNKNOWN rather than as a failure if none of the
+     * attempts got an answer — the same rule the shared execution
+     * controller applies, because a command whose termination nobody
+     * confirmed is not a command anybody may call dead.
+     *
+     * Nothing on the detach path calls this to reconcile a lost connection.
+     * It runs when the CALLER asked for it: `SandboxExecOptions.signal`
+     * aborting, or {@link cancelExecution}.
+     */
+    private confirmCancel;
+    /**
+     * End a command by id, from any host process holding the id and the
+     * bind token. Resolves only on a CONFIRMED termination.
+     *
+     * The outcome is not reported here — a cancelled execution's result and
+     * whatever output it managed is read back through
+     * {@link attachExecution}, which is the op that exists for reading.
+     */
+    cancelExecution(executionId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Observe a command that is already the guest's, from `fromOffset` on,
+     * and resolve with its result.
+     *
+     * It never signals the command. Aborting `signal` stops OBSERVING and
+     * rejects with {@link KubernetesExecutionDetachedError}; it does not
+     * cancel, and the command goes on running. Ending a command is
+     * {@link cancelExecution} and nothing else.
+     */
+    attachExecution(executionId: string, options?: KubernetesAttachExecutionOptions): Promise<SandboxExecResult>;
+    /**
+     * Run one command whose observation can outlive this connection, and —
+     * when the connection is what failed — get it back rather than killing
+     * the command to reconcile.
+     *
+     * The order is exactly: refuse if the guest cannot keep output, reserve
+     * the id, and only then admit the command. Reserving the id the CALLER
+     * named is what makes a retried start idempotent: a second call with the
+     * same id inside retention finds the execution already running or
+     * finished, sends no `execute`, and attaches to the one that exists.
+     *
+     * `SandboxExecOptions.signal` keeps its contract — aborting it runs the
+     * confirmed cancel — and `detachSignal` is its opposite: it ends the
+     * observation and leaves the command alone, for a host that is shutting
+     * down and wants its work to survive the rollout.
+     */
+    execDetached(command: string, argv?: string[], opts?: KubernetesDetachedExecOptions): Promise<SandboxExecResult>;
+    /**
+     * The `execute` leg of a detached run, read frame by frame.
+     *
+     * It deliberately does NOT go through `executeStreamed`: that path
+     * hands its caller `{stream, data}` and nothing else, and the byte
+     * offsets this cursor lives on are on the frames themselves. Reading
+     * them here is what lets a reattach resume exactly where this
+     * connection stopped, on output whose decoded length is not its byte
+     * length — see {@link applyDelta}. The frame union and its validation
+     * are the shared ones, so an ordinary exec and a detached one never
+     * disagree about what the guest said.
+     */
+    private executeRetained;
+    /** One `attach-execution` stream, read to its terminal frame. */
+    private attachOnce;
+    /** The one error a lost observation ends with. */
+    private detached;
 }
 //# sourceMappingURL=transport.d.ts.map