@cloudflare/sandbox 0.9.0 → 0.9.2

package/dist/{sandbox-Cf_Wjrzq.js → sandbox-CReFGUtF.js}

@@ -1,7 +1,8 @@
-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-Ilf8VjmX.js";
-import { t as ErrorCode } from "./errors-Dk2rApYI.js";
+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-CBi-O-pF.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
+import { RpcSession } from "capnweb";
 import path from "node:path/posix";
 
 //#region src/errors/classes.ts
@@ -10,8 +11,8 @@ import path from "node:path/posix";
 * Preserves all error information from container
 */
 var SandboxError = class extends Error {
-	constructor(errorResponse) {
-		super(errorResponse.message);
+	constructor(errorResponse, options) {
+		super(errorResponse.message, options);
 		this.errorResponse = errorResponse;
 		this.name = "SandboxError";
 	}
@@ -194,6 +195,9 @@ var SessionAlreadyExistsError = class extends SandboxError {
 	get sessionId() {
 		return this.context.sessionId;
 	}
+	get containerPlacementId() {
+		return this.context.containerPlacementId;
+	}
 };
 /**
 * Error thrown when a session was destroyed while a command was executing
@@ -660,6 +664,30 @@ var DesktopInvalidCoordinatesError = class extends SandboxError {
 		this.name = "DesktopInvalidCoordinatesError";
 	}
 };
+/**
+* Raised when the capnweb WebSocket session itself fails on the SDK side.
+* Unlike the rest of the SandboxError tree, the container never produces
+* this error — it is synthesised by `translateRPCError` from the plain
+* Errors capnweb / DeferredTransport raise when the connection dies.
+*
+* `kind` distinguishes the failure mode (peer close, upgrade failed, etc.)
+* so callers can branch on a structured code instead of substring-matching
+* on the message.
+*
+* Always retryable: the SDK opens a fresh connection on the next call.
+*/
+var RPCTransportError = class extends SandboxError {
+	constructor(errorResponse, options) {
+		super(errorResponse, options);
+		this.name = "RPCTransportError";
+	}
+	get kind() {
+		return this.errorResponse.context.kind;
+	}
+	get originalMessage() {
+		return this.errorResponse.context.originalMessage;
+	}
+};
 
 //#endregion
 //#region src/errors/adapter.ts
@@ -667,7 +695,7 @@ var DesktopInvalidCoordinatesError = class extends SandboxError {
 * Convert ErrorResponse to appropriate Error class
 * Simple switch statement - we trust the container sends correct context
 */
-function createErrorFromResponse(errorResponse) {
+function createErrorFromResponse(errorResponse, options) {
 	switch (errorResponse.code) {
 		case ErrorCode.FILE_NOT_FOUND: return new FileNotFoundError(errorResponse);
 		case ErrorCode.FILE_EXISTS: return new FileExistsError(errorResponse);
@@ -723,6 +751,7 @@ function createErrorFromResponse(errorResponse) {
 		case ErrorCode.DESKTOP_PROCESS_CRASHED: return new DesktopProcessCrashedError(errorResponse);
 		case ErrorCode.DESKTOP_INVALID_OPTIONS: return new DesktopInvalidOptionsError(errorResponse);
 		case ErrorCode.DESKTOP_INVALID_COORDINATES: return new DesktopInvalidCoordinatesError(errorResponse);
+		case ErrorCode.RPC_TRANSPORT_ERROR: return new RPCTransportError(errorResponse, options);
 		case ErrorCode.VALIDATION_FAILED: return new ValidationFailedError(errorResponse);
 		case ErrorCode.INVALID_JSON_RESPONSE:
 		case ErrorCode.UNKNOWN_ERROR:
@@ -873,8 +902,8 @@ var HttpTransport = class extends BaseTransport {
 */
 const DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
-const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
-const DEFAULT_IDLE_DISCONNECT_MS = 1e3;
+const DEFAULT_CONNECT_TIMEOUT_MS$1 = 3e4;
+const DEFAULT_IDLE_DISCONNECT_MS$1 = 1e3;
 const MIN_TIME_FOR_CONNECT_RETRY_MS = 15e3;
 /**
 * WebSocket transport implementation
@@ -1030,7 +1059,7 @@ var WebSocketTransport = class extends BaseTransport {
 	* parent Container class that supports the WebSocket protocol.
 	*/
 	async connectViaFetch() {
-		const timeoutMs = this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+		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}`;
@@ -1071,7 +1100,7 @@ var WebSocketTransport = class extends BaseTransport {
 	*/
 	connectViaWebSocket() {
 		return new Promise((resolve, reject) => {
-			const timeoutMs = this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+			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`));
@@ -1453,7 +1482,7 @@ var WebSocketTransport = class extends BaseTransport {
 				this.logger.debug("Disconnecting idle WebSocket transport");
 				this.cleanup();
 			}
-		}, DEFAULT_IDLE_DISCONNECT_MS);
+		}, DEFAULT_IDLE_DISCONNECT_MS$1);
 	}
 	clearIdleDisconnectTimer() {
 		if (this.idleDisconnectTimer) {
@@ -1663,12 +1692,12 @@ var BackupClient = class extends BaseHttpClient {
 	* @param archivePath - Where the container should write the archive
 	* @param sessionId - Session context
 	*/
-	async createArchive(dir, archivePath, sessionId, gitignore = false, excludes = []) {
+	async createArchive(dir, archivePath, sessionId, options) {
 		const data = {
 			dir,
 			archivePath,
-			gitignore,
-			excludes,
+			gitignore: options?.gitignore ?? false,
+			excludes: options?.excludes ?? [],
 			sessionId
 		};
 		return await this.post("/api/backup/create", data);
@@ -2589,14 +2618,13 @@ var WatchClient = class extends BaseHttpClient {
 //#endregion
 //#region src/clients/sandbox-client.ts
 /**
-* Main sandbox client that composes all domain-specific clients
-* Provides organized access to all sandbox functionality
+* Main sandbox client that composes all domain-specific clients.
+* Provides organized access to all sandbox functionality.
 *
 * Supports two transport modes:
 * - HTTP (default): Each request is a separate HTTP call
-* - WebSocket: All requests multiplexed over a single connection
-*
-* WebSocket mode reduces sub-request count when running inside Workers/Durable Objects.
+* - WebSocket: All requests multiplexed over a single connection,
+*   reducing sub-request count inside Workers/Durable Objects
 */
 var SandboxClient = class {
 	backup;
@@ -2612,7 +2640,7 @@ var SandboxClient = class {
 	transport = null;
 	constructor(options) {
 		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
-			mode: "websocket",
+			mode: options.transportMode,
 			wsUrl: options.wsUrl,
 			baseUrl: options.baseUrl,
 			logger: options.logger,
@@ -2671,6 +2699,16 @@ var SandboxClient = class {
 		return this.transport?.isConnected() ?? false;
 	}
 	/**
+	* Stream a file directly to the container over a binary RPC channel.
+	*
+	* Requires the capnweb transport (`useWebSocket: 'rpc'`). Calling this
+	* method with the HTTP or WebSocket transports throws an error because those
+	* transports do not support binary streaming.
+	*/
+	writeFileStream(_path, _content, _sessionId) {
+		throw new Error("writeFileStream requires the RPC transport. Enable it with transport: \"rpc\" in sandbox options.");
+	}
+	/**
 	* Connect WebSocket transport (no-op in HTTP mode)
 	* Called automatically on first request, but can be called explicitly
 	* to establish connection upfront.
@@ -2699,6 +2737,507 @@ const BACKUP_ALLOWED_PREFIXES = [
 	"/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 src/container-connection.ts
+const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
+/**
+* Manages a capnweb WebSocket RPC session to the container.
+*
+* The RPC stub is created eagerly in the constructor using a deferred
+* transport. Calls made before `connect()` completes are queued in the
+* transport and flushed once the WebSocket is established.
+*/
+var ContainerConnection = class {
+	stub;
+	session;
+	transport;
+	ws = null;
+	connected = false;
+	connectPromise = null;
+	containerStub;
+	port;
+	logger;
+	constructor(options) {
+		this.containerStub = options.stub;
+		this.port = options.port ?? 3e3;
+		this.logger = options.logger ?? createNoOpLogger();
+		this.transport = new DeferredTransport();
+		this.session = new RpcSession(this.transport);
+		this.stub = this.session.getRemoteMain();
+	}
+	/**
+	* Get the typed RPC stub.
+	*
+	* The stub is available immediately — calls made before connect()
+	* completes are queued in the deferred transport and flushed once
+	* the WebSocket is established.
+	*/
+	rpc() {
+		if (!this.connected && !this.connectPromise) this.connect().catch(() => {});
+		return this.stub;
+	}
+	/**
+	* Return capnweb session statistics. The `imports` and `exports` counts
+	* reflect all in-flight RPC calls, streams, and peer-held references.
+	* An idle session has imports <= 1 && exports <= 1 (the bootstrap stubs).
+	*/
+	getStats() {
+		return this.session.getStats();
+	}
+	isConnected() {
+		return this.connected;
+	}
+	async connect() {
+		if (this.connected) return;
+		if (this.connectPromise) return this.connectPromise;
+		this.connectPromise = this.doConnect();
+		try {
+			await this.connectPromise;
+		} finally {
+			this.connectPromise = null;
+		}
+	}
+	disconnect() {
+		try {
+			this.stub[Symbol.dispose]?.();
+		} catch {}
+		if (this.ws) {
+			try {
+				this.ws.close();
+			} catch {}
+			this.ws = null;
+		}
+		this.connected = false;
+		this.connectPromise = null;
+	}
+	async doConnect() {
+		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
+			});
+			const response = await this.containerStub.fetch(request);
+			clearTimeout(timeout);
+			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.connected = false;
+				this.ws = null;
+				this.logger.debug("ContainerConnection WebSocket closed");
+			});
+			ws.addEventListener("error", () => {
+				this.connected = false;
+				this.ws = null;
+			});
+			this.ws = ws;
+			this.transport.activate(ws);
+			this.connected = true;
+			this.logger.debug("ContainerConnection established", { port: this.port });
+		} catch (error) {
+			clearTimeout(timeout);
+			this.connected = false;
+			this.transport.abort(error);
+			this.logger.error("ContainerConnection failed", error instanceof Error ? error : new Error(String(error)));
+			throw error;
+		}
+	}
+};
+/**
+* RPC transport that queues sends and blocks receives until a WebSocket
+* is provided via `activate()`. Allows the RPC stub to be created before
+* the connection is established — queued calls flush automatically.
+*/
+var DeferredTransport = class {
+	#ws = null;
+	#sendQueue = [];
+	#receiveQueue = [];
+	#receiveResolver;
+	#receiveRejecter;
+	#error;
+	activate(ws) {
+		this.#ws = ws;
+		ws.addEventListener("message", (event) => {
+			if (this.#error) return;
+			if (typeof event.data === "string") if (this.#receiveResolver) {
+				this.#receiveResolver(event.data);
+				this.#receiveResolver = void 0;
+				this.#receiveRejecter = void 0;
+			} else this.#receiveQueue.push(event.data);
+			else this.#fail(/* @__PURE__ */ new TypeError("Received non-string message from WebSocket."));
+		});
+		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/clients/rpc-sandbox-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.
+*
+* capnweb only preserves `error.name` and `error.message` across the wire.
+* The container encodes the full error as a JSON object in the message
+* string: `{"code":"...","message":"...","context":{...}}`.
+*/
+function translateRPCError(error) {
+	if (error instanceof Error) {
+		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-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
+* RPCSandboxClient 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 backed by direct capnweb RPC.
+*
+* Drop-in replacement for SandboxClient when the capnweb transport is active.
+* All operations call the container's SandboxRPCAPI directly over capnweb,
+* bypassing the HTTP handler/router layer entirely.
+*
+* Manages its own WebSocket lifecycle: a fresh `ContainerConnection` 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 RPCSandboxClient = 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;
+	/**
+	* Set the first time the poller observes `conn.isConnected() === true`,
+	* cleared in `destroyConnection()`. Lets us distinguish "the WebSocket
+	* upgrade is still in progress" (don't tear down) from "we were
+	* connected and the peer went away" (do tear down).
+	*/
+	wasEverConnected = false;
+	constructor(options) {
+		this.connOptions = {
+			stub: options.stub,
+			port: options.port,
+			logger: options.logger
+		};
+		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 a new one if none exists or the
+	* previous one was torn down by an idle disconnect. Starts the busy-poll
+	* timer the first time a connection is materialized.
+	*/
+	getConnection() {
+		if (!this.conn) {
+			this.conn = new ContainerConnection(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()) {
+			if (this.wasEverConnected) this.destroyConnection();
+			return;
+		}
+		this.wasEverConnected = true;
+		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 capnweb 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;
+		}
+		this.wasEverConnected = false;
+	}
+	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 desktop() {
+		return wrapStub(this.getConnection().rpc().desktop, this.renewActivity);
+	}
+	get watch() {
+		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
+	}
+	get interpreter() {
+		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
+	}
+	setRetryTimeoutMs(_ms) {}
+	getTransportMode() {
+		return "rpc";
+	}
+	isWebSocketConnected() {
+		return this.conn?.isConnected() ?? false;
+	}
+	async connect() {
+		await this.getConnection().connect();
+	}
+	disconnect() {
+		this.destroyConnection();
+	}
+	async writeFileStream(path$1, stream, sessionId) {
+		return this.files.writeFileStream(path$1, stream, sessionId);
+	}
+};
 
 //#endregion
 //#region src/file-stream.ts
@@ -2834,11 +3373,11 @@ async function collectFile(stream) {
 * - Host header injection
 * - Open redirect vulnerabilities
 */
-var SecurityError = class extends Error {
+var SandboxSecurityError = class extends Error {
 	constructor(message, code) {
 		super(message);
 		this.code = code;
-		this.name = "SecurityError";
+		this.name = "SandboxSecurityError";
 	}
 };
 /**
@@ -2859,8 +3398,8 @@ function validatePort(port) {
 * Only enforces critical requirements - allows maximum developer flexibility
 */
 function sanitizeSandboxId(id) {
-	if (!id || id.length > 63) throw new SecurityError("Sandbox ID must be 1-63 characters long.", "INVALID_SANDBOX_ID_LENGTH");
-	if (id.startsWith("-") || id.endsWith("-")) throw new SecurityError("Sandbox ID cannot start or end with hyphens (DNS requirement).", "INVALID_SANDBOX_ID_HYPHENS");
+	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",
@@ -2871,7 +3410,7 @@ function sanitizeSandboxId(id) {
 		"workers"
 	];
 	const lowerCaseId = id.toLowerCase();
-	if (reservedNames.includes(lowerCaseId)) throw new SecurityError(`Reserved sandbox ID '${id}' is not allowed.`, "RESERVED_SANDBOX_ID");
+	if (reservedNames.includes(lowerCaseId)) throw new SandboxSecurityError(`Reserved sandbox ID '${id}' is not allowed.`, "RESERVED_SANDBOX_ID");
 	return id;
 }
 /**
@@ -2890,23 +3429,23 @@ function validateLanguage(language) {
 		"ts"
 	];
 	const normalized = language.toLowerCase();
-	if (!supportedLanguages.includes(normalized)) throw new SecurityError(`Unsupported language '${language}'. Supported languages: python, javascript, typescript`, "INVALID_LANGUAGE");
+	if (!supportedLanguages.includes(normalized)) throw new SandboxSecurityError(`Unsupported language '${language}'. Supported languages: python, javascript, typescript`, "INVALID_LANGUAGE");
 }
 
 //#endregion
 //#region src/interpreter.ts
 var CodeInterpreter = class {
-	interpreterClient;
+	getInterpreterClient;
 	contexts = /* @__PURE__ */ new Map();
-	constructor(sandbox) {
-		this.interpreterClient = sandbox.client.interpreter;
+	constructor(interpreterClient) {
+		this.getInterpreterClient = typeof interpreterClient === "function" ? interpreterClient : () => interpreterClient;
 	}
 	/**
 	* Create a new code execution context
 	*/
 	async createCodeContext(options = {}) {
 		validateLanguage(options.language);
-		const context = await this.interpreterClient.createCodeContext(options);
+		const context = await this.getInterpreterClient().createCodeContext(options);
 		this.contexts.set(context.id, context);
 		return context;
 	}
@@ -2920,7 +3459,7 @@ var CodeInterpreter = class {
 			context = await this.getOrCreateDefaultContext(language);
 		}
 		const execution = new Execution(code, context);
-		await this.interpreterClient.runCodeStream(context.id, code, options.language, {
+		await this.getInterpreterClient().runCodeStream(context.id, code, options.language, {
 			onStdout: (output) => {
 				execution.logs.stdout.push(output.text);
 				if (options.onStdout) return options.onStdout(output);
@@ -2949,13 +3488,13 @@ var CodeInterpreter = class {
 			const language = options.language || "python";
 			context = await this.getOrCreateDefaultContext(language);
 		}
-		return this.interpreterClient.streamCode(context.id, code, options.language);
+		return this.getInterpreterClient().streamCode(context.id, code, options.language);
 	}
 	/**
 	* List all code contexts
 	*/
 	async listCodeContexts() {
-		const contexts = await this.interpreterClient.listCodeContexts();
+		const contexts = await this.getInterpreterClient().listCodeContexts();
 		for (const context of contexts) this.contexts.set(context.id, context);
 		return contexts;
 	}
@@ -2963,7 +3502,7 @@ var CodeInterpreter = class {
 	* Delete a code context
 	*/
 	async deleteCodeContext(contextId) {
-		await this.interpreterClient.deleteCodeContext(contextId);
+		await this.getInterpreterClient().deleteCodeContext(contextId);
 		this.contexts.delete(contextId);
 	}
 	async getOrCreateDefaultContext(language) {
@@ -3652,7 +4191,7 @@ function isLocalhostPattern(hostname) {
 * 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.9.0";
+const SDK_VERSION = "0.9.2";
 
 //#endregion
 //#region src/sandbox.ts
@@ -3760,7 +4299,7 @@ function enhanceSession(stub, rpcSession) {
 }
 function connect(stub) {
 	return async (request, port) => {
-		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
+		if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
 		const portSwitchedRequest = switchPort(request, port);
 		return await stub.fetch(portSwitchedRequest);
 	};
@@ -3913,6 +4452,30 @@ var Sandbox = class Sandbox extends Container {
 			}
 		});
 	}
+	/**
+	* Create the appropriate client for a given transport protocol.
+	*/
+	createClientForTransport(transport) {
+		if (transport === "rpc") {
+			const self = this;
+			return new RPCSandboxClient({
+				stub: this,
+				port: 3e3,
+				logger: this.logger,
+				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) {
 		super(ctx, env);
 		const envObj = env;
@@ -3925,8 +4488,9 @@ var Sandbox = class Sandbox extends Container {
 			sandboxId: this.ctx.id.toString()
 		});
 		const transportEnv = envObj?.SANDBOX_TRANSPORT;
-		if (transportEnv === "websocket") this.transport = "websocket";
-		else if (transportEnv != null && transportEnv !== "http") this.logger.warn(`Invalid SANDBOX_TRANSPORT value: "${transportEnv}". Must be "http" or "websocket". Defaulting to "http".`);
+		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_ACCOUNT_ID") ?? null;
@@ -3937,8 +4501,8 @@ var Sandbox = class Sandbox extends Container {
 			accessKeyId: this.r2AccessKeyId,
 			secretAccessKey: this.r2SecretAccessKey
 		});
-		this.client = this.createSandboxClient();
-		this.codeInterpreter = new CodeInterpreter(this);
+		this.client = this.createClientForTransport(this.transport);
+		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 		this.ctx.blockConcurrencyWhile(async () => {
 			this.sandboxName = await this.ctx.storage.get("sandboxName") ?? null;
 			this.normalizeId = await this.ctx.storage.get("normalizeId") ?? false;
@@ -3962,8 +4526,8 @@ var Sandbox = class Sandbox extends Container {
 			if (storedTransport && storedTransport !== this.transport) {
 				this.transport = storedTransport;
 				const previousClient = this.client;
-				this.client = this.createSandboxClient();
-				this.codeInterpreter = new CodeInterpreter(this);
+				this.client = this.createClientForTransport(storedTransport);
+				this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 				previousClient.disconnect();
 			}
 			if (storedTransport) this.hasStoredTransport = true;
@@ -4044,8 +4608,8 @@ var Sandbox = class Sandbox extends Container {
 	* Storage is written before the in-memory state and client are updated.
 	*/
 	async setTransport(transport) {
-		if (transport !== "http" && transport !== "websocket") {
-			this.logger.warn(`Invalid transport value: "${transport}". Must be "http" or "websocket". Ignoring.`);
+		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;
@@ -4053,9 +4617,10 @@ var Sandbox = class Sandbox extends Container {
 		const previousClient = this.client;
 		this.transport = transport;
 		this.hasStoredTransport = true;
-		this.client = this.createSandboxClient();
-		this.codeInterpreter = new CodeInterpreter(this);
+		this.client = this.createClientForTransport(transport);
+		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 		previousClient.disconnect();
+		this.renewActivityTimeout();
 		this.logger.debug("Transport updated", { transport });
 	}
 	/**
@@ -4344,9 +4909,46 @@ var Sandbox = class Sandbox extends Container {
 		if (result.exitCode !== 0) throw new S3FSMountError(`S3FS mount failed: ${result.stderr || result.stdout || "Unknown error"}`);
 	}
 	/**
-	* Cleanup and destroy the sandbox container
+	* In-flight `destroy()` promise. While set, concurrent callers coalesce
+	* onto the same teardown instead of triggering a second one. Cleared when
+	* the underlying work settles, so a later call that genuinely needs to
+	* recreate a destroyed sandbox still runs.
+	*
+	* If the underlying teardown hangs (e.g. `super.destroy()` never resolves
+	* because the Containers control plane is unresponsive), every coalesced
+	* caller hangs on the same promise until the Durable Object is evicted.
+	* This is deliberate: a second concurrent teardown would not make a stuck
+	* control plane unstuck, and spawning one would defeat the point of
+	* coalescing. Callers that need bounded waits must apply their own
+	* timeout around `destroy()`.
+	*/
+	inflightDestroy = null;
+	/**
+	* Cleanup and destroy the sandbox container.
+	*
+	* Concurrent calls coalesce: if a previous `destroy()` is still in flight,
+	* subsequent calls await the same underlying work instead of starting a
+	* second teardown. A canonical `sandbox.destroy.coalesced` event is logged
+	* per coalesced call so repeated destroy traffic is observable.
 	*/
 	async destroy() {
+		if (this.inflightDestroy) {
+			logCanonicalEvent(this.logger, {
+				event: "sandbox.destroy.coalesced",
+				outcome: "success",
+				durationMs: 0
+			});
+			return this.inflightDestroy;
+		}
+		const work = this.doDestroy();
+		this.inflightDestroy = work;
+		try {
+			await work;
+		} finally {
+			if (this.inflightDestroy === work) this.inflightDestroy = null;
+		}
+	}
+	async doDestroy() {
 		const startTime = Date.now();
 		let mountsProcessed = 0;
 		let mountFailures = 0;
@@ -4356,7 +4958,6 @@ var Sandbox = class Sandbox extends Container {
 			if (this.ctx.container?.running) try {
 				await this.client.desktop.stop();
 			} catch {}
-			this.client.disconnect();
 			for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
 				mountsProcessed++;
 				if (mountInfo.mountType === "local-sync") try {
@@ -4381,6 +4982,7 @@ var Sandbox = class Sandbox extends Container {
 				}
 			}
 			await this.ctx.storage.delete("portTokens");
+			this.client.disconnect();
 			outcome = "success";
 			await super.destroy();
 		} catch (error) {
@@ -4508,6 +5110,7 @@ var Sandbox = class Sandbox extends Container {
 		this.containerGeneration++;
 		this.defaultSession = null;
 		this.defaultSessionInit = null;
+		this.client.disconnect();
 		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
 		this.activeMounts.clear();
 		await this.ctx.storage.delete("defaultSession");
@@ -4786,22 +5389,43 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	async initializeDefaultSession(sessionId, generation) {
+		let placementId;
 		try {
-			await this.client.utils.createSession({
+			placementId = (await this.client.utils.createSession({
 				id: sessionId,
 				env: this.envVars || {},
 				cwd: "/workspace"
-			});
+			})).containerPlacementId;
 		} catch (error) {
 			if (!(error instanceof SessionAlreadyExistsError)) throw error;
+			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");
 		await this.ctx.storage.put("defaultSession", sessionId);
+		await this.capturePlacementId(placementId);
 		this.defaultSession = sessionId;
 		this.logger.debug("Default session initialized", { sessionId });
 		return sessionId;
 	}
+	/**
+	* Persist the container's placement ID in DO storage.
+	*
+	* Called from the session-create handshake so subsequent reads via
+	* `getContainerPlacementId()` do not require a round-trip to the container. The value
+	* is overwritten on every handshake so that container replacements (which
+	* assign a new placement ID) are reflected on the next session-create.
+	*
+	* A value of `undefined` means the handshake response omitted the field
+	* (older container, unexpected error shape) and the stored value is left
+	* untouched. `null` means the env var is not set in the container and is
+	* stored as-is so callers can distinguish "observed and absent" from "not
+	* yet observed."
+	*/
+	async capturePlacementId(containerPlacementId) {
+		if (containerPlacementId === void 0) return;
+		await this.ctx.storage.put("containerPlacementId", containerPlacementId);
+	}
 	async exec(command, options) {
 		const session = await this.ensureDefaultSession();
 		return this.execWithSession(command, session, options);
@@ -5306,6 +5930,7 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async writeFile(path$1, content, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
+		if (content instanceof ReadableStream) return this.client.writeFileStream(path$1, content, session);
 		return this.client.files.writeFile(path$1, content, session, { encoding: options.encoding });
 	}
 	async deleteFile(path$1, sessionId) {
@@ -5455,7 +6080,7 @@ var Sandbox = class Sandbox extends Container {
 		let outcome = "error";
 		let caughtError;
 		try {
-			if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
+			if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
 			if (options.hostname.endsWith(".workers.dev")) throw new CustomDomainRequiredError({
 				code: ErrorCode.CUSTOM_DOMAIN_REQUIRED,
 				message: `Port exposure requires a custom domain. .workers.dev domains do not support wildcard subdomains required for port proxying.`,
@@ -5471,7 +6096,7 @@ var Sandbox = class Sandbox extends Container {
 			} else token = this.generatePortToken();
 			const tokens = await this.readPortTokens();
 			const existingPort = Object.entries(tokens).find(([p, entry]) => entry.token === token && p !== port.toString());
-			if (existingPort) throw new SecurityError(`Token '${token}' is already in use by port ${existingPort[0]}. Please use a different token.`);
+			if (existingPort) throw new SandboxSecurityError(`Token '${token}' is already in use by port ${existingPort[0]}. Please use a different token.`);
 			const sessionId = await this.ensureDefaultSession();
 			await this.client.ports.exposePort(port, sessionId, options?.name);
 			tokens[port.toString()] = {
@@ -5506,7 +6131,7 @@ var Sandbox = class Sandbox extends Container {
 		let outcome = "error";
 		let caughtError;
 		try {
-			if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
+			if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
 			const tokens = await this.readPortTokens();
 			if (tokens[port.toString()]) {
 				delete tokens[port.toString()];
@@ -5572,9 +6197,9 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	validateCustomToken(token) {
-		if (token.length === 0) throw new SecurityError(`Custom token cannot be empty.`);
-		if (token.length > 16) throw new SecurityError(`Custom token too long. Maximum 16 characters allowed. Received: ${token.length} characters.`);
-		if (!/^[a-z0-9_]+$/.test(token)) throw new SecurityError(`Custom token must contain only lowercase letters (a-z), numbers (0-9), and underscores (_). Invalid token provided.`);
+		if (token.length === 0) throw new SandboxSecurityError(`Custom token cannot be empty.`);
+		if (token.length > 16) throw new SandboxSecurityError(`Custom token too long. Maximum 16 characters allowed. Received: ${token.length} characters.`);
+		if (!/^[a-z0-9_]+$/.test(token)) throw new SandboxSecurityError(`Custom token must contain only lowercase letters (a-z), numbers (0-9), and underscores (_). Invalid token provided.`);
 	}
 	generatePortToken() {
 		const array = new Uint8Array(12);
@@ -5582,10 +6207,10 @@ var Sandbox = class Sandbox extends Container {
 		return btoa(String.fromCharCode(...array)).replace(/\+/g, "_").replace(/\//g, "_").replace(/=/g, "").toLowerCase();
 	}
 	constructPreviewUrl(port, sandboxId, hostname, token) {
-		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
+		if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
 		const effectiveId = this.sandboxName || sandboxId;
 		const hasUppercase = /[A-Z]/.test(effectiveId);
-		if (!this.normalizeId && hasUppercase) throw new SecurityError(`Preview URLs require lowercase sandbox IDs. Your ID "${effectiveId}" contains uppercase letters.\n\nTo fix this:\n1. Create a new sandbox with: getSandbox(ns, "${effectiveId}", { normalizeId: true })\n2. This will create a sandbox with ID: "${effectiveId.toLowerCase()}"\n\nNote: Due to DNS case-insensitivity, IDs with uppercase letters cannot be used with preview URLs.`);
+		if (!this.normalizeId && hasUppercase) throw new SandboxSecurityError(`Preview URLs require lowercase sandbox IDs. Your ID "${effectiveId}" contains uppercase letters.\n\nTo fix this:\n1. Create a new sandbox with: getSandbox(ns, "${effectiveId}", { normalizeId: true })\n2. This will create a sandbox with ID: "${effectiveId.toLowerCase()}"\n\nNote: Due to DNS case-insensitivity, IDs with uppercase letters cannot be used with preview URLs.`);
 		const sanitizedSandboxId = sanitizeSandboxId(sandboxId).toLowerCase();
 		if (isLocalhostPattern(hostname)) {
 			const [host, portStr] = hostname.split(":");
@@ -5595,7 +6220,7 @@ var Sandbox = class Sandbox extends Container {
 				baseUrl.hostname = `${port}-${sanitizedSandboxId}-${token}.${host}`;
 				return baseUrl.toString();
 			} catch (error) {
-				throw new SecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+				throw new SandboxSecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
 			}
 		}
 		try {
@@ -5603,7 +6228,7 @@ var Sandbox = class Sandbox extends Container {
 			baseUrl.hostname = `${port}-${sanitizedSandboxId}-${token}.${hostname}`;
 			return baseUrl.toString();
 		} catch (error) {
-			throw new SecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+			throw new SandboxSecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 	}
 	/**
@@ -5617,12 +6242,13 @@ var Sandbox = class Sandbox extends Container {
 			...options?.env ?? {}
 		});
 		const envPayload = Object.keys(filteredEnv).length > 0 ? filteredEnv : void 0;
-		await this.client.utils.createSession({
+		const response = await this.client.utils.createSession({
 			id: sessionId,
 			...envPayload && { env: envPayload },
 			...options?.cwd && { cwd: options.cwd },
 			...options?.commandTimeoutMs !== void 0 && { commandTimeoutMs: options.commandTimeoutMs }
 		});
+		await this.capturePlacementId(response.containerPlacementId);
 		return this.getSessionWrapper(sessionId);
 	}
 	/**
@@ -5657,6 +6283,26 @@ var Sandbox = class Sandbox extends Container {
 			timestamp: response.timestamp
 		};
 	}
+	/**
+	* Get the Cloudflare placement ID observed for the underlying container.
+	*
+	* The placement ID is captured during the first session-create handshake
+	* after a container start and stored in Durable Object storage, so this
+	* method returns the cached value without contacting the container. A new
+	* placement ID is captured on each subsequent session-create handshake,
+	* which occurs whenever the container has been replaced.
+	*
+	* Returns `null` when a handshake has completed but the container's
+	* `CLOUDFLARE_PLACEMENT_ID` environment variable is not set (for example,
+	* in local development).
+	*
+	* Returns `undefined` when no handshake has been observed yet on this
+	* sandbox. Call any method that triggers session creation (such as
+	* `exec()`) to populate the value.
+	*/
+	async getContainerPlacementId() {
+		return this.ctx.storage.get("containerPlacementId");
+	}
 	getSessionWrapper(sessionId) {
 		return {
 			id: sessionId,
@@ -5796,6 +6442,22 @@ var Sandbox = class Sandbox extends Container {
 		});
 		return this.backupBucket;
 	}
+	normalizeBackupExcludes(excludes) {
+		const normalizedExcludes = [];
+		for (const pattern of excludes) {
+			const normalized = normalizeBackupExcludePattern(pattern);
+			if (normalized === null) {
+				this.logger.warn("Exclude pattern reduced to empty after globstar normalization; skipping", { original: pattern });
+				continue;
+			}
+			if (normalized !== pattern) this.logger.warn("Exclude pattern contained ** (globstar) which mksquashfs does not support; normalized automatically", {
+				original: pattern,
+				normalized
+			});
+			normalizedExcludes.push(normalized);
+		}
+		return normalizedExcludes;
+	}
 	static PRESIGNED_URL_EXPIRY_SECONDS = 3600;
 	/**
 	* Create a unique, dedicated session for a single backup operation.
@@ -6026,10 +6688,14 @@ var Sandbox = class Sandbox extends Container {
 				context: { reason: "excludes must be an array of strings" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
+			const normalizedExcludes = this.normalizeBackupExcludes(excludes);
 			backupSession = await this.ensureBackupSession();
 			backupId = crypto.randomUUID();
 			const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
-			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, gitignore, excludes);
+			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, {
+				gitignore,
+				excludes: normalizedExcludes
+			});
 			if (!createResult.success) throw new BackupCreateError({
 				message: "Container failed to create backup archive",
 				code: ErrorCode.BACKUP_CREATE_FAILED,
@@ -6144,10 +6810,14 @@ var Sandbox = class Sandbox extends Container {
 				context: { reason: "excludes must be an array of strings" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
+			const normalizedExcludes = this.normalizeBackupExcludes(excludes);
 			backupSession = await this.ensureBackupSession();
 			backupId = crypto.randomUUID();
 			const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
-			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, gitignore, excludes);
+			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, {
+				gitignore,
+				excludes: normalizedExcludes
+			});
 			if (!createResult.success) throw new BackupCreateError({
 				message: "Container failed to create backup archive",
 				code: ErrorCode.BACKUP_CREATE_FAILED,
@@ -6498,5 +7168,5 @@ var Sandbox = class Sandbox extends Container {
 };
 
 //#endregion
-export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, SessionTerminatedError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y };
-//# sourceMappingURL=sandbox-Cf_Wjrzq.js.map
+export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, RPCTransportError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y, SessionTerminatedError as z };
+//# sourceMappingURL=sandbox-CReFGUtF.js.map