@cloudflare/sandbox 0.12.1 → 0.13.0-next.633.1

package/dist/{sandbox-DKG3H156.js → sandbox-C9CHzLDx.js}

@@ -1,5 +1,5 @@
-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 { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-aRUdk9K8.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-CpoDEfUZ.js";
 import { Container, ContainerProxy, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import { RpcSession, RpcTarget } from "capnweb";
@@ -629,6 +629,12 @@ var BackupRestoreError = class extends SandboxError {
 		return this.context.backupId;
 	}
 };
+var ContainerUnavailableError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ContainerUnavailableError";
+	}
+};
 /**
 * Raised when the capnweb WebSocket session itself fails on the SDK side.
 * Unlike the rest of the SandboxError tree, the container never produces
@@ -710,6 +716,7 @@ function createErrorFromResponse(errorResponse, options) {
 		case ErrorCode.INTERPRETER_NOT_READY: return new InterpreterNotReadyError(errorResponse);
 		case ErrorCode.CONTEXT_NOT_FOUND: return new ContextNotFoundError(errorResponse);
 		case ErrorCode.CODE_EXECUTION_ERROR: return new CodeExecutionError(errorResponse);
+		case ErrorCode.CONTAINER_UNAVAILABLE: return new ContainerUnavailableError(errorResponse);
 		case ErrorCode.RPC_TRANSPORT_ERROR: return new RPCTransportError(errorResponse, options);
 		case ErrorCode.VALIDATION_FAILED: return new ValidationFailedError(errorResponse);
 		case ErrorCode.INVALID_JSON_RESPONSE:
@@ -720,2719 +727,1098 @@ function createErrorFromResponse(errorResponse, options) {
 }
 
 //#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);
-}
+//#region src/file-stream.ts
 /**
-* 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.
+* Parse SSE (Server-Sent Events) lines from a stream
 */
-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;
+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 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++;
+		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();
 	}
 }
-
-//#endregion
-//#region src/clients/transport/base-transport.ts
 /**
-* Container startup retry configuration
+* 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);
+*   }
+* }
+* ```
 */
-const DEFAULT_RETRY_TIMEOUT_MS$1 = 12e4;
-const MIN_TIME_FOR_RETRY_MS$1 = 15e3;
+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");
+}
 /**
-* Abstract base transport with shared retry logic
+* Collect an entire file into memory from a stream
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns Object containing the file content and metadata
 *
-* 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.txt');
+* const { content, metadata } = await collectFile(stream);
+* console.log('Content:', content);
+* console.log('MIME type:', metadata.mimeType);
+* ```
 */
-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;
-	}
-	getRetryTimeoutMs() {
-		return this.retryTimeoutMs;
-	}
-	/**
-	* 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) {
-		return fetchWithResponseRetry(() => this.doFetch(path$1, options), {
-			retryTimeoutMs: this.retryTimeoutMs,
-			minTimeForRetryMs: MIN_TIME_FOR_RETRY_MS$1,
-			logger: this.logger,
-			retryLogMessage: "Container not ready, retrying",
-			shouldRetry: (response) => response.status === 503,
-			getRetryLogContext: () => ({ mode: this.getMode() }),
-			onRetryExhausted: ({ attempts, elapsedMs }) => {
-				this.logger.error("Container failed to become ready", /* @__PURE__ */ new Error(`Failed after ${attempts} attempts over ${Math.floor(elapsedMs / 1e3)}s`));
-			}
-		});
-	}
-	/**
-	* 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);
+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();
 	}
-	/**
-	* 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
-		};
-		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}`);
+	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;
 		}
-		if (!response.body) throw new Error("No response body for streaming");
-		return response.body;
-	}
-};
+		return {
+			content: combined,
+			metadata
+		};
+	} 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)
 */
-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 validatePort(port) {
+	if (!Number.isInteger(port)) return false;
+	if (port < 1024 || port > 65535) return false;
+	if ([3e3].includes(port)) return false;
+	return true;
+}
 /**
-* WebSocket transport implementation
-*
-* Multiplexes HTTP-like requests over a single WebSocket connection.
-* Useful when running inside Workers/DO where sub-request limits apply.
+* Sanitizes and validates sandbox IDs for DNS compliance and security
+* Only enforces critical requirements - allows maximum developer flexibility
 */
