@cloudflare/sandbox 0.12.0 → 0.13.0-next.632.1

package/dist/{sandbox-Duj2gvUC.js → sandbox-B7ewRruX.js}

@@ -1,4 +1,4 @@
-import { _ as GitLogger, b as getEnvString, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as DEFAULT_GIT_CLONE_TIMEOUT_MS, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, p as logCanonicalEvent, r as isWSResponse, t as generateRequestId, u as createLogger, v as extractRepoName, x as partitionEnvVars, y as filterEnvVars } from "./dist-B_eXrP83.js";
+import { a as shellEscape, c as TraceContext, d as ResultImpl, f as filterEnvVars, i as parseSSEFrames, l as logCanonicalEvent, m as partitionEnvVars, o as createLogger, p as getEnvString, s as createNoOpLogger, u as Execution } from "./dist-mAH_7Ui7.js";
 import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-aRUdk9K8.js";
 import { Container, ContainerProxy, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
@@ -720,2718 +720,1064 @@ function createErrorFromResponse(errorResponse, options) {
 }
 
 //#endregion
-//#region src/clients/transport/base-transport.ts
+//#region src/file-stream.ts
 /**
-* Container startup retry configuration
+* Parse SSE (Server-Sent Events) lines from a stream
 */
-const DEFAULT_RETRY_TIMEOUT_MS$1 = 12e4;
-const MIN_TIME_FOR_RETRY_MS$1 = 15e3;
+async function* parseSSE(stream) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let currentEvent = { data: [] };
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const parsed = parseSSEFrames(buffer, currentEvent);
+			buffer = parsed.remaining;
+			currentEvent = parsed.currentEvent;
+			for (const frame of parsed.events) try {
+				yield JSON.parse(frame.data);
+			} catch {}
+		}
+		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
+		for (const frame of finalParsed.events) try {
+			yield JSON.parse(frame.data);
+		} catch {}
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {}
+		reader.releaseLock();
+	}
+}
 /**
-* Abstract base transport with shared retry logic
+* Stream a file from the sandbox with automatic base64 decoding for binary files
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
 *
-* Handles 503 retry for container startup - shared by all transports.
-* Subclasses implement the transport-specific fetch and stream logic.
+* @example
+* ```ts
+* const stream = await sandbox.readFileStream('/path/to/file.png');
+* for await (const chunk of streamFile(stream)) {
+*   if (chunk instanceof Uint8Array) {
+*     // Binary chunk
+*     console.log('Binary chunk:', chunk.length, 'bytes');
+*   } else {
+*     // Text chunk
+*     console.log('Text chunk:', chunk);
+*   }
+* }
+* ```
 */
