@cloudflare/sandbox 0.8.11 → 0.9.0

package/dist/{file-stream-Bn2PceyF.js → sandbox-Cf_Wjrzq.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-Ilf8VjmX.js";
-import { t as ErrorCode } from "./errors-Bz21XTBJ.js";
+import { t as ErrorCode } from "./errors-Dk2rApYI.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import path from "node:path/posix";
@@ -208,6 +208,24 @@ var SessionDestroyedError = class extends SandboxError {
 	}
 };
 /**
+* Error thrown when a session's underlying shell exited without an explicit
+* `destroy()` call (user ran `exit`, the shell crashed, or a child process
+* took the shell down). The session-local state is gone, but the next call
+* with the same sessionId will transparently start a fresh session.
+*/
+var SessionTerminatedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "SessionTerminatedError";
+	}
+	get sessionId() {
+		return this.context.sessionId;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
+};
+/**
 * Error thrown when a port is already exposed
 */
 var PortAlreadyExposedError = class extends SandboxError {
@@ -674,6 +692,7 @@ function createErrorFromResponse(errorResponse) {
 		case ErrorCode.PROCESS_ERROR: return new ProcessError(errorResponse);
 		case ErrorCode.SESSION_ALREADY_EXISTS: return new SessionAlreadyExistsError(errorResponse);
 		case ErrorCode.SESSION_DESTROYED: return new SessionDestroyedError(errorResponse);
+		case ErrorCode.SESSION_TERMINATED: return new SessionTerminatedError(errorResponse);
 		case ErrorCode.PORT_ALREADY_EXPOSED: return new PortAlreadyExposedError(errorResponse);
 		case ErrorCode.PORT_NOT_EXPOSED: return new PortNotExposedError(errorResponse);
 		case ErrorCode.INVALID_PORT_NUMBER:
@@ -1645,18 +1664,14 @@ var BackupClient = class extends BaseHttpClient {
 	* @param sessionId - Session context
 	*/
 	async createArchive(dir, archivePath, sessionId, gitignore = false, excludes = []) {
-		try {
-			const data = {
-				dir,
-				archivePath,
-				gitignore,
-				excludes,
-				sessionId
-			};
-			return await this.post("/api/backup/create", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			dir,
+			archivePath,
+			gitignore,
+			excludes,
+			sessionId
+		};
+		return await this.post("/api/backup/create", data);
 	}
 	/**
 	* Tell the container to restore a squashfs archive into a directory.
@@ -1665,16 +1680,12 @@ var BackupClient = class extends BaseHttpClient {
 	* @param sessionId - Session context
 	*/
 	async restoreArchive(dir, archivePath, sessionId) {
-		try {
-			const data = {
-				dir,
-				archivePath,
-				sessionId
-			};
-			return await this.post("/api/backup/restore", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			dir,
+			archivePath,
+			sessionId
+		};
+		return await this.post("/api/backup/restore", data);
 	}
 };
 
@@ -1770,280 +1781,200 @@ var DesktopClient = class extends BaseHttpClient {
 	* Get desktop lifecycle and process health status.
 	*/
 	async status() {
-		try {
-			return await this.get("/api/desktop/status");
-		} catch (error) {
-			throw error;
-		}
+		return await this.get("/api/desktop/status");
 	}
 	async screenshot(options) {
-		try {
-			const wantsBytes = options?.format === "bytes";
-			const data = {
-				format: "base64",
-				...options?.imageFormat !== void 0 && { imageFormat: options.imageFormat },
-				...options?.quality !== void 0 && { quality: options.quality },
-				...options?.showCursor !== void 0 && { showCursor: options.showCursor }
+		const wantsBytes = options?.format === "bytes";
+		const data = {
+			format: "base64",
+			...options?.imageFormat !== void 0 && { imageFormat: options.imageFormat },
+			...options?.quality !== void 0 && { quality: options.quality },
+			...options?.showCursor !== void 0 && { showCursor: options.showCursor }
+		};
+		const response = await this.post("/api/desktop/screenshot", data);
+		if (wantsBytes) {
+			const binaryString = atob(response.data);
+			const bytes = new Uint8Array(binaryString.length);
+			for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+			return {
+				...response,
+				data: bytes
 			};
-			const response = await this.post("/api/desktop/screenshot", data);
-			if (wantsBytes) {
-				const binaryString = atob(response.data);
-				const bytes = new Uint8Array(binaryString.length);
-				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
-				return {
-					...response,
-					data: bytes
-				};
-			}
-			return response;
-		} catch (error) {
-			throw error;
 		}
+		return response;
 	}
 	async screenshotRegion(region, options) {
-		try {
-			const wantsBytes = options?.format === "bytes";
-			const data = {
-				region,
-				format: "base64",
-				...options?.imageFormat !== void 0 && { imageFormat: options.imageFormat },
-				...options?.quality !== void 0 && { quality: options.quality },
-				...options?.showCursor !== void 0 && { showCursor: options.showCursor }
+		const wantsBytes = options?.format === "bytes";
+		const data = {
+			region,
+			format: "base64",
+			...options?.imageFormat !== void 0 && { imageFormat: options.imageFormat },
+			...options?.quality !== void 0 && { quality: options.quality },
+			...options?.showCursor !== void 0 && { showCursor: options.showCursor }
+		};
+		const response = await this.post("/api/desktop/screenshot/region", data);
+		if (wantsBytes) {
+			const binaryString = atob(response.data);
+			const bytes = new Uint8Array(binaryString.length);
+			for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+			return {
+				...response,
+				data: bytes
 			};
-			const response = await this.post("/api/desktop/screenshot/region", data);
-			if (wantsBytes) {
-				const binaryString = atob(response.data);
-				const bytes = new Uint8Array(binaryString.length);
-				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
-				return {
-					...response,
-					data: bytes
-				};
-			}
-			return response;
-		} catch (error) {
-			throw error;
 		}
+		return response;
 	}
 	/**
 	* Single-click at the given coordinates.
 	*/
 	async click(x, y, options) {
-		try {
-			await this.post("/api/desktop/mouse/click", {
-				x,
-				y,
-				button: options?.button ?? "left",
-				clickCount: 1
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/click", {
+			x,
+			y,
+			button: options?.button ?? "left",
+			clickCount: 1
+		});
 	}
 	/**
 	* Double-click at the given coordinates.
 	*/
 	async doubleClick(x, y, options) {
-		try {
-			await this.post("/api/desktop/mouse/click", {
-				x,
-				y,
-				button: options?.button ?? "left",
-				clickCount: 2
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/click", {
+			x,
+			y,
+			button: options?.button ?? "left",
+			clickCount: 2
+		});
 	}
 	/**
 	* Triple-click at the given coordinates.
 	*/
 	async tripleClick(x, y, options) {
-		try {
-			await this.post("/api/desktop/mouse/click", {
-				x,
-				y,
-				button: options?.button ?? "left",
-				clickCount: 3
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/click", {
+			x,
+			y,
+			button: options?.button ?? "left",
+			clickCount: 3
+		});
 	}
 	/**
 	* Right-click at the given coordinates.
 	*/
 	async rightClick(x, y) {
-		try {
-			await this.post("/api/desktop/mouse/click", {
-				x,
-				y,
-				button: "right",
-				clickCount: 1
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/click", {
+			x,
+			y,
+			button: "right",
+			clickCount: 1
+		});
 	}
 	/**
 	* Middle-click at the given coordinates.
 	*/
 	async middleClick(x, y) {
-		try {
-			await this.post("/api/desktop/mouse/click", {
-				x,
-				y,
-				button: "middle",
-				clickCount: 1
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/click", {
+			x,
+			y,
+			button: "middle",
+			clickCount: 1
+		});
 	}
 	/**
 	* Press and hold a mouse button.
 	*/
 	async mouseDown(x, y, options) {
-		try {
-			await this.post("/api/desktop/mouse/down", {
-				...x !== void 0 && { x },
-				...y !== void 0 && { y },
-				button: options?.button ?? "left"
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/down", {
+			...x !== void 0 && { x },
+			...y !== void 0 && { y },
+			button: options?.button ?? "left"
+		});
 	}
 	/**
 	* Release a held mouse button.
 	*/
 	async mouseUp(x, y, options) {
-		try {
-			await this.post("/api/desktop/mouse/up", {
-				...x !== void 0 && { x },
-				...y !== void 0 && { y },
-				button: options?.button ?? "left"
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/up", {
+			...x !== void 0 && { x },
+			...y !== void 0 && { y },
+			button: options?.button ?? "left"
+		});
 	}
 	/**
 	* Move the mouse cursor to coordinates.
 	*/
 	async moveMouse(x, y) {
-		try {
-			await this.post("/api/desktop/mouse/move", {
-				x,
-				y
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/move", {
+			x,
+			y
+		});
 	}
 	/**
 	* Drag from start coordinates to end coordinates.
 	*/
 	async drag(startX, startY, endX, endY, options) {
-		try {
-			await this.post("/api/desktop/mouse/drag", {
-				startX,
-				startY,
-				endX,
-				endY,
-				button: options?.button ?? "left"
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/drag", {
+			startX,
+			startY,
+			endX,
+			endY,
+			button: options?.button ?? "left"
+		});
 	}
 	/**
 	* Scroll at coordinates in the specified direction.
 	*/
 	async scroll(x, y, direction, amount = 3) {
-		try {
-			await this.post("/api/desktop/mouse/scroll", {
-				x,
-				y,
-				direction,
-				amount
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/mouse/scroll", {
+			x,
+			y,
+			direction,
+			amount
+		});
 	}
 	/**
 	* Get the current cursor coordinates.
 	*/
 	async getCursorPosition() {
-		try {
-			return await this.get("/api/desktop/mouse/position");
-		} catch (error) {
-			throw error;
-		}
+		return await this.get("/api/desktop/mouse/position");
 	}
 	/**
 	* Type text into the focused element.
 	*/
 	async type(text, options) {
-		try {
-			await this.post("/api/desktop/keyboard/type", {
-				text,
-				...options?.delayMs !== void 0 && { delayMs: options.delayMs }
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/keyboard/type", {
+			text,
+			...options?.delayMs !== void 0 && { delayMs: options.delayMs }
+		});
 	}
 	/**
 	* Press and release a key or key combination.
 	*/
 	async press(key) {
-		try {
-			await this.post("/api/desktop/keyboard/press", { key });
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/keyboard/press", { key });
 	}
 	/**
 	* Press and hold a key.
 	*/
 	async keyDown(key) {
-		try {
-			await this.post("/api/desktop/keyboard/down", { key });
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/keyboard/down", { key });
 	}
 	/**
 	* Release a held key.
 	*/
 	async keyUp(key) {
-		try {
-			await this.post("/api/desktop/keyboard/up", { key });
-		} catch (error) {
-			throw error;
-		}
+		await this.post("/api/desktop/keyboard/up", { key });
 	}
 	/**
 	* Get the active desktop screen size.
 	*/
 	async getScreenSize() {
-		try {
-			return await this.get("/api/desktop/screen/size");
-		} catch (error) {
-			throw error;
-		}
+		return await this.get("/api/desktop/screen/size");
 	}
 	/**
 	* Get health status for a specific desktop process.
 	*/
 	async getProcessStatus(name) {
-		try {
-			return await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
-		} catch (error) {
-			throw error;
-		}
+		return await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
 	}
 };
 
@@ -2060,16 +1991,12 @@ var FileClient = class extends BaseHttpClient {
 	* @param options - Optional settings (recursive)
 	*/
 	async mkdir(path$1, sessionId, options) {
-		try {
-			const data = {
-				path: path$1,
-				sessionId,
-				recursive: options?.recursive ?? false
-			};
-			return await this.post("/api/mkdir", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			sessionId,
+			recursive: options?.recursive ?? false
+		};
+		return await this.post("/api/mkdir", data);
 	}
 	/**
 	* Write content to a file
@@ -2079,17 +2006,13 @@ var FileClient = class extends BaseHttpClient {
 	* @param options - Optional settings (encoding)
 	*/
 	async writeFile(path$1, content, sessionId, options) {
-		try {
-			const data = {
-				path: path$1,
-				content,
-				sessionId,
-				encoding: options?.encoding
-			};
-			return await this.post("/api/write", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			content,
+			sessionId,
+			encoding: options?.encoding
+		};
+		return await this.post("/api/write", data);
 	}
 	/**
 	* Read content from a file
@@ -2098,16 +2021,12 @@ var FileClient = class extends BaseHttpClient {
 	* @param options - Optional settings (encoding)
 	*/
 	async readFile(path$1, sessionId, options) {
-		try {
-			const data = {
-				path: path$1,
-				sessionId,
-				encoding: options?.encoding
-			};
-			return await this.post("/api/read", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			sessionId,
+			encoding: options?.encoding
+		};
+		return await this.post("/api/read", data);
 	}
 	/**
 	* Stream a file using Server-Sent Events
@@ -2116,15 +2035,11 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	*/
 	async readFileStream(path$1, sessionId) {
-		try {
-			const data = {
-				path: path$1,
-				sessionId
-			};
-			return await this.doStreamFetch("/api/read/stream", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			sessionId
+		};
+		return await this.doStreamFetch("/api/read/stream", data);
 	}
 	/**
 	* Delete a file
@@ -2132,15 +2047,11 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	*/
 	async deleteFile(path$1, sessionId) {
-		try {
-			const data = {
-				path: path$1,
-				sessionId
-			};
-			return await this.post("/api/delete", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			sessionId
+		};
+		return await this.post("/api/delete", data);
 	}
 	/**
 	* Rename a file
@@ -2149,16 +2060,12 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	*/
 	async renameFile(path$1, newPath, sessionId) {
-		try {
-			const data = {
-				oldPath: path$1,
-				newPath,
-				sessionId
-			};
-			return await this.post("/api/rename", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			oldPath: path$1,
+			newPath,
+			sessionId
+		};
+		return await this.post("/api/rename", data);
 	}
 	/**
 	* Move a file
@@ -2167,16 +2074,12 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	*/
 	async moveFile(path$1, newPath, sessionId) {
-		try {
-			const data = {
-				sourcePath: path$1,
-				destinationPath: newPath,
-				sessionId
-			};
-			return await this.post("/api/move", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			sourcePath: path$1,
+			destinationPath: newPath,
+			sessionId
+		};
+		return await this.post("/api/move", data);
 	}
 	/**
 	* List files in a directory
@@ -2185,16 +2088,12 @@ var FileClient = class extends BaseHttpClient {
 	* @param options - Optional settings (recursive, includeHidden)
 	*/
 	async listFiles(path$1, sessionId, options) {
-		try {
-			const data = {
-				path: path$1,
-				sessionId,
-				options: options || {}
-			};
-			return await this.post("/api/list-files", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			sessionId,
+			options: options || {}
+		};
+		return await this.post("/api/list-files", data);
 	}
 	/**
 	* Check if a file or directory exists
@@ -2202,15 +2101,11 @@ var FileClient = class extends BaseHttpClient {
 	* @param sessionId - The session ID for this operation
 	*/
 	async exists(path$1, sessionId) {
-		try {
-			const data = {
-				path: path$1,
-				sessionId
-			};
-			return await this.post("/api/exists", data);
-		} catch (error) {
-			throw error;
-		}
+		const data = {
+			path: path$1,
+			sessionId
+		};
+		return await this.post("/api/exists", data);
 	}
 };
 
@@ -2232,26 +2127,22 @@ var GitClient = class GitClient extends BaseHttpClient {
 	* @param options - Optional settings (branch, targetDir, depth, timeoutMs)
 	*/
 	async checkout(repoUrl, sessionId, options) {
-		try {
-			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 });
-		} catch (error) {
-			throw error;
+		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 });
 	}
 };
 
@@ -2444,41 +2335,29 @@ var PortClient = class extends BaseHttpClient {
 	* @param name - Optional name for the port
 	*/
 	async exposePort(port, sessionId, name) {
-		try {
-			const data = {
-				port,
-				sessionId,
-				name
-			};
-			return await this.post("/api/expose-port", data);
-		} catch (error) {
-			throw error;
-		}
-	}
+		const data = {
+			port,
+			sessionId,
+			name
+		};
+		return await this.post("/api/expose-port", data);
+	}
 	/**
 	* Unexpose a port and remove its preview URL
 	* @param port - Port number to unexpose
 	* @param sessionId - The session ID for this operation
 	*/
 	async unexposePort(port, sessionId) {
-		try {
-			const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
-			return await this.delete(url);
-		} catch (error) {
-			throw error;
-		}
+		const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
+		return await this.delete(url);
 	}
 	/**
 	* Get all currently exposed ports
 	* @param sessionId - The session ID for this operation
 	*/
 	async getExposedPorts(sessionId) {
-		try {
-			const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
-			return await this.get(url);
-		} catch (error) {
-			throw error;
-		}
+		const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
+		return await this.get(url);
 	}
 	/**
 	* Watch a port for readiness via SSE stream
@@ -2486,11 +2365,7 @@ var PortClient = class extends BaseHttpClient {
 	* @returns SSE stream that emits PortWatchEvent objects
 	*/
 	async watchPort(request) {
-		try {
-			return await this.doStreamFetch("/api/port-watch", request);
-		} catch (error) {
-			throw error;
-		}
+		return await this.doStreamFetch("/api/port-watch", request);
 	}
 };
 
@@ -2507,90 +2382,62 @@ var ProcessClient = class extends BaseHttpClient {
 	* @param options - Optional settings (processId)
 	*/
 	async startProcess(command, sessionId, options) {
-		try {
-			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);
-		} catch (error) {
-			throw error;
-		}
+		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() {
-		try {
-			return await this.get(`/api/process/list`);
-		} catch (error) {
-			throw error;
-		}
+		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) {
-		try {
-			const url = `/api/process/${processId}`;
-			return await this.get(url);
-		} catch (error) {
-			throw error;
-		}
+		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) {
-		try {
-			const url = `/api/process/${processId}`;
-			return await this.delete(url);
-		} catch (error) {
-			throw error;
-		}
+		const url = `/api/process/${processId}`;
+		return await this.delete(url);
 	}
 	/**
 	* Kill all running processes (sandbox-scoped, not session-scoped)
 	*/
 	async killAllProcesses() {
-		try {
-			return await this.delete(`/api/process/kill-all`);
-		} catch (error) {
-			throw error;
-		}
+		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) {
-		try {
-			const url = `/api/process/${processId}/logs`;
-			return await this.get(url);
-		} catch (error) {
-			throw error;
-		}
+		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) {
-		try {
-			const url = `/api/process/${processId}/stream`;
-			return await this.doStreamFetch(url, void 0, "GET");
-		} catch (error) {
-			throw error;
-		}
+		const url = `/api/process/${processId}/stream`;
+		return await this.doStreamFetch(url, void 0, "GET");
 	}
 };
 
@@ -2604,43 +2451,27 @@ var UtilityClient = class extends BaseHttpClient {
 	* Ping the sandbox to check if it's responsive
 	*/
 	async ping() {
-		try {
-			return (await this.get("/api/ping")).message;
-		} catch (error) {
-			throw error;
-		}
+		return (await this.get("/api/ping")).message;
 	}
 	/**
 	* Get list of available commands in the sandbox environment
 	*/
 	async getCommands() {
-		try {
-			return (await this.get("/api/commands")).availableCommands;
-		} catch (error) {
-			throw error;
-		}
+		return (await this.get("/api/commands")).availableCommands;
 	}
 	/**
 	* Create a new execution session
 	* @param options - Session configuration (id, env, cwd)
 	*/
 	async createSession(options) {
-		try {
-			return await this.post("/api/session/create", options);
-		} catch (error) {
-			throw error;
-		}
+		return await this.post("/api/session/create", options);
 	}
 	/**
 	* Delete an execution session
 	* @param sessionId - Session ID to delete
 	*/
 	async deleteSession(sessionId) {
-		try {
-			return await this.post("/api/session/delete", { sessionId });
-		} catch (error) {
-			throw error;
-		}
+		return await this.post("/api/session/delete", { sessionId });
 	}
 	/**
 	* Get the container version
@@ -2682,12 +2513,8 @@ var WatchClient = class extends BaseHttpClient {
 	* @param request - Watch request with path and options
 	*/
 	async watch(request) {
-		try {
-			const stream = await this.doStreamFetch("/api/watch", request);
-			return await this.waitForReadiness(stream);
-		} catch (error) {
-			throw error;
-		}
+		const stream = await this.doStreamFetch("/api/watch", request);
+		return await this.waitForReadiness(stream);
 	}
 	/**
 	* Read SSE chunks until the `watching` event appears, then return a
@@ -2873,6 +2700,128 @@ const BACKUP_ALLOWED_PREFIXES = [
 	"/app"
 ];
 
+//#endregion
+//#region src/file-stream.ts
+/**
+* Parse SSE (Server-Sent Events) lines from a stream
+*/
+async function* parseSSE(stream) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let currentEvent = { data: [] };
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const parsed = parseSSEFrames(buffer, currentEvent);
+			buffer = parsed.remaining;
+			currentEvent = parsed.currentEvent;
+			for (const frame of parsed.events) try {
+				yield JSON.parse(frame.data);
+			} catch {}
+		}
+		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
+		for (const frame of finalParsed.events) try {
+			yield JSON.parse(frame.data);
+		} catch {}
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {}
+		reader.releaseLock();
+	}
+}
+/**
+* Stream a file from the sandbox with automatic base64 decoding for binary files
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
+*
+* @example
+* ```ts
+* const stream = await sandbox.readFileStream('/path/to/file.png');
+* for await (const chunk of streamFile(stream)) {
+*   if (chunk instanceof Uint8Array) {
+*     // Binary chunk
+*     console.log('Binary chunk:', chunk.length, 'bytes');
+*   } else {
+*     // Text chunk
+*     console.log('Text chunk:', chunk);
+*   }
+* }
+* ```
+*/
+async function* streamFile(stream) {
+	let metadata = null;
+	for await (const event of parseSSE(stream)) switch (event.type) {
+		case "metadata":
+			metadata = {
+				mimeType: event.mimeType,
+				size: event.size,
+				isBinary: event.isBinary,
+				encoding: event.encoding
+			};
+			break;
+		case "chunk":
+			if (!metadata) throw new Error("Received chunk before metadata");
+			if (metadata.isBinary && metadata.encoding === "base64") {
+				const binaryString = atob(event.data);
+				const bytes = new Uint8Array(binaryString.length);
+				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+				yield bytes;
+			} else yield event.data;
+			break;
+		case "complete":
+			if (!metadata) throw new Error("Stream completed without metadata");
+			return metadata;
+		case "error": throw new Error(`File streaming error: ${event.error}`);
+	}
+	throw new Error("Stream ended unexpectedly");
+}
+/**
+* Collect an entire file into memory from a stream
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns Object containing the file content and metadata
+*
+* @example
+* ```ts
+* const stream = await sandbox.readFileStream('/path/to/file.txt');
+* const { content, metadata } = await collectFile(stream);
+* console.log('Content:', content);
+* console.log('MIME type:', metadata.mimeType);
+* ```
+*/
+async function collectFile(stream) {
+	const chunks = [];
+	const generator = streamFile(stream);
+	let result = await generator.next();
+	while (!result.done) {
+		chunks.push(result.value);
+		result = await generator.next();
+	}
+	const metadata = result.value;
+	if (!metadata) throw new Error("Failed to get file metadata");
+	if (metadata.isBinary) {
+		const totalLength = chunks.reduce((sum, chunk) => sum + (chunk instanceof Uint8Array ? chunk.length : 0), 0);
+		const combined = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of chunks) if (chunk instanceof Uint8Array) {
+			combined.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return {
+			content: combined,
+			metadata
+		};
+	} else return {
+		content: chunks.filter((c) => typeof c === "string").join(""),
+		metadata
+	};
+}
+
 //#endregion
 //#region src/security.ts
 /**
@@ -3124,55 +3073,220 @@ function asyncIterableToSSEStream(events, options) {
 }
 
 //#endregion
-//#region src/local-mount-sync.ts
-const DEFAULT_POLL_INTERVAL_MS = 1e3;
-const DEFAULT_ECHO_SUPPRESS_TTL_MS = 2e3;
-const MAX_BACKOFF_MS = 3e4;
-const SYNC_CONCURRENCY = 5;
+//#region src/storage-mount/errors.ts
 /**
-* Manages bidirectional sync between an R2 binding and a container directory.
+* Bucket mount and unmount error classes
 *
-* R2 -> Container: polls bucket.list() to detect changes, then transfers diffs.
-* Container -> R2: uses inotifywait via the watch API to detect file changes.
+* Validation errors (InvalidMountConfigError, MissingCredentialsError) are thrown
+* before any container interaction. BucketUnmountError is thrown after a failed
+* fusermount call inside the container.
 */
-var LocalMountSyncManager = class {
-	bucket;
-	mountPath;
-	prefix;
-	readOnly;
-	client;
-	sessionId;
-	logger;
-	pollIntervalMs;
-	echoSuppressTtlMs;
-	snapshot = /* @__PURE__ */ new Map();
-	echoSuppressSet = /* @__PURE__ */ new Set();
-	pollTimer = null;
-	watchReconnectTimer = null;
-	watchAbortController = null;
-	running = false;
-	consecutivePollFailures = 0;
-	consecutiveWatchFailures = 0;
-	constructor(options) {
-		this.bucket = options.bucket;
-		this.mountPath = options.mountPath;
-		this.prefix = options.prefix;
-		this.readOnly = options.readOnly;
-		this.client = options.client;
-		this.sessionId = options.sessionId;
-		this.logger = options.logger.child({ operation: "local-mount-sync" });
-		this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-		this.echoSuppressTtlMs = options.echoSuppressTtlMs ?? DEFAULT_ECHO_SUPPRESS_TTL_MS;
+/**
+* Base error for bucket mounting operations
+*/
+var BucketMountError = class extends Error {
+	code;
+	constructor(message, code = ErrorCode.BUCKET_MOUNT_ERROR) {
+		super(message);
+		this.name = "BucketMountError";
+		this.code = code;
 	}
-	/**
-	* Start bidirectional sync. Performs initial full sync, then starts
-	* the R2 poll loop and (if not readOnly) the container watch loop.
-	*/
-	async start() {
-		this.running = true;
-		await this.client.files.mkdir(this.mountPath, this.sessionId, { recursive: true });
-		await this.fullSyncR2ToContainer();
-		this.schedulePoll();
+};
+/**
+* Thrown when S3FS mount command fails
+*/
+var S3FSMountError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.S3FS_MOUNT_ERROR);
+		this.name = "S3FSMountError";
+	}
+};
+/**
+* Thrown when fusermount -u fails to unmount a FUSE filesystem
+*/
+var BucketUnmountError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.BUCKET_UNMOUNT_ERROR);
+		this.name = "BucketUnmountError";
+	}
+};
+/**
+* Thrown when no credentials found in environment
+*/
+var MissingCredentialsError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.MISSING_CREDENTIALS);
+		this.name = "MissingCredentialsError";
+	}
+};
+/**
+* Thrown when bucket name, mount path, or options are invalid
+*/
+var InvalidMountConfigError = class extends BucketMountError {
+	constructor(message) {
+		super(message, ErrorCode.INVALID_MOUNT_CONFIG);
+		this.name = "InvalidMountConfigError";
+	}
+};
+
+//#endregion
+//#region src/storage-mount/credential-detection.ts
+/**
+* Detect credentials for bucket mounting from environment variables
+* Priority order:
+* 1. Explicit options.credentials
+* 2. Standard AWS env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
+* 3. Standard R2 env vars: R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
+* 4. Error: no credentials found
+*
+* @param options - Mount options
+* @param envVars - Environment variables
+* @returns Detected credentials
+* @throws MissingCredentialsError if no credentials found
+*/
+function detectCredentials(options, envVars) {
+	if (options.credentials) return options.credentials;
+	const awsAccessKeyId = envVars.AWS_ACCESS_KEY_ID;
+	const awsSecretAccessKey = envVars.AWS_SECRET_ACCESS_KEY;
+	if (awsAccessKeyId && awsSecretAccessKey) return {
+		accessKeyId: awsAccessKeyId,
+		secretAccessKey: awsSecretAccessKey
+	};
+	/**
+	* Priority 3: Standard R2 env vars
+	*
+	* AWS vars still take precedence over R2 vars in case both are set
+	*/
+	const r2AccessKeyId = envVars.R2_ACCESS_KEY_ID;
+	const r2SecretAccessKey = envVars.R2_SECRET_ACCESS_KEY;
+	if (r2AccessKeyId && r2SecretAccessKey) return {
+		accessKeyId: r2AccessKeyId,
+		secretAccessKey: r2SecretAccessKey
+	};
+	throw new MissingCredentialsError("No credentials found. Set R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or pass explicit credentials in options.");
+}
+
+//#endregion
+//#region src/storage-mount/provider-detection.ts
+/**
+* Detect provider from endpoint URL using pattern matching
+*/
+function detectProviderFromUrl(endpoint) {
+	try {
+		const hostname = new URL(endpoint).hostname.toLowerCase();
+		if (hostname.endsWith(".r2.cloudflarestorage.com")) return "r2";
+		if (hostname.endsWith(".amazonaws.com") || hostname === "s3.amazonaws.com") return "s3";
+		if (hostname === "storage.googleapis.com") return "gcs";
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Get s3fs flags for a given provider
+*
+* Based on s3fs-fuse wiki recommendations:
+* https://github.com/s3fs-fuse/s3fs-fuse/wiki/Non-Amazon-S3
+*/
+function getProviderFlags(provider) {
+	if (!provider) return ["use_path_request_style"];
+	switch (provider) {
+		case "r2": return ["nomixupload"];
+		case "s3": return [];
+		case "gcs": return [];
+		default: return ["use_path_request_style"];
+	}
+}
+/**
+* Resolve s3fs options by combining provider defaults with user overrides
+*/
+function resolveS3fsOptions(provider, userOptions) {
+	const providerFlags = getProviderFlags(provider);
+	if (!userOptions || userOptions.length === 0) return providerFlags;
+	const allFlags = [...providerFlags, ...userOptions];
+	const flagMap = /* @__PURE__ */ new Map();
+	for (const flag of allFlags) {
+		const [flagName] = flag.split("=");
+		flagMap.set(flagName, flag);
+	}
+	return Array.from(flagMap.values());
+}
+
+//#endregion
+//#region src/storage-mount/validation.ts
+function validatePrefix(prefix) {
+	if (!prefix.startsWith("/")) throw new InvalidMountConfigError(`Prefix must start with '/': "${prefix}"`);
+}
+function validateBucketName(bucket, mountPath) {
+	if (bucket.includes(":")) {
+		const [bucketName, prefixPart] = bucket.split(":");
+		throw new InvalidMountConfigError(`Bucket name cannot contain ':'. To mount a prefix, use the 'prefix' option:\n  mountBucket('${bucketName}', '${mountPath}', { ...options, prefix: '${prefixPart}' })`);
+	}
+	if (!/^[a-z0-9]([a-z0-9.-]{0,61}[a-z0-9])?$/.test(bucket)) throw new InvalidMountConfigError(`Invalid bucket name: "${bucket}". Bucket names must be 3-63 characters, lowercase alphanumeric, dots, or hyphens, and cannot start/end with dots or hyphens.`);
+}
+/**
+* Builds the s3fs source string from bucket name and optional prefix.
+* Format: "bucket" or "bucket:/prefix/" for subdirectory mounts.
+*
+* @param bucket - The bucket name
+* @param prefix - Optional prefix/subdirectory path
+* @returns The s3fs source string
+*/
+function buildS3fsSource(bucket, prefix) {
+	return prefix ? `${bucket}:${prefix}` : bucket;
+}
+
+//#endregion
+//#region src/local-mount-sync.ts
+const DEFAULT_POLL_INTERVAL_MS = 1e3;
+const DEFAULT_ECHO_SUPPRESS_TTL_MS = 2e3;
+const MAX_BACKOFF_MS = 3e4;
+const SYNC_CONCURRENCY = 5;
+/**
+* Manages bidirectional sync between an R2 binding and a container directory.
+*
+* R2 -> Container: polls bucket.list() to detect changes, then transfers diffs.
+* Container -> R2: uses inotifywait via the watch API to detect file changes.
+*/
+var LocalMountSyncManager = class {
+	bucket;
+	mountPath;
+	prefix;
+	readOnly;
+	client;
+	sessionId;
+	logger;
+	pollIntervalMs;
+	echoSuppressTtlMs;
+	snapshot = /* @__PURE__ */ new Map();
+	echoSuppressSet = /* @__PURE__ */ new Set();
+	pollTimer = null;
+	watchReconnectTimer = null;
+	watchAbortController = null;
+	running = false;
+	consecutivePollFailures = 0;
+	consecutiveWatchFailures = 0;
+	constructor(options) {
+		this.bucket = options.bucket;
+		this.mountPath = options.mountPath;
+		if (options.prefix !== void 0) validatePrefix(options.prefix);
+		this.prefix = options.prefix?.replace(/^\//, "") || void 0;
+		this.readOnly = options.readOnly;
+		this.client = options.client;
+		this.sessionId = options.sessionId;
+		this.logger = options.logger.child({ operation: "local-mount-sync" });
+		this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+		this.echoSuppressTtlMs = options.echoSuppressTtlMs ?? DEFAULT_ECHO_SUPPRESS_TTL_MS;
+	}
+	/**
+	* Start bidirectional sync. Performs initial full sync, then starts
+	* the R2 poll loop and (if not readOnly) the container watch loop.
+	*/
+	async start() {
+		this.running = true;
+		await this.client.files.mkdir(this.mountPath, this.sessionId, { recursive: true });
+		await this.fullSyncR2ToContainer();
+		this.schedulePoll();
 		if (!this.readOnly) this.startContainerWatch();
 		this.logger.info("Local mount sync started", {
 			mountPath: this.mountPath,
@@ -3532,181 +3646,23 @@ function isLocalhostPattern(hostname) {
 }
 
 //#endregion
-//#region src/storage-mount/errors.ts
-/**
-* Bucket mount and unmount error classes
-*
-* Validation errors (InvalidMountConfigError, MissingCredentialsError) are thrown
-* before any container interaction. BucketUnmountError is thrown after a failed
-* fusermount call inside the container.
-*/
-/**
-* Base error for bucket mounting operations
-*/
-var BucketMountError = class extends Error {
-	code;
-	constructor(message, code = ErrorCode.BUCKET_MOUNT_ERROR) {
-		super(message);
-		this.name = "BucketMountError";
-		this.code = code;
-	}
-};
-/**
-* Thrown when S3FS mount command fails
-*/
-var S3FSMountError = class extends BucketMountError {
-	constructor(message) {
-		super(message, ErrorCode.S3FS_MOUNT_ERROR);
-		this.name = "S3FSMountError";
-	}
-};
-/**
-* Thrown when fusermount -u fails to unmount a FUSE filesystem
-*/
-var BucketUnmountError = class extends BucketMountError {
-	constructor(message) {
-		super(message, ErrorCode.BUCKET_UNMOUNT_ERROR);
-		this.name = "BucketUnmountError";
-	}
-};
-/**
-* Thrown when no credentials found in environment
-*/
-var MissingCredentialsError = class extends BucketMountError {
-	constructor(message) {
-		super(message, ErrorCode.MISSING_CREDENTIALS);
-		this.name = "MissingCredentialsError";
-	}
-};
+//#region src/version.ts
 /**
-* Thrown when bucket name, mount path, or options are invalid
+* SDK version - automatically synchronized with package.json by Changesets
+* 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
 */
-var InvalidMountConfigError = class extends BucketMountError {
-	constructor(message) {
-		super(message, ErrorCode.INVALID_MOUNT_CONFIG);
-		this.name = "InvalidMountConfigError";
-	}
-};
-
-//#endregion
-//#region src/storage-mount/credential-detection.ts
-/**
-* Detect credentials for bucket mounting from environment variables
-* Priority order:
-* 1. Explicit options.credentials
-* 2. Standard AWS env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
-* 3. Standard R2 env vars: R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
-* 4. Error: no credentials found
-*
-* @param options - Mount options
-* @param envVars - Environment variables
-* @returns Detected credentials
-* @throws MissingCredentialsError if no credentials found
-*/
-function detectCredentials(options, envVars) {
-	if (options.credentials) return options.credentials;
-	const awsAccessKeyId = envVars.AWS_ACCESS_KEY_ID;
-	const awsSecretAccessKey = envVars.AWS_SECRET_ACCESS_KEY;
-	if (awsAccessKeyId && awsSecretAccessKey) return {
-		accessKeyId: awsAccessKeyId,
-		secretAccessKey: awsSecretAccessKey
-	};
-	/**
-	* Priority 3: Standard R2 env vars
-	*
-	* AWS vars still take precedence over R2 vars in case both are set
-	*/
-	const r2AccessKeyId = envVars.R2_ACCESS_KEY_ID;
-	const r2SecretAccessKey = envVars.R2_SECRET_ACCESS_KEY;
-	if (r2AccessKeyId && r2SecretAccessKey) return {
-		accessKeyId: r2AccessKeyId,
-		secretAccessKey: r2SecretAccessKey
-	};
-	throw new MissingCredentialsError("No credentials found. Set R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or pass explicit credentials in options.");
-}
-
-//#endregion
-//#region src/storage-mount/provider-detection.ts
-/**
-* Detect provider from endpoint URL using pattern matching
-*/
-function detectProviderFromUrl(endpoint) {
-	try {
-		const hostname = new URL(endpoint).hostname.toLowerCase();
-		if (hostname.endsWith(".r2.cloudflarestorage.com")) return "r2";
-		if (hostname.endsWith(".amazonaws.com") || hostname === "s3.amazonaws.com") return "s3";
-		if (hostname === "storage.googleapis.com") return "gcs";
-		return null;
-	} catch {
-		return null;
-	}
-}
-/**
-* Get s3fs flags for a given provider
-*
-* Based on s3fs-fuse wiki recommendations:
-* https://github.com/s3fs-fuse/s3fs-fuse/wiki/Non-Amazon-S3
-*/
-function getProviderFlags(provider) {
-	if (!provider) return ["use_path_request_style"];
-	switch (provider) {
-		case "r2": return ["nomixupload"];
-		case "s3": return [];
-		case "gcs": return [];
-		default: return ["use_path_request_style"];
-	}
-}
-/**
-* Resolve s3fs options by combining provider defaults with user overrides
-*/
-function resolveS3fsOptions(provider, userOptions) {
-	const providerFlags = getProviderFlags(provider);
-	if (!userOptions || userOptions.length === 0) return providerFlags;
-	const allFlags = [...providerFlags, ...userOptions];
-	const flagMap = /* @__PURE__ */ new Map();
-	for (const flag of allFlags) {
-		const [flagName] = flag.split("=");
-		flagMap.set(flagName, flag);
-	}
-	return Array.from(flagMap.values());
-}
-
-//#endregion
-//#region src/storage-mount/validation.ts
-function validatePrefix(prefix) {
-	if (!prefix.startsWith("/")) throw new InvalidMountConfigError(`Prefix must start with '/': "${prefix}"`);
-}
-function validateBucketName(bucket, mountPath) {
-	if (bucket.includes(":")) {
-		const [bucketName, prefixPart] = bucket.split(":");
-		throw new InvalidMountConfigError(`Bucket name cannot contain ':'. To mount a prefix, use the 'prefix' option:\n  mountBucket('${bucketName}', '${mountPath}', { ...options, prefix: '${prefixPart}' })`);
-	}
-	if (!/^[a-z0-9]([a-z0-9.-]{0,61}[a-z0-9])?$/.test(bucket)) throw new InvalidMountConfigError(`Invalid bucket name: "${bucket}". Bucket names must be 3-63 characters, lowercase alphanumeric, dots, or hyphens, and cannot start/end with dots or hyphens.`);
-}
-/**
-* Builds the s3fs source string from bucket name and optional prefix.
-* Format: "bucket" or "bucket:/prefix/" for subdirectory mounts.
-*
-* @param bucket - The bucket name
-* @param prefix - Optional prefix/subdirectory path
-* @returns The s3fs source string
-*/
-function buildS3fsSource(bucket, prefix) {
-	return prefix ? `${bucket}:${prefix}` : bucket;
-}
-
-//#endregion
-//#region src/version.ts
-/**
-* SDK version - automatically synchronized with package.json by Changesets
-* 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.8.11";
+const SDK_VERSION = "0.9.0";
 
 //#endregion
 //#region src/sandbox.ts
 const sandboxConfigurationCache = /* @__PURE__ */ new WeakMap();
+const BACKUP_DEFAULT_TTL_SECONDS = 259200;
+const BACKUP_MAX_NAME_LENGTH = 256;
+const BACKUP_CONTAINER_DIR = "/var/backups";
+const BACKUP_STORAGE_PREFIX = "backups";
+const BACKUP_ARCHIVE_OBJECT_NAME = "data.sqsh";
+const BACKUP_METADATA_OBJECT_NAME = "meta.json";
 function getNamespaceConfigurationCache(namespace) {
 	const existing = sandboxConfigurationCache.get(namespace);
 	if (existing) return existing;
@@ -3723,14 +3679,14 @@ function buildSandboxConfiguration(effectiveId, options, cached) {
 		name: effectiveId,
 		normalizeId: options?.normalizeId
 	};
-	if (options?.baseUrl !== void 0 && cached?.baseUrl !== options.baseUrl) configuration.baseUrl = options.baseUrl;
 	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.baseUrl !== void 0 || configuration.sleepAfter !== void 0 || configuration.keepAlive !== void 0 || configuration.containerTimeouts !== void 0;
+	return configuration.sandboxName !== void 0 || configuration.sleepAfter !== void 0 || configuration.keepAlive !== void 0 || configuration.containerTimeouts !== void 0 || configuration.transport !== void 0;
 }
 function mergeSandboxConfiguration(cached, configuration) {
 	return {
@@ -3739,20 +3695,20 @@ function mergeSandboxConfiguration(cached, configuration) {
 			sandboxName: configuration.sandboxName.name,
 			normalizeId: configuration.sandboxName.normalizeId
 		},
-		...configuration.baseUrl !== void 0 && { baseUrl: configuration.baseUrl },
 		...configuration.sleepAfter !== void 0 && { sleepAfter: configuration.sleepAfter },
 		...configuration.keepAlive !== void 0 && { keepAlive: configuration.keepAlive },
-		...configuration.containerTimeouts !== void 0 && { containerTimeouts: configuration.containerTimeouts }
+		...configuration.containerTimeouts !== void 0 && { containerTimeouts: configuration.containerTimeouts },
+		...configuration.transport !== void 0 && { transport: configuration.transport }
 	};
 }
 function applySandboxConfiguration(stub, configuration) {
 	if (stub.configure) return stub.configure(configuration);
 	const operations = [];
 	if (configuration.sandboxName) operations.push(stub.setSandboxName?.(configuration.sandboxName.name, configuration.sandboxName.normalizeId) ?? Promise.resolve());
-	if (configuration.baseUrl !== void 0) operations.push(stub.setBaseUrl?.(configuration.baseUrl) ?? Promise.resolve());
 	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) {
@@ -3823,13 +3779,21 @@ var Sandbox = class Sandbox extends Container {
 	codeInterpreter;
 	sandboxName = null;
 	normalizeId = false;
-	baseUrl = null;
 	defaultSession = null;
+	containerGeneration = 0;
+	defaultSessionInit = null;
 	envVars = {};
 	logger;
 	keepAliveEnabled = false;
 	activeMounts = /* @__PURE__ */ new Map();
 	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.
@@ -3863,6 +3827,15 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	containerTimeouts = { ...this.DEFAULT_CONTAINER_TIMEOUTS };
 	/**
+	* True once containerTimeouts has been written to storage at least once
+	* (either via setContainerTimeouts or restored on cold start). Gates the
+	* idempotency check in setContainerTimeouts so a first explicit call
+	* persists even when the requested values already equal the in-memory
+	* defaults, distinguishing "user intent recorded" from "running on
+	* env/SDK defaults".
+	*/
+	hasStoredContainerTimeouts = false;
+	/**
 	* Desktop environment operations.
 	* Within the DO, this getter provides direct access to DesktopClient.
 	* Over RPC, the getSandbox() proxy intercepts this property and routes
@@ -3967,16 +3940,17 @@ var Sandbox = class Sandbox extends Container {
 		this.client = this.createSandboxClient();
 		this.codeInterpreter = new CodeInterpreter(this);
 		this.ctx.blockConcurrencyWhile(async () => {
-			this.sandboxName = await this.ctx.storage.get("sandboxName") || null;
-			this.normalizeId = await this.ctx.storage.get("normalizeId") || false;
-			this.defaultSession = await this.ctx.storage.get("defaultSession") || null;
-			this.keepAliveEnabled = await this.ctx.storage.get("keepAliveEnabled") || false;
+			this.sandboxName = await this.ctx.storage.get("sandboxName") ?? null;
+			this.normalizeId = await this.ctx.storage.get("normalizeId") ?? false;
+			this.defaultSession = await this.ctx.storage.get("defaultSession") ?? null;
+			this.keepAliveEnabled = await this.ctx.storage.get("keepAliveEnabled") ?? false;
 			const storedTimeouts = await this.ctx.storage.get("containerTimeouts");
 			if (storedTimeouts) {
 				this.containerTimeouts = {
 					...this.containerTimeouts,
 					...storedTimeouts
 				};
+				this.hasStoredContainerTimeouts = true;
 				this.client.setRetryTimeoutMs(this.computeRetryTimeoutMs());
 			}
 			const storedSleepAfter = await this.ctx.storage.get("sleepAfter");
@@ -3984,6 +3958,15 @@ 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.createSandboxClient();
+				this.codeInterpreter = new CodeInterpreter(this);
+				previousClient.disconnect();
+			}
+			if (storedTransport) this.hasStoredTransport = true;
 			if (this.interceptHttps) this.envVars = {
 				...this.envVars,
 				SANDBOX_INTERCEPT_HTTPS: "1"
@@ -3991,34 +3974,29 @@ var Sandbox = class Sandbox extends Container {
 		});
 	}
 	async setSandboxName(name, normalizeId) {
-		if (!this.sandboxName) {
-			this.sandboxName = name;
-			this.normalizeId = normalizeId || false;
-			await this.ctx.storage.put("sandboxName", name);
-			await this.ctx.storage.put("normalizeId", this.normalizeId);
-		}
+		if (this.sandboxName !== null) return;
+		const effectiveNormalizeId = normalizeId ?? false;
+		await Promise.all([this.ctx.storage.put("sandboxName", name), this.ctx.storage.put("normalizeId", effectiveNormalizeId)]);
+		this.sandboxName = name;
+		this.normalizeId = effectiveNormalizeId;
 	}
 	async configure(configuration) {
 		if (configuration.sandboxName) await this.setSandboxName(configuration.sandboxName.name, configuration.sandboxName.normalizeId);
-		if (configuration.baseUrl !== void 0) await this.setBaseUrl(configuration.baseUrl);
 		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);
-	}
-	async setBaseUrl(baseUrl) {
-		if (!this.baseUrl) {
-			this.baseUrl = baseUrl;
-			await this.ctx.storage.put("baseUrl", baseUrl);
-		} else if (this.baseUrl !== baseUrl) throw new Error("Base URL already set and different from one previously provided");
+		if (configuration.transport !== void 0) await this.setTransport(configuration.transport);
 	}
 	async setSleepAfter(sleepAfter) {
-		this.sleepAfter = sleepAfter;
+		if (this.sleepAfter === sleepAfter) return;
 		await this.ctx.storage.put("sleepAfter", sleepAfter);
+		this.sleepAfter = sleepAfter;
 		this.renewActivityTimeout();
 	}
 	async setKeepAlive(keepAlive) {
-		this.keepAliveEnabled = keepAlive;
+		if (this.keepAliveEnabled === keepAlive) return;
 		await this.ctx.storage.put("keepAliveEnabled", keepAlive);
+		this.keepAliveEnabled = keepAlive;
 		if (!keepAlive) this.renewActivityTimeout();
 	}
 	async setEnvVars(envVars) {
@@ -4042,19 +4020,45 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	/**
-	* RPC method to configure container startup timeouts
+	* RPC method to configure container startup timeouts. Idempotent once
+	* the values have been persisted: re-applying the same timeout set is a
+	* no-op. The transport retry budget is recomputed only when at least
+	* one timeout actually changes. Storage is written before the in-memory
+	* mirror and derived state are updated.
 	*/
 	async setContainerTimeouts(timeouts) {
 		const validated = { ...this.containerTimeouts };
 		if (timeouts.instanceGetTimeoutMS !== void 0) validated.instanceGetTimeoutMS = this.validateTimeout(timeouts.instanceGetTimeoutMS, "instanceGetTimeoutMS", 5e3, 3e5);
 		if (timeouts.portReadyTimeoutMS !== void 0) validated.portReadyTimeoutMS = this.validateTimeout(timeouts.portReadyTimeoutMS, "portReadyTimeoutMS", 1e4, 6e5);
 		if (timeouts.waitIntervalMS !== void 0) validated.waitIntervalMS = this.validateTimeout(timeouts.waitIntervalMS, "waitIntervalMS", 100, 5e3);
+		if (this.hasStoredContainerTimeouts && validated.instanceGetTimeoutMS === this.containerTimeouts.instanceGetTimeoutMS && validated.portReadyTimeoutMS === this.containerTimeouts.portReadyTimeoutMS && validated.waitIntervalMS === this.containerTimeouts.waitIntervalMS) return;
+		await this.ctx.storage.put("containerTimeouts", validated);
 		this.containerTimeouts = validated;
-		await this.ctx.storage.put("containerTimeouts", this.containerTimeouts);
+		this.hasStoredContainerTimeouts = true;
 		this.client.setRetryTimeoutMs(this.computeRetryTimeoutMs());
 		this.logger.debug("Container timeouts updated", this.containerTimeouts);
 	}
 	/**
+	* RPC method to set the transport protocol. Idempotent once the value
+	* has been persisted: re-applying the same transport is a no-op.
+	* 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.`);
+			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.createSandboxClient();
+		this.codeInterpreter = new CodeInterpreter(this);
+		previousClient.disconnect();
+		this.logger.debug("Transport updated", { transport });
+	}
+	/**
 	* Validate a timeout value is within acceptable range
 	* Throws error if invalid - used for user-provided values
 	*/
@@ -4102,6 +4106,7 @@ var Sandbox = class Sandbox extends Container {
 	* @throws InvalidMountConfigError if bucket name, mount path, or endpoint is invalid
 	*/
 	async mountBucket(bucket, mountPath, options) {
+		if (options.prefix !== void 0) validatePrefix(options.prefix);
 		if ("localBucket" in options && options.localBucket) {
 			await this.mountBucketLocal(bucket, mountPath, options);
 			return;
@@ -4294,7 +4299,6 @@ var Sandbox = class Sandbox extends Container {
 		validateBucketName(bucket, mountPath);
 		if (!mountPath.startsWith("/")) throw new InvalidMountConfigError(`Mount path must be absolute (start with /): "${mountPath}"`);
 		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path "${mountPath}" is already in use by bucket "${this.activeMounts.get(mountPath)?.bucket}". Unmount the existing bucket first or use a different mount path.`);
-		if (options.prefix !== void 0) validatePrefix(options.prefix);
 	}
 	/**
 	* Generate unique password file path for s3fs credentials
@@ -4376,6 +4380,7 @@ var Sandbox = class Sandbox extends Container {
 					await this.deletePasswordFile(mountInfo.passwordFilePath);
 				}
 			}
+			await this.ctx.storage.delete("portTokens");
 			outcome = "success";
 			await super.destroy();
 		} catch (error) {
@@ -4392,11 +4397,84 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
-	onStart() {
+	async onStart() {
 		this.logger.debug("Sandbox started");
 		this.checkVersionCompatibility().catch((error) => {
 			this.logger.error("Version compatibility check failed", error instanceof Error ? error : new Error(String(error)));
 		});
+		try {
+			await this.restoreExposedPorts();
+		} catch (error) {
+			this.logger.error("Failed to restore exposed ports after container start", error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	/**
+	* Re-expose ports on the container runtime using tokens persisted in DO
+	* storage. Called from onStart() after a container (re)start.
+	*
+	* The DO storage holds the source of truth for which ports should be
+	* exposed, which tokens authorize them, and the friendly name (if any)
+	* that the caller set when first exposing the port. If a port is already
+	* exposed on the container this is a no-op for that port. Individual port
+	* failures are logged but do not abort the overall restore — a transient
+	* failure for one port must not prevent the others from being restored.
+	*/
+	async restoreExposedPorts() {
+		const savedTokens = await this.readPortTokens();
+		const portEntries = Object.entries(savedTokens);
+		if (portEntries.length === 0) return;
+		const startTime = Date.now();
+		let restored = 0;
+		let skipped = 0;
+		let failed = 0;
+		const sessionId = await this.ensureDefaultSession();
+		const exposedSet = await this.client.ports.getExposedPorts(sessionId).then((response) => new Set(response.ports.map((p) => p.port))).catch((error) => {
+			this.logger.warn("Failed to fetch exposed ports for restore; assuming none exposed", { error: error instanceof Error ? error.message : String(error) });
+			return /* @__PURE__ */ new Set();
+		});
+		for (const [portStr, entry] of portEntries) {
+			const port = Number.parseInt(portStr, 10);
+			if (!Number.isFinite(port) || !validatePort(port)) {
+				this.logger.warn("Skipping restore of invalid port in storage", { port: portStr });
+				failed++;
+				continue;
+			}
+			if (exposedSet.has(port)) {
+				skipped++;
+				continue;
+			}
+			try {
+				await this.client.ports.exposePort(port, sessionId, entry.name);
+				restored++;
+			} catch (error) {
+				failed++;
+				this.logger.warn("Failed to re-expose port on container restart", {
+					port,
+					error: error instanceof Error ? error.message : String(error)
+				});
+			}
+		}
+		logCanonicalEvent(this.logger, {
+			event: "port.restore",
+			outcome: failed === 0 ? "success" : "error",
+			durationMs: Date.now() - startTime,
+			restored,
+			skipped,
+			failed,
+			total: portEntries.length
+		});
+	}
+	/**
+	* Read the `portTokens` map from DO storage, normalizing the legacy
+	* string-valued format (just a token) to the current object format
+	* ({ token, name? }). The legacy format predates port-name persistence and
+	* can appear on any DO whose storage was written before that change.
+	*/
+	async readPortTokens() {
+		const raw = await this.ctx.storage.get("portTokens") ?? {};
+		const normalized = {};
+		for (const [port, value] of Object.entries(raw)) normalized[port] = typeof value === "string" ? { token: value } : value;
+		return normalized;
 	}
 	/**
 	* Check if the container version matches the SDK version
@@ -4427,10 +4505,12 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async onStop() {
 		this.logger.debug("Sandbox stopped");
-		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
+		this.containerGeneration++;
 		this.defaultSession = null;
+		this.defaultSessionInit = null;
+		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
 		this.activeMounts.clear();
-		await Promise.all([this.ctx.storage.delete("portTokens"), this.ctx.storage.delete("defaultSession")]);
+		await this.ctx.storage.delete("defaultSession");
 	}
 	onError(error) {
 		this.logger.error("Sandbox error", error instanceof Error ? error : new Error(String(error)));
@@ -4681,33 +4761,46 @@ var Sandbox = class Sandbox extends Container {
 		return 3e3;
 	}
 	/**
-	* Ensure default session exists - lazy initialization
-	* This is called automatically by all public methods that need a session
-	*
-	* The session ID is persisted to DO storage. On container restart, if the
-	* container already has this session (from a previous instance), we sync
-	* our state rather than failing on duplicate creation.
+	* Return the default session id, lazily creating the container session
+	* on first use. Called by every public method that needs a session.
+	* Concurrent callers that target the same sessionId share one
+	* in-flight initialization promise.
 	*/
 	async ensureDefaultSession() {
 		const sessionId = `sandbox-${this.sandboxName || "default"}`;
 		if (this.defaultSession === sessionId) return this.defaultSession;
+		const generation = this.containerGeneration;
+		const pending = this.defaultSessionInit;
+		if (pending?.sessionId === sessionId && pending.generation === generation) return pending.promise;
+		const promise = this.initializeDefaultSession(sessionId, generation);
+		const init = {
+			sessionId,
+			generation,
+			promise
+		};
+		this.defaultSessionInit = init;
+		try {
+			return await promise;
+		} finally {
+			if (this.defaultSessionInit === init) this.defaultSessionInit = null;
+		}
+	}
+	async initializeDefaultSession(sessionId, generation) {
 		try {
 			await this.client.utils.createSession({
 				id: sessionId,
 				env: this.envVars || {},
 				cwd: "/workspace"
 			});
-			this.defaultSession = sessionId;
-			await this.ctx.storage.put("defaultSession", sessionId);
-			this.logger.debug("Default session initialized", { sessionId });
 		} catch (error) {
-			if (error instanceof SessionAlreadyExistsError) {
-				this.logger.debug("Session exists in container but not in DO state, syncing", { sessionId });
-				this.defaultSession = sessionId;
-				await this.ctx.storage.put("defaultSession", sessionId);
-			} else throw error;
+			if (!(error instanceof SessionAlreadyExistsError)) throw error;
+			this.logger.debug("Session exists in container but not in DO state, syncing", { sessionId });
 		}
-		return this.defaultSession;
+		if (generation !== this.containerGeneration) throw new Error("Default session initialization was invalidated by a container stop");
+		await this.ctx.storage.put("defaultSession", sessionId);
+		this.defaultSession = sessionId;
+		this.logger.debug("Default session initialized", { sessionId });
+		return sessionId;
 	}
 	async exec(command, options) {
 		const session = await this.ensureDefaultSession();
@@ -5270,8 +5363,8 @@ var Sandbox = class Sandbox extends Container {
 				token: options?.token
 			})).url;
 		} catch {
-			const existingToken = (await this.ctx.storage.get("portTokens") || {})["6080"];
-			if (existingToken && this.sandboxName) url = this.constructPreviewUrl(6080, this.sandboxName, hostname, existingToken);
+			const existingEntry = (await this.readPortTokens())["6080"];
+			if (existingEntry && this.sandboxName) url = this.constructPreviewUrl(6080, this.sandboxName, hostname, existingEntry.token);
 			else throw new Error("Failed to get desktop stream URL: port 6080 could not be exposed and no existing token found.");
 		}
 		try {
@@ -5330,6 +5423,12 @@ var Sandbox = class Sandbox extends Container {
 	/**
 	* Expose a port and get a preview URL for accessing services running in the sandbox
 	*
+	* Preview URLs survive transient container restarts: the token and any
+	* friendly name are persisted in Durable Object storage, and the port is
+	* automatically re-exposed on the container when it comes back up. Tokens
+	* are cleared only on explicit `unexposePort()` or full sandbox
+	* `destroy()`.
+	*
 	* @param port - Port number to expose (1024-65535)
 	* @param options - Configuration options
 	* @param options.hostname - Your Worker's domain name (required for preview URL construction)
@@ -5370,12 +5469,15 @@ var Sandbox = class Sandbox extends Container {
 				this.validateCustomToken(options.token);
 				token = options.token;
 			} else token = this.generatePortToken();
-			const tokens = await this.ctx.storage.get("portTokens") || {};
-			const existingPort = Object.entries(tokens).find(([p, t]) => t === token && p !== port.toString());
+			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.`);
 			const sessionId = await this.ensureDefaultSession();
 			await this.client.ports.exposePort(port, sessionId, options?.name);
-			tokens[port.toString()] = token;
+			tokens[port.toString()] = {
+				token,
+				name: options?.name
+			};
 			await this.ctx.storage.put("portTokens", tokens);
 			const url = this.constructPreviewUrl(port, this.sandboxName, options.hostname, token);
 			outcome = "success";
@@ -5405,13 +5507,17 @@ var Sandbox = class Sandbox extends Container {
 		let caughtError;
 		try {
 			if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
-			const sessionId = await this.ensureDefaultSession();
-			await this.client.ports.unexposePort(port, sessionId);
-			const tokens = await this.ctx.storage.get("portTokens") || {};
+			const tokens = await this.readPortTokens();
 			if (tokens[port.toString()]) {
 				delete tokens[port.toString()];
 				await this.ctx.storage.put("portTokens", tokens);
 			}
+			const sessionId = await this.ensureDefaultSession();
+			try {
+				await this.client.ports.unexposePort(port, sessionId);
+			} catch (error) {
+				if (!(error instanceof PortNotExposedError)) throw error;
+			}
 			outcome = "success";
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
@@ -5430,15 +5536,18 @@ var Sandbox = class Sandbox extends Container {
 		const sessionId = await this.ensureDefaultSession();
 		const response = await this.client.ports.getExposedPorts(sessionId);
 		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
-		const tokens = await this.ctx.storage.get("portTokens") || {};
-		return response.ports.map((port) => {
-			const token = tokens[port.port.toString()];
-			if (!token) throw new Error(`Port ${port.port} is exposed but has no token. This should not happen.`);
-			return {
-				url: this.constructPreviewUrl(port.port, this.sandboxName, hostname, token),
+		const tokens = await this.readPortTokens();
+		return response.ports.flatMap((port) => {
+			const entry = tokens[port.port.toString()];
+			if (!entry) {
+				this.logger.warn("Port exposed on container but no token in storage; omitting from preview URL list", { port: port.port });
+				return [];
+			}
+			return [{
+				url: this.constructPreviewUrl(port.port, this.sandboxName, hostname, entry.token),
 				port: port.port,
 				status: port.status
-			};
+			}];
 		});
 	}
 	async isPortExposed(port) {
@@ -5451,14 +5560,10 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	async validatePortToken(port, token) {
-		if (!await this.isPortExposed(port)) return false;
-		const storedToken = (await this.ctx.storage.get("portTokens") || {})[port.toString()];
-		if (!storedToken) {
-			this.logger.error("Port is exposed but has no token - bug detected", void 0, { port });
-			return false;
-		}
+		const entry = (await this.readPortTokens())[port.toString()];
+		if (!entry) return false;
 		const encoder = new TextEncoder();
-		const a = encoder.encode(storedToken);
+		const a = encoder.encode(entry.token);
 		const b = encoder.encode(token);
 		try {
 			return crypto.subtle.timingSafeEqual(a, b);
@@ -5732,18 +5837,6 @@ var Sandbox = class Sandbox extends Container {
 		};
 	}
 	/**
-	* Generate a presigned GET URL for downloading an object from R2.
-	* The container can curl this URL directly without credentials.
-	*/
-	async generatePresignedGetUrl(r2Key) {
-		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
-		const encodedBucket = encodeURIComponent(bucketName);
-		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
-		const url = new URL(`https://${accountId}.r2.cloudflarestorage.com/${encodedBucket}/${encodedKey}`);
-		url.searchParams.set("X-Amz-Expires", String(Sandbox.PRESIGNED_URL_EXPIRY_SECONDS));
-		return (await client.sign(new Request(url), { aws: { signQuery: true } })).url;
-	}
-	/**
 	* Generate a presigned PUT URL for uploading an object to R2.
 	* The container can curl PUT to this URL directly without credentials.
 	*/
@@ -5880,15 +5973,14 @@ var Sandbox = class Sandbox extends Container {
 	* under the `backups/` prefix after the desired retention period.
 	*/
 	async createBackup(options) {
+		if (options.localBucket) return this.enqueueBackupOp(() => this.doCreateBackupLocal(options));
 		this.requireBackupBucket();
 		return this.enqueueBackupOp(() => this.doCreateBackup(options));
 	}
 	async doCreateBackup(options) {
 		const bucket = this.requireBackupBucket();
 		this.requirePresignedUrlSupport();
-		const DEFAULT_TTL_SECONDS = 259200;
-		const MAX_NAME_LENGTH = 256;
-		const { dir, name, ttl = DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
+		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
 		const backupStartTime = Date.now();
 		let backupId;
 		let sizeBytes;
@@ -5898,11 +5990,11 @@ var Sandbox = class Sandbox extends Container {
 		try {
 			Sandbox.validateBackupDir(dir, "BackupOptions.dir");
 			if (name !== void 0) {
-				if (typeof name !== "string" || name.length > MAX_NAME_LENGTH) throw new InvalidBackupConfigError({
-					message: `BackupOptions.name must be a string of at most ${MAX_NAME_LENGTH} characters`,
+				if (typeof name !== "string" || name.length > BACKUP_MAX_NAME_LENGTH) throw new InvalidBackupConfigError({
+					message: `BackupOptions.name must be a string of at most ${BACKUP_MAX_NAME_LENGTH} characters`,
 					code: ErrorCode.INVALID_BACKUP_CONFIG,
 					httpStatus: 400,
-					context: { reason: `name must be a string of at most ${MAX_NAME_LENGTH} characters` },
+					context: { reason: `name must be a string of at most ${BACKUP_MAX_NAME_LENGTH} characters` },
 					timestamp: (/* @__PURE__ */ new Date()).toISOString()
 				});
 				if (/[\u0000-\u001f\u007f]/.test(name)) throw new InvalidBackupConfigError({
@@ -5936,7 +6028,7 @@ var Sandbox = class Sandbox extends Container {
 			});
 			backupSession = await this.ensureBackupSession();
 			backupId = crypto.randomUUID();
-			const archivePath = `/var/backups/${backupId}.sqsh`;
+			const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
 			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, gitignore, excludes);
 			if (!createResult.success) throw new BackupCreateError({
 				message: "Container failed to create backup archive",
@@ -5949,8 +6041,8 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			sizeBytes = createResult.sizeBytes;
-			const r2Key = `backups/${backupId}/data.sqsh`;
-			const metaKey = `backups/${backupId}/meta.json`;
+			const r2Key = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
+			const metaKey = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_METADATA_OBJECT_NAME}`;
 			await this.uploadBackupPresigned(archivePath, r2Key, createResult.sizeBytes, backupId, dir, backupSession);
 			const metadata = {
 				id: backupId,
@@ -5970,9 +6062,9 @@ var Sandbox = class Sandbox extends Container {
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
 			if (backupId && backupSession) {
-				const archivePath = `/var/backups/${backupId}.sqsh`;
-				const r2Key = `backups/${backupId}/data.sqsh`;
-				const metaKey = `backups/${backupId}/meta.json`;
+				const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
+				const r2Key = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
+				const metaKey = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_METADATA_OBJECT_NAME}`;
 				await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
 				await bucket.delete(r2Key).catch(() => {});
 				await bucket.delete(metaKey).catch(() => {});
@@ -5993,61 +6085,200 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	/**
-	* Restore a backup from R2 into a directory.
-	*
-	* Flow:
-	*   1. DO reads metadata from R2 and checks TTL
-	*   2. Container mounts the backup archive from R2 via s3fs
-	*   3. Container mounts the squashfs archive with FUSE overlayfs
-	*
-	* The target directory becomes an overlay mount with the backup as a
-	* read-only lower layer and a writable upper layer for copy-on-write.
-	* Any processes writing to the directory should be stopped first.
-	*
-	* **Mount Lifecycle**: The FUSE overlay mount persists only while the
-	* container is running. When the sandbox sleeps or the container restarts,
-	* the mount is lost and the directory becomes empty. Re-restore from the
-	* backup handle to recover. This is an ephemeral restore, not a persistent
-	* extraction.
-	*
-	* The backup is restored into `backup.dir`. This may differ from the
-	* directory that was originally backed up, allowing cross-directory restore.
-	*
-	* Overlapping backups are independent: restoring a parent directory
-	* overwrites everything inside it, including subdirectories that were
-	* backed up separately. When restoring both, restore the parent first.
-	*
-	* Concurrent backup/restore calls on the same sandbox are serialized.
+	* Local-dev implementation of createBackup.
+	* Uses the R2 binding directly instead of presigned URLs.
+	* Archive format is identical to production (squashfs + meta.json).
 	*/
-	async restoreBackup(backup) {
-		this.requireBackupBucket();
-		return this.enqueueBackupOp(() => this.doRestoreBackup(backup));
-	}
-	async doRestoreBackup(backup) {
-		const restoreStartTime = Date.now();
-		const bucket = this.requireBackupBucket();
-		this.requirePresignedUrlSupport();
-		const { id, dir } = backup;
+	async doCreateBackupLocal(options) {
+		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
+		const backupStartTime = Date.now();
+		let backupId;
+		let sizeBytes;
 		let outcome = "error";
 		let caughtError;
 		let backupSession;
+		const bucket = this.env.BACKUP_BUCKET;
+		if (!bucket || !isR2Bucket(bucket)) throw new InvalidBackupConfigError({
+			message: "BACKUP_BUCKET R2 binding not found in env. Add a BACKUP_BUCKET R2 binding to your wrangler.jsonc for local backup support.",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "Missing BACKUP_BUCKET R2 binding" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
 		try {
-			if (!id || typeof id !== "string") throw new InvalidBackupConfigError({
-				message: "Invalid backup: missing or invalid id",
+			Sandbox.validateBackupDir(dir, "BackupOptions.dir");
+			if (name !== void 0) {
+				if (typeof name !== "string" || name.length > BACKUP_MAX_NAME_LENGTH) throw new InvalidBackupConfigError({
+					message: `BackupOptions.name must be a string of at most ${BACKUP_MAX_NAME_LENGTH} characters`,
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: `name must be a string of at most ${BACKUP_MAX_NAME_LENGTH} characters` },
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+				if (/[\u0000-\u001f\u007f]/.test(name)) throw new InvalidBackupConfigError({
+					message: "BackupOptions.name must not contain control characters",
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: "name must not contain control characters" },
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			if (ttl <= 0) throw new InvalidBackupConfigError({
+				message: "BackupOptions.ttl must be a positive number of seconds",
 				code: ErrorCode.INVALID_BACKUP_CONFIG,
 				httpStatus: 400,
-				context: { reason: "missing or invalid id" },
+				context: { reason: "ttl must be a positive number of seconds" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			if (!Sandbox.UUID_REGEX.test(id)) throw new InvalidBackupConfigError({
-				message: "Invalid backup: id must be a valid UUID (e.g. from createBackup)",
+			if (typeof gitignore !== "boolean") throw new InvalidBackupConfigError({
+				message: "BackupOptions.gitignore must be a boolean",
 				code: ErrorCode.INVALID_BACKUP_CONFIG,
 				httpStatus: 400,
-				context: { reason: "id must be a valid UUID" },
+				context: { reason: "gitignore must be a boolean" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			if (!Array.isArray(excludes) || !excludes.every((e) => typeof e === "string")) throw new InvalidBackupConfigError({
+				message: "BackupOptions.excludes must be an array of strings",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "excludes must be an array of strings" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			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);
+			if (!createResult.success) throw new BackupCreateError({
+				message: "Container failed to create backup archive",
+				code: ErrorCode.BACKUP_CREATE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			sizeBytes = createResult.sizeBytes;
+			const r2Key = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
+			const metaKey = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_METADATA_OBJECT_NAME}`;
+			const { content } = await collectFile(await this.client.files.readFileStream(archivePath, backupSession));
+			const archiveData = content instanceof Uint8Array ? content : new TextEncoder().encode(content);
+			await bucket.put(r2Key, archiveData);
+			const head = await bucket.head(r2Key);
+			if (!head || head.size !== createResult.sizeBytes) throw new BackupCreateError({
+				message: `Upload verification failed: expected ${createResult.sizeBytes} bytes, got ${head?.size ?? 0}`,
+				code: ErrorCode.BACKUP_CREATE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const metadata = {
+				id: backupId,
+				dir,
+				name: name || null,
+				sizeBytes: createResult.sizeBytes,
+				ttl,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			await bucket.put(metaKey, JSON.stringify(metadata));
+			outcome = "success";
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
+			return {
+				id: backupId,
+				dir,
+				localBucket: true
+			};
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			if (backupId && backupSession) {
+				const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
+				const r2Key = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
+				const metaKey = `${BACKUP_STORAGE_PREFIX}/${backupId}/${BACKUP_METADATA_OBJECT_NAME}`;
+				await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
+				await bucket.delete(r2Key).catch(() => {});
+				await bucket.delete(metaKey).catch(() => {});
+			}
+			throw error;
+		} finally {
+			if (backupSession) await this.client.utils.deleteSession(backupSession).catch(() => {});
+			logCanonicalEvent(this.logger, {
+				event: "backup.create",
+				outcome,
+				durationMs: Date.now() - backupStartTime,
+				backupId,
+				dir,
+				name,
+				sizeBytes,
+				provider: "local-binding",
+				error: caughtError
+			});
+		}
+	}
+	/**
+	* Restore a backup from R2 into a directory.
+	*
+	* **Production flow** (`localBucket` not set):
+	*   1. DO reads metadata from R2 and checks TTL
+	*   2. Container mounts the backup archive from R2 via s3fs
+	*   3. Container mounts the squashfs archive with FUSE overlayfs
+	*
+	* The target directory becomes an overlay mount with the backup as a
+	* read-only lower layer and a writable upper layer for copy-on-write.
+	* Any processes writing to the directory should be stopped first.
+	*
+	* **Mount Lifecycle**: The FUSE overlay mount persists only while the
+	* container is running. When the sandbox sleeps or the container restarts,
+	* the mount is lost and the directory becomes empty. Re-restore from the
+	* backup handle to recover. This is an ephemeral restore, not a persistent
+	* extraction.
+	*
+	* **Local-dev flow** (`localBucket: true` on the originating `createBackup` call):
+	*   1. DO reads metadata and checks TTL via R2 binding
+	*   2. DO downloads the archive from R2 and writes it to the container
+	*   3. Container extracts the archive with `unsquashfs` (no FUSE needed)
+	*
+	* The backup is restored into `backup.dir`. This may differ from the
+	* directory that was originally backed up, allowing cross-directory restore.
+	*
+	* Overlapping backups are independent: restoring a parent directory
+	* overwrites everything inside it, including subdirectories that were
+	* backed up separately. When restoring both, restore the parent first.
+	*
+	* Concurrent backup/restore calls on the same sandbox are serialized.
+	*/
+	async restoreBackup(backup) {
+		if (backup.localBucket) return this.enqueueBackupOp(() => this.doRestoreBackupLocal(backup));
+		this.requireBackupBucket();
+		return this.enqueueBackupOp(() => this.doRestoreBackup(backup));
+	}
+	async doRestoreBackup(backup) {
+		const restoreStartTime = Date.now();
+		const bucket = this.requireBackupBucket();
+		this.requirePresignedUrlSupport();
+		const { id, dir } = backup;
+		let outcome = "error";
+		let caughtError;
+		let backupSession;
+		try {
+			if (!id || typeof id !== "string") throw new InvalidBackupConfigError({
+				message: "Invalid backup: missing or invalid id",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "missing or invalid id" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			if (!Sandbox.UUID_REGEX.test(id)) throw new InvalidBackupConfigError({
+				message: "Invalid backup: id must be a valid UUID (e.g. from createBackup)",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "id must be a valid UUID" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			Sandbox.validateBackupDir(dir, "Invalid backup: dir");
-			const metaKey = `backups/${id}/meta.json`;
+			const metaKey = `${BACKUP_STORAGE_PREFIX}/${id}/${BACKUP_METADATA_OBJECT_NAME}`;
 			const metaObject = await bucket.get(metaKey);
 			if (!metaObject) throw new BackupNotFoundError({
 				message: `Backup not found: ${id}. Verify the backup ID is correct and the backup has not been deleted.`,
@@ -6080,7 +6311,7 @@ var Sandbox = class Sandbox extends Container {
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			const r2Key = `backups/${id}/data.sqsh`;
+			const r2Key = `${BACKUP_STORAGE_PREFIX}/${id}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
 			if (!await bucket.head(r2Key)) throw new BackupNotFoundError({
 				message: `Backup archive not found in R2: ${id}. The archive may have been deleted by R2 lifecycle rules.`,
 				code: ErrorCode.BACKUP_NOT_FOUND,
@@ -6089,7 +6320,7 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			backupSession = await this.ensureBackupSession();
-			const r2MountPath = `/var/backups/r2mount/${id}`;
+			const r2MountPath = `${BACKUP_CONTAINER_DIR}/r2mount/${id}`;
 			const archivePath = `${r2MountPath}/data.sqsh`;
 			const mountGlob = `/var/backups/mounts/r2mount/${id}/data`;
 			await this.execWithSession(`/usr/bin/fusermount3 -uz ${shellEscape(dir)} 2>/dev/null || true`, backupSession, { origin: "internal" }).catch(() => {});
@@ -6133,130 +6364,139 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
-};
-
-//#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 {
+	/**
+	* Local-dev implementation of restoreBackup.
+	* Uses the R2 binding directly instead of presigned URLs, and
+	* unsquashfs for extraction instead of squashfuse + fuse-overlayfs.
+	*/
+	async doRestoreBackupLocal(backup) {
+		const restoreStartTime = Date.now();
+		const { id, dir } = backup;
+		let outcome = "error";
+		let caughtError;
+		let backupSession;
+		const bucket = this.env.BACKUP_BUCKET;
+		if (!bucket || !isR2Bucket(bucket)) throw new InvalidBackupConfigError({
+			message: "BACKUP_BUCKET R2 binding not found in env. Add a BACKUP_BUCKET R2 binding to your wrangler.jsonc for local backup support.",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "Missing BACKUP_BUCKET R2 binding" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
 		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
+			if (!id || typeof id !== "string") throw new InvalidBackupConfigError({
+				message: "Invalid backup: missing or invalid id",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "missing or invalid id" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			if (!Sandbox.UUID_REGEX.test(id)) throw new InvalidBackupConfigError({
+				message: "Invalid backup: id must be a valid UUID (e.g. from createBackup)",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "id must be a valid UUID" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			Sandbox.validateBackupDir(dir, "Invalid backup: dir");
+			const metaKey = `${BACKUP_STORAGE_PREFIX}/${id}/${BACKUP_METADATA_OBJECT_NAME}`;
+			const metaObject = await bucket.get(metaKey);
+			if (!metaObject) throw new BackupNotFoundError({
+				message: `Backup not found: ${id}. Verify the backup ID is correct and the backup has not been deleted.`,
+				code: ErrorCode.BACKUP_NOT_FOUND,
+				httpStatus: 404,
+				context: { backupId: id },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const metadata = await metaObject.json();
+			const TTL_BUFFER_MS = 60 * 1e3;
+			const createdAt = new Date(metadata.createdAt).getTime();
+			if (Number.isNaN(createdAt)) throw new BackupRestoreError({
+				message: `Backup metadata has invalid createdAt timestamp: ${metadata.createdAt}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId: id
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const expiresAt = createdAt + metadata.ttl * 1e3;
+			if (Date.now() + TTL_BUFFER_MS > expiresAt) throw new BackupExpiredError({
+				message: `Backup ${id} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
+				code: ErrorCode.BACKUP_EXPIRED,
+				httpStatus: 400,
+				context: {
+					backupId: id,
+					expiredAt: new Date(expiresAt).toISOString()
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const r2Key = `${BACKUP_STORAGE_PREFIX}/${id}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
+			const archiveObject = await bucket.get(r2Key);
+			if (!archiveObject) throw new BackupNotFoundError({
+				message: `Backup archive not found in R2: ${id}. The archive may have been deleted by R2 lifecycle rules.`,
+				code: ErrorCode.BACKUP_NOT_FOUND,
+				httpStatus: 404,
+				context: { backupId: id },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			backupSession = await this.ensureBackupSession();
+			const archivePath = `${BACKUP_CONTAINER_DIR}/${id}.sqsh`;
+			const archiveBuffer = await archiveObject.arrayBuffer();
+			const base64Content = Buffer.from(archiveBuffer).toString("base64");
+			await this.execWithSession(`mkdir -p ${BACKUP_CONTAINER_DIR}`, backupSession, { origin: "internal" });
+			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 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}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId: id
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
+			outcome = "success";
+			return {
+				success: true,
+				dir,
+				id
 			};
-			break;
-		case "chunk":
-			if (!metadata) throw new Error("Received chunk before metadata");
-			if (metadata.isBinary && metadata.encoding === "base64") {
-				const binaryString = atob(event.data);
-				const bytes = new Uint8Array(binaryString.length);
-				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
-				yield bytes;
-			} else yield event.data;
-			break;
-		case "complete":
-			if (!metadata) throw new Error("Stream completed without metadata");
-			return metadata;
-		case "error": throw new Error(`File streaming error: ${event.error}`);
-	}
-	throw new Error("Stream ended unexpectedly");
-}
-/**
-* Collect an entire file into memory from a stream
-*
-* @param stream - The ReadableStream from readFileStream()
-* @returns Object containing the file content and metadata
-*
-* @example
-* ```ts
-* const stream = await sandbox.readFileStream('/path/to/file.txt');
-* const { content, metadata } = await collectFile(stream);
-* console.log('Content:', content);
-* console.log('MIME type:', metadata.mimeType);
-* ```
-*/
-async function collectFile(stream) {
-	const chunks = [];
-	const generator = streamFile(stream);
-	let result = await generator.next();
-	while (!result.done) {
-		chunks.push(result.value);
-		result = await generator.next();
-	}
-	const metadata = result.value;
-	if (!metadata) throw new Error("Failed to get file metadata");
-	if (metadata.isBinary) {
-		const totalLength = chunks.reduce((sum, chunk) => sum + (chunk instanceof Uint8Array ? chunk.length : 0), 0);
-		const combined = new Uint8Array(totalLength);
-		let offset = 0;
-		for (const chunk of chunks) if (chunk instanceof Uint8Array) {
-			combined.set(chunk, offset);
-			offset += chunk.length;
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			if (id && backupSession) {
+				const archivePath = `${BACKUP_CONTAINER_DIR}/${id}.sqsh`;
+				await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
+			}
+			throw error;
+		} finally {
+			if (backupSession) await this.client.utils.deleteSession(backupSession).catch(() => {});
+			logCanonicalEvent(this.logger, {
+				event: "backup.restore",
+				outcome,
+				durationMs: Date.now() - restoreStartTime,
+				backupId: id,
+				dir,
+				provider: "local-binding",
+				error: caughtError
+			});
 		}
-		return {
-			content: combined,
-			metadata
-		};
-	} else return {
-		content: chunks.filter((c) => typeof c === "string").join(""),
-		metadata
-	};
-}
+	}
+};
 
 //#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, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, proxyTerminal as d, asyncIterableToSSEStream as f, SandboxClient as g, CodeInterpreter as h, getSandbox as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, responseToAsyncIterable as m, streamFile as n, BucketUnmountError as o, parseSSEStream as p, Sandbox as r, InvalidMountConfigError as s, collectFile as t, proxyToSandbox as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y };
-//# sourceMappingURL=file-stream-Bn2PceyF.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, 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