-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";
-	}
-	/**
-	* Check if WebSocket is connected
-	*/
-	isConnected() {
-		return this.state === "connected" && this.ws?.readyState === WebSocket.OPEN;
-	}
-	/**
-	* Connect to the WebSocket server
-	*
-	* The connection promise is assigned synchronously so concurrent
-	* callers share the same connection attempt.
-	*/
-	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;
-		}
-	}
-	/**
-	* Disconnect from the WebSocket server
-	*/
-	disconnect() {
-		this.cleanup();
-	}
-	/**
-	* 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.
-	*/
-	isWebSocketConnecting() {
-		return this.state === "connecting";
-	}
-	/**
-	* 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()`.
-	*/
-	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" }
-		});
-	}
-	/**
-	* Streaming fetch implementation.
-	*
-	* Delegates to `requestStream()`, which applies the re-entrancy guard.
-	*/
-	async fetchStream(path$1, body, method = "POST", headers) {
-		return this.requestStream(method, path$1, body, headers);
-	}
-	/**
-	* Parse request body from RequestInit
-	*/
-	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)}`);
-		}
-		throw new Error(`WebSocket transport only supports string bodies. Got: ${typeof body}`);
-	}
-	/**
-	* Normalize RequestInit headers into a plain object for WSRequest.
-	*/
-	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;
+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
+*/
+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");
+}
+/**
+* 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>`.
+*
+* Throws `SandboxSecurityError` on any violation. Designed to be called
+* before any other tunnel work so callers see a fast, deterministic
+* failure.
+*/
+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;
 	}
 	/**
-	* Internal connection logic
+	* Create a new code execution context
 	*/
-	async doConnect() {
-		this.state = "connecting";
-		if (this.config.stub) await this.connectViaFetch();
-		else await this.connectViaWebSocket();
-	}
-	async fetchUpgradeWithRetry(attemptUpgrade) {
-		return fetchWithResponseRetry(attemptUpgrade, {
-			retryTimeoutMs: this.getRetryTimeoutMs(),
-			minTimeForRetryMs: MIN_TIME_FOR_CONNECT_RETRY_MS,
-			logger: this.logger,
-			retryLogMessage: "WebSocket upgrade returned retryable status, retrying",
-			shouldRetry: isRetryableWebSocketUpgradeResponse
-		});
+	async createCodeContext(options = {}) {
+		validateLanguage(options.language);
+		const context = await this.getInterpreterClient().createCodeContext(options);
+		this.contexts.set(context.id, context);
+		return context;
 	}
 	/**
-	* 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.
+	* Run code with optional context
 	*/
-	async connectViaFetch() {
-		const timeoutMs = this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS$1;
-		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));
-			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();
-			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 });
-		} catch (error) {
-			this.state = "error";
-			this.logger.error("WebSocket fetch connection failed", error instanceof Error ? error : new Error(String(error)));
-			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);
+	async runCode(code, options = {}) {
+		let context = options.context;
+		if (!context) {
+			const language = options.language || "python";
+			context = await this.getOrCreateDefaultContext(language);
 		}
-	}
-	/**
-	* Connect using standard WebSocket API (browser/Node style)
-	*/
-	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);
-			}
-		});
-	}
-	/**
-	* 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).
-	*/
-	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);
-				},
-				isStreaming: false,
-				timeoutId
-			});
-			try {
-				this.send(request);
-			} catch (error) {
-				clearTimeout(timeoutId);
-				this.pendingRequests.delete(id);
-				this.scheduleIdleDisconnect();
-				reject(error instanceof Error ? error : new Error(String(error)));
-			}
-		});
-	}
-	/**
-	* 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)));
+		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;
 	}
 	/**
-	* 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
-		});
-	}
-	/**
-	* 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
-		});
-		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();
-		}
-	}
-	/**
-	* 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);
-	}
-	/**
-	* Handle an error message
+	* Run code and return a streaming response
 	*/