-var BaseTransport = class {
-	config;
-	logger;
-	retryTimeoutMs;
-	constructor(config) {
-		this.config = config;
-		this.logger = config.logger ?? createNoOpLogger();
-		this.retryTimeoutMs = config.retryTimeoutMs ?? DEFAULT_RETRY_TIMEOUT_MS$1;
-	}
-	setRetryTimeoutMs(ms) {
-		this.retryTimeoutMs = ms;
+async function* streamFile(stream) {
+	let metadata = null;
+	for await (const event of parseSSE(stream)) switch (event.type) {
+		case "metadata":
+			metadata = {
+				mimeType: event.mimeType,
+				size: event.size,
+				isBinary: event.isBinary,
+				encoding: event.encoding
+			};
+			break;
+		case "chunk":
+			if (!metadata) throw new Error("Received chunk before metadata");
+			if (metadata.isBinary && metadata.encoding === "base64") {
+				const binaryString = atob(event.data);
+				const bytes = new Uint8Array(binaryString.length);
+				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+				yield bytes;
+			} else yield event.data;
+			break;
+		case "complete":
+			if (!metadata) throw new Error("Stream completed without metadata");
+			return metadata;
+		case "error": throw new Error(`File streaming error: ${event.error}`);
 	}
-	getRetryTimeoutMs() {
-		return this.retryTimeoutMs;
+	throw new Error("Stream ended unexpectedly");
+}
+/**
+* Collect an entire file into memory from a stream
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns Object containing the file content and metadata
+*
+* @example
+* ```ts
+* const stream = await sandbox.readFileStream('/path/to/file.txt');
+* const { content, metadata } = await collectFile(stream);
+* console.log('Content:', content);
+* console.log('MIME type:', metadata.mimeType);
+* ```
+*/
+async function collectFile(stream) {
+	const chunks = [];
+	const generator = streamFile(stream);
+	let result = await generator.next();
+	while (!result.done) {
+		chunks.push(result.value);
+		result = await generator.next();
 	}
-	/**
-	* Fetch with automatic retry for 503 (container starting)
-	*
-	* This is the primary entry point for making requests. It wraps the
-	* transport-specific doFetch() with retry logic for container startup.
-	*/
-	async fetch(path$1, options) {
-		const startTime = Date.now();
-		let attempt = 0;
-		while (true) {
-			const response = await this.doFetch(path$1, options);
-			if (response.status === 503) {
-				const elapsed = Date.now() - startTime;
-				const remaining = this.retryTimeoutMs - elapsed;
-				if (remaining > MIN_TIME_FOR_RETRY_MS$1) {
-					const delay = Math.min(3e3 * 2 ** attempt, 3e4);
-					this.logger.info("Container not ready, retrying", {
-						status: response.status,
-						attempt: attempt + 1,
-						delayMs: delay,
-						remainingSec: Math.floor(remaining / 1e3),
-						mode: this.getMode()
-					});
-					await this.sleep(delay);
-					attempt++;
-					continue;
-				}
-				this.logger.error("Container failed to become ready", /* @__PURE__ */ new Error(`Failed after ${attempt + 1} attempts over ${Math.floor(elapsed / 1e3)}s`));
-			}
-			return response;
+	const metadata = result.value;
+	if (!metadata) throw new Error("Failed to get file metadata");
+	if (metadata.isBinary) {
+		const totalLength = chunks.reduce((sum, chunk) => sum + (chunk instanceof Uint8Array ? chunk.length : 0), 0);
+		const combined = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of chunks) if (chunk instanceof Uint8Array) {
+			combined.set(chunk, offset);
+			offset += chunk.length;
 		}
-	}
-	/**
-	* Build a URL targeting the container's HTTP server.
-	*/
-	buildContainerUrl(path$1) {
-		if (this.config.stub) return `http://localhost:${this.config.port || 3e3}${path$1}`;
-		return `${this.config.baseUrl ?? `http://localhost:${this.config.port || 3e3}`}${path$1}`;
-	}
-	/**
-	* Single HTTP request to the container — no WebSocket, no 503 retry.
-	*/
-	httpFetch(path$1, options) {
-		const url = this.buildContainerUrl(path$1);
-		if (this.config.stub) return this.config.stub.containerFetch(url, options || {}, this.config.port);
-		return globalThis.fetch(url, options);
-	}
-	/**
-	* Streaming HTTP request to the container — no WebSocket, no 503 retry.
-	*/
-	async httpFetchStream(path$1, body, method = "POST", headers) {
-		const url = this.buildContainerUrl(path$1);
-		const init = {
-			method,
-			headers: body && method === "POST" ? {
-				...headers,
-				"Content-Type": "application/json"
-			} : headers,
-			body: body && method === "POST" ? JSON.stringify(body) : void 0
+		return {
+			content: combined,
+			metadata
 		};
-		let response;
-		if (this.config.stub) response = await this.config.stub.containerFetch(url, init, this.config.port);
-		else response = await globalThis.fetch(url, init);
-		if (!response.ok) {
-			const errorBody = await response.text();
-			throw new Error(`HTTP error! status: ${response.status} - ${errorBody}`);
-		}
-		if (!response.body) throw new Error("No response body for streaming");
-		return response.body;
-	}
-	/**
-	* Sleep utility for retry delays
-	*/
-	sleep(ms) {
-		return new Promise((resolve) => setTimeout(resolve, ms));
-	}
-};
+	} else return {
+		content: chunks.filter((c) => typeof c === "string").join(""),
+		metadata
+	};
+}
 
 //#endregion
-//#region src/clients/transport/http-transport.ts
+//#region src/security.ts
 /**
-* HTTP transport implementation
-*
-* Uses standard fetch API for communication with the container.
-* HTTP is stateless, so connect/disconnect are no-ops.
+* Security utilities for URL construction and input validation
 *
-* All HTTP request logic lives in {@link BaseTransport.httpFetch} and
-* {@link BaseTransport.httpFetchStream}; this subclass simply wires
-* the abstract `doFetch` / `fetchStream` hooks to those shared helpers.
+* This module contains critical security functions to prevent:
+* - URL injection attacks
+* - SSRF (Server-Side Request Forgery) attacks
+* - DNS rebinding attacks
+* - Host header injection
+* - Open redirect vulnerabilities
 */
-var HttpTransport = class extends BaseTransport {
-	getMode() {
-		return "http";
-	}
-	async connect() {}
-	disconnect() {}
-	isConnected() {
-		return true;
-	}
-	async doFetch(path$1, options) {
-		return this.httpFetch(path$1, options);
-	}
-	async fetchStream(path$1, body, method = "POST", headers) {
-		return this.httpFetchStream(path$1, body, method, headers);
+var SandboxSecurityError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "SandboxSecurityError";
 	}
 };
-
-//#endregion
-//#region src/clients/transport/ws-transport.ts
 /**
-* Default timeout values (all in milliseconds)
+* Validates port numbers for sandbox services.
+*
+* Rules:
+* - Range: 1024-65535 (privileged ports require root, which containers don't have)
+* - Reserved: 3000 (sandbox control plane)
+*/
+function validatePort(port) {
+	if (!Number.isInteger(port)) return false;
+	if (port < 1024 || port > 65535) return false;
+	if ([3e3].includes(port)) return false;
+	return true;
+}
+/**
+* Sanitizes and validates sandbox IDs for DNS compliance and security
+* Only enforces critical requirements - allows maximum developer flexibility
+*/
+function sanitizeSandboxId(id) {
+	if (!id || id.length > 63) throw new SandboxSecurityError("Sandbox ID must be 1-63 characters long.", "INVALID_SANDBOX_ID_LENGTH");
+	if (id.startsWith("-") || id.endsWith("-")) throw new SandboxSecurityError("Sandbox ID cannot start or end with hyphens (DNS requirement).", "INVALID_SANDBOX_ID_HYPHENS");
+	const reservedNames = [
+		"www",
+		"api",
+		"admin",
+		"root",
+		"system",
+		"cloudflare",
+		"workers"
+	];
+	const lowerCaseId = id.toLowerCase();
+	if (reservedNames.includes(lowerCaseId)) throw new SandboxSecurityError(`Reserved sandbox ID '${id}' is not allowed.`, "RESERVED_SANDBOX_ID");
+	return id;
+}
+/**
+* Validates language for code interpreter
+* Only allows supported languages
 */
-const DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
-const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
-const DEFAULT_CONNECT_TIMEOUT_MS$1 = 3e4;
-const DEFAULT_IDLE_DISCONNECT_MS$1 = 1e3;
-const MIN_TIME_FOR_CONNECT_RETRY_MS = 15e3;
+function validateLanguage(language) {
+	if (!language) return;
+	const supportedLanguages = [
+		"python",
+		"python3",
+		"javascript",
+		"js",
+		"node",
+		"typescript",
+		"ts"
+	];
+	const normalized = language.toLowerCase();
+	if (!supportedLanguages.includes(normalized)) throw new SandboxSecurityError(`Unsupported language '${language}'. Supported languages: python, javascript, typescript`, "INVALID_LANGUAGE");
+}
 /**
-* WebSocket transport implementation
+* Validates a single DNS label for use as a Cloudflare Tunnel hostname.
+*
+* Used by `sandbox.tunnels.get(port, { name })` to reject obviously-bad
+* input client-side before any network call. Whether the chosen label is
+* actually available under the configured zone is left to the Cloudflare
+* API (returned as a typed error).
+*
+* Rules:
+* - 1–63 characters
+* - Lowercase letters, digits, and internal hyphens only
+* - No leading or trailing hyphen
+* - No dots — multi-label hostnames need a delegated subdomain zone or
+*   Advanced Certificate Manager, which are out of scope for this
+*   feature. Universal SSL only covers `<label>.<zone>`.
 *
-* Multiplexes HTTP-like requests over a single WebSocket connection.
-* Useful when running inside Workers/DO where sub-request limits apply.
+* Throws `SandboxSecurityError` on any violation. Designed to be called
+* before any other tunnel work so callers see a fast, deterministic
+* failure.
 */
-var WebSocketTransport = class extends BaseTransport {
-	ws = null;
-	state = "disconnected";
-	pendingRequests = /* @__PURE__ */ new Map();
-	connectPromise = null;
-	idleDisconnectTimer = null;
-	boundHandleMessage;
-	boundHandleClose;
-	constructor(config) {
-		super(config);
-		if (!config.wsUrl) throw new Error("wsUrl is required for WebSocket transport");
-		this.boundHandleMessage = this.handleMessage.bind(this);
-		this.boundHandleClose = this.handleClose.bind(this);
-	}
-	getMode() {
-		return "websocket";
+const TUNNEL_NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function validateTunnelName(name) {
+	if (typeof name !== "string") throw new SandboxSecurityError(`Tunnel name must be a string. Received: ${typeof name}`, "INVALID_TUNNEL_NAME");
+	if (name.length === 0 || name.length > 63) throw new SandboxSecurityError(`Tunnel name '${name}' must be 1–63 characters long.`, "INVALID_TUNNEL_NAME_LENGTH");
+	if (!TUNNEL_NAME_REGEX.test(name)) throw new SandboxSecurityError(`Tunnel name '${name}' is not a valid DNS label. Use lowercase letters, digits, and internal hyphens only (no dots, no leading/trailing hyphens).`, "INVALID_TUNNEL_NAME_FORMAT");
+}
+
+//#endregion
+//#region src/interpreter.ts
+var CodeInterpreter = class {
+	getInterpreterClient;
+	contexts = /* @__PURE__ */ new Map();
+	constructor(interpreterClient) {
+		this.getInterpreterClient = typeof interpreterClient === "function" ? interpreterClient : () => interpreterClient;
 	}
 	/**
-	* Check if WebSocket is connected
+	* Create a new code execution context
 	*/
-	isConnected() {
-		return this.state === "connected" && this.ws?.readyState === WebSocket.OPEN;
+	async createCodeContext(options = {}) {
+		validateLanguage(options.language);
+		const context = await this.getInterpreterClient().createCodeContext(options);
+		this.contexts.set(context.id, context);
+		return context;
 	}
 	/**
-	* Connect to the WebSocket server
-	*
-	* The connection promise is assigned synchronously so concurrent
-	* callers share the same connection attempt.
+	* Run code with optional context
 	*/
-	async connect() {
-		this.clearIdleDisconnectTimer();
-		if (this.isConnected()) return;
-		if (this.connectPromise) return this.connectPromise;
-		this.connectPromise = this.doConnect();
-		try {
-			await this.connectPromise;
-		} finally {
-			this.connectPromise = null;
+	async runCode(code, options = {}) {
+		let context = options.context;
+		if (!context) {
+			const language = options.language || "python";
+			context = await this.getOrCreateDefaultContext(language);
 		}
+		const execution = new Execution(code, context);
+		await this.getInterpreterClient().runCodeStream(context.id, code, options.language, {
+			onStdout: (output) => {
+				execution.logs.stdout.push(output.text);
+				if (options.onStdout) return options.onStdout(output);
+			},
+			onStderr: (output) => {
+				execution.logs.stderr.push(output.text);
+				if (options.onStderr) return options.onStderr(output);
+			},
+			onResult: async (result) => {
+				execution.results.push(new ResultImpl(result));
+				if (options.onResult) return options.onResult(result);
+			},
+			onError: (error) => {
+				execution.error = error;
+				if (options.onError) return options.onError(error);
+			}
+		});
+		return execution;
 	}
 	/**
-	* Disconnect from the WebSocket server
+	* Run code and return a streaming response
 	*/
-	disconnect() {
-		this.cleanup();
+	async runCodeStream(code, options = {}) {
+		let context = options.context;
+		if (!context) {
+			const language = options.language || "python";
+			context = await this.getOrCreateDefaultContext(language);
+		}
+		return this.getInterpreterClient().streamCode(context.id, code, options.language);
 	}
 	/**
-	* Whether a WebSocket connection is currently being established.
-	*
-	* When true, awaiting `connectPromise` from a nested call would deadlock:
-	* the outer `connectViaFetch → stub.fetch → containerFetch →
-	* startAndWaitForPorts → blockConcurrencyWhile(onStart)` chain may call
-	* back into the SDK (e.g. `exec()`), which would await the same
-	* `connectPromise` that cannot resolve until `onStart` returns.
-	*
-	* Callers use this to fall back to a direct HTTP request, which is safe
-	* because `startAndWaitForPorts()` calls `setHealthy()` before invoking
-	* `onStart()`, so `containerFetch()` routes directly to the container.
+	* List all code contexts
 	*/
-	isWebSocketConnecting() {
-		return this.state === "connecting";
+	async listCodeContexts() {
+		const contexts = await this.getInterpreterClient().listCodeContexts();
+		for (const context of contexts) this.contexts.set(context.id, context);
+		return contexts;
 	}
 	/**
-	* Transport-specific fetch implementation.
-	* Converts WebSocket response to standard Response object.
-	*
-	* Falls back to HTTP while a WebSocket connection is being established
-	* to avoid the re-entrant deadlock described in `isWebSocketConnecting()`.
+	* Delete a code context
 	*/
-	async doFetch(path$1, options) {
-		if (this.isWebSocketConnecting()) return this.httpFetch(path$1, options);
-		await this.connect();
-		const method = options?.method || "GET";
-		const body = this.parseBody(options?.body);
-		const headers = this.normalizeHeaders(options?.headers);
-		const result = await this.request(method, path$1, body, headers, options?.requestTimeoutMs);
-		return new Response(JSON.stringify(result.body), {
-			status: result.status,
-			headers: { "Content-Type": "application/json" }
+	async deleteCodeContext(contextId) {
+		await this.getInterpreterClient().deleteCodeContext(contextId);
+		this.contexts.delete(contextId);
+	}
+	async getOrCreateDefaultContext(language) {
+		for (const context of this.contexts.values()) if (context.language === language) return context;
+		return this.createCodeContext({ language });
+	}
+};
+
+//#endregion
+//#region src/pty/proxy.ts
+async function proxyTerminal(stub, sessionId, request, options) {
+	if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId is required for terminal access");
+	if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") throw new Error("terminal() requires a WebSocket upgrade request");
+	const params = new URLSearchParams({ sessionId });
+	if (options?.cols) params.set("cols", String(options.cols));
+	if (options?.rows) params.set("rows", String(options.rows));
+	if (options?.shell) params.set("shell", options.shell);
+	const ptyUrl = `http://localhost/ws/pty?${params}`;
+	const ptyRequest = new Request(ptyUrl, request);
+	return stub.fetch(switchPort(ptyRequest, 3e3));
+}
+
+//#endregion
+//#region src/preview-proxy-protocol.ts
+/** @internal */
+const PREVIEW_PROXY_HEADER = "x-sandbox-preview-proxy";
+/** @internal */
+const PREVIEW_PROXY_PORT_HEADER = "x-sandbox-preview-port";
+/** @internal */
+const PREVIEW_PROXY_TOKEN_HEADER = "x-sandbox-preview-token";
+/** @internal */
+const PREVIEW_PROXY_SANDBOX_ID_HEADER = "x-sandbox-preview-sandbox-id";
+/** @internal */
+const PREVIEW_PROXY_HEADERS = [
+	PREVIEW_PROXY_HEADER,
+	PREVIEW_PROXY_PORT_HEADER,
+	PREVIEW_PROXY_TOKEN_HEADER,
+	PREVIEW_PROXY_SANDBOX_ID_HEADER
+];
+
+//#endregion
+//#region ../shared/src/backup.ts
+/**
+* Absolute directory prefixes supported by backup and restore operations.
+*/
+const BACKUP_ALLOWED_PREFIXES = [
+	"/workspace",
+	"/home",
+	"/tmp",
+	"/var/tmp",
+	"/app"
+];
+function normalizeBackupExcludePattern(pattern) {
+	let normalized = pattern;
+	while (normalized.startsWith("**/")) normalized = normalized.slice(3);
+	while (normalized.includes("/**/")) normalized = normalized.replace(/\/\*\*\//g, "/");
+	if (normalized.endsWith("/**")) normalized = normalized.slice(0, -3);
+	if (!normalized || normalized === "**") return null;
+	return normalized;
+}
+
+//#endregion
+//#region ../shared/src/internal.ts
+const DISABLE_SESSION_TOKEN = "__DISABLE_SESSION__";
+
+//#endregion
+//#region src/response-retry.ts
+const DEFAULT_INITIAL_RETRY_DELAY_MS = 3e3;
+const DEFAULT_MAX_RETRY_DELAY_MS = 3e4;
+const RETRYABLE_WEBSOCKET_UPGRADE_STATUSES = new Set([
+	500,
+	502,
+	503,
+	504
+]);
+function isRetryableWebSocketUpgradeResponse(response) {
+	return RETRYABLE_WEBSOCKET_UPGRADE_STATUSES.has(response.status);
+}
+/**
+* Retry Response-returning operations while their response remains retryable.
+* The retry budget covers the whole operation; each attempt owns any
+* per-request timeout inside the caller-provided `fetchResponse` function.
+*/
+async function fetchWithResponseRetry(fetchResponse, options) {
+	const startTime = Date.now();
+	let attempt = 0;
+	while (true) {
+		const response = await fetchResponse();
+		if (!options.shouldRetry(response)) return response;
+		const elapsed = Date.now() - startTime;
+		const remaining = options.retryTimeoutMs - elapsed;
+		if (remaining <= options.minTimeForRetryMs) {
+			options.onRetryExhausted?.({
+				attempts: attempt + 1,
+				elapsedMs: elapsed,
+				response
+			});
+			return response;
+		}
+		const delay = Math.min(DEFAULT_INITIAL_RETRY_DELAY_MS * 2 ** attempt, DEFAULT_MAX_RETRY_DELAY_MS);
+		options.logger.info(options.retryLogMessage, {
+			status: response.status,
+			attempt: attempt + 1,
+			delayMs: delay,
+			remainingSec: Math.floor(remaining / 1e3),
+			...options.getRetryLogContext?.(response)
 		});
+		await new Promise((resolve) => setTimeout(resolve, delay));
+		attempt++;
+	}
+}
+
+//#endregion
+//#region src/container-control/connection.ts
+const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
+const DEFAULT_RETRY_TIMEOUT_MS = 12e4;
+const MIN_TIME_FOR_RETRY_MS = 15e3;
+/**
+* Manages a capnweb WebSocket RPC session to the container.
+*
+* The RPC stub is created eagerly in the constructor using a deferred
+* transport. Calls made before `connect()` completes are queued in the
+* transport and flushed once the WebSocket is established.
+*/
+var ContainerControlConnection = class {
+	stub;
+	session;
+	transport;
+	ws = null;
+	connected = false;
+	connectPromise = null;
+	containerStub;
+	port;
+	logger;
+	retryTimeoutMs;
+	onClose;
+	constructor(options) {
+		this.containerStub = options.stub;
+		this.port = options.port ?? 3e3;
+		this.logger = options.logger ?? createNoOpLogger();
+		this.retryTimeoutMs = options.retryTimeoutMs ?? DEFAULT_RETRY_TIMEOUT_MS;
+		this.onClose = options.onClose;
+		this.transport = new DeferredTransport();
+		this.session = new RpcSession(this.transport, options.localMain);
+		this.stub = this.session.getRemoteMain();
 	}
 	/**
-	* Streaming fetch implementation.
+	* Get the typed RPC stub.
 	*
-	* Delegates to `requestStream()`, which applies the re-entrancy guard.
+	* The stub is available immediately — calls made before connect()
+	* completes are queued in the deferred transport and flushed once
+	* the WebSocket is established.
 	*/
-	async fetchStream(path$1, body, method = "POST", headers) {
-		return this.requestStream(method, path$1, body, headers);
+	rpc() {
+		if (!this.connected && !this.connectPromise) this.connect().catch(() => {});
+		return this.stub;
 	}
 	/**
-	* Parse request body from RequestInit
+	* Return capnweb session statistics. The `imports` and `exports` counts
+	* reflect all in-flight RPC calls, streams, and peer-held references.
+	* An idle session has imports <= 1 && exports <= 1 (the bootstrap stubs).
 	*/
-	parseBody(body) {
-		if (!body) return;
-		if (typeof body === "string") try {
-			return JSON.parse(body);
-		} catch (error) {
-			throw new Error(`Request body must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	getStats() {
+		return this.session.getStats();
+	}
+	isConnected() {
+		return this.connected;
+	}
+	async connect() {
+		if (this.connected) return;
+		if (this.connectPromise) return this.connectPromise;
+		this.connectPromise = this.doConnect();
+		try {
+			await this.connectPromise;
+		} finally {
+			this.connectPromise = null;
+		}
+	}
+	disconnect() {
+		try {
+			this.stub[Symbol.dispose]?.();
+		} catch {}
+		if (this.ws) {
+			this.ws.removeEventListener("close", this.onWebSocketClose);
+			this.ws.removeEventListener("error", this.onWebSocketError);
+			try {
+				this.ws.close();
+			} catch {}
+			this.ws = null;
 		}
-		throw new Error(`WebSocket transport only supports string bodies. Got: ${typeof body}`);
+		this.connected = false;
+		this.connectPromise = null;
 	}
 	/**
-	* Normalize RequestInit headers into a plain object for WSRequest.
+	* Update the upgrade retry budget without recreating the connection. Takes
+	* effect on the next `connect()`; an in-flight connect uses the value
+	* captured at start.
 	*/
-	normalizeHeaders(headers) {
-		if (!headers) return;
-		const normalized = {};
-		new Headers(headers).forEach((value, key) => {
-			normalized[key] = value;
-		});
-		return Object.keys(normalized).length > 0 ? normalized : void 0;
+	setRetryTimeoutMs(ms) {
+		this.retryTimeoutMs = ms;
 	}
 	/**
-	* Internal connection logic
+	* Run the owner-provided `onClose` callback exactly once per call,
+	* swallowing any errors so a buggy listener can't keep the connection
+	* object in a half-torn-down state.
 	*/
-	async doConnect() {
-		this.state = "connecting";
-		if (this.config.stub) await this.connectViaFetch();
-		else await this.connectViaWebSocket();
-	}
-	async fetchUpgradeWithRetry(attemptUpgrade) {
-		const retryTimeoutMs = this.getRetryTimeoutMs();
-		const startTime = Date.now();
-		let attempt = 0;
-		while (true) {
-			const response = await attemptUpgrade();
-			if (response.status !== 503) return response;
-			const remaining = retryTimeoutMs - (Date.now() - startTime);
-			if (remaining <= MIN_TIME_FOR_CONNECT_RETRY_MS) return response;
-			const delay = Math.min(3e3 * 2 ** attempt, 3e4);
-			this.logger.info("WebSocket container not ready, retrying", {
-				status: response.status,
-				attempt: attempt + 1,
-				delayMs: delay,
-				remainingSec: Math.floor(remaining / 1e3)
-			});
-			await this.sleep(delay);
-			attempt++;
+	fireOnClose() {
+		if (!this.onClose) return;
+		try {
+			this.onClose();
+		} catch (err) {
+			this.logger.warn("ContainerControlConnection onClose handler threw", { error: err instanceof Error ? err.message : String(err) });
 		}
 	}
 	/**
-	* Connect using fetch-based WebSocket (Cloudflare Workers style)
-	* This is required when running inside a Durable Object.
-	*
-	* Uses stub.fetch() which routes WebSocket upgrade requests through the
-	* parent Container class that supports the WebSocket protocol.
+	* WebSocket `close` listener. Defined as a bound arrow field so the
+	* same reference can be passed to both `addEventListener` and
+	* `removeEventListener` — a fresh anonymous lambda would silently
+	* fail to unbind.
 	*/
-	async connectViaFetch() {
-		const timeoutMs = this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS$1;
+	onWebSocketClose = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		this.logger.debug("ContainerControlConnection WebSocket closed");
+		if (wasConnected) this.fireOnClose();
+	};
+	/**
+	* WebSocket `error` listener. Same field-form rationale as
+	* {@link onWebSocketClose}.
+	*/
+	onWebSocketError = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		if (wasConnected) this.fireOnClose();
+	};
+	async doConnect() {
 		try {
-			const wsPath = new URL(this.config.wsUrl).pathname;
-			const httpUrl = `http://localhost:${this.config.port || 3e3}${wsPath}`;
-			const response = await this.fetchUpgradeWithRetry(() => this.fetchUpgradeAttempt(httpUrl, timeoutMs));
+			const response = await this.fetchUpgradeWithRetry();
 			if (response.status !== 101) throw new Error(`WebSocket upgrade failed: ${response.status} ${response.statusText}`);
 			const ws = response.webSocket;
 			if (!ws) throw new Error("No WebSocket in upgrade response");
 			ws.accept();
+			ws.addEventListener("close", this.onWebSocketClose);
+			ws.addEventListener("error", this.onWebSocketError);
 			this.ws = ws;
-			this.state = "connected";
-			this.ws.addEventListener("close", this.boundHandleClose);
-			this.ws.addEventListener("message", this.boundHandleMessage);
-			this.logger.debug("WebSocket connected via fetch", { url: this.config.wsUrl });
+			this.transport.activate(ws);
+			this.connected = true;
+			this.logger.debug("ContainerControlConnection established", { port: this.port });
 		} catch (error) {
-			this.state = "error";
-			this.logger.error("WebSocket fetch connection failed", error instanceof Error ? error : new Error(String(error)));
+			this.connected = false;
+			this.transport.abort(error);
+			this.logger.error("ContainerControlConnection failed", error instanceof Error ? error : new Error(String(error)));
+			this.fireOnClose();
 			throw error;
 		}
 	}
-	async fetchUpgradeAttempt(httpUrl, timeoutMs) {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), timeoutMs);
-		try {
-			const request = new Request(httpUrl, {
-				headers: {
-					Upgrade: "websocket",
-					Connection: "Upgrade"
-				},
-				signal: controller.signal
-			});
-			return await this.config.stub.fetch(request);
-		} finally {
-			clearTimeout(timeout);
-		}
-	}
 	/**
-	* Connect using standard WebSocket API (browser/Node style)
+	* Issue WebSocket upgrade fetches, retrying transient control-plane
+	* unavailability responses until either the upgrade succeeds, a
+	* non-retryable status is returned, or the retry budget runs out.
 	*/
-	connectViaWebSocket() {
-		return new Promise((resolve, reject) => {
-			const timeoutMs = this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS$1;
-			const timeout = setTimeout(() => {
-				this.cleanup();
-				reject(/* @__PURE__ */ new Error(`WebSocket connection timeout after ${timeoutMs}ms`));
-			}, timeoutMs);
-			try {
-				this.ws = new WebSocket(this.config.wsUrl);
-				const onOpen = () => {
-					clearTimeout(timeout);
-					this.ws?.removeEventListener("open", onOpen);
-					this.ws?.removeEventListener("error", onConnectError);
-					this.state = "connected";
-					this.logger.debug("WebSocket connected", { url: this.config.wsUrl });
-					resolve();
-				};
-				const onConnectError = () => {
-					clearTimeout(timeout);
-					this.ws?.removeEventListener("open", onOpen);
-					this.ws?.removeEventListener("error", onConnectError);
-					this.state = "error";
-					this.logger.error("WebSocket error", /* @__PURE__ */ new Error("WebSocket connection failed"));
-					reject(/* @__PURE__ */ new Error("WebSocket connection failed"));
-				};
-				this.ws.addEventListener("open", onOpen);
-				this.ws.addEventListener("error", onConnectError);
-				this.ws.addEventListener("close", this.boundHandleClose);
-				this.ws.addEventListener("message", this.boundHandleMessage);
-			} catch (error) {
-				clearTimeout(timeout);
-				this.state = "error";
-				reject(error);
-			}
+	async fetchUpgradeWithRetry() {
+		return fetchWithResponseRetry(() => this.fetchUpgradeAttempt(), {
+			retryTimeoutMs: this.retryTimeoutMs,
+			minTimeForRetryMs: MIN_TIME_FOR_RETRY_MS,
+			logger: this.logger,
+			retryLogMessage: "ContainerControlConnection upgrade returned retryable status, retrying",
+			shouldRetry: isRetryableWebSocketUpgradeResponse
 		});
 	}
 	/**
-	* Send a request and wait for response.
-	*
-	* Only reachable from `doFetch()`, which already applies the re-entrancy
-	* guard via `isWebSocketConnecting()`. The `connect()` call here handles
-	* the case where the WebSocket was closed between `doFetch` and `request`
-	* (idle disconnect).
+	* Single WebSocket-upgrade fetch attempt. Owns its own AbortController so
+	* each retry gets a fresh per-attempt connect timeout independent of the
+	* total retry budget.
 	*/
-	async request(method, path$1, body, headers, requestTimeoutMs) {
-		await this.connect();
-		this.clearIdleDisconnectTimer();
-		const id = generateRequestId();
-		const request = {
-			type: "request",
-			id,
-			method,
-			path: path$1,
-			body,
-			headers
-		};
-		return new Promise((resolve, reject) => {
-			const timeoutMs = requestTimeoutMs ?? this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-			const timeoutId = setTimeout(() => {
-				this.pendingRequests.delete(id);
-				this.scheduleIdleDisconnect();
-				reject(/* @__PURE__ */ new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path$1}`));
-			}, timeoutMs);
-			this.pendingRequests.set(id, {
-				resolve: (response) => {
-					clearTimeout(timeoutId);
-					this.pendingRequests.delete(id);
-					this.scheduleIdleDisconnect();
-					resolve({
-						status: response.status,
-						body: response.body
-					});
-				},
-				reject: (error) => {
-					clearTimeout(timeoutId);
-					this.pendingRequests.delete(id);
-					this.scheduleIdleDisconnect();
-					reject(error);
+	async fetchUpgradeAttempt() {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), DEFAULT_CONNECT_TIMEOUT_MS);
+		try {
+			const url = `http://localhost:${this.port}/rpc`;
+			const request = new Request(url, {
+				headers: {
+					Upgrade: "websocket",
+					Connection: "Upgrade"
 				},
-				isStreaming: false,
-				timeoutId
+				signal: controller.signal
 			});
-			try {
-				this.send(request);
-			} catch (error) {
-				clearTimeout(timeoutId);
-				this.pendingRequests.delete(id);
-				this.scheduleIdleDisconnect();
-				reject(error instanceof Error ? error : new Error(String(error)));
-			}
-		});
+			return await this.containerStub.fetch(request);
+		} finally {
+			clearTimeout(timeout);
+		}
 	}
-	/**
-	* Send a streaming request and return a ReadableStream.
-	*
-	* The stream will receive data chunks as they arrive over the WebSocket.
-	* Format matches SSE for compatibility with existing streaming code.
-	*
-	* This method waits for the first message before returning. If the server
-	* responds with an error (non-streaming response), it throws immediately
-	* rather than returning a stream that will error later.
-	*
-	* Uses an inactivity timeout instead of a total-duration timeout so that
-	* long-running streams (e.g. execStream from an agent) stay alive as long
-	* as data is flowing. The timer resets on every chunk or response message.
-	*
-	* Falls back to HTTP while a WebSocket connection is being established
-	* to avoid the re-entrant deadlock described in `isWebSocketConnecting()`.
-	*/
-	async requestStream(method, path$1, body, headers) {
-		if (this.isWebSocketConnecting()) return this.httpFetchStream(path$1, body, method, headers);
-		await this.connect();
-		this.clearIdleDisconnectTimer();
-		const id = generateRequestId();
-		const request = {
-			type: "request",
-			id,
-			method,
-			path: path$1,
-			body,
-			headers
-		};
-		const idleTimeoutMs = this.config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
-		return new Promise((resolveStream, rejectStream) => {
-			let streamController;
-			let firstMessageReceived = false;
-			const createIdleTimeout = () => {
-				return setTimeout(() => {
-					this.pendingRequests.delete(id);
-					this.scheduleIdleDisconnect();
-					const error = /* @__PURE__ */ new Error(`Stream idle timeout after ${idleTimeoutMs}ms: ${method} ${path$1}`);
-					if (firstMessageReceived) try {
-						streamController?.error(error);
-					} catch {}
-					else rejectStream(error);
-				}, idleTimeoutMs);
-			};
-			const timeoutId = createIdleTimeout();
-			const stream = new ReadableStream({
-				start: (controller) => {
-					streamController = controller;
-				},
-				cancel: () => {
-					const pending = this.pendingRequests.get(id);
-					if (pending?.timeoutId) clearTimeout(pending.timeoutId);
-					try {
-						this.send({
-							type: "cancel",
-							id
-						});
-					} catch (error) {
-						this.logger.debug("Failed to send stream cancel message", {
-							id,
-							error: error instanceof Error ? error.message : String(error)
-						});
-					}
-					this.pendingRequests.delete(id);
-					this.scheduleIdleDisconnect();
-				}
-			});
-			this.pendingRequests.set(id, {
-				resolve: (response) => {
-					const pending = this.pendingRequests.get(id);
-					if (pending?.timeoutId) clearTimeout(pending.timeoutId);
-					this.pendingRequests.delete(id);
-					this.scheduleIdleDisconnect();
-					if (!firstMessageReceived) {
-						firstMessageReceived = true;
-						if (response.status >= 400) rejectStream(/* @__PURE__ */ new Error(`Stream error: ${response.status} - ${JSON.stringify(response.body)}`));
-						else {
-							streamController?.close();
-							resolveStream(stream);
-						}
-					} else if (response.status >= 400) try {
-						streamController?.error(/* @__PURE__ */ new Error(`Stream error: ${response.status} - ${JSON.stringify(response.body)}`));
-					} catch {}
-					else streamController?.close();
-				},
-				reject: (error) => {
-					const pending = this.pendingRequests.get(id);
-					if (pending?.timeoutId) clearTimeout(pending.timeoutId);
-					this.pendingRequests.delete(id);
-					this.scheduleIdleDisconnect();
-					if (firstMessageReceived) try {
-						streamController?.error(error);
-					} catch {}
-					else rejectStream(error);
-				},
-				streamController: void 0,
-				isStreaming: true,
-				timeoutId,
-				onFirstChunk: () => {
-					if (!firstMessageReceived) {
-						firstMessageReceived = true;
-						const pending = this.pendingRequests.get(id);
-						if (pending) {
-							pending.streamController = streamController;
-							if (pending.bufferedChunks) {
-								try {
-									for (const buffered of pending.bufferedChunks) streamController.enqueue(buffered);
-								} catch (error) {
-									this.logger.debug("Failed to flush buffered chunks, cleaning up", {
-										id,
-										error: error instanceof Error ? error.message : String(error)
-									});
-									if (pending.timeoutId) clearTimeout(pending.timeoutId);
-									this.pendingRequests.delete(id);
-									this.scheduleIdleDisconnect();
-								}
-								pending.bufferedChunks = void 0;
-							}
-						}
-						resolveStream(stream);
-					}
-				}
-			});
-			try {
-				this.send(request);
-			} catch (error) {
-				clearTimeout(timeoutId);
-				this.pendingRequests.delete(id);
-				this.scheduleIdleDisconnect();
-				rejectStream(error instanceof Error ? error : new Error(String(error)));
-			}
+};
+/**
+* RPC transport that queues sends and blocks receives until a WebSocket
+* is provided via `activate()`. Allows the RPC stub to be created before
+* the connection is established — queued calls flush automatically.
+*/
+var DeferredTransport = class {
+	#ws = null;
+	#sendQueue = [];
+	#receiveQueue = [];
+	#receiveResolver;
+	#receiveRejecter;
+	#error;
+	activate(ws) {
+		this.#ws = ws;
+		ws.addEventListener("message", (event) => {
+			if (this.#error) return;
+			if (typeof event.data === "string") if (this.#receiveResolver) {
+				this.#receiveResolver(event.data);
+				this.#receiveResolver = void 0;
+				this.#receiveRejecter = void 0;
+			} else this.#receiveQueue.push(event.data);
+			else this.#fail(/* @__PURE__ */ new TypeError("Received non-string message from WebSocket."));
 		});
-	}
-	/**
-	* Send a message over the WebSocket
-	*/
-	send(message) {
-		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) throw new Error("WebSocket not connected");
-		this.ws.send(JSON.stringify(message));
-		this.logger.debug("WebSocket sent", {
-			id: message.id,
-			type: message.type,
-			method: message.type === "request" ? message.method : void 0,
-			path: message.type === "request" ? message.path : void 0
+		ws.addEventListener("close", (event) => {
+			this.#fail(/* @__PURE__ */ new Error(`Peer closed WebSocket: ${event.code} ${event.reason}`));
 		});
-	}
-	/**
-	* Handle incoming WebSocket messages
-	*/
-	handleMessage(event) {
-		try {
-			const message = JSON.parse(event.data);
-			if (isWSResponse(message)) this.handleResponse(message);
-			else if (isWSStreamChunk(message)) this.handleStreamChunk(message);
-			else if (isWSError(message)) this.handleError(message);
-			else this.logger.warn("Unknown WebSocket message type", { message });
-		} catch (error) {
-			this.logger.error("Failed to parse WebSocket message", error instanceof Error ? error : new Error(String(error)));
-		}
-	}
-	/**
-	* Handle a response message
-	*/
-	handleResponse(response) {
-		const pending = this.pendingRequests.get(response.id);
-		if (!pending) {
-			this.logger.warn("Received response for unknown request", { id: response.id });
-			return;
-		}
-		this.logger.debug("WebSocket response", {
-			id: response.id,
-			status: response.status,
-			done: response.done
+		ws.addEventListener("error", () => {
+			this.#fail(/* @__PURE__ */ new Error("WebSocket connection failed."));
 		});
-		if (response.done) pending.resolve(response);
-	}
-	/**
-	* Handle a stream chunk message
-	*
-	* Resets the idle timeout on every chunk so that long-running streams
-	* with continuous output are not killed by the inactivity timer.
-	*/
-	handleStreamChunk(chunk) {
-		const pending = this.pendingRequests.get(chunk.id);
-		if (!pending) {
-			this.logger.warn("Received stream chunk for unknown request", { id: chunk.id });
-			return;
-		}
-		if (pending.onFirstChunk) {
-			pending.onFirstChunk();
-			pending.onFirstChunk = void 0;
-		}
-		if (pending.isStreaming) this.resetStreamIdleTimeout(chunk.id, pending);
-		if (!pending.streamController) {
-			if (!pending.bufferedChunks) pending.bufferedChunks = [];
-			const encoder$1 = new TextEncoder();
-			let sseData$1;
-			if (chunk.event) sseData$1 = `event: ${chunk.event}\ndata: ${chunk.data}\n\n`;
-			else sseData$1 = `data: ${chunk.data}\n\n`;
-			pending.bufferedChunks.push(encoder$1.encode(sseData$1));
-			return;
-		}
-		const encoder = new TextEncoder();
-		let sseData;
-		if (chunk.event) sseData = `event: ${chunk.event}\ndata: ${chunk.data}\n\n`;
-		else sseData = `data: ${chunk.data}\n\n`;
-		try {
-			pending.streamController.enqueue(encoder.encode(sseData));
-		} catch (error) {
-			this.logger.debug("Failed to enqueue stream chunk, cleaning up", {
-				id: chunk.id,
-				error: error instanceof Error ? error.message : String(error)
-			});
-			if (pending.timeoutId) clearTimeout(pending.timeoutId);
-			this.pendingRequests.delete(chunk.id);
-			this.scheduleIdleDisconnect();
-		}
+		for (const msg of this.#sendQueue) ws.send(msg);
+		this.#sendQueue = [];
 	}
-	/**
-	* Reset the idle timeout for a streaming request.
-	* Called on every incoming chunk to keep the stream alive while data flows.
-	*/
-	resetStreamIdleTimeout(id, pending) {
-		if (pending.timeoutId) clearTimeout(pending.timeoutId);
-		const idleTimeoutMs = this.config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
-		pending.timeoutId = setTimeout(() => {
-			this.pendingRequests.delete(id);
-			this.scheduleIdleDisconnect();
-			if (pending.streamController) try {
-				pending.streamController.error(/* @__PURE__ */ new Error(`Stream idle timeout after ${idleTimeoutMs}ms`));
-			} catch {}
-		}, idleTimeoutMs);
+	async send(message) {
+		if (this.#ws) this.#ws.send(message);
+		else this.#sendQueue.push(message);
 	}
-	/**
-	* Handle an error message
-	*/
-	handleError(error) {
-		if (error.id) {
-			const pending = this.pendingRequests.get(error.id);
-			if (pending) {
-				pending.reject(/* @__PURE__ */ new Error(`${error.code}: ${error.message}`));
-				return;
-			}
-		}
-		this.logger.error("WebSocket error message", new Error(error.message), {
-			code: error.code,
-			status: error.status
+	async receive() {
+		if (this.#receiveQueue.length > 0) return this.#receiveQueue.shift();
+		if (this.#error) throw this.#error;
+		return new Promise((resolve, reject) => {
+			this.#receiveResolver = resolve;
+			this.#receiveRejecter = reject;
 		});
 	}
-	/**
-	* Handle WebSocket close
-	*/
-	handleClose(event) {
-		this.state = "disconnected";
-		this.ws = null;
-		this.connectPromise = null;
-		const closeError = /* @__PURE__ */ new Error(`WebSocket closed: ${event.code} ${event.reason || "No reason"}`);
-		for (const [, pending] of this.pendingRequests) {
-			if (pending.timeoutId) clearTimeout(pending.timeoutId);
-			if (pending.streamController) try {
-				pending.streamController.error(closeError);
-			} catch {}
-			pending.reject(closeError);
-		}
-		this.pendingRequests.clear();
-	}
-	/**
-	* Cleanup resources
-	*/
-	cleanup() {
-		this.clearIdleDisconnectTimer();
-		if (this.ws) {
-			this.ws.removeEventListener("close", this.boundHandleClose);
-			this.ws.removeEventListener("message", this.boundHandleMessage);
-			this.ws.close();
-			this.ws = null;
+	abort(reason) {
+		this.#fail(reason instanceof Error ? reason : new Error(String(reason)));
+		if (this.#ws) {
+			const message = reason instanceof Error ? reason.message : String(reason);
+			this.#ws.close(3e3, message);
 		}
-		this.state = "disconnected";
-		this.connectPromise = null;
-		for (const pending of this.pendingRequests.values()) if (pending.timeoutId) clearTimeout(pending.timeoutId);
-		this.pendingRequests.clear();
 	}
-	scheduleIdleDisconnect() {
-		if (!this.isConnected() || this.pendingRequests.size > 0) return;
-		this.clearIdleDisconnectTimer();
-		this.idleDisconnectTimer = setTimeout(() => {
-			this.idleDisconnectTimer = null;
-			if (this.pendingRequests.size === 0 && this.isConnected()) {
-				this.logger.debug("Disconnecting idle WebSocket transport");
-				this.cleanup();
-			}
-		}, DEFAULT_IDLE_DISCONNECT_MS$1);
-	}
-	clearIdleDisconnectTimer() {
-		if (this.idleDisconnectTimer) {
-			clearTimeout(this.idleDisconnectTimer);
-			this.idleDisconnectTimer = null;
-		}
+	#fail(err) {
+		if (this.#error) return;
+		this.#error = err;
+		this.#receiveRejecter?.(err);
+		this.#receiveResolver = void 0;
+		this.#receiveRejecter = void 0;
 	}
 };
 
 //#endregion
-//#region src/clients/transport/factory.ts
+//#region src/container-control/client.ts
+/** Close the idle capnweb WebSocket promptly so the DO can sleep. */
+const DEFAULT_IDLE_DISCONNECT_MS = 1e3;
 /**
-* Create a route-based compatibility transport instance based on mode.
+* How often the busy/idle poller samples `getStats()`.
 *
-* Selects the HTTP or custom WebSocket transport for the route-based client
-* layer.
+* Sets two worst-case bounds:
 *
-* @example
-* ```typescript
-* // HTTP transport (default)
-* const http = createTransport({
-*   mode: 'http',
-*   baseUrl: 'http://localhost:3000'
-* });
+*   1. **Idle-detection lag.** Time between the session going idle on
+*      the wire and the DO observing it (and arming the disconnect).
+*      Bounded by `pollInterval`.
+*   2. **Activity-renewal lag while busy.** While a stream is active we
+*      renew the DO's activity timeout once per tick. The alarm could
+*      fire as late as `sleepAfter` after the last renew, so the
+*      effective margin against a mid-stream sleep is
+*      `sleepAfter - pollInterval`.
 *
-* // WebSocket transport
-* const ws = createTransport({
-*   mode: 'websocket',
-*   wsUrl: 'ws://localhost:3000/ws'
-* });
-* ```
+* **Invariant: `pollInterval` must be comfortably less than the
+* smallest configurable `sleepAfter`.** Aim for at least 2-3× headroom.
+* The minimum `sleepAfter` exercised by the E2E suite is 3s, so 1s gives
+* 3× margin and at least two renewals during a 3s window. If a smaller
+* `sleepAfter` is ever supported, drop this proportionally.
 */
-function createTransport(options) {
-	switch (options.mode) {
-		case "http": return new HttpTransport(options);
-		case "websocket": return new WebSocketTransport(options);
-	}
-}
-
-//#endregion
-//#region src/clients/base-client.ts
+const BUSY_POLL_INTERVAL_MS = 1e3;
+/**
+* Baseline getStats() values for an idle session. The bootstrap stub on each
+* side accounts for 1 import and 1 export.
+*/
+const IDLE_IMPORT_THRESHOLD = 1;
+const IDLE_EXPORT_THRESHOLD = 1;
 /**
-* Abstract base class for route-based HTTP/WebSocket compatibility clients.
+* Translate a capnweb-propagated error into a typed SandboxError.
+*
+* Two wire formats are supported for backward compatibility with older
+* container images:
 *
-* Requests go through the Transport abstraction layer, which handles:
-* - HTTP and WebSocket route-based modes transparently
-* - Automatic retry for 503 errors while the container is starting
-* - Streaming responses for the existing route API
+*  1. Propagated error properties (capnweb >= 0.8.0). The container throws a
+*     `ServiceError`-shaped object with own enumerable `code` and `details`
+*     properties. capnweb walks `Object.keys()` and reconstructs those fields
+*     on the SDK side.
+*  2. Legacy JSON-encoded message. Older containers encoded the structured
+*     payload as a JSON string in `error.message`.
 *
-* DO-to-container control-channel capabilities live in `container-control/`.
-* This layer supports the route-based compatibility API.
+* The JSON-fallback branch can be removed once all older container images are
+* no longer in service.
 */
-var BaseHttpClient = class {
-	options;
-	logger;
-	transport;
-	constructor(options = {}) {
-		this.options = options;
-		this.logger = options.logger ?? createNoOpLogger();
-		if (options.transport) this.transport = options.transport;
-		else this.transport = createTransport({
-			mode: options.transportMode ?? "http",
-			baseUrl: options.baseUrl ?? "http://localhost:3000",
-			wsUrl: options.wsUrl,
-			logger: this.logger,
-			stub: options.stub,
-			port: options.port,
-			retryTimeoutMs: options.retryTimeoutMs
+function translateRPCError(error) {
+	if (error instanceof Error) {
+		const propagated = error;
+		if (typeof propagated.code === "string" && Object.hasOwn(ErrorCode, propagated.code)) {
+			const code = propagated.code;
+			const context = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
+			throw createErrorFromResponse({
+				code,
+				message: error.message,
+				context,
+				httpStatus: getHttpStatus(code),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		let payload;
+		try {
+			payload = JSON.parse(error.message);
+		} catch {}
+		if (payload && typeof payload.code === "string" && typeof payload.message === "string") throw createErrorFromResponse({
+			code: payload.code,
+			message: payload.message,
+			context: payload.context ?? {},
+			httpStatus: getHttpStatus(payload.code),
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
+		throw createErrorFromResponse(buildTransportErrorResponse(error), { cause: error });
 	}
-	/**
-	* Update the transport's 503 retry budget
-	*/
-	setRetryTimeoutMs(ms) {
-		this.transport.setRetryTimeoutMs(ms);
-	}
-	/**
-	* Check if using WebSocket transport
-	*/
-	isWebSocketMode() {
-		return this.transport.getMode() === "websocket";
-	}
-	/**
-	* Core fetch method - delegates to Transport which handles retry logic
-	*/
-	async doFetch(path$1, options) {
-		const { defaultHeaders } = this.options;
-		if (defaultHeaders) options = {
-			...options,
-			headers: {
-				...defaultHeaders,
-				...options?.headers
-			}
-		};
-		return this.transport.fetch(path$1, options);
-	}
-	/**
-	* Make a POST request with JSON body
-	*/
-	async post(endpoint, data, responseHandler, requestOptions) {
-		const response = await this.doFetch(endpoint, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify(data),
-			...requestOptions
-		});
-		return await this.handleResponse(response, responseHandler);
-	}
-	/**
-	* Make a GET request
-	*/
-	async get(endpoint, responseHandler) {
-		const response = await this.doFetch(endpoint, { method: "GET" });
-		return await this.handleResponse(response, responseHandler);
-	}
-	/**
-	* Make a DELETE request
-	*/
-	async delete(endpoint, responseHandler) {
-		const response = await this.doFetch(endpoint, { method: "DELETE" });
-		return await this.handleResponse(response, responseHandler);
-	}
-	/**
-	* Handle HTTP response with error checking and parsing
-	*/
-	async handleResponse(response, customHandler) {
-		if (!response.ok) await this.handleErrorResponse(response);
-		if (customHandler) return customHandler(response);
-		try {
-			return await response.json();
-		} catch (error) {
-			throw createErrorFromResponse({
-				code: ErrorCode.INVALID_JSON_RESPONSE,
-				message: `Invalid JSON response: ${error instanceof Error ? error.message : "Unknown parsing error"}`,
-				context: {},
-				httpStatus: response.status,
-				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			});
-		}
-	}
-	/**
-	* Handle error responses with consistent error throwing
-	*/
-	async handleErrorResponse(response) {
-		let errorData;
-		try {
-			errorData = await response.json();
-		} catch {
-			errorData = {
-				code: ErrorCode.INTERNAL_ERROR,
-				message: `HTTP error! status: ${response.status}`,
-				context: { statusText: response.statusText },
-				httpStatus: response.status,
-				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			};
-		}
-		const error = createErrorFromResponse(errorData);
-		this.options.onError?.(errorData.message, void 0);
-		throw error;
-	}
-	/**
-	* Create a streaming response handler for Server-Sent Events
-	*/
-	async handleStreamResponse(response) {
-		if (!response.ok) await this.handleErrorResponse(response);
-		if (!response.body) throw new Error("No response body for streaming");
-		return response.body;
-	}
-	/**
-	* Stream request handler
-	*
-	* HTTP mode uses doFetch + handleStreamResponse for typed error handling.
-	* For WebSocket mode, uses Transport's streaming support.
-	*
-	* @param path - The API path to call
-	* @param body - Optional request body (for POST requests)
-	* @param method - HTTP method (default: POST, use GET for process logs)
-	*/
-	async doStreamFetch(path$1, body, method = "POST") {
-		const streamHeaders = method === "POST" ? {
-			...this.options.defaultHeaders,
-			"Content-Type": "application/json"
-		} : this.options.defaultHeaders;
-		if (this.transport.getMode() === "websocket") return this.transport.fetchStream(path$1, body, method, streamHeaders);
-		const response = await this.doFetch(path$1, {
-			method,
-			headers: { "Content-Type": "application/json" },
-			body: body && method === "POST" ? JSON.stringify(body) : void 0
-		});
-		return await this.handleStreamResponse(response);
-	}
-};
-
-//#endregion
-//#region src/clients/backup-client.ts
-/**
-* Client for backup operations.
-*
-* Handles communication with the container's backup endpoints.
-* The container creates/extracts squashfs archives locally.
-* R2 upload/download is handled by the Sandbox DO, not by this client.
-*/
-var BackupClient = class extends BaseHttpClient {
-	/**
-	* Tell the container to create a squashfs archive from a directory.
-	* @param dir - Directory to back up
-	* @param archivePath - Where the container should write the archive
-	* @param sessionId - Session context
-	*/
-	async createArchive(dir, archivePath, sessionId, options) {
-		const data = {
-			dir,
-			archivePath,
-			gitignore: options?.gitignore ?? false,
-			excludes: options?.excludes ?? [],
-			compression: options?.compression,
-			sessionId
-		};
-		return await this.post("/api/backup/create", data);
-	}
-	/**
-	* Tell the container to restore a squashfs archive into a directory.
-	* @param dir - Target directory
-	* @param archivePath - Path to the archive file in the container
-	* @param sessionId - Session context
-	*/
-	async restoreArchive(dir, archivePath, sessionId) {
-		const data = {
-			dir,
-			archivePath,
-			sessionId
-		};
-		return await this.post("/api/backup/restore", data);
-	}
-	async uploadParts(request, sessionId) {
-		return this.post("/api/backup/upload-parts", {
-			...request,
-			sessionId: sessionId ?? request.sessionId
-		});
-	}
-};
-
-//#endregion
-//#region src/clients/command-client.ts
-/**
-* Client for command execution operations
-*/
-var CommandClient = class extends BaseHttpClient {
-	/**
-	* Execute a command and return the complete result
-	* @param command - The command to execute
-	* @param sessionId - The session ID for this command execution
-	* @param timeoutMs - Optional timeout in milliseconds (unlimited by default)
-	* @param env - Optional environment variables for this command
-	* @param cwd - Optional working directory for this command
-	*/
-	async execute(command, sessionId, options) {
-		try {
-			const data = {
-				command,
-				sessionId,
-				...options?.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
-				...options?.env !== void 0 && { env: options.env },
-				...options?.cwd !== void 0 && { cwd: options.cwd },
-				...options?.origin !== void 0 && { origin: options.origin }
-			};
-			const response = await this.post("/api/execute", data);
-			this.options.onCommandComplete?.(response.success, response.exitCode, response.stdout, response.stderr, response.command);
-			return response;
-		} catch (error) {
-			this.options.onError?.(error instanceof Error ? error.message : String(error), command);
-			throw error;
-		}
-	}
-	/**
-	* Execute a command and return a stream of events
-	* @param command - The command to execute
-	* @param sessionId - The session ID for this command execution
-	* @param options - Optional per-command execution settings
-	*/
-	async executeStream(command, sessionId, options) {
-		try {
-			const data = {
-				command,
-				sessionId,
-				...options?.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
-				...options?.env !== void 0 && { env: options.env },
-				...options?.cwd !== void 0 && { cwd: options.cwd },
-				...options?.origin !== void 0 && { origin: options.origin }
-			};
-			return await this.doStreamFetch("/api/execute/stream", data);
-		} catch (error) {
-			this.options.onError?.(error instanceof Error ? error.message : String(error), command);
-			throw error;
-		}
-	}
-};
-
-//#endregion
-//#region src/clients/file-client.ts
-/**
-* Client for file system operations
-*/
-var FileClient = class extends BaseHttpClient {
-	/**
-	* Create a directory
-	* @param path - Directory path to create
-	* @param sessionId - The session ID for this operation
-	* @param options - Optional settings (recursive)
-	*/
-	async mkdir(path$1, sessionId, options) {
-		const data = {
-			path: path$1,
-			sessionId,
-			recursive: options?.recursive ?? false
-		};
-		return await this.post("/api/mkdir", data);
-	}
-	/**
-	* Write content to a file
-	* @param path - File path to write to
-	* @param content - Content to write
-	* @param sessionId - The session ID for this operation
-	* @param options - Optional settings (encoding)
-	*/
-	async writeFile(path$1, content, sessionId, options) {
-		const data = {
-			path: path$1,
-			content,
-			sessionId,
-			encoding: options?.encoding
-		};
-		return await this.post("/api/write", data);
-	}
-	async readFile(path$1, sessionId, options) {
-		if (options?.encoding === "none") throw new Error("readFile with encoding: 'none' requires the rpc transport. Set SANDBOX_TRANSPORT=rpc.");
-		const data = {
-			path: path$1,
-			sessionId,
-			encoding: options?.encoding
-		};
-		return await this.post("/api/read", data);
-	}
-	/**
-	* Stream a file using Server-Sent Events
-	* Returns a ReadableStream of SSE events containing metadata, chunks, and completion
-	* @param path - File path to stream
-	* @param sessionId - The session ID for this operation
-	*/
-	async readFileStream(path$1, sessionId) {
-		const data = {
-			path: path$1,
-			sessionId
-		};
-		return await this.doStreamFetch("/api/read/stream", data);
-	}
-	/**
-	* Delete a file
-	* @param path - File path to delete
-	* @param sessionId - The session ID for this operation
-	*/
-	async deleteFile(path$1, sessionId) {
-		const data = {
-			path: path$1,
-			sessionId
-		};
-		return await this.post("/api/delete", data);
-	}
-	/**
-	* Rename a file
-	* @param path - Current file path
-	* @param newPath - New file path
-	* @param sessionId - The session ID for this operation
-	*/
-	async renameFile(path$1, newPath, sessionId) {
-		const data = {
-			oldPath: path$1,
-			newPath,
-			sessionId
-		};
-		return await this.post("/api/rename", data);
-	}
-	/**
-	* Move a file
-	* @param path - Current file path
-	* @param newPath - Destination file path
-	* @param sessionId - The session ID for this operation
-	*/
-	async moveFile(path$1, newPath, sessionId) {
-		const data = {
-			sourcePath: path$1,
-			destinationPath: newPath,
-			sessionId
-		};
-		return await this.post("/api/move", data);
-	}
-	/**
-	* List files in a directory
-	* @param path - Directory path to list
-	* @param sessionId - The session ID for this operation
-	* @param options - Optional settings (recursive, includeHidden)
-	*/
-	async listFiles(path$1, sessionId, options) {
-		const data = {
-			path: path$1,
-			sessionId,
-			options: options || {}
-		};
-		return await this.post("/api/list-files", data);
-	}
-	/**
-	* Check if a file or directory exists
-	* @param path - Path to check
-	* @param sessionId - The session ID for this operation
-	*/
-	async exists(path$1, sessionId) {
-		const data = {
-			path: path$1,
-			sessionId
-		};
-		return await this.post("/api/exists", data);
-	}
-	/**
-	* Write a file via a raw binary stream over the RPC transport.
-	* Throws on HTTP and WebSocket transports — use writeFile() with a string instead.
-	*/
-	writeFileStream(_path, _content, _sessionId) {
-		throw new Error("writeFileStream requires the rpc transport. Set SANDBOX_TRANSPORT=rpc.");
-	}
-};
-
-//#endregion
-//#region src/clients/git-client.ts
-/**
-* Client for Git repository operations
-*/
-var GitClient = class GitClient extends BaseHttpClient {
-	static REQUEST_TIMEOUT_BUFFER_MS = 3e4;
-	constructor(options = {}) {
-		super(options);
-		this.logger = new GitLogger(this.logger);
-	}
-	/**
-	* Clone a Git repository
-	* @param repoUrl - URL of the Git repository to clone
-	* @param sessionId - The session ID for this operation
-	* @param options - Optional settings (branch, targetDir, depth, timeoutMs)
-	*/
-	async checkout(repoUrl, sessionId, options) {
-		const timeoutMs = options?.timeoutMs ?? DEFAULT_GIT_CLONE_TIMEOUT_MS;
-		let targetDir = options?.targetDir;
-		if (!targetDir) targetDir = `/workspace/${extractRepoName(repoUrl)}`;
-		const data = {
-			repoUrl,
-			sessionId,
-			targetDir
-		};
-		if (options?.branch) data.branch = options.branch;
-		if (options?.depth !== void 0) {
-			if (!Number.isInteger(options.depth) || options.depth <= 0) throw new Error(`Invalid depth value: ${options.depth}. Must be a positive integer (e.g., 1, 5, 10).`);
-			data.depth = options.depth;
-		}
-		if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) throw new Error(`Invalid timeout value: ${timeoutMs}. Must be a positive integer number of milliseconds.`);
-		data.timeoutMs = timeoutMs;
-		return await this.post("/api/git/checkout", data, void 0, { requestTimeoutMs: timeoutMs + GitClient.REQUEST_TIMEOUT_BUFFER_MS });
-	}
-};
-
-//#endregion
-//#region src/clients/interpreter-client.ts
-var InterpreterClient = class extends BaseHttpClient {
-	maxRetries = 3;
-	retryDelayMs = 1e3;
-	async createCodeContext(options = {}) {
-		return this.executeWithRetry(async () => {
-			const response = await this.doFetch("/api/contexts", {
-				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({
-					language: options.language || "python",
-					cwd: options.cwd || "/workspace",
-					env_vars: options.envVars
-				})
-			});
-			if (!response.ok) throw await this.parseErrorResponse(response);
-			const data = await response.json();
-			if (!data.success) throw new Error(`Failed to create context: ${JSON.stringify(data)}`);
-			return {
-				id: data.contextId,
-				language: data.language,
-				cwd: data.cwd || "/workspace",
-				createdAt: new Date(data.timestamp),
-				lastUsed: new Date(data.timestamp)
-			};
-		});
-	}
-	async runCodeStream(contextId, code, language, callbacks, timeoutMs) {
-		return this.executeWithRetry(async () => {
-			const stream = await this.doStreamFetch("/api/execute/code", {
-				context_id: contextId,
-				code,
-				language,
-				...timeoutMs !== void 0 && { timeout_ms: timeoutMs }
-			});
-			for await (const chunk of this.readLines(stream)) await this.parseExecutionResult(chunk, callbacks);
-		});
-	}
-	async listCodeContexts() {
-		return this.executeWithRetry(async () => {
-			const response = await this.doFetch("/api/contexts", {
-				method: "GET",
-				headers: { "Content-Type": "application/json" }
-			});
-			if (!response.ok) throw await this.parseErrorResponse(response);
-			const data = await response.json();
-			if (!data.success) throw new Error(`Failed to list contexts: ${JSON.stringify(data)}`);
-			return data.contexts.map((ctx) => ({
-				id: ctx.id,
-				language: ctx.language,
-				cwd: ctx.cwd || "/workspace",
-				createdAt: new Date(data.timestamp),
-				lastUsed: new Date(data.timestamp)
-			}));
-		});
-	}
-	async deleteCodeContext(contextId) {
-		return this.executeWithRetry(async () => {
-			const response = await this.doFetch(`/api/contexts/${contextId}`, {
-				method: "DELETE",
-				headers: { "Content-Type": "application/json" }
-			});
-			if (!response.ok) throw await this.parseErrorResponse(response);
-		});
-	}
-	/**
-	* Get a raw stream for code execution.
-	* Used by CodeInterpreter.runCodeStreaming() for direct stream access.
-	*/
-	async streamCode(contextId, code, language) {
-		return this.doStreamFetch("/api/execute/code", {
-			context_id: contextId,
-			code,
-			language
-		});
-	}
-	/**
-	* Execute an operation with automatic retry for transient errors
-	*/
-	async executeWithRetry(operation) {
-		let lastError;
-		for (let attempt = 0; attempt < this.maxRetries; attempt++) try {
-			return await operation();
-		} catch (error) {
-			lastError = error;
-			if (this.isRetryableError(error)) {
-				if (attempt < this.maxRetries - 1) {
-					const delay = this.retryDelayMs * 2 ** attempt + Math.random() * 1e3;
-					await new Promise((resolve) => setTimeout(resolve, delay));
-					continue;
-				}
-			}
-			throw error;
-		}
-		throw lastError || /* @__PURE__ */ new Error("Execution failed after retries");
-	}
-	isRetryableError(error) {
-		if (error instanceof InterpreterNotReadyError) return true;
-		if (error instanceof Error) return error.message.includes("not ready") || error.message.includes("initializing");
-		return false;
-	}
-	async parseErrorResponse(response) {
-		try {
-			return createErrorFromResponse(await response.json());
-		} catch {
-			return createErrorFromResponse({
-				code: ErrorCode.INTERNAL_ERROR,
-				message: `HTTP ${response.status}: ${response.statusText}`,
-				context: {},
-				httpStatus: response.status,
-				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			});
-		}
-	}
-	async *readLines(stream) {
-		const reader = stream.getReader();
-		let buffer = "";
-		try {
-			while (true) {
-				const { done, value } = await reader.read();
-				if (value) buffer += new TextDecoder().decode(value);
-				if (done) break;
-				let newlineIdx = buffer.indexOf("\n");
-				while (newlineIdx !== -1) {
-					yield buffer.slice(0, newlineIdx);
-					buffer = buffer.slice(newlineIdx + 1);
-					newlineIdx = buffer.indexOf("\n");
-				}
-			}
-			if (buffer.length > 0) yield buffer;
-		} finally {
-			try {
-				await reader.cancel();
-			} catch {}
-			reader.releaseLock();
-		}
-	}
-	async parseExecutionResult(line, callbacks) {
-		if (!line.trim()) return;
-		if (!line.startsWith("data: ")) return;
-		try {
-			const jsonData = line.substring(6);
-			const data = JSON.parse(jsonData);
-			switch (data.type) {
-				case "stdout":
-					if (callbacks.onStdout && data.text) await callbacks.onStdout({
-						text: data.text,
-						timestamp: data.timestamp || Date.now()
-					});
-					break;
-				case "stderr":
-					if (callbacks.onStderr && data.text) await callbacks.onStderr({
-						text: data.text,
-						timestamp: data.timestamp || Date.now()
-					});
-					break;
-				case "result":
-					if (callbacks.onResult) {
-						const result = new ResultImpl(data);
-						await callbacks.onResult(result);
-					}
-					break;
-				case "error":
-					if (callbacks.onError) await callbacks.onError({
-						name: data.ename || "Error",
-						message: data.evalue || "Unknown error",
-						traceback: data.traceback || []
-					});
-					break;
-				case "execution_complete": break;
-			}
-		} catch {}
-	}
-};
-
-//#endregion
-//#region src/clients/port-client.ts
-/**
-* Client for port readiness operations.
-*/
-var PortClient = class extends BaseHttpClient {
-	/**
-	* Watch a port for readiness via SSE stream
-	* @param request - Port watch configuration
-	* @returns SSE stream that emits PortWatchEvent objects
-	*/
-	async watchPort(request) {
-		return await this.doStreamFetch("/api/port-watch", request);
-	}
-};
-
-//#endregion
-//#region src/clients/process-client.ts
-/**
-* Client for background process management
-*/
-var ProcessClient = class extends BaseHttpClient {
-	/**
-	* Start a background process
-	* @param command - Command to execute as a background process
-	* @param sessionId - The session ID for this operation
-	* @param options - Optional settings (processId)
-	*/
-	async startProcess(command, sessionId, options) {
-		const data = {
-			command,
-			sessionId,
-			...options?.origin !== void 0 && { origin: options.origin },
-			...options?.processId !== void 0 && { processId: options.processId },
-			...options?.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
-			...options?.env !== void 0 && { env: options.env },
-			...options?.cwd !== void 0 && { cwd: options.cwd },
-			...options?.encoding !== void 0 && { encoding: options.encoding },
-			...options?.autoCleanup !== void 0 && { autoCleanup: options.autoCleanup }
-		};
-		return await this.post("/api/process/start", data);
-	}
-	/**
-	* List all processes (sandbox-scoped, not session-scoped)
-	*/
-	async listProcesses() {
-		return await this.get(`/api/process/list`);
-	}
-	/**
-	* Get information about a specific process (sandbox-scoped, not session-scoped)
-	* @param processId - ID of the process to retrieve
-	*/
-	async getProcess(processId) {
-		const url = `/api/process/${processId}`;
-		return await this.get(url);
-	}
-	/**
-	* Kill a specific process (sandbox-scoped, not session-scoped)
-	* @param processId - ID of the process to kill
-	*/
-	async killProcess(processId) {
-		const url = `/api/process/${processId}`;
-		return await this.delete(url);
-	}
-	/**
-	* Kill all running processes (sandbox-scoped, not session-scoped)
-	*/
-	async killAllProcesses() {
-		return await this.delete(`/api/process/kill-all`);
-	}
-	/**
-	* Get logs from a specific process (sandbox-scoped, not session-scoped)
-	* @param processId - ID of the process to get logs from
-	*/
-	async getProcessLogs(processId) {
-		const url = `/api/process/${processId}/logs`;
-		return await this.get(url);
-	}
-	/**
-	* Stream logs from a specific process (sandbox-scoped, not session-scoped)
-	* @param processId - ID of the process to stream logs from
-	*/
-	async streamProcessLogs(processId) {
-		const url = `/api/process/${processId}/stream`;
-		return await this.doStreamFetch(url, void 0, "GET");
-	}
-};
-
-//#endregion
-//#region src/clients/utility-client.ts
-/**
-* Client for health checks and utility operations
-*/
-var UtilityClient = class extends BaseHttpClient {
-	/**
-	* Ping the sandbox to check if it's responsive
-	*/
-	async ping() {
-		return (await this.get("/api/ping")).message;
-	}
-	/**
-	* Get list of available commands in the sandbox environment
-	*/
-	async getCommands() {
-		return (await this.get("/api/commands")).availableCommands;
-	}
-	/**
-	* Create a new execution session
-	* @param options - Session configuration (id, env, cwd)
-	*/
-	async createSession(options) {
-		return await this.post("/api/session/create", options);
-	}
-	/**
-	* Delete an execution session
-	* @param sessionId - Session ID to delete
-	*/
-	async deleteSession(sessionId) {
-		return await this.post("/api/session/delete", { sessionId });
-	}
-	/**
-	* Get the container version
-	* Returns the version embedded in the Docker image during build
-	*/
-	async getVersion() {
-		try {
-			return (await this.get("/api/version")).version;
-		} catch (error) {
-			this.logger.debug("Failed to get container version (may be old container)", { error });
-			return "unknown";
-		}
-	}
-	listSessions() {
-		throw new Error("listSessions requires the RPC transport. Set SANDBOX_TRANSPORT=rpc.");
-	}
-};
-
-//#endregion
-//#region src/clients/watch-client.ts
-/**
-* Client for file watch operations
-* Uses inotify under the hood for native filesystem event notifications
-*
-* @internal This client is used internally by the SDK.
-* Users should use `sandbox.watch()` or `sandbox.checkChanges()` instead.
-*/
-var WatchClient = class extends BaseHttpClient {
-	/**
-	* Check whether a path changed since a previously returned version.
-	*/
-	async checkChanges(request) {
-		return this.post("/api/watch/check", request);
-	}
-	/**
-	* Start watching a directory for changes.
-	* The returned promise resolves only after the watcher is established
-	* on the filesystem (i.e. the `watching` SSE event has been received).
-	* The returned stream still contains the `watching` event so consumers
-	* using `parseSSEStream` will see the full event sequence.
-	*
-	* @param request - Watch request with path and options
-	*/
-	async watch(request) {
-		const stream = await this.doStreamFetch("/api/watch", request);
-		return await this.waitForReadiness(stream);
-	}
-	/**
-	* Read SSE chunks until the `watching` event appears, then return a
-	* wrapper stream that replays the buffered chunks followed by the
-	* remaining original stream data.
-	*/
-	async waitForReadiness(stream) {
-		const reader = stream.getReader();
-		const bufferedChunks = [];
-		const decoder = new TextDecoder();
-		let buffer = "";
-		let currentEvent = { data: [] };
-		let watcherReady = false;
-		const processEventData = (eventData) => {
-			let event;
-			try {
-				event = JSON.parse(eventData);
-			} catch {
-				return;
-			}
-			if (event.type === "watching") watcherReady = true;
-			if (event.type === "error") throw new Error(event.error || "Watch failed to establish");
-		};
-		try {
-			while (!watcherReady) {
-				const { done, value } = await reader.read();
-				if (done) {
-					const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
-					for (const frame of finalParsed.events) {
-						processEventData(frame.data);
-						if (watcherReady) break;
-					}
-					if (watcherReady) break;
-					throw new Error("Watch stream ended before watcher was established");
-				}
-				bufferedChunks.push(value);
-				buffer += decoder.decode(value, { stream: true });
-				const parsed = parseSSEFrames(buffer, currentEvent);
-				buffer = parsed.remaining;
-				currentEvent = parsed.currentEvent;
-				for (const frame of parsed.events) {
-					processEventData(frame.data);
-					if (watcherReady) break;
-				}
-			}
-		} catch (error) {
-			reader.cancel().catch(() => {});
-			throw error;
-		}
-		let replayIndex = 0;
-		return new ReadableStream({
-			pull(controller) {
-				if (replayIndex < bufferedChunks.length) {
-					controller.enqueue(bufferedChunks[replayIndex++]);
-					return;
-				}
-				return reader.read().then(({ done: d, value: v }) => {
-					if (d) {
-						controller.close();
-						return;
-					}
-					controller.enqueue(v);
-				});
-			},
-			cancel() {
-				return reader.cancel();
-			}
-		});
-	}
-};
-
-//#endregion
-//#region src/clients/sandbox-client.ts
-/**
-* Route-based compatibility sandbox client that composes all domain-specific
-* HTTP API clients.
-*
-* This client supports the route-based HTTP and custom WebSocket transports.
-* The primary DO-to-container control path is ContainerControlClient under
-* `container-control/`. This client supports route-based compatibility,
-* debugging, local development, and fallback behavior.
-*/
-var SandboxClient = class {
-	backup;
-	commands;
-	files;
-	processes;
-	ports;
-	git;
-	interpreter;
-	utils;
-	watch;
-	/**
-	* Tunnels are RPC-only — the route-based transport does not implement them.
-	* This getter exists so the `PublicKeys<SandboxClient> satisfies
-	* PublicKeys<SandboxAPI>` compile-time check holds. Calling any method on
-	* the returned proxy throws a clear `RPC transport required` error.
-	*/
-	tunnels = createTunnelsNotImplemented();
-	transport = null;
-	constructor(options) {
-		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
-			mode: options.transportMode,
-			wsUrl: options.wsUrl,
-			baseUrl: options.baseUrl,
-			logger: options.logger,
-			stub: options.stub,
-			port: options.port,
-			retryTimeoutMs: options.retryTimeoutMs
-		});
-		const clientOptions = {
-			baseUrl: "http://localhost:3000",
-			...options,
-			transport: this.transport ?? options.transport
-		};
-		this.backup = new BackupClient(clientOptions);
-		this.commands = new CommandClient(clientOptions);
-		this.files = new FileClient(clientOptions);
-		this.processes = new ProcessClient(clientOptions);
-		this.ports = new PortClient(clientOptions);
-		this.git = new GitClient(clientOptions);
-		this.interpreter = new InterpreterClient(clientOptions);
-		this.utils = new UtilityClient(clientOptions);
-		this.watch = new WatchClient(clientOptions);
-	}
-	/**
-	* Update the 503 retry budget on all transports without recreating the client.
-	*
-	* In WebSocket mode a single shared transport is used, so one update covers
-	* every sub-client. In HTTP mode each sub-client owns its own transport, so
-	* all of them are updated individually.
-	*/
-	setRetryTimeoutMs(ms) {
-		if (this.transport) this.transport.setRetryTimeoutMs(ms);
-		else {
-			this.backup.setRetryTimeoutMs(ms);
-			this.commands.setRetryTimeoutMs(ms);
-			this.files.setRetryTimeoutMs(ms);
-			this.processes.setRetryTimeoutMs(ms);
-			this.ports.setRetryTimeoutMs(ms);
-			this.git.setRetryTimeoutMs(ms);
-			this.interpreter.setRetryTimeoutMs(ms);
-			this.utils.setRetryTimeoutMs(ms);
-			this.watch.setRetryTimeoutMs(ms);
-		}
-	}
-	/**
-	* Get the current transport mode
-	*/
-	getTransportMode() {
-		return this.transport?.getMode() ?? "http";
-	}
-	/**
-	* Check if WebSocket is connected (only relevant in WebSocket mode)
-	*/
-	isWebSocketConnected() {
-		return this.transport?.isConnected() ?? false;
-	}
-	/**
-	* Connect WebSocket transport (no-op in HTTP mode)
-	* Called automatically on first request, but can be called explicitly
-	* to establish connection upfront.
-	*/
-	async connect() {
-		if (this.transport) await this.transport.connect();
-	}
-	/**
-	* Disconnect WebSocket transport (no-op in HTTP mode)
-	* Should be called when the sandbox is destroyed.
-	*/
-	disconnect() {
-		if (this.transport) this.transport.disconnect();
-	}
-};
-function createTunnelsNotImplemented() {
-	const message = "sandbox.tunnels.* requires the RPC transport. Enable it with transport: \"rpc\" in sandbox options.";
-	return new Proxy({}, { get() {
-		return () => {
-			throw new Error(message);
-		};
-	} });
-}
-
-//#endregion
-//#region ../shared/src/backup.ts
-/**
-* Absolute directory prefixes supported by backup and restore operations.
-*/
-const BACKUP_ALLOWED_PREFIXES = [
-	"/workspace",
-	"/home",
-	"/tmp",
-	"/var/tmp",
-	"/app"
-];
-function normalizeBackupExcludePattern(pattern) {
-	let normalized = pattern;
-	while (normalized.startsWith("**/")) normalized = normalized.slice(3);
-	while (normalized.includes("/**/")) normalized = normalized.replace(/\/\*\*\//g, "/");
-	if (normalized.endsWith("/**")) normalized = normalized.slice(0, -3);
-	if (!normalized || normalized === "**") return null;
-	return normalized;
-}
-
-//#endregion
-//#region ../shared/src/internal.ts
-const DISABLE_SESSION_TOKEN = "__DISABLE_SESSION__";
-
-//#endregion
-//#region src/container-control/connection.ts
-const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
-const DEFAULT_RETRY_TIMEOUT_MS = 12e4;
-const MIN_TIME_FOR_RETRY_MS = 15e3;
-const MAX_RETRY_BACKOFF_MS = 3e4;
-/**
-* Manages a capnweb WebSocket RPC session to the container.
-*
-* The RPC stub is created eagerly in the constructor using a deferred
-* transport. Calls made before `connect()` completes are queued in the
-* transport and flushed once the WebSocket is established.
-*/
-var ContainerControlConnection = class {
-	stub;
-	session;
-	transport;
-	ws = null;
-	connected = false;
-	connectPromise = null;
-	containerStub;
-	port;
-	logger;
-	retryTimeoutMs;
-	onClose;
-	constructor(options) {
-		this.containerStub = options.stub;
-		this.port = options.port ?? 3e3;
-		this.logger = options.logger ?? createNoOpLogger();
-		this.retryTimeoutMs = options.retryTimeoutMs ?? DEFAULT_RETRY_TIMEOUT_MS;
-		this.onClose = options.onClose;
-		this.transport = new DeferredTransport();
-		this.session = new RpcSession(this.transport, options.localMain);
-		this.stub = this.session.getRemoteMain();
-	}
-	/**
-	* Get the typed RPC stub.
-	*
-	* The stub is available immediately — calls made before connect()
-	* completes are queued in the deferred transport and flushed once
-	* the WebSocket is established.
-	*/
-	rpc() {
-		if (!this.connected && !this.connectPromise) this.connect().catch(() => {});
-		return this.stub;
-	}
-	/**
-	* Return capnweb session statistics. The `imports` and `exports` counts
-	* reflect all in-flight RPC calls, streams, and peer-held references.
-	* An idle session has imports <= 1 && exports <= 1 (the bootstrap stubs).
-	*/
-	getStats() {
-		return this.session.getStats();
-	}
-	isConnected() {
-		return this.connected;
-	}
-	async connect() {
-		if (this.connected) return;
-		if (this.connectPromise) return this.connectPromise;
-		this.connectPromise = this.doConnect();
-		try {
-			await this.connectPromise;
-		} finally {
-			this.connectPromise = null;
-		}
-	}
-	disconnect() {
-		try {
-			this.stub[Symbol.dispose]?.();
-		} catch {}
-		if (this.ws) {
-			this.ws.removeEventListener("close", this.onWebSocketClose);
-			this.ws.removeEventListener("error", this.onWebSocketError);
-			try {
-				this.ws.close();
-			} catch {}
-			this.ws = null;
-		}
-		this.connected = false;
-		this.connectPromise = null;
-	}
-	/**
-	* Update the 503 retry budget without recreating the connection. Takes
-	* effect on the next `connect()`; an in-flight connect uses the value
-	* captured at start. Mirrors `WebSocketTransport.setRetryTimeoutMs`.
-	*/
-	setRetryTimeoutMs(ms) {
-		this.retryTimeoutMs = ms;
-	}
-	/**
-	* Run the owner-provided `onClose` callback exactly once per call,
-	* swallowing any errors so a buggy listener can't keep the connection
-	* object in a half-torn-down state.
-	*/
-	fireOnClose() {
-		if (!this.onClose) return;
-		try {
-			this.onClose();
-		} catch (err) {
-			this.logger.warn("ContainerControlConnection onClose handler threw", { error: err instanceof Error ? err.message : String(err) });
-		}
-	}
-	/**
-	* WebSocket `close` listener. Defined as a bound arrow field so the
-	* same reference can be passed to both `addEventListener` and
-	* `removeEventListener` — a fresh anonymous lambda would silently
-	* fail to unbind.
-	*/
-	onWebSocketClose = () => {
-		const wasConnected = this.connected;
-		this.connected = false;
-		this.ws = null;
-		this.logger.debug("ContainerControlConnection WebSocket closed");
-		if (wasConnected) this.fireOnClose();
-	};
-	/**
-	* WebSocket `error` listener. Same field-form rationale as
-	* {@link onWebSocketClose}.
-	*/
-	onWebSocketError = () => {
-		const wasConnected = this.connected;
-		this.connected = false;
-		this.ws = null;
-		if (wasConnected) this.fireOnClose();
-	};
-	async doConnect() {
-		try {
-			const response = await this.fetchUpgradeWithRetry();
-			if (response.status !== 101) throw new Error(`WebSocket upgrade failed: ${response.status} ${response.statusText}`);
-			const ws = response.webSocket;
-			if (!ws) throw new Error("No WebSocket in upgrade response");
-			ws.accept();
-			ws.addEventListener("close", this.onWebSocketClose);
-			ws.addEventListener("error", this.onWebSocketError);
-			this.ws = ws;
-			this.transport.activate(ws);
-			this.connected = true;
-			this.logger.debug("ContainerControlConnection established", { port: this.port });
-		} catch (error) {
-			this.connected = false;
-			this.transport.abort(error);
-			this.logger.error("ContainerControlConnection failed", error instanceof Error ? error : new Error(String(error)));
-			throw error;
-		}
-	}
-	/**
-	* Issue WebSocket upgrade fetches, retrying transient 503 responses with
-	* exponential backoff (3s → 6s → 12s → … capped at 30s) until either
-	* the upgrade succeeds, a non-503 status is returned, or the retry budget
-	* runs out. Mirrors `WebSocketTransport.fetchUpgradeWithRetry` so both
-	* transports behave the same way during container startup.
-	*/
-	async fetchUpgradeWithRetry() {
-		const retryTimeoutMs = this.retryTimeoutMs;
-		const startTime = Date.now();
-		let attempt = 0;
-		while (true) {
-			const response = await this.fetchUpgradeAttempt();
-			if (response.status !== 503) return response;
-			const remaining = retryTimeoutMs - (Date.now() - startTime);
-			if (remaining <= MIN_TIME_FOR_RETRY_MS) return response;
-			const delay = Math.min(3e3 * 2 ** attempt, MAX_RETRY_BACKOFF_MS);
-			this.logger.info("ContainerControlConnection upgrade returned 503, retrying", {
-				attempt: attempt + 1,
-				delayMs: delay,
-				remainingSec: Math.floor(remaining / 1e3)
-			});
-			await this.sleep(delay);
-			attempt++;
-		}
-	}
-	/**
-	* Single WebSocket-upgrade fetch attempt. Owns its own AbortController so
-	* each retry gets a fresh per-attempt connect timeout independent of the
-	* total retry budget.
-	*/
-	async fetchUpgradeAttempt() {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), DEFAULT_CONNECT_TIMEOUT_MS);
-		try {
-			const url = `http://localhost:${this.port}/rpc`;
-			const request = new Request(url, {
-				headers: {
-					Upgrade: "websocket",
-					Connection: "Upgrade"
-				},
-				signal: controller.signal
-			});
-			return await this.containerStub.fetch(request);
-		} finally {
-			clearTimeout(timeout);
-		}
-	}
-	sleep(ms) {
-		return new Promise((resolve) => setTimeout(resolve, ms));
-	}
-};
-/**
-* RPC transport that queues sends and blocks receives until a WebSocket
-* is provided via `activate()`. Allows the RPC stub to be created before
-* the connection is established — queued calls flush automatically.
-*/
-var DeferredTransport = class {
-	#ws = null;
-	#sendQueue = [];
-	#receiveQueue = [];
-	#receiveResolver;
-	#receiveRejecter;
-	#error;
-	activate(ws) {
-		this.#ws = ws;
-		ws.addEventListener("message", (event) => {
-			if (this.#error) return;
-			if (typeof event.data === "string") if (this.#receiveResolver) {
-				this.#receiveResolver(event.data);
-				this.#receiveResolver = void 0;
-				this.#receiveRejecter = void 0;
-			} else this.#receiveQueue.push(event.data);
-			else this.#fail(/* @__PURE__ */ new TypeError("Received non-string message from WebSocket."));
-		});
-		ws.addEventListener("close", (event) => {
-			this.#fail(/* @__PURE__ */ new Error(`Peer closed WebSocket: ${event.code} ${event.reason}`));
-		});
-		ws.addEventListener("error", () => {
-			this.#fail(/* @__PURE__ */ new Error("WebSocket connection failed."));
-		});
-		for (const msg of this.#sendQueue) ws.send(msg);
-		this.#sendQueue = [];
-	}
-	async send(message) {
-		if (this.#ws) this.#ws.send(message);
-		else this.#sendQueue.push(message);
-	}
-	async receive() {
-		if (this.#receiveQueue.length > 0) return this.#receiveQueue.shift();
-		if (this.#error) throw this.#error;
-		return new Promise((resolve, reject) => {
-			this.#receiveResolver = resolve;
-			this.#receiveRejecter = reject;
-		});
-	}
-	abort(reason) {
-		this.#fail(reason instanceof Error ? reason : new Error(String(reason)));
-		if (this.#ws) {
-			const message = reason instanceof Error ? reason.message : String(reason);
-			this.#ws.close(3e3, message);
-		}
-	}
-	#fail(err) {
-		if (this.#error) return;
-		this.#error = err;
-		this.#receiveRejecter?.(err);
-		this.#receiveResolver = void 0;
-		this.#receiveRejecter = void 0;
-	}
-};
-
-//#endregion
-//#region src/container-control/client.ts
-/** Close the idle capnweb WebSocket promptly so the DO can sleep. */
-const DEFAULT_IDLE_DISCONNECT_MS = 1e3;
-/**
-* How often the busy/idle poller samples `getStats()`.
-*
-* Sets two worst-case bounds:
-*
-*   1. **Idle-detection lag.** Time between the session going idle on
-*      the wire and the DO observing it (and arming the disconnect).
-*      Bounded by `pollInterval`.
-*   2. **Activity-renewal lag while busy.** While a stream is active we
-*      renew the DO's activity timeout once per tick. The alarm could
-*      fire as late as `sleepAfter` after the last renew, so the
-*      effective margin against a mid-stream sleep is
-*      `sleepAfter - pollInterval`.
-*
-* **Invariant: `pollInterval` must be comfortably less than the
-* smallest configurable `sleepAfter`.** Aim for at least 2-3× headroom.
-* The minimum `sleepAfter` exercised by the E2E suite is 3s, so 1s gives
-* 3× margin and at least two renewals during a 3s window. If a smaller
-* `sleepAfter` is ever supported, drop this proportionally.
-*/
-const BUSY_POLL_INTERVAL_MS = 1e3;
-/**
-* Baseline getStats() values for an idle session. The bootstrap stub on each
-* side accounts for 1 import and 1 export.
-*/
-const IDLE_IMPORT_THRESHOLD = 1;
-const IDLE_EXPORT_THRESHOLD = 1;
-/**
-* Translate a capnweb-propagated error into a typed SandboxError.
-*
-* Two wire formats are supported for backward compatibility with older
-* container images:
-*
-*  1. Propagated error properties (capnweb >= 0.8.0). The container throws a
-*     `ServiceError`-shaped object with own enumerable `code` and `details`
-*     properties. capnweb walks `Object.keys()` and reconstructs those fields
-*     on the SDK side.
-*  2. Legacy JSON-encoded message. Older containers encoded the structured
-*     payload as a JSON string in `error.message`.
-*
-* The JSON-fallback branch can be removed once all older container images are
-* no longer in service.
-*/
-function translateRPCError(error) {
-	if (error instanceof Error) {
-		const propagated = error;
-		if (typeof propagated.code === "string" && Object.hasOwn(ErrorCode, propagated.code)) {
-			const code = propagated.code;
-			const context = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
-			throw createErrorFromResponse({
-				code,
-				message: error.message,
-				context,
-				httpStatus: getHttpStatus(code),
-				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			});
-		}
-		let payload;
-		try {
-			payload = JSON.parse(error.message);
-		} catch {}
-		if (payload && typeof payload.code === "string" && typeof payload.message === "string") throw createErrorFromResponse({
-			code: payload.code,
-			message: payload.message,
-			context: payload.context ?? {},
-			httpStatus: getHttpStatus(payload.code),
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		throw createErrorFromResponse(buildTransportErrorResponse(error), { cause: error });
-	}
-	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
-}
-/**
-* Inspect a transport-level Error's message and produce the ErrorResponse
-* that becomes an RPCTransportError. Pattern strings are pinned to the exact
-* messages emitted by capnweb's WebSocketTransport (see capnweb's
-* src/websocket.ts) and our DeferredTransport in container-control/connection.ts —
-* notably the trailing period in `WebSocket connection failed.` matches
-* capnweb verbatim. The DeferredTransport tests in
-* tests/container-connection.test.ts pin the literal strings.
-*/
-function buildTransportErrorResponse(error) {
-	const message = error.message;
-	const errorName = error.name;
-	let kind = "unknown";
-	let closeCode;
-	let closeReason;
-	if (errorName === "TypeError") kind = "invalid_frame";
-	else if (errorName === "SyntaxError") kind = "protocol_error";
-	else {
-		const peerCloseMatch = message.match(/^Peer closed WebSocket: (\d+) ?(.*)$/);
-		if (peerCloseMatch) {
-			kind = "peer_closed";
-			closeCode = Number(peerCloseMatch[1]);
-			closeReason = peerCloseMatch[2] || void 0;
-		} else if (message === "WebSocket connection failed.") kind = "connection_failed";
-		else if (message.startsWith("WebSocket upgrade failed")) kind = "upgrade_failed";
-		else if (message === "No WebSocket in upgrade response") kind = "upgrade_failed";
-		else if (message === "RPC session was shut down by disposing the main stub" || message === "RPC was canceled because the RpcPromise was disposed.") kind = "session_disposed";
-	}
-	const context = {
-		kind,
-		originalMessage: message,
-		errorName,
-		...closeCode !== void 0 ? { closeCode } : {},
-		...closeReason !== void 0 ? { closeReason } : {}
-	};
-	return {
-		code: ErrorCode.RPC_TRANSPORT_ERROR,
-		message,
-		context,
-		httpStatus: getHttpStatus(ErrorCode.RPC_TRANSPORT_ERROR),
-		suggestion: getSuggestion(ErrorCode.RPC_TRANSPORT_ERROR, context),
-		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	};
-}
-/**
-* Wrap a capnweb RPC stub so that every method call translates errors
-* from the JSON wire format into typed SandboxError instances and signals
-* activity at call start.
-*
-* `onCallStarted` fires synchronously when an RPC method is invoked. The
-* ContainerControlClient uses this to renew the DO's activity timeout
-* immediately, so even a call that completes entirely between two
-* busy-poll ticks still pushes the sleepAfter deadline forward.
-*
-* Note: there is no `onCallSettled` hook. A method whose returned promise
-* resolves with a `ReadableStream` is *not* finished when the promise
-* settles — capnweb keeps the export alive until the stream ends. The
-* busy/idle poll on `getStats()` is the source of truth for that.
-*/
-function wrapStub(stub, onCallStarted) {
-	return new Proxy(stub, { get(target, prop, receiver) {
-		const value = Reflect.get(target, prop, receiver);
-		if (typeof value !== "function") return value;
-		return (...args) => {
-			onCallStarted();
-			try {
-				const result = Reflect.apply(value, target, args);
-				if (result != null && typeof result.then === "function") return result.catch(translateRPCError);
-				return result;
-			} catch (err) {
-				translateRPCError(err);
-			}
-		};
-	} });
-}
-/**
-* SandboxClient-compatible facade backed by direct capnweb RPC.
-*
-* All operations call the container's SandboxAPI control interface directly
-* over capnweb, bypassing the HTTP handler/router layer entirely.
-*
-* Manages its own WebSocket lifecycle: a fresh `ContainerControlConnection` is
-* created on demand and torn down after `idleDisconnectMs` of inactivity.
-* Busy/idle detection relies on `RpcSession.getStats()` which tracks all
-* in-flight RPC calls and stream exports — including long-lived streaming
-* RPCs that would be invisible to a simple per-call request counter (see
-* the file-level comment for the full rationale).
-*/
-var ContainerControlClient = class {
-	connOptions;
-	idleDisconnectMs;
-	busyPollIntervalMs;
-	logger;
-	onActivity;
-	onSessionBusy;
-	onSessionIdle;
-	conn = null;
-	idleTimer = null;
-	busyPollTimer = null;
-	/** Tracks whether we currently believe the session is busy. */
-	busy = false;
-	constructor(options) {
-		this.connOptions = {
-			stub: options.stub,
-			port: options.port,
-			localMain: options.localMain,
-			logger: options.logger,
-			retryTimeoutMs: options.retryTimeoutMs,
-			onClose: () => {
-				if (this.conn) this.destroyConnection();
-			}
-		};
-		this.idleDisconnectMs = options.idleDisconnectMs ?? DEFAULT_IDLE_DISCONNECT_MS;
-		this.busyPollIntervalMs = options.busyPollIntervalMs ?? BUSY_POLL_INTERVAL_MS;
-		this.logger = options.logger ?? createNoOpLogger();
-		this.onActivity = options.onActivity;
-		this.onSessionBusy = options.onSessionBusy;
-		this.onSessionIdle = options.onSessionIdle;
-	}
-	/**
-	* Return the current connection, creating one when the client is disconnected.
-	* Starts the busy-poll timer the first time a connection is materialized.
-	*/
-	getConnection() {
-		if (!this.conn) {
-			this.conn = new ContainerControlConnection(this.connOptions);
-			this.startBusyPoll();
-		}
-		return this.conn;
-	}
-	/**
-	* Called synchronously at the start of each RPC method invocation.
-	* Renews the DO activity timeout so the sleepAfter alarm is pushed
-	* forward before the container processes the call.
-	*/
-	renewActivity = () => {
-		this.onActivity?.();
-	};
-	/**
-	* Sample `getStats()` and update busy/idle state. While busy, renews the
-	* activity timeout each tick so an in-flight stream keeps pushing the
-	* sleepAfter deadline forward. On the busy → idle edge, fires
-	* `onSessionIdle` and schedules the WebSocket disconnect.
-	*
-	* If the WebSocket has dropped underneath us (container crash, network
-	* blip) we tear the connection down here. `destroyConnection()` fires
-	* `onSessionIdle` if we were busy, so the DO's inflight counter doesn't
-	* stay pinned forever waiting for a peer that's never going to reply.
-	*/
-	pollBusyState = () => {
-		const conn = this.conn;
-		if (!conn) return;
-		if (!conn.isConnected()) return;
-		const { imports, exports } = conn.getStats();
-		if (imports > IDLE_IMPORT_THRESHOLD || exports > IDLE_EXPORT_THRESHOLD) {
-			if (!this.busy) {
-				this.busy = true;
-				this.onSessionBusy?.();
-			}
-			this.onActivity?.();
-			this.clearIdleTimer();
-		} else if (this.busy) {
-			this.busy = false;
-			this.onSessionIdle?.();
-			this.scheduleIdleDisconnect();
-		} else if (!this.idleTimer) this.scheduleIdleDisconnect();
-	};
-	startBusyPoll() {
-		if (this.busyPollTimer) return;
-		this.busyPollTimer = setInterval(this.pollBusyState, this.busyPollIntervalMs);
-	}
-	stopBusyPoll() {
-		if (this.busyPollTimer) {
-			clearInterval(this.busyPollTimer);
-			this.busyPollTimer = null;
-		}
-	}
-	scheduleIdleDisconnect() {
-		this.clearIdleTimer();
-		this.idleTimer = setTimeout(() => {
-			this.idleTimer = null;
-			const conn = this.conn;
-			if (!conn || !conn.isConnected()) return;
-			const { imports, exports } = conn.getStats();
-			if (imports <= IDLE_IMPORT_THRESHOLD && exports <= IDLE_EXPORT_THRESHOLD) {
-				this.logger.debug("Disconnecting idle RPC connection");
-				this.destroyConnection();
-			}
-		}, this.idleDisconnectMs);
-	}
-	clearIdleTimer() {
-		if (this.idleTimer) {
-			clearTimeout(this.idleTimer);
-			this.idleTimer = null;
-		}
-	}
-	destroyConnection() {
-		this.stopBusyPoll();
-		this.clearIdleTimer();
-		if (this.busy) {
-			this.busy = false;
-			this.onSessionIdle?.();
-		}
-		if (this.conn) {
-			this.conn.disconnect();
-			this.conn = null;
-		}
-	}
-	get commands() {
-		return wrapStub(this.getConnection().rpc().commands, this.renewActivity);
-	}
-	get files() {
-		return wrapStub(this.getConnection().rpc().files, this.renewActivity);
-	}
-	get processes() {
-		return wrapStub(this.getConnection().rpc().processes, this.renewActivity);
-	}
-	get ports() {
-		return wrapStub(this.getConnection().rpc().ports, this.renewActivity);
-	}
-	get git() {
-		return wrapStub(this.getConnection().rpc().git, this.renewActivity);
-	}
-	get utils() {
-		return wrapStub(this.getConnection().rpc().utils, this.renewActivity);
-	}
-	get backup() {
-		return wrapStub(this.getConnection().rpc().backup, this.renewActivity);
-	}
-	get watch() {
-		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
-	}
-	get tunnels() {
-		return wrapStub(this.getConnection().rpc().tunnels, this.renewActivity);
-	}
-	get interpreter() {
-		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
-	}
-	/**
-	* Update the 503 upgrade-retry budget. Applies to the current connection
-	* (if any) and is remembered for any future connections created after the
-	* client is torn down and reconnected.
-	*/
-	setRetryTimeoutMs(ms) {
-		this.connOptions.retryTimeoutMs = ms;
-		this.conn?.setRetryTimeoutMs(ms);
-	}
-	getTransportMode() {
-		return "rpc";
-	}
-	isWebSocketConnected() {
-		return this.conn?.isConnected() ?? false;
-	}
-	async connect() {
-		await this.getConnection().connect();
-	}
-	disconnect() {
-		this.destroyConnection();
-	}
-};
-
-//#endregion
-//#region src/current-runtime-identity.ts
-const CURRENT_RUNTIME_IDENTITY_STORAGE_KEY = "currentRuntimeIdentity";
-var RuntimeIdentityInactiveError = class extends Error {
-	constructor() {
-		super("Runtime identity is no longer active");
-		this.name = "RuntimeIdentityInactiveError";
-	}
-};
-var RuntimeIdentity = class {
-	id;
-	constructor(record) {
-		this.id = record.id;
-	}
-	owns(record) {
-		return record.runtimeIdentityID === this.id;
-	}
-	scope(value) {
-		return {
-			...value,
-			runtimeIdentityID: this.id
-		};
-	}
-};
-var CurrentRuntimeIdentity = class {
-	/**
-	* Runtime identity is stored in Durable Object storage so a reconstructed DO
-	* can still recognize the live container runtime it owns. In-memory state is
-	* only a cache and cannot define runtime-scoped correctness.
-	*/
-	constructor(storage, getContainerState, isContainerRunning) {
-		this.storage = storage;
-		this.getContainerState = getContainerState;
-		this.isContainerRunning = isContainerRunning;
-	}
-	async get() {
-		const status = await this.getStatus();
-		return status.status === "active" ? status.runtime : null;
-	}
-	async getStatus() {
-		const state = await this.getContainerState();
-		if (state.status !== "healthy") return {
-			status: "inactive",
-			reason: "runtime-not-healthy",
-			containerStatus: state.status
-		};
-		if (!this.isContainerRunning()) return {
-			status: "inactive",
-			reason: "runtime-not-running",
-			containerStatus: state.status
-		};
-		const runtime = await this.getStored();
-		if (!runtime) return {
-			status: "inactive",
-			reason: "missing-runtime-id",
-			containerStatus: state.status
-		};
-		return {
-			status: "active",
-			runtime,
-			containerStatus: state.status
-		};
-	}
-	async getStored(storage = this.storage) {
-		const record = await storage.get(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY) ?? null;
-		return record ? new RuntimeIdentity(record) : null;
-	}
-	async markStarted() {
-		const record = { id: crypto.randomUUID() };
-		await this.storage.put(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY, record);
-		return new RuntimeIdentity(record);
-	}
-	async clear() {
-		await this.storage.delete(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY);
-	}
-	async isActive(runtime) {
-		return (await this.get())?.id === runtime.id;
-	}
-	async assertActive(runtime) {
-		if (!await this.isActive(runtime)) throw new RuntimeIdentityInactiveError();
-	}
-};
-
-//#endregion
-//#region src/file-stream.ts
-/**
-* Parse SSE (Server-Sent Events) lines from a stream
-*/
-async function* parseSSE(stream) {
-	const reader = stream.getReader();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	let currentEvent = { data: [] };
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			buffer += decoder.decode(value, { stream: true });
-			const parsed = parseSSEFrames(buffer, currentEvent);
-			buffer = parsed.remaining;
-			currentEvent = parsed.currentEvent;
-			for (const frame of parsed.events) try {
-				yield JSON.parse(frame.data);
-			} catch {}
-		}
-		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
-		for (const frame of finalParsed.events) try {
-			yield JSON.parse(frame.data);
-		} catch {}
-	} finally {
-		try {
-			await reader.cancel();
-		} catch {}
-		reader.releaseLock();
-	}
-}
-/**
-* Stream a file from the sandbox with automatic base64 decoding for binary files
-*
-* @param stream - The ReadableStream from readFileStream()
-* @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
-*
-* @example
-* ```ts
-* const stream = await sandbox.readFileStream('/path/to/file.png');
-* for await (const chunk of streamFile(stream)) {
-*   if (chunk instanceof Uint8Array) {
-*     // Binary chunk
-*     console.log('Binary chunk:', chunk.length, 'bytes');
-*   } else {
-*     // Text chunk
-*     console.log('Text chunk:', chunk);
-*   }
-* }
-* ```
-*/
-async function* streamFile(stream) {
-	let metadata = null;
-	for await (const event of parseSSE(stream)) switch (event.type) {
-		case "metadata":
-			metadata = {
-				mimeType: event.mimeType,
-				size: event.size,
-				isBinary: event.isBinary,
-				encoding: event.encoding
-			};
-			break;
-		case "chunk":
-			if (!metadata) throw new Error("Received chunk before metadata");
-			if (metadata.isBinary && metadata.encoding === "base64") {
-				const binaryString = atob(event.data);
-				const bytes = new Uint8Array(binaryString.length);
-				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
-				yield bytes;
-			} else yield event.data;
-			break;
-		case "complete":
-			if (!metadata) throw new Error("Stream completed without metadata");
-			return metadata;
-		case "error": throw new Error(`File streaming error: ${event.error}`);
-	}
-	throw new Error("Stream ended unexpectedly");
-}
-/**
-* Collect an entire file into memory from a stream
-*
-* @param stream - The ReadableStream from readFileStream()
-* @returns Object containing the file content and metadata
-*
-* @example
-* ```ts
-* const stream = await sandbox.readFileStream('/path/to/file.txt');
-* const { content, metadata } = await collectFile(stream);
-* console.log('Content:', content);
-* console.log('MIME type:', metadata.mimeType);
-* ```
-*/
-async function collectFile(stream) {
-	const chunks = [];
-	const generator = streamFile(stream);
-	let result = await generator.next();
-	while (!result.done) {
-		chunks.push(result.value);
-		result = await generator.next();
-	}
-	const metadata = result.value;
-	if (!metadata) throw new Error("Failed to get file metadata");
-	if (metadata.isBinary) {
-		const totalLength = chunks.reduce((sum, chunk) => sum + (chunk instanceof Uint8Array ? chunk.length : 0), 0);
-		const combined = new Uint8Array(totalLength);
-		let offset = 0;
-		for (const chunk of chunks) if (chunk instanceof Uint8Array) {
-			combined.set(chunk, offset);
-			offset += chunk.length;
-		}
-		return {
-			content: combined,
-			metadata
-		};
-	} else return {
-		content: chunks.filter((c) => typeof c === "string").join(""),
-		metadata
-	};
-}
-
-//#endregion
-//#region src/security.ts
-/**
-* Security utilities for URL construction and input validation
-*
-* This module contains critical security functions to prevent:
-* - URL injection attacks
-* - SSRF (Server-Side Request Forgery) attacks
-* - DNS rebinding attacks
-* - Host header injection
-* - Open redirect vulnerabilities
-*/
-var SandboxSecurityError = class extends Error {
-	constructor(message, code) {
-		super(message);
-		this.code = code;
-		this.name = "SandboxSecurityError";
-	}
-};
-/**
-* Validates port numbers for sandbox services.
-*
-* Rules:
-* - Range: 1024-65535 (privileged ports require root, which containers don't have)
-* - Reserved: 3000 (sandbox control plane)
-*/
-function validatePort(port) {
-	if (!Number.isInteger(port)) return false;
-	if (port < 1024 || port > 65535) return false;
-	if ([3e3].includes(port)) return false;
-	return true;
+	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
 }
 /**
-* Sanitizes and validates sandbox IDs for DNS compliance and security
-* Only enforces critical requirements - allows maximum developer flexibility
+* Inspect a transport-level Error's message and produce the ErrorResponse
+* that becomes an RPCTransportError. Pattern strings are pinned to the exact
+* messages emitted by capnweb's WebSocket transport (see capnweb's
+* src/websocket.ts) and our DeferredTransport in container-control/connection.ts —
+* notably the trailing period in `WebSocket connection failed.` matches
+* capnweb verbatim. The DeferredTransport tests in
+* tests/container-connection.test.ts pin the literal strings.
 */
-function sanitizeSandboxId(id) {
-	if (!id || id.length > 63) throw new SandboxSecurityError("Sandbox ID must be 1-63 characters long.", "INVALID_SANDBOX_ID_LENGTH");
-	if (id.startsWith("-") || id.endsWith("-")) throw new SandboxSecurityError("Sandbox ID cannot start or end with hyphens (DNS requirement).", "INVALID_SANDBOX_ID_HYPHENS");
-	const reservedNames = [
-		"www",
-		"api",
-		"admin",
-		"root",
-		"system",
-		"cloudflare",
-		"workers"
-	];
-	const lowerCaseId = id.toLowerCase();
-	if (reservedNames.includes(lowerCaseId)) throw new SandboxSecurityError(`Reserved sandbox ID '${id}' is not allowed.`, "RESERVED_SANDBOX_ID");
-	return id;
+function buildTransportErrorResponse(error) {
+	const message = error.message;
+	const errorName = error.name;
+	let kind = "unknown";
+	let closeCode;
+	let closeReason;
+	if (errorName === "TypeError") kind = "invalid_frame";
+	else if (errorName === "SyntaxError") kind = "protocol_error";
+	else {
+		const peerCloseMatch = message.match(/^Peer closed WebSocket: (\d+) ?(.*)$/);
+		if (peerCloseMatch) {
+			kind = "peer_closed";
+			closeCode = Number(peerCloseMatch[1]);
+			closeReason = peerCloseMatch[2] || void 0;
+		} else if (message === "WebSocket connection failed.") kind = "connection_failed";
+		else if (message.startsWith("WebSocket upgrade failed")) kind = "upgrade_failed";
+		else if (message === "No WebSocket in upgrade response") kind = "upgrade_failed";
+		else if (message === "RPC session was shut down by disposing the main stub" || message === "RPC was canceled because the RpcPromise was disposed.") kind = "session_disposed";
+	}
+	const context = {
+		kind,
+		originalMessage: message,
+		errorName,
+		...closeCode !== void 0 ? { closeCode } : {},
+		...closeReason !== void 0 ? { closeReason } : {}
+	};
+	return {
+		code: ErrorCode.RPC_TRANSPORT_ERROR,
+		message,
+		context,
+		httpStatus: getHttpStatus(ErrorCode.RPC_TRANSPORT_ERROR),
+		suggestion: getSuggestion(ErrorCode.RPC_TRANSPORT_ERROR, context),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
 }
 /**
-* Validates language for code interpreter
-* Only allows supported languages
+* Wrap a capnweb RPC stub so that every method call translates errors
+* from the JSON wire format into typed SandboxError instances and signals
+* activity at call start.
+*
+* `onCallStarted` fires synchronously when an RPC method is invoked. The
+* ContainerControlClient uses this to renew the DO's activity timeout
+* immediately, so even a call that completes entirely between two
+* busy-poll ticks still pushes the sleepAfter deadline forward.
+*
+* Note: there is no `onCallSettled` hook. A method whose returned promise
+* resolves with a `ReadableStream` is *not* finished when the promise
+* settles — capnweb keeps the export alive until the stream ends. The
+* busy/idle poll on `getStats()` is the source of truth for that.
 */
-function validateLanguage(language) {
-	if (!language) return;
-	const supportedLanguages = [
-		"python",
-		"python3",
-		"javascript",
-		"js",
-		"node",
-		"typescript",
-		"ts"
-	];
-	const normalized = language.toLowerCase();
-	if (!supportedLanguages.includes(normalized)) throw new SandboxSecurityError(`Unsupported language '${language}'. Supported languages: python, javascript, typescript`, "INVALID_LANGUAGE");
+function wrapStub(stub, onCallStarted) {
+	return new Proxy(stub, { get(target, prop, receiver) {
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value !== "function") return value;
+		return (...args) => {
+			onCallStarted();
+			try {
+				const result = Reflect.apply(value, target, args);
+				if (result != null && typeof result.then === "function") return result.catch(translateRPCError);
+				return result;
+			} catch (err) {
+				translateRPCError(err);
+			}
+		};
+	} });
 }
 /**
-* Validates a single DNS label for use as a Cloudflare Tunnel hostname.
-*
-* Used by `sandbox.tunnels.get(port, { name })` to reject obviously-bad
-* input client-side before any network call. Whether the chosen label is
-* actually available under the configured zone is left to the Cloudflare
-* API (returned as a typed error).
+* Sandbox control facade backed by direct capnweb RPC.
 *
-* Rules:
-* - 1–63 characters
-* - Lowercase letters, digits, and internal hyphens only
-* - No leading or trailing hyphen
-* - No dots — multi-label hostnames need a delegated subdomain zone or
-*   Advanced Certificate Manager, which are out of scope for this
-*   feature. Universal SSL only covers `<label>.<zone>`.
+* All operations call the container's SandboxAPI control interface directly
+* over capnweb, bypassing the HTTP handler/router layer entirely.
 *
-* Throws `SandboxSecurityError` on any violation. Designed to be called
-* before any other tunnel work so callers see a fast, deterministic
-* failure.
+* Manages its own WebSocket lifecycle: a fresh `ContainerControlConnection` is
+* created on demand and torn down after `idleDisconnectMs` of inactivity.
+* Busy/idle detection relies on `RpcSession.getStats()` which tracks all
+* in-flight RPC calls and stream exports — including long-lived streaming
+* RPCs that would be invisible to a simple per-call request counter (see
+* the file-level comment for the full rationale).
 */
-const TUNNEL_NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
-function validateTunnelName(name) {
-	if (typeof name !== "string") throw new SandboxSecurityError(`Tunnel name must be a string. Received: ${typeof name}`, "INVALID_TUNNEL_NAME");
-	if (name.length === 0 || name.length > 63) throw new SandboxSecurityError(`Tunnel name '${name}' must be 1–63 characters long.`, "INVALID_TUNNEL_NAME_LENGTH");
-	if (!TUNNEL_NAME_REGEX.test(name)) throw new SandboxSecurityError(`Tunnel name '${name}' is not a valid DNS label. Use lowercase letters, digits, and internal hyphens only (no dots, no leading/trailing hyphens).`, "INVALID_TUNNEL_NAME_FORMAT");
-}
-
-//#endregion
-//#region src/interpreter.ts
-var CodeInterpreter = class {
-	getInterpreterClient;
-	contexts = /* @__PURE__ */ new Map();
-	constructor(interpreterClient) {
-		this.getInterpreterClient = typeof interpreterClient === "function" ? interpreterClient : () => interpreterClient;
+var ContainerControlClient = class {
+	connOptions;
+	idleDisconnectMs;
+	busyPollIntervalMs;
+	logger;
+	onActivity;
+	onSessionBusy;
+	onSessionIdle;
+	conn = null;
+	idleTimer = null;
+	busyPollTimer = null;
+	/** Tracks whether we currently believe the session is busy. */
+	busy = false;
+	constructor(options) {
+		this.connOptions = {
+			stub: options.stub,
+			port: options.port,
+			localMain: options.localMain,
+			logger: options.logger,
+			retryTimeoutMs: options.retryTimeoutMs,
+			onClose: () => {
+				if (this.conn) this.destroyConnection();
+			}
+		};
+		this.idleDisconnectMs = options.idleDisconnectMs ?? DEFAULT_IDLE_DISCONNECT_MS;
+		this.busyPollIntervalMs = options.busyPollIntervalMs ?? BUSY_POLL_INTERVAL_MS;
+		this.logger = options.logger ?? createNoOpLogger();
+		this.onActivity = options.onActivity;
+		this.onSessionBusy = options.onSessionBusy;
+		this.onSessionIdle = options.onSessionIdle;
 	}
 	/**
-	* Create a new code execution context
+	* Return the current connection, creating one when the client is disconnected.
+	* Starts the busy-poll timer the first time a connection is materialized.
 	*/
-	async createCodeContext(options = {}) {
-		validateLanguage(options.language);
-		const context = await this.getInterpreterClient().createCodeContext(options);
-		this.contexts.set(context.id, context);
-		return context;
+	getConnection() {
+		if (!this.conn) {
+			this.conn = new ContainerControlConnection(this.connOptions);
+			this.startBusyPoll();
+		}
+		return this.conn;
 	}
 	/**
-	* Run code with optional context
+	* Called synchronously at the start of each RPC method invocation.
+	* Renews the DO activity timeout so the sleepAfter alarm is pushed
+	* forward before the container processes the call.
 	*/
-	async runCode(code, options = {}) {
-		let context = options.context;
-		if (!context) {
-			const language = options.language || "python";
-			context = await this.getOrCreateDefaultContext(language);
-		}
-		const execution = new Execution(code, context);
-		await this.getInterpreterClient().runCodeStream(context.id, code, options.language, {
-			onStdout: (output) => {
-				execution.logs.stdout.push(output.text);
-				if (options.onStdout) return options.onStdout(output);
-			},
-			onStderr: (output) => {
-				execution.logs.stderr.push(output.text);
-				if (options.onStderr) return options.onStderr(output);
-			},
-			onResult: async (result) => {
-				execution.results.push(new ResultImpl(result));
-				if (options.onResult) return options.onResult(result);
-			},
-			onError: (error) => {
-				execution.error = error;
-				if (options.onError) return options.onError(error);
+	renewActivity = () => {
+		this.onActivity?.();
+	};
+	/**
+	* Sample `getStats()` and update busy/idle state. While busy, renews the
+	* activity timeout each tick so an in-flight stream keeps pushing the
+	* sleepAfter deadline forward. On the busy → idle edge, fires
+	* `onSessionIdle` and schedules the WebSocket disconnect.
+	*
+	* If the WebSocket has dropped underneath us (container crash, network
+	* blip) we tear the connection down here. `destroyConnection()` fires
+	* `onSessionIdle` if we were busy, so the DO's inflight counter doesn't
+	* stay pinned forever waiting for a peer that's never going to reply.
+	*/
+	pollBusyState = () => {
+		const conn = this.conn;
+		if (!conn) return;
+		if (!conn.isConnected()) return;
+		const { imports, exports } = conn.getStats();
+		if (imports > IDLE_IMPORT_THRESHOLD || exports > IDLE_EXPORT_THRESHOLD) {
+			if (!this.busy) {
+				this.busy = true;
+				this.onSessionBusy?.();
+			}
+			this.onActivity?.();
+			this.clearIdleTimer();
+		} else if (this.busy) {
+			this.busy = false;
+			this.onSessionIdle?.();
+			this.scheduleIdleDisconnect();
+		} else if (!this.idleTimer) this.scheduleIdleDisconnect();
+	};
+	startBusyPoll() {
+		if (this.busyPollTimer) return;
+		this.busyPollTimer = setInterval(this.pollBusyState, this.busyPollIntervalMs);
+	}
+	stopBusyPoll() {
+		if (this.busyPollTimer) {
+			clearInterval(this.busyPollTimer);
+			this.busyPollTimer = null;
+		}
+	}
+	scheduleIdleDisconnect() {
+		this.clearIdleTimer();
+		this.idleTimer = setTimeout(() => {
+			this.idleTimer = null;
+			const conn = this.conn;
+			if (!conn || !conn.isConnected()) return;
+			const { imports, exports } = conn.getStats();
+			if (imports <= IDLE_IMPORT_THRESHOLD && exports <= IDLE_EXPORT_THRESHOLD) {
+				this.logger.debug("Disconnecting idle RPC connection");
+				this.destroyConnection();
 			}
-		});
-		return execution;
+		}, this.idleDisconnectMs);
 	}
-	/**
-	* Run code and return a streaming response
-	*/
-	async runCodeStream(code, options = {}) {
-		let context = options.context;
-		if (!context) {
-			const language = options.language || "python";
-			context = await this.getOrCreateDefaultContext(language);
+	clearIdleTimer() {
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
 		}
-		return this.getInterpreterClient().streamCode(context.id, code, options.language);
+	}
+	destroyConnection() {
+		this.stopBusyPoll();
+		this.clearIdleTimer();
+		if (this.busy) {
+			this.busy = false;
+			this.onSessionIdle?.();
+		}
+		if (this.conn) {
+			this.conn.disconnect();
+			this.conn = null;
+		}
+	}
+	get commands() {
+		return wrapStub(this.getConnection().rpc().commands, this.renewActivity);
+	}
+	get files() {
+		return wrapStub(this.getConnection().rpc().files, this.renewActivity);
+	}
+	get processes() {
+		return wrapStub(this.getConnection().rpc().processes, this.renewActivity);
+	}
+	get ports() {
+		return wrapStub(this.getConnection().rpc().ports, this.renewActivity);
+	}
+	get git() {
+		return wrapStub(this.getConnection().rpc().git, this.renewActivity);
+	}
+	get utils() {
+		return wrapStub(this.getConnection().rpc().utils, this.renewActivity);
+	}
+	get backup() {
+		return wrapStub(this.getConnection().rpc().backup, this.renewActivity);
+	}
+	get watch() {
+		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
+	}
+	get tunnels() {
+		return wrapStub(this.getConnection().rpc().tunnels, this.renewActivity);
+	}
+	get interpreter() {
+		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
 	}
 	/**
-	* List all code contexts
+	* Update the upgrade retry budget. Applies to the current connection
+	* (if any) and is remembered for any future connections created after the
+	* client is torn down and reconnected.
 	*/
-	async listCodeContexts() {
-		const contexts = await this.getInterpreterClient().listCodeContexts();
-		for (const context of contexts) this.contexts.set(context.id, context);
-		return contexts;
+	setRetryTimeoutMs(ms) {
+		this.connOptions.retryTimeoutMs = ms;
+		this.conn?.setRetryTimeoutMs(ms);
+	}
+	isWebSocketConnected() {
+		return this.conn?.isConnected() ?? false;
+	}
+	async connect() {
+		await this.getConnection().connect();
+	}
+	disconnect() {
+		this.destroyConnection();
+	}
+};
+
+//#endregion
+//#region src/current-runtime-identity.ts
+const CURRENT_RUNTIME_IDENTITY_STORAGE_KEY = "currentRuntimeIdentity";
+var RuntimeIdentityInactiveError = class extends Error {
+	constructor() {
+		super("Runtime identity is no longer active");
+		this.name = "RuntimeIdentityInactiveError";
+	}
+};
+var RuntimeIdentity = class {
+	id;
+	constructor(record) {
+		this.id = record.id;
+	}
+	owns(record) {
+		return record.runtimeIdentityID === this.id;
+	}
+	scope(value) {
+		return {
+			...value,
+			runtimeIdentityID: this.id
+		};
 	}
+};
+var CurrentRuntimeIdentity = class {
 	/**
-	* Delete a code context
+	* Runtime identity is stored in Durable Object storage so a reconstructed DO
+	* can still recognize the live container runtime it owns. In-memory state is
+	* only a cache and cannot define runtime-scoped correctness.
 	*/
-	async deleteCodeContext(contextId) {
-		await this.getInterpreterClient().deleteCodeContext(contextId);
-		this.contexts.delete(contextId);
+	constructor(storage, getContainerState, isContainerRunning) {
+		this.storage = storage;
+		this.getContainerState = getContainerState;
+		this.isContainerRunning = isContainerRunning;
 	}
-	async getOrCreateDefaultContext(language) {
-		for (const context of this.contexts.values()) if (context.language === language) return context;
-		return this.createCodeContext({ language });
+	async get() {
+		const status = await this.getStatus();
+		return status.status === "active" ? status.runtime : null;
+	}
+	async getStatus() {
+		const state = await this.getContainerState();
+		if (state.status !== "healthy") return {
+			status: "inactive",
+			reason: "runtime-not-healthy",
+			containerStatus: state.status
+		};
+		if (!this.isContainerRunning()) return {
+			status: "inactive",
+			reason: "runtime-not-running",
+			containerStatus: state.status
+		};
+		const runtime = await this.getStored();
+		if (!runtime) return {
+			status: "inactive",
+			reason: "missing-runtime-id",
+			containerStatus: state.status
+		};
+		return {
+			status: "active",
+			runtime,
+			containerStatus: state.status
+		};
+	}
+	async getStored(storage = this.storage) {
+		const record = await storage.get(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY) ?? null;
+		return record ? new RuntimeIdentity(record) : null;
+	}
+	async markStarted() {
+		const record = { id: crypto.randomUUID() };
+		await this.storage.put(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY, record);
+		return new RuntimeIdentity(record);
+	}
+	async clear() {
+		await this.storage.delete(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY);
+	}
+	async isActive(runtime) {
+		return (await this.get())?.id === runtime.id;
+	}
+	async assertActive(runtime) {
+		if (!await this.isActive(runtime)) throw new RuntimeIdentityInactiveError();
 	}
 };
 
@@ -4098,24 +2444,6 @@ function bridgePreviewWebSocket(response, lifecycle, settleForward) {
 	});
 }
 
-//#endregion
-//#region src/preview-proxy-protocol.ts
-/** @internal */
-const PREVIEW_PROXY_HEADER = "x-sandbox-preview-proxy";
-/** @internal */
-const PREVIEW_PROXY_PORT_HEADER = "x-sandbox-preview-port";
-/** @internal */
-const PREVIEW_PROXY_TOKEN_HEADER = "x-sandbox-preview-token";
-/** @internal */
-const PREVIEW_PROXY_SANDBOX_ID_HEADER = "x-sandbox-preview-sandbox-id";
-/** @internal */
-const PREVIEW_PROXY_HEADERS = [
-	PREVIEW_PROXY_HEADER,
-	PREVIEW_PROXY_PORT_HEADER,
-	PREVIEW_PROXY_TOKEN_HEADER,
-	PREVIEW_PROXY_SANDBOX_ID_HEADER
-];
-
 //#endregion
 //#region src/preview-url.ts
 function isLocalhostPattern(hostname) {
@@ -4128,20 +2456,6 @@ function isLocalhostPattern(hostname) {
 	return hostPart === "localhost" || hostPart === "127.0.0.1" || hostPart === "0.0.0.0";
 }
 
-//#endregion
-//#region src/pty/proxy.ts
-async function proxyTerminal(stub, sessionId, request, options) {
-	if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId is required for terminal access");
-	if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") throw new Error("terminal() requires a WebSocket upgrade request");
-	const params = new URLSearchParams({ sessionId });
-	if (options?.cols) params.set("cols", String(options.cols));
-	if (options?.rows) params.set("rows", String(options.rows));
-	if (options?.shell) params.set("shell", options.shell);
-	const ptyUrl = `http://localhost/ws/pty?${params}`;
-	const ptyRequest = new Request(ptyUrl, request);
-	return stub.fetch(switchPort(ptyRequest, 3e3));
-}
-
 //#endregion
 //#region src/storage-mount/r2-egress-handler.ts
 const XML_NS = "xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"";
@@ -5520,10 +3834,9 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 	*   4. spawn cloudflared inside the container
 	*   5. persist the record + meta
 	*
-	* Failure between (2) and (5) intentionally leaves the Cloudflare-side
-	* resources in place so a retry can re-discover them via
-	* `findTunnelByName` and the DNS reuse path. See
-	* `.plans/09-named-tunnel-api.md § Retry-friendly failure model`.
+	* Failure between (2) and (5) leaves the Cloudflare-side resources in
+	* place. Later calls re-discover the tunnel with `findTunnelByName` and
+	* reuse the DNS record through the CNAME upsert path.
 	*/
 	async #provisionNamedTunnel(port, name) {
 		if (!this.#host.sandboxId) throw new Error("Named tunnels require host.sandboxId on the tunnels handler.");
@@ -5802,11 +4115,9 @@ function createTunnelsHandler(host) {
 *     cache hit falls through to `#provisionNamedTunnel` to respawn
 *     `cloudflared`.
 *
-* Crucially, named-tunnel metadata (including `dnsRecordId`) is
-* preserved so `destroy(port)` and `sandbox.destroy()` can still clean
-* up the Cloudflare-side resources after a restart. Wiping meta
-* unconditionally — the previous behaviour — silently leaked the tunnel
-* and DNS record on every restart.
+* Named-tunnel metadata, including `dnsRecordId`, is preserved so
+* `destroy(port)` and `sandbox.destroy()` can clean up Cloudflare-side
+* resources after a restart.
 */
 async function pruneTunnelsForRestart(storage) {
 	await storage.transaction(async (txn) => {
@@ -5833,7 +4144,7 @@ async function pruneTunnelsForRestart(storage) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.12.0";
+const SDK_VERSION = "0.13.0-next.632.1";
 
 //#endregion
 //#region src/sandbox.ts
@@ -5967,11 +4278,10 @@ function buildSandboxConfiguration(effectiveId, options, cached) {
 	if (options?.sleepAfter !== void 0 && cached?.sleepAfter !== options.sleepAfter) configuration.sleepAfter = options.sleepAfter;
 	if (options?.keepAlive !== void 0 && cached?.keepAlive !== options.keepAlive) configuration.keepAlive = options.keepAlive;
 	if (options?.containerTimeouts && !sameContainerTimeouts(cached?.containerTimeouts, options.containerTimeouts)) configuration.containerTimeouts = options.containerTimeouts;
-	if (options?.transport !== void 0 && cached?.transport !== options.transport) configuration.transport = options.transport;
 	return configuration;
 }
 function hasSandboxConfiguration(configuration) {
-	return configuration.sandboxName !== void 0 || configuration.sleepAfter !== void 0 || configuration.keepAlive !== void 0 || configuration.containerTimeouts !== void 0 || configuration.transport !== void 0;
+	return configuration.sandboxName !== void 0 || configuration.sleepAfter !== void 0 || configuration.keepAlive !== void 0 || configuration.containerTimeouts !== void 0;
 }
 function mergeSandboxConfiguration(cached, configuration) {
 	return {
@@ -5982,8 +4292,7 @@ function mergeSandboxConfiguration(cached, configuration) {
 		},
 		...configuration.sleepAfter !== void 0 && { sleepAfter: configuration.sleepAfter },
 		...configuration.keepAlive !== void 0 && { keepAlive: configuration.keepAlive },
-		...configuration.containerTimeouts !== void 0 && { containerTimeouts: configuration.containerTimeouts },
-		...configuration.transport !== void 0 && { transport: configuration.transport }
+		...configuration.containerTimeouts !== void 0 && { containerTimeouts: configuration.containerTimeouts }
 	};
 }
 function applySandboxConfiguration(stub, configuration) {
@@ -5993,7 +4302,6 @@ function applySandboxConfiguration(stub, configuration) {
 	if (configuration.sleepAfter !== void 0) operations.push(stub.setSleepAfter?.(configuration.sleepAfter) ?? Promise.resolve());
 	if (configuration.keepAlive !== void 0) operations.push(stub.setKeepAlive?.(configuration.keepAlive) ?? Promise.resolve());
 	if (configuration.containerTimeouts !== void 0) operations.push(stub.setContainerTimeouts?.(configuration.containerTimeouts) ?? Promise.resolve());
-	if (configuration.transport !== void 0) operations.push(stub.setTransport?.(configuration.transport) ?? Promise.resolve());
 	return Promise.all(operations).then(() => void 0);
 }
 function getSandbox(ns, id, options) {
@@ -6119,14 +4427,6 @@ var Sandbox = class Sandbox extends Container {
 	activeMounts = /* @__PURE__ */ new Map();
 	mountOperationQueue = Promise.resolve();
 	currentRuntime;
-	transport = "http";
-	/**
-	* True once transport has been written to storage at least once (either
-	* via setTransport or restored on cold start). Gates the idempotency
-	* check so a first explicit call persists even when the requested value
-	* already equals the env-derived in-memory default.
-	*/
-	hasStoredTransport = false;
 	backupBucket = null;
 	/**
 	* Serializes backup operations to prevent concurrent create/restore on the same sandbox.
@@ -6201,63 +4501,40 @@ var Sandbox = class Sandbox extends Container {
 		return fn.apply(client, args);
 	}
 	/**
-	* Compute the transport retry budget from current container timeouts.
+	* Compute the control-channel upgrade retry budget from current container
+	* timeouts.
 	*
 	* The budget covers the full container startup window (instance provisioning
-	* + port readiness) plus a 30s margin for the maximum single backoff delay
-	* (capped at 30s in BaseTransport). The 120s floor preserves the previous
-	* default for short timeout configurations.
+	* + port readiness) plus a 30s margin for the maximum single backoff delay.
+	* The 120s floor preserves the default for short timeout configurations.
 	*/
 	computeRetryTimeoutMs() {
 		const startupBudgetMs = this.containerTimeouts.instanceGetTimeoutMS + this.containerTimeouts.portReadyTimeoutMS;
 		return Math.max(12e4, startupBudgetMs + 3e4);
 	}
 	/**
-	* Create the route-based compatibility client with current HTTP/WebSocket
-	* transport settings.
+	* Create the single control-plane client used for all SDK operations.
 	*/
-	createSandboxClient() {
-		return new SandboxClient({
-			logger: this.logger,
-			port: 3e3,
+	createClient() {
+		const self = this;
+		return new ContainerControlClient({
 			stub: this,
+			port: 3e3,
+			logger: this.logger,
 			retryTimeoutMs: this.computeRetryTimeoutMs(),
-			defaultHeaders: { "X-Sandbox-Id": this.ctx.id.toString() },
-			...this.transport === "websocket" && {
-				transportMode: "websocket",
-				wsUrl: "ws://localhost:3000/ws"
+			localMain: this.controlCallback,
+			onActivity: () => {
+				this.renewActivityTimeout();
+			},
+			onSessionBusy: () => {
+				self.inflightRequests = (self.inflightRequests ?? 0) + 1;
+			},
+			onSessionIdle: () => {
+				self.inflightRequests = Math.max(0, (self.inflightRequests ?? 0) - 1);
+				if (self.inflightRequests === 0) this.renewActivityTimeout();
 			}
 		});
 	}
-	/**
-	* Create the appropriate client for the configured control path.
-	*
-	* `rpc` currently selects the primary container-control client. `http` and
-	* `websocket` select the route-based compatibility client.
-	*/
-	createClientForTransport(transport) {
-		if (transport === "rpc") {
-			const self = this;
-			return new ContainerControlClient({
-				stub: this,
-				port: 3e3,
-				logger: this.logger,
-				retryTimeoutMs: this.computeRetryTimeoutMs(),
-				localMain: this.controlCallback,
-				onActivity: () => {
-					this.renewActivityTimeout();
-				},
-				onSessionBusy: () => {
-					self.inflightRequests++;
-				},
-				onSessionIdle: () => {
-					self.inflightRequests = Math.max(0, self.inflightRequests - 1);
-					if (self.inflightRequests === 0) this.renewActivityTimeout();
-				}
-			});
-		}
-		return this.createSandboxClient();
-	}
 	constructor(ctx, env$1) {
 		super(ctx, env$1);
 		const envObj = env$1;
@@ -6270,10 +4547,6 @@ var Sandbox = class Sandbox extends Container {
 			sandboxId: this.ctx.id.toString()
 		});
 		this.currentRuntime = new CurrentRuntimeIdentity(this.ctx.storage, () => this.getState(), () => this.ctx.container?.running === true);
-		const transportEnv = envObj?.SANDBOX_TRANSPORT;
-		if (transportEnv === "websocket" || transportEnv === "rpc") this.transport = transportEnv;
-		else if (transportEnv != null && transportEnv !== "http") this.logger.warn(`Invalid SANDBOX_TRANSPORT value: "${transportEnv}". Must be "http", "websocket", or "rpc". Defaulting to "http".`);
-		this.logger.info(`Using ${this.transport} transport`);
 		const backupBucket = envObj?.BACKUP_BUCKET;
 		if (isR2Bucket(backupBucket)) this.backupBucket = backupBucket;
 		this.r2AccountId = getEnvString(envObj, "CLOUDFLARE_R2_ACCOUNT_ID") ?? getEnvString(envObj, "CLOUDFLARE_ACCOUNT_ID") ?? null;
@@ -6332,7 +4605,7 @@ var Sandbox = class Sandbox extends Container {
 			secretAccessKey: this.r2SecretAccessKey
 		});
 		this.controlCallback = new SandboxControlCallbackImpl(() => this.tunnelExitHandler, this.logger);
-		this.client = this.createClientForTransport(this.transport);
+		this.client = this.createClient();
 		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 		this.ctx.blockConcurrencyWhile(async () => {
 			this.sandboxName = await this.ctx.storage.get("sandboxName") ?? null;
@@ -6353,18 +4626,6 @@ var Sandbox = class Sandbox extends Container {
 				this.sleepAfter = storedSleepAfter;
 				this.renewActivityTimeout();
 			}
-			const storedTransport = await this.ctx.storage.get("transport");
-			if (storedTransport && storedTransport !== this.transport) {
-				this.transport = storedTransport;
-				const previousClient = this.client;
-				this.client = this.createClientForTransport(storedTransport);
-				this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
-				this.tunnelsHandler = null;
-				this.tunnelExitHandler = null;
-				this.destroyAllTunnels = null;
-				previousClient.disconnect();
-			}
-			if (storedTransport) this.hasStoredTransport = true;
 			if (this.interceptHttps) this.envVars = {
 				...this.envVars,
 				SANDBOX_INTERCEPT_HTTPS: "1"
@@ -6383,7 +4644,6 @@ var Sandbox = class Sandbox extends Container {
 		if (configuration.sleepAfter !== void 0) await this.setSleepAfter(configuration.sleepAfter);
 		if (configuration.keepAlive !== void 0) await this.setKeepAlive(configuration.keepAlive);
 		if (configuration.containerTimeouts !== void 0) await this.setContainerTimeouts(configuration.containerTimeouts);
-		if (configuration.transport !== void 0) await this.setTransport(configuration.transport);
 	}
 	async setSleepAfter(sleepAfter) {
 		if (this.sleepAfter === sleepAfter) return;
@@ -6429,25 +4689,6 @@ var Sandbox = class Sandbox extends Container {
 		this.client.setRetryTimeoutMs(this.computeRetryTimeoutMs());
 		this.logger.debug("Container timeouts updated", this.containerTimeouts);
 	}
-	async setTransport(transport) {
-		if (transport !== "http" && transport !== "websocket" && transport !== "rpc") {
-			this.logger.warn(`Invalid transport value: "${transport}". Must be "http", "websocket", or "rpc". Ignoring.`);
-			return;
-		}
-		if (this.hasStoredTransport && this.transport === transport) return;
-		await this.ctx.storage.put("transport", transport);
-		const previousClient = this.client;
-		this.transport = transport;
-		this.hasStoredTransport = true;
-		this.client = this.createClientForTransport(transport);
-		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
-		this.tunnelsHandler = null;
-		this.tunnelExitHandler = null;
-		this.destroyAllTunnels = null;
-		previousClient.disconnect();
-		this.renewActivityTimeout();
-		this.logger.debug("Transport updated", { transport });
-	}
 	validateTimeout(value, name, min, max) {
 		if (typeof value !== "number" || Number.isNaN(value) || !Number.isFinite(value)) throw new Error(`${name} must be a valid finite number, got ${value}`);
 		if (value < min || value > max) throw new Error(`${name} must be between ${min}-${max}ms, got ${value}ms`);
@@ -8464,7 +6705,8 @@ var Sandbox = class Sandbox extends Container {
 	}
 	/**
 	* Namespaced tunnel API. Quick tunnels are zero-config preview URLs
-	* backed by Cloudflare's trycloudflare service.
+	* backed by Cloudflare's trycloudflare service. Named tunnels bind a
+	* stable hostname under the configured Cloudflare zone.
 	*
 	* - `tunnels.get(port)` — idempotent. Returns the cached tunnel for
 	*   `port` if one exists in DO storage, otherwise spawns a fresh
@@ -8474,12 +6716,11 @@ var Sandbox = class Sandbox extends Container {
 	* - `tunnels.destroy(portOrInfo)` — tear down by port number or by
 	*   the record returned from `get()`.
 	*
-	* Storage is cleared on container restart (`onStart`), so URLs do
-	* not survive a container restart — the next `get(port)` call will
-	* spawn a fresh tunnel with a new URL.
-	*
-	* Requires the RPC transport. Calling this on a route-based transport
-	* throws "RPC transport required".
+	* Container restarts drop quick-tunnel records because their
+	* `*.trycloudflare.com` URLs are tied to the dead cloudflared process.
+	* Named-tunnel records stay in storage and are marked for respawn so the
+	* next `get(port, { name })` call reuses the Cloudflare tunnel and DNS
+	* record while starting a fresh cloudflared process.
 	*/
 	get tunnels() {
 		this.ensureTunnelsBuilt();
@@ -8488,8 +6729,7 @@ var Sandbox = class Sandbox extends Container {
 	/**
 	* Lazily construct both the public tunnels handler and its sibling
 	* exit-handler callback. Called from the `tunnels` getter on first
-	* access and on every access after a transport swap clears both
-	* fields.
+	* access.
 	*/
 	ensureTunnelsBuilt() {
 		if (this.tunnelsHandler) return;
@@ -9856,34 +8096,18 @@ var Sandbox = class Sandbox extends Container {
 			backupSession = await this.ensureBackupSession();
 			const archivePath = `${BACKUP_CONTAINER_DIR}/${id}.sqsh`;
 			await this.execWithSession(`mkdir -p ${BACKUP_CONTAINER_DIR}`, backupSession, { origin: "internal" });
-			if (this.transport === "rpc") {
-				const body = archiveObject.body;
-				if (!body) throw new BackupRestoreError({
-					message: `R2 archive object has no body stream for backup ${id}`,
-					code: ErrorCode.BACKUP_RESTORE_FAILED,
-					httpStatus: 500,
-					context: {
-						dir,
-						backupId: id
-					},
-					timestamp: (/* @__PURE__ */ new Date()).toISOString()
-				});
-				await this.client.files.writeFileStream(archivePath, body, backupSession);
-			} else {
-				const archiveBuffer = await archiveObject.arrayBuffer();
-				const base64Content = Buffer.from(archiveBuffer).toString("base64");
-				const writeResult = await this.client.files.writeFile(archivePath, base64Content, backupSession, { encoding: "base64" });
-				if (!writeResult.success) throw new BackupRestoreError({
-					message: `Failed to write backup archive to ${archivePath}: ${"error" in writeResult && typeof writeResult.error === "object" && writeResult.error !== null && "message" in writeResult.error && typeof writeResult.error.message === "string" ? writeResult.error.message : `File write returned success: false for '${archivePath}'`}`,
-					code: ErrorCode.BACKUP_RESTORE_FAILED,
-					httpStatus: 500,
-					context: {
-						dir,
-						backupId: id
-					},
-					timestamp: (/* @__PURE__ */ new Date()).toISOString()
-				});
-			}
+			const body = archiveObject.body;
+			if (!body) throw new BackupRestoreError({
+				message: `R2 archive object has no body stream for backup ${id}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId: id
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			await this.client.files.writeFileStream(archivePath, body, backupSession);
 			const extractResult = await this.execWithSession(`/usr/bin/unsquashfs -f -d ${shellEscape(dir)} ${shellEscape(archivePath)}`, backupSession, { origin: "internal" });
 			if (extractResult.exitCode !== 0) throw new BackupRestoreError({
 				message: `unsquashfs extraction failed (exit code ${extractResult.exitCode}): ${extractResult.stderr}`,
@@ -9983,5 +8207,5 @@ var Sandbox = class Sandbox extends Container {
 };
 
 //#endregion
-export { FileClient as A, RPCTransportError as B, collectFile as C, ProcessClient as D, UtilityClient as E, BackupNotFoundError as F, BackupRestoreError as I, InvalidBackupConfigError as L, BackupClient as M, BackupCreateError as N, PortClient as O, BackupExpiredError as P, ProcessExitedBeforeReadyError as R, validateTunnelName as S, SandboxClient as T, SessionTerminatedError as V, responseToAsyncIterable as _, PREVIEW_PROXY_HEADER as a, sanitizeSandboxId as b, PREVIEW_PROXY_SANDBOX_ID_HEADER as c, BucketUnmountError as d, InvalidMountConfigError as f, parseSSEStream as g, asyncIterableToSSEStream as h, proxyTerminal as i, CommandClient as j, GitClient as k, PREVIEW_PROXY_TOKEN_HEADER as l, S3FSMountError as m, Sandbox as n, PREVIEW_PROXY_HEADERS as o, MissingCredentialsError as p, getSandbox as r, PREVIEW_PROXY_PORT_HEADER as s, ContainerProxy$1 as t, BucketMountError as u, CodeInterpreter as v, streamFile as w, validatePort as x, SandboxSecurityError as y, ProcessReadyTimeoutError as z };
-//# sourceMappingURL=sandbox-Duj2gvUC.js.map
+export { ProcessExitedBeforeReadyError as A, collectFile as C, BackupNotFoundError as D, BackupExpiredError as E, RPCTransportError as M, SessionTerminatedError as N, BackupRestoreError as O, validateTunnelName as S, BackupCreateError as T, proxyTerminal as _, BucketUnmountError as a, sanitizeSandboxId as b, S3FSMountError as c, responseToAsyncIterable as d, PREVIEW_PROXY_HEADER as f, PREVIEW_PROXY_TOKEN_HEADER as g, PREVIEW_PROXY_SANDBOX_ID_HEADER as h, BucketMountError as i, ProcessReadyTimeoutError as j, InvalidBackupConfigError as k, asyncIterableToSSEStream as l, PREVIEW_PROXY_PORT_HEADER as m, Sandbox as n, InvalidMountConfigError as o, PREVIEW_PROXY_HEADERS as p, getSandbox as r, MissingCredentialsError as s, ContainerProxy$1 as t, parseSSEStream as u, CodeInterpreter as v, streamFile as w, validatePort as x, SandboxSecurityError as y };
+//# sourceMappingURL=sandbox-B7ewRruX.js.map