-	handleError(error) {
-		if (error.id) {
-			const pending = this.pendingRequests.get(error.id);
-			if (pending) {
-				pending.reject(/* @__PURE__ */ new Error(`${error.code}: ${error.message}`));
-				return;
-			}
+	async runCodeStream(code, options = {}) {
+		let context = options.context;
+		if (!context) {
+			const language = options.language || "python";
+			context = await this.getOrCreateDefaultContext(language);
 		}
-		this.logger.error("WebSocket error message", new Error(error.message), {
-			code: error.code,
-			status: error.status
-		});
+		return this.getInterpreterClient().streamCode(context.id, code, options.language);
 	}
 	/**
-	* Handle WebSocket close
+	* List all code contexts
 	*/
-	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();
+	async listCodeContexts() {
+		const contexts = await this.getInterpreterClient().listCodeContexts();
+		for (const context of contexts) this.contexts.set(context.id, context);
+		return contexts;
 	}
 	/**
-	* Cleanup resources
+	* Delete a code context
 	*/
-	cleanup() {
-		this.clearIdleDisconnectTimer();
-		if (this.ws) {
-			this.ws.removeEventListener("close", this.boundHandleClose);
-			this.ws.removeEventListener("message", this.boundHandleMessage);
-			this.ws.close();
-			this.ws = null;
-		}
-		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);
+	async deleteCodeContext(contextId) {
+		await this.getInterpreterClient().deleteCodeContext(contextId);
+		this.contexts.delete(contextId);
 	}
-	clearIdleDisconnectTimer() {
-		if (this.idleDisconnectTimer) {
-			clearTimeout(this.idleDisconnectTimer);
-			this.idleDisconnectTimer = null;
-		}
+	async getOrCreateDefaultContext(language) {
+		for (const context of this.contexts.values()) if (context.language === language) return context;
+		return this.createCodeContext({ language });
 	}
 };
 
 //#endregion
-//#region src/clients/transport/factory.ts
-/**
-* Create a route-based compatibility transport instance based on mode.
-*
-* Selects the HTTP or custom WebSocket transport for the route-based client
-* layer.
-*
-* @example
-* ```typescript
-* // HTTP transport (default)
-* const http = createTransport({
-*   mode: 'http',
-*   baseUrl: 'http://localhost:3000'
-* });
-*
-* // WebSocket transport
-* const ws = createTransport({
-*   mode: 'websocket',
-*   wsUrl: 'ws://localhost:3000/ws'
-* });
-* ```
+//#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.
 */
-function createTransport(options) {
-	switch (options.mode) {
-		case "http": return new HttpTransport(options);
-		case "websocket": return new WebSocketTransport(options);
+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/clients/base-client.ts
+//#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;
+function isErrorResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.code === "string" && Object.values(ErrorCode).includes(candidate.code) && typeof candidate.message === "string" && typeof candidate.httpStatus === "number" && typeof candidate.timestamp === "string" && typeof candidate.context === "object" && candidate.context !== null;
+}
 /**
-* Abstract base class for route-based HTTP/WebSocket compatibility clients.
-*
-* 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
+* Manages a capnweb WebSocket RPC session to the container.
 *
-* DO-to-container control-channel capabilities live in `container-control/`.
-* This layer supports the route-based compatibility API.
+* 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 BaseHttpClient = class {
-	options;
-	logger;
+var ContainerControlConnection = class {
+	stub;
+	session;
 	transport;
-	constructor(options = {}) {
-		this.options = options;
+	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();
-		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
-		});
+		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();
 	}
 	/**
-	* Update the transport's 503 retry budget
+	* 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.
 	*/
-	setRetryTimeoutMs(ms) {
-		this.transport.setRetryTimeoutMs(ms);
+	rpc() {
+		if (!this.connected && !this.connectPromise) this.connect().catch(() => {});
+		return this.stub;
 	}
 	/**
-	* Check if using WebSocket transport
+	* 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).
 	*/
-	isWebSocketMode() {
-		return this.transport.getMode() === "websocket";
+	getStats() {
+		return this.session.getStats();
 	}
-	/**
-	* 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);
+	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;
 	}
 	/**
-	* Make a POST request with JSON body
+	* 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.
 	*/
-	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);
+	setRetryTimeoutMs(ms) {
+		this.retryTimeoutMs = ms;
 	}
 	/**
-	* Make a GET request
+	* 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 get(endpoint, responseHandler) {
-		const response = await this.doFetch(endpoint, { method: "GET" });
-		return await this.handleResponse(response, responseHandler);
+	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) });
+		}
 	}
 	/**
-	* Make a DELETE request
+	* 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 delete(endpoint, responseHandler) {
-		const response = await this.doFetch(endpoint, { method: "DELETE" });
-		return await this.handleResponse(response, responseHandler);
-	}
+	onWebSocketClose = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		this.logger.debug("ContainerControlConnection WebSocket closed");
+		if (wasConnected) this.fireOnClose();
+	};
 	/**
-	* Handle HTTP response with error checking and parsing
+	* WebSocket `error` listener. Same field-form rationale as
+	* {@link onWebSocketClose}.
 	*/
-	async handleResponse(response, customHandler) {
-		if (!response.ok) await this.handleErrorResponse(response);
-		if (customHandler) return customHandler(response);
+	onWebSocketError = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		if (wasConnected) this.fireOnClose();
+	};
+	async doConnect() {
 		try {
-			return await response.json();
+			const response = await this.fetchUpgradeWithRetry();
+			if (response.status !== 101) {
+				const structuredError = await this.parseStructuredUpgradeError(response);
+				if (structuredError) throw createErrorFromResponse(structuredError);
+				if (isRetryableWebSocketUpgradeResponse(response)) throw createErrorFromResponse({
+					code: ErrorCode.CONTAINER_UNAVAILABLE,
+					message: "Container is starting. Please retry in a moment.",
+					context: { reason: "startup" },
+					httpStatus: 503,
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					suggestion: "The container is not ready yet. Retry the operation in a moment."
+				});
+				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) {
-			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()
-			});
+			this.connected = false;
+			this.transport.abort(error);
+			this.logger.error("ContainerControlConnection failed", error instanceof Error ? error : new Error(String(error)));
+			this.fireOnClose();
+			throw error;
 		}
 	}
-	/**
-	* Handle error responses with consistent error throwing
-	*/
-	async handleErrorResponse(response) {
-		let errorData;
+	async parseStructuredUpgradeError(response) {
+		if (!(response.headers.get("Content-Type") ?? "").includes("application/json")) return null;
+		let body;
 		try {
-			errorData = await response.json();
+			body = await response.clone().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()
-			};
+			return null;
 		}
-		const error = createErrorFromResponse(errorData);
-		this.options.onError?.(errorData.message, void 0);
-		throw error;
+		if (!isErrorResponse(body)) return null;
+		return body;
 	}
 	/**
-	* Create a streaming response handler for Server-Sent Events
+	* 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.
 	*/
-	async handleStreamResponse(response) {
-		if (!response.ok) await this.handleErrorResponse(response);
-		if (!response.body) throw new Error("No response body for streaming");
-		return response.body;
+	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
+		});
 	}
 	/**
-	* 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)
+	* 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 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);
+	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);
+		}
 	}
 };
-
-//#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.
+* 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 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);
+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 = [];
 	}
-	/**
-	* 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 send(message) {
+		if (this.#ws) this.#ws.send(message);
+		else this.#sendQueue.push(message);
 	}
-	async uploadParts(request, sessionId) {
-		return this.post("/api/backup/upload-parts", {
-			...request,
-			sessionId: sessionId ?? request.sessionId
+	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;
 		});
 	}
-};
-
-//#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;
+	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);
 		}
 	}
-	/**
-	* 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;
-		}
+	#fail(err) {
+		if (this.#error) return;
+		this.#error = err;
+		this.#receiveRejecter?.(err);
+		this.#receiveResolver = void 0;
+		this.#receiveRejecter = void 0;
 	}
 };
 
 //#endregion
-//#region src/clients/file-client.ts
+//#region src/container-control/client.ts
+/** Close the idle capnweb WebSocket promptly so the DO can sleep. */
+const DEFAULT_IDLE_DISCONNECT_MS = 1e3;
 /**
-* Client for file system operations
+* 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.
 */
-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
+const BUSY_POLL_INTERVAL_MS = 1e3;
 /**
-* Client for Git repository operations
+* Baseline getStats() values for an idle session. The bootstrap stub on each
+* side accounts for 1 import and 1 export.
 */
-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,
+const IDLE_IMPORT_THRESHOLD = 1;
+const IDLE_EXPORT_THRESHOLD = 1;
+function isLocalSandboxError(error) {
+	if (!("errorResponse" in error)) return false;
+	const response = error.errorResponse;
+	return typeof response?.code === "string" && Object.hasOwn(ErrorCode, response.code) && typeof response.message === "string" && typeof response.httpStatus === "number" && typeof response.timestamp === "string" && typeof response.context === "object" && response.context !== null;
+}
+/**
+* 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) {
+		if (isLocalSandboxError(error)) throw 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,
-				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" }
+				message: error.message,
+				context,
+				httpStatus: getHttpStatus(code),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			if (!response.ok) throw await this.parseErrorResponse(response);
+		}
+		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 });
 	}
-	/**
-	* 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
+	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
+}
 /**
-* Client for health checks and utility operations
+* 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.
 */
-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.");
+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";
 	}
-};
-
-//#endregion
-//#region src/clients/watch-client.ts
+	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()
+	};
+}
 /**
-* Client for file watch operations
-* Uses inotify under the hood for native filesystem event notifications
+* 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.
 *
-* @internal This client is used internally by the SDK.
-* Users should use `sandbox.watch()` or `sandbox.checkChanges()` instead.
+* 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.
 */
-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;
+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 {
-				event = JSON.parse(eventData);
-			} catch {
-				return;
+				const result = Reflect.apply(value, target, args);
+				if (result != null && typeof result.then === "function") return result.catch(translateRPCError);
+				return result;
+			} catch (err) {
+				translateRPCError(err);
 			}
-			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.
+* Sandbox control 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.
 *
-* 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.
+* 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 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;
+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) {
-		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
-			mode: options.transportMode,
-			wsUrl: options.wsUrl,
-			baseUrl: options.baseUrl,
-			logger: options.logger,
+		this.connOptions = {
 			stub: options.stub,
 			port: options.port,
-			retryTimeoutMs: options.retryTimeoutMs
-		});
-		const clientOptions = {
-			baseUrl: "http://localhost:3000",
-			...options,
-			transport: this.transport ?? options.transport
+			localMain: options.localMain,
+			logger: options.logger,
+			retryTimeoutMs: options.retryTimeoutMs,
+			onClose: () => {
+				if (this.conn) this.destroyConnection();
+			}
 		};
-		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);
+		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;
 	}
 	/**
-	* Update the transport retry budget 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.
+	* Return the current connection, creating one when the client is disconnected.
+	* Starts the busy-poll timer the first time a connection is materialized.
 	*/
-	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);
+	getConnection() {
+		if (!this.conn) {
+			this.conn = new ContainerControlConnection(this.connOptions);
+			this.startBusyPoll();
 		}
+		return this.conn;
 	}
 	/**
-	* Get the current transport mode
-	*/
-	getTransportMode() {
-		return this.transport?.getMode() ?? "http";
-	}
-	/**
-	* Check if WebSocket is connected (only relevant in WebSocket mode)
+	* 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.
 	*/
-	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;
-/**
-* 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();
-	}
+	renewActivity = () => {
+		this.onActivity?.();
+	};
 	/**
-	* Get the typed RPC stub.
+	* 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.
 	*
-	* The stub is available immediately — calls made before connect()
-	* completes are queued in the deferred transport and flushed once
-	* the WebSocket is established.
+	* 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.
 	*/
-	rpc() {
-		if (!this.connected && !this.connectPromise) this.connect().catch(() => {});
-		return this.stub;
+	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);
 	}
-	/**
-	* 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();
+	stopBusyPoll() {
+		if (this.busyPollTimer) {
+			clearInterval(this.busyPollTimer);
+			this.busyPollTimer = null;
+		}
 	}
-	isConnected() {
-		return this.connected;
+	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);
 	}
-	async connect() {
-		if (this.connected) return;
-		if (this.connectPromise) return this.connectPromise;
-		this.connectPromise = this.doConnect();
-		try {
-			await this.connectPromise;
-		} finally {
-			this.connectPromise = null;
+	clearIdleTimer() {
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = 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;
+	destroyConnection() {
+		this.stopBusyPoll();
+		this.clearIdleTimer();
+		if (this.busy) {
+			this.busy = false;
+			this.onSessionIdle?.();
+		}
+		if (this.conn) {
+			this.conn.disconnect();
+			this.conn = null;
 		}
-		this.connected = false;
-		this.connectPromise = null;
 	}
-	/**
-	* 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. Mirrors `WebSocketTransport.setRetryTimeoutMs`.
-	*/
-	setRetryTimeoutMs(ms) {
-		this.retryTimeoutMs = ms;
+	get commands() {
+		return wrapStub(this.getConnection().rpc().commands, this.renewActivity);
 	}
-	/**
-	* 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) });
-		}
+	get files() {
+		return wrapStub(this.getConnection().rpc().files, this.renewActivity);
 	}
-	/**
-	* 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;
-		}
+	get processes() {
+		return wrapStub(this.getConnection().rpc().processes, this.renewActivity);
 	}
-	/**
-	* 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.
-	*/
-	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
-		});
+	get ports() {
+		return wrapStub(this.getConnection().rpc().ports, this.renewActivity);
 	}
-	/**
-	* 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);
-		}
-	}
-};
-/**
-* 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 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}`);
+	get git() {
+		return wrapStub(this.getConnection().rpc().git, this.renewActivity);
 	}
-	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();
+	get utils() {
+		return wrapStub(this.getConnection().rpc().utils, this.renewActivity);
 	}
-	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";
+	get backup() {
+		return wrapStub(this.getConnection().rpc().backup, this.renewActivity);
 	}
-};
-/**
-* 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
-*/
-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");
-}
-/**
-* 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>`.
-*
-* Throws `SandboxSecurityError` on any violation. Designed to be called
-* before any other tunnel work so callers see a fast, deterministic
-* failure.
-*/
-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;
+	get watch() {
+		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
 	}
-	/**
-	* Create a new code execution context
-	*/
-	async createCodeContext(options = {}) {
-		validateLanguage(options.language);
-		const context = await this.getInterpreterClient().createCodeContext(options);
-		this.contexts.set(context.id, context);
-		return context;
+	get tunnels() {
+		return wrapStub(this.getConnection().rpc().tunnels, this.renewActivity);
 	}
-	/**
-	* Run code with optional context
-	*/
-	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;
+	get interpreter() {
+		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
 	}
 	/**
-	* Run code and return a streaming response
+	* 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 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);
+	setRetryTimeoutMs(ms) {
+		this.connOptions.retryTimeoutMs = ms;
+		this.conn?.setRetryTimeoutMs(ms);
 	}
-	/**
-	* List all code contexts
-	*/
-	async listCodeContexts() {
-		const contexts = await this.getInterpreterClient().listCodeContexts();
-		for (const context of contexts) this.contexts.set(context.id, context);
-		return contexts;
+	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();
 	}
 };
 
@@ -4099,24 +2485,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) {
@@ -4129,20 +2497,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/\"";
@@ -5521,10 +3875,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.");
@@ -5803,11 +4156,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) => {
@@ -5834,7 +4185,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.1";
+const SDK_VERSION = "0.13.0-next.633.1";
 
 //#endregion
 //#region src/sandbox.ts
@@ -5901,6 +4252,8 @@ const BACKUP_MULTIPART_MAX_PARTS = 64;
 const BACKUP_DOWNLOAD_PARALLEL_PARTS = 8;
 const BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE = 10 * 1024 * 1024;
 const BACKUP_DOWNLOAD_MAX_PARTS = 64;
+const DEFAULT_SESSION_INIT_MAX_ATTEMPTS = 2;
+const DEFAULT_SESSION_RESTART_SETTLE_MS = 100;
 /**
 * Calculate the optimal number of parts for multipart upload/download
 * based on archive size. Larger archives benefit from more parallelism.
@@ -5968,11 +4321,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 {
@@ -5983,8 +4335,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) {
@@ -5994,7 +4345,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) {
@@ -6120,14 +4470,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.
@@ -6202,63 +4544,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;
@@ -6271,10 +4590,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;
@@ -6333,7 +4648,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;
@@ -6354,18 +4669,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"
@@ -6384,7 +4687,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;
@@ -6430,25 +4732,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`);
@@ -7272,12 +5555,12 @@ var Sandbox = class Sandbox extends Container {
 		} catch (e) {
 			if (this.isNoInstanceError(e)) {
 				const errorBody$1 = {
-					code: ErrorCode.INTERNAL_ERROR,
+					code: ErrorCode.CONTAINER_UNAVAILABLE,
 					message: "Container is currently provisioning. This can take several minutes on first deployment.",
-					context: { phase: "provisioning" },
+					context: { reason: "provisioning" },
 					httpStatus: 503,
 					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-					suggestion: "This is expected during first deployment. The SDK will retry automatically."
+					suggestion: "The container is still being provisioned. Retry the operation in a moment."
 				};
 				return new Response(JSON.stringify(errorBody$1), {
 					status: 503,
@@ -7319,15 +5602,12 @@ var Sandbox = class Sandbox extends Container {
 					error: e instanceof Error ? e.message : String(e)
 				});
 				const errorBody$1 = {
-					code: ErrorCode.INTERNAL_ERROR,
+					code: ErrorCode.CONTAINER_UNAVAILABLE,
 					message: "Container is starting. Please retry in a moment.",
-					context: {
-						phase: "startup",
-						error: e instanceof Error ? e.message : String(e)
-					},
+					context: { reason: "startup" },
 					httpStatus: 503,
 					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-					suggestion: "The container is booting. The SDK will retry automatically."
+					suggestion: "The container is not ready yet. Retry the operation in a moment."
 				};
 				return new Response(JSON.stringify(errorBody$1), {
 					status: 503,
@@ -7343,15 +5623,12 @@ var Sandbox = class Sandbox extends Container {
 				error: e instanceof Error ? e.message : String(e)
 			});
 			const errorBody = {
-				code: ErrorCode.INTERNAL_ERROR,
+				code: ErrorCode.CONTAINER_UNAVAILABLE,
 				message: "Container is starting. Please retry in a moment.",
-				context: {
-					phase: "startup",
-					error: e instanceof Error ? e.message : String(e)
-				},
+				context: { reason: "startup" },
 				httpStatus: 503,
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-				suggestion: "The SDK will retry automatically. If this persists, the container may need redeployment."
+				suggestion: "The container is not ready yet. Retry the operation in a moment."
 			};
 			return new Response(JSON.stringify(errorBody), {
 				status: 503,
@@ -7597,6 +5874,15 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async ensureDefaultSession() {
 		const sessionId = `sandbox-${this.sandboxName || "default"}`;
+		for (let attempt = 1; attempt <= DEFAULT_SESSION_INIT_MAX_ATTEMPTS; attempt++) try {
+			return await this.getOrInitializeDefaultSession(sessionId);
+		} catch (error) {
+			if (!this.isDefaultSessionInitContainerRestart(error) || attempt === DEFAULT_SESSION_INIT_MAX_ATTEMPTS) throw error;
+			await new Promise((resolve) => setTimeout(resolve, DEFAULT_SESSION_RESTART_SETTLE_MS));
+		}
+		throw new Error("Default session initialization failed unexpectedly");
+	}
+	async getOrInitializeDefaultSession(sessionId) {
 		if (this.defaultSession === sessionId) return this.defaultSession;
 		const generation = this.containerGeneration;
 		const pending = this.defaultSessionInit;
@@ -7614,6 +5900,9 @@ var Sandbox = class Sandbox extends Container {
 			if (this.defaultSessionInit === init) this.defaultSessionInit = null;
 		}
 	}
+	isDefaultSessionInitContainerRestart(error) {
+		return error instanceof ContainerUnavailableError && error.context.reason === "container_restarted";
+	}
 	async initializeDefaultSession(sessionId, generation) {
 		let placementId;
 		try {
@@ -7627,7 +5916,17 @@ var Sandbox = class Sandbox extends Container {
 			placementId = error.containerPlacementId;
 			this.logger.debug("Session exists in container but not in DO state, syncing", { sessionId });
 		}
-		if (generation !== this.containerGeneration) throw new Error("Default session initialization was invalidated by a container stop");
+		if (generation !== this.containerGeneration) throw new ContainerUnavailableError({
+			code: ErrorCode.CONTAINER_UNAVAILABLE,
+			message: "Container restarted while the default session was being initialized.",
+			context: {
+				reason: "container_restarted",
+				sessionId
+			},
+			httpStatus: 503,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			suggestion: "The container restarted while the SDK was preparing the default session. Retry the operation to use the new container."
+		});
 		await this.ctx.storage.put("defaultSession", sessionId);
 		await this.capturePlacementId(placementId);
 		this.defaultSession = sessionId;
@@ -8465,7 +6764,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
@@ -8475,12 +6775,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();
@@ -8489,8 +6788,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;
@@ -9857,34 +8155,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}`,
@@ -9984,5 +8266,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-DKG3H156.js.map
+export { InvalidBackupConfigError as A, collectFile as C, BackupNotFoundError as D, BackupExpiredError as E, ProcessReadyTimeoutError as M, RPCTransportError as N, BackupRestoreError as O, SessionTerminatedError as P, 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, ProcessExitedBeforeReadyError as j, ContainerUnavailableError 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-C9CHzLDx.js.map