@cloudflare/sandbox 0.7.20 → 0.8.0

package/dist/index.js

@@ -1,6 +1,6 @@
-import { _ as filterEnvVars, a as isExecResult, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as extractRepoName, h as GitLogger, i as isWSStreamChunk, l as shellEscape, m as ResultImpl, n as isWSError, o as isProcess, p as Execution, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createLogger, v as getEnvString, y as partitionEnvVars } from "./dist-CwUZf_TJ.js";
+import { _ as extractRepoName, a as isExecResult, b as partitionEnvVars, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as GitLogger, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, o as isProcess, p as logCanonicalEvent, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createLogger, v as filterEnvVars, y as getEnvString } from "./dist-CmfvOT-w.js";
 import { t as ErrorCode } from "./errors-CaSfB5Bm.js";
-import { Container, getContainer, switchPort } from "@cloudflare/containers";
+import { Container, ContainerProxy, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import path from "node:path/posix";
 
@@ -804,9 +804,9 @@ var HttpTransport = class extends BaseTransport {
 		if (this.config.stub) return this.config.stub.containerFetch(url, options || {}, this.config.port);
 		return globalThis.fetch(url, options);
 	}
-	async fetchStream(path$1, body, method = "POST") {
+	async fetchStream(path$1, body, method = "POST", headers) {
 		const url = this.buildUrl(path$1);
-		const options = this.buildStreamOptions(body, method);
+		const options = this.buildStreamOptions(body, method, headers);
 		let response;
 		if (this.config.stub) response = await this.config.stub.containerFetch(url, options, this.config.port);
 		else response = await globalThis.fetch(url, options);
@@ -821,10 +821,13 @@ var HttpTransport = class extends BaseTransport {
 		if (this.config.stub) return `http://localhost:${this.config.port}${path$1}`;
 		return `${this.baseUrl}${path$1}`;
 	}
-	buildStreamOptions(body, method) {
+	buildStreamOptions(body, method, headers) {
 		return {
 			method,
-			headers: body && method === "POST" ? { "Content-Type": "application/json" } : void 0,
+			headers: body && method === "POST" ? {
+				...headers,
+				"Content-Type": "application/json"
+			} : headers,
 			body: body && method === "POST" ? JSON.stringify(body) : void 0
 		};
 	}
@@ -896,7 +899,8 @@ var WebSocketTransport = class extends BaseTransport {
 		await this.connect();
 		const method = options?.method || "GET";
 		const body = this.parseBody(options?.body);
-		const result = await this.request(method, path$1, body);
+		const headers = this.normalizeHeaders(options?.headers);
+		const result = await this.request(method, path$1, body, headers);
 		return new Response(JSON.stringify(result.body), {
 			status: result.status,
 			headers: { "Content-Type": "application/json" }
@@ -905,8 +909,8 @@ var WebSocketTransport = class extends BaseTransport {
 	/**
 	* Streaming fetch implementation
 	*/
-	async fetchStream(path$1, body, method = "POST") {
-		return this.requestStream(method, path$1, body);
+	async fetchStream(path$1, body, method = "POST", headers) {
+		return this.requestStream(method, path$1, body, headers);
 	}
 	/**
 	* Parse request body from RequestInit
@@ -921,6 +925,17 @@ var WebSocketTransport = class extends BaseTransport {
 		throw new Error(`WebSocket transport only supports string bodies. Got: ${typeof body}`);
 	}
 	/**
+	* Normalize RequestInit headers into a plain object for WSRequest.
+	*/
+	normalizeHeaders(headers) {
+		if (!headers) return;
+		const normalized = {};
+		new Headers(headers).forEach((value, key) => {
+			normalized[key] = value;
+		});
+		return Object.keys(normalized).length > 0 ? normalized : void 0;
+	}
+	/**
 	* Internal connection logic
 	*/
 	async doConnect() {
@@ -1009,7 +1024,7 @@ var WebSocketTransport = class extends BaseTransport {
 	/**
 	* Send a request and wait for response
 	*/
-	async request(method, path$1, body) {
+	async request(method, path$1, body, headers) {
 		await this.connect();
 		const id = generateRequestId();
 		const request = {
@@ -1017,7 +1032,8 @@ var WebSocketTransport = class extends BaseTransport {
 			id,
 			method,
 			path: path$1,
-			body
+			body,
+			headers
 		};
 		return new Promise((resolve, reject) => {
 			const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
@@ -1065,7 +1081,7 @@ var WebSocketTransport = class extends BaseTransport {
 	* long-running streams (e.g. execStream from an agent) stay alive as long
 	* as data is flowing. The timer resets on every chunk or response message.
 	*/
-	async requestStream(method, path$1, body) {
+	async requestStream(method, path$1, body, headers) {
 		await this.connect();
 		const id = generateRequestId();
 		const request = {
@@ -1073,7 +1089,8 @@ var WebSocketTransport = class extends BaseTransport {
 			id,
 			method,
 			path: path$1,
-			body
+			body,
+			headers
 		};
 		const idleTimeoutMs = this.config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
 		return new Promise((resolveStream, rejectStream) => {
@@ -1398,6 +1415,14 @@ var BaseHttpClient = class {
 	* Core fetch method - delegates to Transport which handles retry logic
 	*/
 	async doFetch(path$1, options) {
+		const { defaultHeaders } = this.options;
+		if (defaultHeaders) options = {
+			...options,
+			headers: {
+				...defaultHeaders,
+				...options?.headers
+			}
+		};
 		return this.transport.fetch(path$1, options);
 	}
 	/**
@@ -1482,12 +1507,11 @@ var BaseHttpClient = class {
 	* @param method - HTTP method (default: POST, use GET for process logs)
 	*/
 	async doStreamFetch(path$1, body, method = "POST") {
-		if (this.transport.getMode() === "websocket") try {
-			return await this.transport.fetchStream(path$1, body, method);
-		} catch (error) {
-			this.logError(`stream ${method} ${path$1}`, error);
-			throw error;
-		}
+		const streamHeaders = method === "POST" ? {
+			...this.options.defaultHeaders,
+			"Content-Type": "application/json"
+		} : this.options.defaultHeaders;
+		if (this.transport.getMode() === "websocket") return this.transport.fetchStream(path$1, body, method, streamHeaders);
 		const response = await this.doFetch(path$1, {
 			method,
 			headers: { "Content-Type": "application/json" },
@@ -1495,25 +1519,6 @@ var BaseHttpClient = class {
 		});
 		return this.handleStreamResponse(response);
 	}
-	/**
-	* Utility method to log successful operations
-	*/
-	logSuccess(operation, details) {
-		this.logger.info(operation, details ? { details } : void 0);
-	}
-	/**
-	* Utility method to log errors intelligently
-	* Only logs unexpected errors (5xx), not expected errors (4xx)
-	*
-	* - 4xx errors (validation, not found, conflicts): Don't log (expected client errors)
-	* - 5xx errors (server failures, internal errors): DO log (unexpected server errors)
-	*/
-	logError(operation, error) {
-		if (error && typeof error === "object" && "httpStatus" in error) {
-			const httpStatus = error.httpStatus;
-			if (httpStatus >= 500) this.logger.error(`Unexpected error in ${operation}`, error instanceof Error ? error : new Error(String(error)), { httpStatus });
-		} else this.logger.error(`Error in ${operation}`, error instanceof Error ? error : new Error(String(error)));
-	}
 };
 
 //#endregion
@@ -1541,11 +1546,8 @@ var BackupClient = class extends BaseHttpClient {
 				excludes,
 				sessionId
 			};
-			const response = await this.post("/api/backup/create", data);
-			this.logSuccess("Backup archive created", `${dir} -> ${archivePath}`);
-			return response;
+			return await this.post("/api/backup/create", data);
 		} catch (error) {
-			this.logError("createArchive", error);
 			throw error;
 		}
 	}
@@ -1562,11 +1564,8 @@ var BackupClient = class extends BaseHttpClient {
 				archivePath,
 				sessionId
 			};
-			const response = await this.post("/api/backup/restore", data);
-			this.logSuccess("Backup archive restored", `${archivePath} -> ${dir}`);
-			return response;
+			return await this.post("/api/backup/restore", data);
 		} catch (error) {
-			this.logError("restoreArchive", error);
 			throw error;
 		}
 	}
@@ -1593,14 +1592,13 @@ var CommandClient = class extends BaseHttpClient {
 				sessionId,
 				...options?.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
 				...options?.env !== void 0 && { env: options.env },
-				...options?.cwd !== void 0 && { cwd: options.cwd }
+				...options?.cwd !== void 0 && { cwd: options.cwd },
+				...options?.origin !== void 0 && { origin: options.origin }
 			};
 			const response = await this.post("/api/execute", data);
-			this.logSuccess("Command executed", `${command}, Success: ${response.success}`);
 			this.options.onCommandComplete?.(response.success, response.exitCode, response.stdout, response.stderr, response.command);
 			return response;
 		} catch (error) {
-			this.logError("execute", error);
 			this.options.onError?.(error instanceof Error ? error.message : String(error), command);
 			throw error;
 		}
@@ -1618,13 +1616,11 @@ var CommandClient = class extends BaseHttpClient {
 				sessionId,
 				...options?.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
 				...options?.env !== void 0 && { env: options.env },
-				...options?.cwd !== void 0 && { cwd: options.cwd }
+				...options?.cwd !== void 0 && { cwd: options.cwd },
+				...options?.origin !== void 0 && { origin: options.origin }
 			};
-			const stream = await this.doStreamFetch("/api/execute/stream", data);
-			this.logSuccess("Command stream started", command);
-			return stream;
+			return await this.doStreamFetch("/api/execute/stream", data);
 		} catch (error) {
-			this.logError("executeStream", error);
 			this.options.onError?.(error instanceof Error ? error.message : String(error), command);
 			throw error;
 		}
@@ -1646,11 +1642,8 @@ var DesktopClient = class extends BaseHttpClient {
 				...options?.resolution !== void 0 && { resolution: options.resolution },
 				...options?.dpi !== void 0 && { dpi: options.dpi }
 			};
-			const response = await this.post("/api/desktop/start", data);
-			this.logSuccess("Desktop started", `${response.resolution[0]}x${response.resolution[1]}`);
-			return response;
+			return await this.post("/api/desktop/start", data);
 		} catch (error) {
-			this.logError("desktop.start", error);
 			this.options.onError?.(error instanceof Error ? error.message : String(error));
 			throw error;
 		}
@@ -1660,11 +1653,8 @@ var DesktopClient = class extends BaseHttpClient {
 	*/
 	async stop() {
 		try {
-			const response = await this.post("/api/desktop/stop", {});
-			this.logSuccess("Desktop stopped");
-			return response;
+			return await this.post("/api/desktop/stop", {});
 		} catch (error) {
-			this.logError("desktop.stop", error);
 			this.options.onError?.(error instanceof Error ? error.message : String(error));
 			throw error;
 		}
@@ -1674,11 +1664,8 @@ var DesktopClient = class extends BaseHttpClient {
 	*/
 	async status() {
 		try {
-			const response = await this.get("/api/desktop/status");
-			this.logSuccess("Desktop status retrieved", response.status);
-			return response;
+			return await this.get("/api/desktop/status");
 		} catch (error) {
-			this.logError("desktop.status", error);
 			throw error;
 		}
 	}
@@ -1692,7 +1679,6 @@ var DesktopClient = class extends BaseHttpClient {
 				...options?.showCursor !== void 0 && { showCursor: options.showCursor }
 			};
 			const response = await this.post("/api/desktop/screenshot", data);
-			this.logSuccess("Screenshot captured", `${response.width}x${response.height}`);
 			if (wantsBytes) {
 				const binaryString = atob(response.data);
 				const bytes = new Uint8Array(binaryString.length);
@@ -1704,7 +1690,6 @@ var DesktopClient = class extends BaseHttpClient {
 			}
 			return response;
 		} catch (error) {
-			this.logError("desktop.screenshot", error);
 			throw error;
 		}
 	}
@@ -1719,7 +1704,6 @@ var DesktopClient = class extends BaseHttpClient {
 				...options?.showCursor !== void 0 && { showCursor: options.showCursor }
 			};
 			const response = await this.post("/api/desktop/screenshot/region", data);
-			this.logSuccess("Region screenshot captured", `${region.width}x${region.height}`);
 			if (wantsBytes) {
 				const binaryString = atob(response.data);
 				const bytes = new Uint8Array(binaryString.length);
@@ -1731,7 +1715,6 @@ var DesktopClient = class extends BaseHttpClient {
 			}
 			return response;
 		} catch (error) {
-			this.logError("desktop.screenshotRegion", error);
 			throw error;
 		}
 	}
@@ -1746,9 +1729,7 @@ var DesktopClient = class extends BaseHttpClient {
 				button: options?.button ?? "left",
 				clickCount: 1
 			});
-			this.logSuccess("Mouse click", `(${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.click", error);
 			throw error;
 		}
 	}
@@ -1763,9 +1744,7 @@ var DesktopClient = class extends BaseHttpClient {
 				button: options?.button ?? "left",
 				clickCount: 2
 			});
-			this.logSuccess("Mouse double click", `(${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.doubleClick", error);
 			throw error;
 		}
 	}
@@ -1780,9 +1759,7 @@ var DesktopClient = class extends BaseHttpClient {
 				button: options?.button ?? "left",
 				clickCount: 3
 			});
-			this.logSuccess("Mouse triple click", `(${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.tripleClick", error);
 			throw error;
 		}
 	}
@@ -1797,9 +1774,7 @@ var DesktopClient = class extends BaseHttpClient {
 				button: "right",
 				clickCount: 1
 			});
-			this.logSuccess("Mouse right click", `(${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.rightClick", error);
 			throw error;
 		}
 	}
@@ -1814,9 +1789,7 @@ var DesktopClient = class extends BaseHttpClient {
 				button: "middle",
 				clickCount: 1
 			});
-			this.logSuccess("Mouse middle click", `(${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.middleClick", error);
 			throw error;
 		}
 	}
@@ -1830,9 +1803,7 @@ var DesktopClient = class extends BaseHttpClient {
 				...y !== void 0 && { y },
 				button: options?.button ?? "left"
 			});
-			this.logSuccess("Mouse down", x !== void 0 ? `(${x}, ${y})` : "current position");
 		} catch (error) {
-			this.logError("desktop.mouseDown", error);
 			throw error;
 		}
 	}
@@ -1846,9 +1817,7 @@ var DesktopClient = class extends BaseHttpClient {
 				...y !== void 0 && { y },
 				button: options?.button ?? "left"
 			});
-			this.logSuccess("Mouse up", x !== void 0 ? `(${x}, ${y})` : "current position");
 		} catch (error) {
-			this.logError("desktop.mouseUp", error);
 			throw error;
 		}
 	}
@@ -1861,9 +1830,7 @@ var DesktopClient = class extends BaseHttpClient {
 				x,
 				y
 			});
-			this.logSuccess("Mouse move", `(${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.moveMouse", error);
 			throw error;
 		}
 	}
@@ -1879,9 +1846,7 @@ var DesktopClient = class extends BaseHttpClient {
 				endY,
 				button: options?.button ?? "left"
 			});
-			this.logSuccess("Mouse drag", `(${startX},${startY}) -> (${endX},${endY})`);
 		} catch (error) {
-			this.logError("desktop.drag", error);
 			throw error;
 		}
 	}
@@ -1896,9 +1861,7 @@ var DesktopClient = class extends BaseHttpClient {
 				direction,
 				amount
 			});
-			this.logSuccess("Mouse scroll", `${direction} ${amount} at (${x}, ${y})`);
 		} catch (error) {
-			this.logError("desktop.scroll", error);
 			throw error;
 		}
 	}
@@ -1907,11 +1870,8 @@ var DesktopClient = class extends BaseHttpClient {
 	*/
 	async getCursorPosition() {
 		try {
-			const response = await this.get("/api/desktop/mouse/position");
-			this.logSuccess("Cursor position retrieved", `(${response.x}, ${response.y})`);
-			return response;
+			return await this.get("/api/desktop/mouse/position");
 		} catch (error) {
-			this.logError("desktop.getCursorPosition", error);
 			throw error;
 		}
 	}
@@ -1924,9 +1884,7 @@ var DesktopClient = class extends BaseHttpClient {
 				text,
 				...options?.delayMs !== void 0 && { delayMs: options.delayMs }
 			});
-			this.logSuccess("Keyboard type", `${text.length} chars`);
 		} catch (error) {
-			this.logError("desktop.type", error);
 			throw error;
 		}
 	}
@@ -1936,9 +1894,7 @@ var DesktopClient = class extends BaseHttpClient {
 	async press(key) {
 		try {
 			await this.post("/api/desktop/keyboard/press", { key });
-			this.logSuccess("Key press", key);
 		} catch (error) {
-			this.logError("desktop.press", error);
 			throw error;
 		}
 	}
@@ -1948,9 +1904,7 @@ var DesktopClient = class extends BaseHttpClient {
 	async keyDown(key) {
 		try {
 			await this.post("/api/desktop/keyboard/down", { key });
-			this.logSuccess("Key down", key);
 		} catch (error) {
-			this.logError("desktop.keyDown", error);
 			throw error;
 		}
 	}
@@ -1960,9 +1914,7 @@ var DesktopClient = class extends BaseHttpClient {
 	async keyUp(key) {
 		try {
 			await this.post("/api/desktop/keyboard/up", { key });
-			this.logSuccess("Key up", key);
 		} catch (error) {
-			this.logError("desktop.keyUp", error);
 			throw error;
 		}
 	}
@@ -1971,11 +1923,8 @@ var DesktopClient = class extends BaseHttpClient {
 	*/
 	async getScreenSize() {
 		try {
-			const response = await this.get("/api/desktop/screen/size");
-			this.logSuccess("Screen size retrieved", `${response.width}x${response.height}`);
-			return response;
+			return await this.get("/api/desktop/screen/size");
 		} catch (error) {
-			this.logError("desktop.getScreenSize", error);
 			throw error;
 		}
 	}
@@ -1984,11 +1933,8 @@ var DesktopClient = class extends BaseHttpClient {
 	*/
 	async getProcessStatus(name) {
 		try {
-			const response = await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
-			this.logSuccess("Desktop process status retrieved", name);
-			return response;
+			return await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
 		} catch (error) {
-			this.logError("desktop.getProcessStatus", error);
 			throw error;
 		}
 	}
@@ -2013,11 +1959,8 @@ var FileClient = class extends BaseHttpClient {
 				sessionId,
 				recursive: options?.recursive ?? false
 			};
-			const response = await this.post("/api/mkdir", data);
-			this.logSuccess("Directory created", `${path$1} (recursive: ${data.recursive})`);
-			return response;
+			return await this.post("/api/mkdir", data);
 		} catch (error) {
-			this.logError("mkdir", error);
 			throw error;
 		}
 	}
@@ -2036,11 +1979,8 @@ var FileClient = class extends BaseHttpClient {
 				sessionId,
 				encoding: options?.encoding
 			};
-			const response = await this.post("/api/write", data);
-			this.logSuccess("File written", `${path$1} (${content.length} chars)`);
-			return response;
+			return await this.post("/api/write", data);
 		} catch (error) {
-			this.logError("writeFile", error);
 			throw error;
 		}
 	}
@@ -2057,11 +1997,8 @@ var FileClient = class extends BaseHttpClient {
 				sessionId,
 				encoding: options?.encoding
 			};
-			const response = await this.post("/api/read", data);
-			this.logSuccess("File read", `${path$1} (${response.content.length} chars)`);
-			return response;
+			return await this.post("/api/read", data);
 		} catch (error) {
-			this.logError("readFile", error);
 			throw error;
 		}
 	}
@@ -2077,11 +2014,8 @@ var FileClient = class extends BaseHttpClient {
 				path: path$1,
 				sessionId
 			};
-			const stream = await this.doStreamFetch("/api/read/stream", data);
-			this.logSuccess("File stream started", path$1);
-			return stream;
+			return await this.doStreamFetch("/api/read/stream", data);
 		} catch (error) {
-			this.logError("readFileStream", error);
 			throw error;
 		}
 	}
@@ -2096,11 +2030,8 @@ var FileClient = class extends BaseHttpClient {
 				path: path$1,
 				sessionId
 			};
-			const response = await this.post("/api/delete", data);
-			this.logSuccess("File deleted", path$1);
-			return response;
+			return await this.post("/api/delete", data);
 		} catch (error) {
-			this.logError("deleteFile", error);
 			throw error;
 		}
 	}
@@ -2117,11 +2048,8 @@ var FileClient = class extends BaseHttpClient {
 				newPath,
 				sessionId
 			};
-			const response = await this.post("/api/rename", data);
-			this.logSuccess("File renamed", `${path$1} -> ${newPath}`);
-			return response;
+			return await this.post("/api/rename", data);
 		} catch (error) {
-			this.logError("renameFile", error);
 			throw error;
 		}
 	}
@@ -2138,11 +2066,8 @@ var FileClient = class extends BaseHttpClient {
 				destinationPath: newPath,
 				sessionId
 			};
-			const response = await this.post("/api/move", data);
-			this.logSuccess("File moved", `${path$1} -> ${newPath}`);
-			return response;
+			return await this.post("/api/move", data);
 		} catch (error) {
-			this.logError("moveFile", error);
 			throw error;
 		}
 	}
@@ -2159,11 +2084,8 @@ var FileClient = class extends BaseHttpClient {
 				sessionId,
 				options: options || {}
 			};
-			const response = await this.post("/api/list-files", data);
-			this.logSuccess("Files listed", `${path$1} (${response.count} files)`);
-			return response;
+			return await this.post("/api/list-files", data);
 		} catch (error) {
-			this.logError("listFiles", error);
 			throw error;
 		}
 	}
@@ -2178,11 +2100,8 @@ var FileClient = class extends BaseHttpClient {
 				path: path$1,
 				sessionId
 			};
-			const response = await this.post("/api/exists", data);
-			this.logSuccess("Path existence checked", `${path$1} (exists: ${response.exists})`);
-			return response;
+			return await this.post("/api/exists", data);
 		} catch (error) {
-			this.logError("exists", error);
 			throw error;
 		}
 	}
@@ -2218,11 +2137,8 @@ var GitClient = class extends BaseHttpClient {
 				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;
 			}
-			const response = await this.post("/api/git/checkout", data);
-			this.logSuccess("Repository cloned", `${repoUrl} (branch: ${response.branch}) -> ${response.targetDir}`);
-			return response;
+			return await this.post("/api/git/checkout", data);
 		} catch (error) {
-			this.logError("checkout", error);
 			throw error;
 		}
 	}
@@ -2313,7 +2229,6 @@ var InterpreterClient = class extends BaseHttpClient {
 		for (let attempt = 0; attempt < this.maxRetries; attempt++) try {
 			return await operation();
 		} catch (error) {
-			this.logError("executeWithRetry", error);
 			lastError = error;
 			if (this.isRetryableError(error)) {
 				if (attempt < this.maxRetries - 1) {
@@ -2401,9 +2316,7 @@ var InterpreterClient = class extends BaseHttpClient {
 					break;
 				case "execution_complete": break;
 			}
-		} catch (error) {
-			this.logError("parseExecutionResult", error);
-		}
+		} catch {}
 	}
 };
 
@@ -2426,11 +2339,8 @@ var PortClient = class extends BaseHttpClient {
 				sessionId,
 				name
 			};
-			const response = await this.post("/api/expose-port", data);
-			this.logSuccess("Port exposed", `${port} exposed at ${response.url}${name ? ` (${name})` : ""}`);
-			return response;
+			return await this.post("/api/expose-port", data);
 		} catch (error) {
-			this.logError("exposePort", error);
 			throw error;
 		}
 	}
@@ -2442,11 +2352,8 @@ var PortClient = class extends BaseHttpClient {
 	async unexposePort(port, sessionId) {
 		try {
 			const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
-			const response = await this.delete(url);
-			this.logSuccess("Port unexposed", `${port}`);
-			return response;
+			return await this.delete(url);
 		} catch (error) {
-			this.logError("unexposePort", error);
 			throw error;
 		}
 	}
@@ -2457,11 +2364,8 @@ var PortClient = class extends BaseHttpClient {
 	async getExposedPorts(sessionId) {
 		try {
 			const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
-			const response = await this.get(url);
-			this.logSuccess("Exposed ports retrieved", `${response.ports.length} ports exposed`);
-			return response;
+			return await this.get(url);
 		} catch (error) {
-			this.logError("getExposedPorts", error);
 			throw error;
 		}
 	}
@@ -2472,11 +2376,8 @@ var PortClient = class extends BaseHttpClient {
 	*/
 	async watchPort(request) {
 		try {
-			const stream = await this.doStreamFetch("/api/port-watch", request);
-			this.logSuccess("Port watch started", `port ${request.port}`);
-			return stream;
+			return await this.doStreamFetch("/api/port-watch", request);
 		} catch (error) {
-			this.logError("watchPort", error);
 			throw error;
 		}
 	}
@@ -2499,6 +2400,7 @@ var ProcessClient = class extends BaseHttpClient {
 			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 },
@@ -2506,11 +2408,8 @@ var ProcessClient = class extends BaseHttpClient {
 				...options?.encoding !== void 0 && { encoding: options.encoding },
 				...options?.autoCleanup !== void 0 && { autoCleanup: options.autoCleanup }
 			};
-			const response = await this.post("/api/process/start", data);
-			this.logSuccess("Process started", `${command} (ID: ${response.processId})`);
-			return response;
+			return await this.post("/api/process/start", data);
 		} catch (error) {
-			this.logError("startProcess", error);
 			throw error;
 		}
 	}
@@ -2519,11 +2418,8 @@ var ProcessClient = class extends BaseHttpClient {
 	*/
 	async listProcesses() {
 		try {
-			const response = await this.get(`/api/process/list`);
-			this.logSuccess("Processes listed", `${response.processes.length} processes`);
-			return response;
+			return await this.get(`/api/process/list`);
 		} catch (error) {
-			this.logError("listProcesses", error);
 			throw error;
 		}
 	}
@@ -2534,11 +2430,8 @@ var ProcessClient = class extends BaseHttpClient {
 	async getProcess(processId) {
 		try {
 			const url = `/api/process/${processId}`;
-			const response = await this.get(url);
-			this.logSuccess("Process retrieved", `ID: ${processId}`);
-			return response;
+			return await this.get(url);
 		} catch (error) {
-			this.logError("getProcess", error);
 			throw error;
 		}
 	}
@@ -2549,11 +2442,8 @@ var ProcessClient = class extends BaseHttpClient {
 	async killProcess(processId) {
 		try {
 			const url = `/api/process/${processId}`;
-			const response = await this.delete(url);
-			this.logSuccess("Process killed", `ID: ${processId}`);
-			return response;
+			return await this.delete(url);
 		} catch (error) {
-			this.logError("killProcess", error);
 			throw error;
 		}
 	}
@@ -2562,11 +2452,8 @@ var ProcessClient = class extends BaseHttpClient {
 	*/
 	async killAllProcesses() {
 		try {
-			const response = await this.delete(`/api/process/kill-all`);
-			this.logSuccess("All processes killed", `${response.cleanedCount} processes terminated`);
-			return response;
+			return await this.delete(`/api/process/kill-all`);
 		} catch (error) {
-			this.logError("killAllProcesses", error);
 			throw error;
 		}
 	}
@@ -2577,11 +2464,8 @@ var ProcessClient = class extends BaseHttpClient {
 	async getProcessLogs(processId) {
 		try {
 			const url = `/api/process/${processId}/logs`;
-			const response = await this.get(url);
-			this.logSuccess("Process logs retrieved", `ID: ${processId}, stdout: ${response.stdout.length} chars, stderr: ${response.stderr.length} chars`);
-			return response;
+			return await this.get(url);
 		} catch (error) {
-			this.logError("getProcessLogs", error);
 			throw error;
 		}
 	}
@@ -2592,11 +2476,8 @@ var ProcessClient = class extends BaseHttpClient {
 	async streamProcessLogs(processId) {
 		try {
 			const url = `/api/process/${processId}/stream`;
-			const stream = await this.doStreamFetch(url, void 0, "GET");
-			this.logSuccess("Process log stream started", `ID: ${processId}`);
-			return stream;
+			return await this.doStreamFetch(url, void 0, "GET");
 		} catch (error) {
-			this.logError("streamProcessLogs", error);
 			throw error;
 		}
 	}
@@ -2613,11 +2494,8 @@ var UtilityClient = class extends BaseHttpClient {
 	*/
 	async ping() {
 		try {
-			const response = await this.get("/api/ping");
-			this.logSuccess("Ping successful", response.message);
-			return response.message;
+			return (await this.get("/api/ping")).message;
 		} catch (error) {
-			this.logError("ping", error);
 			throw error;
 		}
 	}
@@ -2626,11 +2504,8 @@ var UtilityClient = class extends BaseHttpClient {
 	*/
 	async getCommands() {
 		try {
-			const response = await this.get("/api/commands");
-			this.logSuccess("Commands retrieved", `${response.count} commands available`);
-			return response.availableCommands;
+			return (await this.get("/api/commands")).availableCommands;
 		} catch (error) {
-			this.logError("getCommands", error);
 			throw error;
 		}
 	}
@@ -2640,11 +2515,8 @@ var UtilityClient = class extends BaseHttpClient {
 	*/
 	async createSession(options) {
 		try {
-			const response = await this.post("/api/session/create", options);
-			this.logSuccess("Session created", `ID: ${options.id}`);
-			return response;
+			return await this.post("/api/session/create", options);
 		} catch (error) {
-			this.logError("createSession", error);
 			throw error;
 		}
 	}
@@ -2654,11 +2526,8 @@ var UtilityClient = class extends BaseHttpClient {
 	*/
 	async deleteSession(sessionId) {
 		try {
-			const response = await this.post("/api/session/delete", { sessionId });
-			this.logSuccess("Session deleted", `ID: ${sessionId}`);
-			return response;
+			return await this.post("/api/session/delete", { sessionId });
 		} catch (error) {
-			this.logError("deleteSession", error);
 			throw error;
 		}
 	}
@@ -2668,9 +2537,7 @@ var UtilityClient = class extends BaseHttpClient {
 	*/
 	async getVersion() {
 		try {
-			const response = await this.get("/api/version");
-			this.logSuccess("Version retrieved", response.version);
-			return response.version;
+			return (await this.get("/api/version")).version;
 		} catch (error) {
 			this.logger.debug("Failed to get container version (may be old container)", { error });
 			return "unknown";
@@ -2700,11 +2567,8 @@ var WatchClient = class extends BaseHttpClient {
 	async watch(request) {
 		try {
 			const stream = await this.doStreamFetch("/api/watch", request);
-			const readyStream = await this.waitForReadiness(stream);
-			this.logSuccess("File watch started", request.path);
-			return readyStream;
+			return await this.waitForReadiness(stream);
 		} catch (error) {
-			this.logError("watch", error);
 			throw error;
 		}
 	}
@@ -3698,7 +3562,7 @@ function buildS3fsSource(bucket, prefix) {
 * 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.7.20";
+const SDK_VERSION = "0.8.0";
 
 //#endregion
 //#region src/sandbox.ts
@@ -3929,6 +3793,7 @@ var Sandbox = class Sandbox extends Container {
 			port: 3e3,
 			stub: this,
 			retryTimeoutMs: this.computeRetryTimeoutMs(),
+			defaultHeaders: { "X-Sandbox-Id": this.ctx.id.toString() },
 			...this.transport === "websocket" && {
 				transportMode: "websocket",
 				wsUrl: "ws://localhost:3000/ws"
@@ -4022,12 +3887,12 @@ var Sandbox = class Sandbox extends Container {
 		if (this.defaultSession) {
 			for (const key of toUnset) {
 				const unsetCommand = `unset ${key}`;
-				const result = await this.client.commands.execute(unsetCommand, this.defaultSession);
+				const result = await this.client.commands.execute(unsetCommand, this.defaultSession, { origin: "internal" });
 				if (result.exitCode !== 0) throw new Error(`Failed to unset ${key}: ${result.stderr || "Unknown error"}`);
 			}
 			for (const [key, value] of Object.entries(toSet)) {
 				const exportCommand = `export ${key}=${shellEscape(value)}`;
-				const result = await this.client.commands.execute(exportCommand, this.defaultSession);
+				const result = await this.client.commands.execute(exportCommand, this.defaultSession, { origin: "internal" });
 				if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
 			}
 		}
@@ -4093,7 +3958,6 @@ var Sandbox = class Sandbox extends Container {
 	* @throws InvalidMountConfigError if bucket name, mount path, or endpoint is invalid
 	*/
 	async mountBucket(bucket, mountPath, options) {
-		this.logger.info(`Mounting bucket ${bucket} to ${mountPath}`);
 		if ("localBucket" in options && options.localBucket) {
 			await this.mountBucketLocal(bucket, mountPath, options);
 			return;
@@ -4104,82 +3968,118 @@ var Sandbox = class Sandbox extends Container {
 	* Local dev mount: bidirectional sync via R2 binding + file/watch APIs
 	*/
 	async mountBucketLocal(bucket, mountPath, options) {
-		const r2Binding = this.env[bucket];
-		if (!r2Binding || !isR2Bucket(r2Binding)) throw new InvalidMountConfigError(`R2 binding "${bucket}" not found in env or is not an R2Bucket. Make sure the binding name matches your wrangler.jsonc R2 binding.`);
-		if (!mountPath || !mountPath.startsWith("/")) throw new InvalidMountConfigError(`Invalid mount path: "${mountPath}". Must be an absolute path starting with /`);
-		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path already in use: ${mountPath}`);
-		const sessionId = await this.ensureDefaultSession();
-		const syncManager = new LocalMountSyncManager({
-			bucket: r2Binding,
-			mountPath,
-			prefix: options.prefix,
-			readOnly: options.readOnly ?? false,
-			client: this.client,
-			sessionId,
-			logger: this.logger
-		});
-		const mountInfo = {
-			mountType: "local-sync",
-			bucket,
-			mountPath,
-			syncManager,
-			mounted: false
-		};
-		this.activeMounts.set(mountPath, mountInfo);
+		const mountStartTime = Date.now();
+		let mountOutcome = "error";
+		let mountError;
 		try {
-			await syncManager.start();
-			mountInfo.mounted = true;
-			this.logger.info(`Successfully mounted bucket ${bucket} to ${mountPath} (local sync)`);
+			const r2Binding = this.env[bucket];
+			if (!r2Binding || !isR2Bucket(r2Binding)) throw new InvalidMountConfigError(`R2 binding "${bucket}" not found in env or is not an R2Bucket. Make sure the binding name matches your wrangler.jsonc R2 binding.`);
+			if (!mountPath || !mountPath.startsWith("/")) throw new InvalidMountConfigError(`Invalid mount path: "${mountPath}". Must be an absolute path starting with /`);
+			if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path already in use: ${mountPath}`);
+			const sessionId = await this.ensureDefaultSession();
+			const syncManager = new LocalMountSyncManager({
+				bucket: r2Binding,
+				mountPath,
+				prefix: options.prefix,
+				readOnly: options.readOnly ?? false,
+				client: this.client,
+				sessionId,
+				logger: this.logger
+			});
+			const mountInfo = {
+				mountType: "local-sync",
+				bucket,
+				mountPath,
+				syncManager,
+				mounted: false
+			};
+			this.activeMounts.set(mountPath, mountInfo);
+			try {
+				await syncManager.start();
+				mountInfo.mounted = true;
+			} catch (error) {
+				await syncManager.stop();
+				this.activeMounts.delete(mountPath);
+				throw error;
+			}
+			mountOutcome = "success";
 		} catch (error) {
-			await syncManager.stop();
-			this.activeMounts.delete(mountPath);
+			mountError = error instanceof Error ? error : new Error(String(error));
 			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "bucket.mount",
+				outcome: mountOutcome,
+				durationMs: Date.now() - mountStartTime,
+				bucket,
+				mountPath,
+				provider: "local-sync",
+				prefix: options.prefix,
+				error: mountError
+			});
 		}
 	}
 	/**
 	* Production mount: S3FS-FUSE inside the container
 	*/
 	async mountBucketFuse(bucket, mountPath, options) {
+		const mountStartTime = Date.now();
 		const prefix = options.prefix || void 0;
-		this.validateMountOptions(bucket, mountPath, {
-			...options,
-			prefix
-		});
-		const s3fsSource = buildS3fsSource(bucket, prefix);
-		const provider = options.provider || detectProviderFromUrl(options.endpoint);
-		this.logger.debug(`Detected provider: ${provider || "unknown"}`, {
-			explicitProvider: options.provider,
-			prefix
-		});
-		const envObj = this.env;
-		const credentials = detectCredentials(options, {
-			AWS_ACCESS_KEY_ID: getEnvString(envObj, "AWS_ACCESS_KEY_ID"),
-			AWS_SECRET_ACCESS_KEY: getEnvString(envObj, "AWS_SECRET_ACCESS_KEY"),
-			R2_ACCESS_KEY_ID: this.r2AccessKeyId || void 0,
-			R2_SECRET_ACCESS_KEY: this.r2SecretAccessKey || void 0,
-			...this.envVars
-		});
-		const passwordFilePath = this.generatePasswordFilePath();
-		const mountInfo = {
-			mountType: "fuse",
-			bucket: s3fsSource,
-			mountPath,
-			endpoint: options.endpoint,
-			provider,
-			passwordFilePath,
-			mounted: false
-		};
-		this.activeMounts.set(mountPath, mountInfo);
+		let mountOutcome = "error";
+		let mountError;
+		let passwordFilePath;
+		let provider = null;
 		try {
+			this.validateMountOptions(bucket, mountPath, {
+				...options,
+				prefix
+			});
+			const s3fsSource = buildS3fsSource(bucket, prefix);
+			provider = options.provider || detectProviderFromUrl(options.endpoint);
+			this.logger.debug(`Detected provider: ${provider || "unknown"}`, {
+				explicitProvider: options.provider,
+				prefix
+			});
+			const envObj = this.env;
+			const credentials = detectCredentials(options, {
+				AWS_ACCESS_KEY_ID: getEnvString(envObj, "AWS_ACCESS_KEY_ID"),
+				AWS_SECRET_ACCESS_KEY: getEnvString(envObj, "AWS_SECRET_ACCESS_KEY"),
+				R2_ACCESS_KEY_ID: this.r2AccessKeyId || void 0,
+				R2_SECRET_ACCESS_KEY: this.r2SecretAccessKey || void 0,
+				...this.envVars
+			});
+			passwordFilePath = this.generatePasswordFilePath();
+			const mountInfo = {
+				mountType: "fuse",
+				bucket: s3fsSource,
+				mountPath,
+				endpoint: options.endpoint,
+				provider,
+				passwordFilePath,
+				mounted: false
+			};
+			this.activeMounts.set(mountPath, mountInfo);
 			await this.createPasswordFile(passwordFilePath, bucket, credentials);
-			await this.exec(`mkdir -p ${shellEscape(mountPath)}`);
+			await this.execInternal(`mkdir -p ${shellEscape(mountPath)}`);
 			await this.executeS3FSMount(s3fsSource, mountPath, options, provider, passwordFilePath);
 			mountInfo.mounted = true;
-			this.logger.info(`Successfully mounted bucket ${bucket} to ${mountPath}`);
+			mountOutcome = "success";
 		} catch (error) {
-			await this.deletePasswordFile(passwordFilePath);
+			mountError = error instanceof Error ? error : new Error(String(error));
+			if (passwordFilePath) await this.deletePasswordFile(passwordFilePath);
 			this.activeMounts.delete(mountPath);
 			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "bucket.mount",
+				outcome: mountOutcome,
+				durationMs: Date.now() - mountStartTime,
+				bucket,
+				mountPath,
+				provider: provider || "unknown",
+				prefix,
+				error: mountError
+			});
 		}
 	}
 	/**
@@ -4189,21 +4089,37 @@ var Sandbox = class Sandbox extends Container {
 	* @throws InvalidMountConfigError if mount path doesn't exist or isn't mounted
 	*/
 	async unmountBucket(mountPath) {
-		this.logger.info(`Unmounting bucket from ${mountPath}`);
+		const unmountStartTime = Date.now();
+		let unmountOutcome = "error";
+		let unmountError;
 		const mountInfo = this.activeMounts.get(mountPath);
-		if (!mountInfo) throw new InvalidMountConfigError(`No active mount found at path: ${mountPath}`);
-		if (mountInfo.mountType === "local-sync") {
-			await mountInfo.syncManager.stop();
-			mountInfo.mounted = false;
-			this.activeMounts.delete(mountPath);
-		} else try {
-			await this.exec(`fusermount -u ${shellEscape(mountPath)}`);
-			mountInfo.mounted = false;
-			this.activeMounts.delete(mountPath);
+		try {
+			if (!mountInfo) throw new InvalidMountConfigError(`No active mount found at path: ${mountPath}`);
+			if (mountInfo.mountType === "local-sync") {
+				await mountInfo.syncManager.stop();
+				mountInfo.mounted = false;
+				this.activeMounts.delete(mountPath);
+			} else try {
+				await this.execInternal(`fusermount -u ${shellEscape(mountPath)}`);
+				mountInfo.mounted = false;
+				this.activeMounts.delete(mountPath);
+			} finally {
+				await this.deletePasswordFile(mountInfo.passwordFilePath);
+			}
+			unmountOutcome = "success";
+		} catch (error) {
+			unmountError = error instanceof Error ? error : new Error(String(error));
+			throw error;
 		} finally {
-			await this.deletePasswordFile(mountInfo.passwordFilePath);
+			logCanonicalEvent(this.logger, {
+				event: "bucket.unmount",
+				outcome: unmountOutcome,
+				durationMs: Date.now() - unmountStartTime,
+				mountPath,
+				bucket: mountInfo?.bucket,
+				error: unmountError
+			});
 		}
-		this.logger.info(`Successfully unmounted bucket from ${mountPath}`);
 	}
 	/**
 	* Validate mount options
@@ -4232,18 +4148,19 @@ var Sandbox = class Sandbox extends Container {
 	async createPasswordFile(passwordFilePath, bucket, credentials) {
 		const content = `${bucket}:${credentials.accessKeyId}:${credentials.secretAccessKey}`;
 		await this.writeFile(passwordFilePath, content);
-		await this.exec(`chmod 0600 ${shellEscape(passwordFilePath)}`);
-		this.logger.debug(`Created password file: ${passwordFilePath}`);
+		await this.execInternal(`chmod 0600 ${shellEscape(passwordFilePath)}`);
 	}
 	/**
 	* Delete password file
 	*/
 	async deletePasswordFile(passwordFilePath) {
 		try {
-			await this.exec(`rm -f ${shellEscape(passwordFilePath)}`);
-			this.logger.debug(`Deleted password file: ${passwordFilePath}`);
+			await this.execInternal(`rm -f ${shellEscape(passwordFilePath)}`);
 		} catch (error) {
-			this.logger.warn(`Failed to delete password file ${passwordFilePath}`, { error: error instanceof Error ? error.message : String(error) });
+			this.logger.warn("password file cleanup failed", {
+				passwordFilePath,
+				error: error instanceof Error ? error.message : String(error)
+			});
 		}
 	}
 	/**
@@ -4258,44 +4175,61 @@ var Sandbox = class Sandbox extends Container {
 		s3fsArgs.push(`url=${options.endpoint}`);
 		const optionsStr = shellEscape(s3fsArgs.join(","));
 		const mountCmd = `s3fs ${shellEscape(bucket)} ${shellEscape(mountPath)} -o ${optionsStr}`;
-		this.logger.debug("Executing s3fs mount", {
-			bucket,
-			mountPath,
-			provider,
-			resolvedOptions
-		});
-		const result = await this.exec(mountCmd);
+		const result = await this.execInternal(mountCmd);
 		if (result.exitCode !== 0) throw new S3FSMountError(`S3FS mount failed: ${result.stderr || result.stdout || "Unknown error"}`);
-		this.logger.debug("Mount command executed successfully");
 	}
 	/**
 	* Cleanup and destroy the sandbox container
 	*/
 	async destroy() {
-		this.logger.info("Destroying sandbox container");
-		if (this.ctx.container?.running) try {
-			await this.client.desktop.stop();
-		} catch {}
-		this.client.disconnect();
-		for (const [mountPath, mountInfo] of this.activeMounts.entries()) if (mountInfo.mountType === "local-sync") try {
-			await mountInfo.syncManager.stop();
-			mountInfo.mounted = false;
-		} catch (error) {
-			const errorMsg = error instanceof Error ? error.message : String(error);
-			this.logger.warn(`Failed to stop local sync for ${mountPath}: ${errorMsg}`);
-		}
-		else {
-			if (mountInfo.mounted) try {
-				this.logger.info(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
-				await this.exec(`fusermount -u ${shellEscape(mountPath)}`);
-				mountInfo.mounted = false;
-			} catch (error) {
-				const errorMsg = error instanceof Error ? error.message : String(error);
-				this.logger.warn(`Failed to unmount bucket ${mountInfo.bucket} from ${mountPath}: ${errorMsg}`);
+		const startTime = Date.now();
+		let mountsProcessed = 0;
+		let mountFailures = 0;
+		let outcome = "error";
+		let caughtError;
+		try {
+			if (this.ctx.container?.running) try {
+				await this.client.desktop.stop();
+			} catch {}
+			this.client.disconnect();
+			for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
+				mountsProcessed++;
+				if (mountInfo.mountType === "local-sync") try {
+					await mountInfo.syncManager.stop();
+					mountInfo.mounted = false;
+				} catch (error) {
+					mountFailures++;
+					const errorMsg = error instanceof Error ? error.message : String(error);
+					this.logger.warn(`Failed to stop local sync for ${mountPath}: ${errorMsg}`);
+				}
+				else {
+					if (mountInfo.mounted) try {
+						this.logger.debug(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
+						await this.execInternal(`fusermount -u ${shellEscape(mountPath)}`);
+						mountInfo.mounted = false;
+					} catch (error) {
+						mountFailures++;
+						const errorMsg = error instanceof Error ? error.message : String(error);
+						this.logger.warn(`Failed to unmount bucket ${mountInfo.bucket} from ${mountPath}: ${errorMsg}`);
+					}
+					await this.deletePasswordFile(mountInfo.passwordFilePath);
+				}
 			}
-			await this.deletePasswordFile(mountInfo.passwordFilePath);
+			outcome = "success";
+			await super.destroy();
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "sandbox.destroy",
+				outcome,
+				durationMs: Date.now() - startTime,
+				mountsProcessed,
+				mountFailures,
+				error: caughtError
+			});
 		}
-		await super.destroy();
 	}
 	onStart() {
 		this.logger.debug("Sandbox started");
@@ -4308,23 +4242,27 @@ var Sandbox = class Sandbox extends Container {
 	* Logs a warning if there's a mismatch
 	*/
 	async checkVersionCompatibility() {
+		const sdkVersion = SDK_VERSION;
+		let containerVersion;
+		let outcome;
 		try {
-			const sdkVersion = SDK_VERSION;
-			const containerVersion = await this.client.utils.getVersion();
-			if (containerVersion === "unknown") {
-				this.logger.warn("Container version check: Container version could not be determined. This may indicate an outdated container image. Please update your container to match SDK version " + sdkVersion);
-				return;
-			}
-			if (containerVersion !== sdkVersion) {
-				const message = `Version mismatch detected! SDK version (${sdkVersion}) does not match container version (${containerVersion}). This may cause compatibility issues. Please update your container image to version ${sdkVersion}`;
-				this.logger.warn(message);
-			} else this.logger.debug("Version check passed", {
-				sdkVersion,
-				containerVersion
-			});
+			containerVersion = await this.client.utils.getVersion();
+			if (containerVersion === "unknown") outcome = "container_version_unknown";
+			else if (containerVersion !== sdkVersion) outcome = "version_mismatch";
+			else outcome = "compatible";
 		} catch (error) {
-			this.logger.debug("Version compatibility check encountered an error", { error: error instanceof Error ? error.message : String(error) });
-		}
+			outcome = "check_failed";
+			containerVersion = void 0;
+		}
+		const successLevel = outcome === "compatible" ? "debug" : outcome === "container_version_unknown" ? "info" : "warn";
+		logCanonicalEvent(this.logger, {
+			event: "version.check",
+			outcome: "success",
+			durationMs: 0,
+			sdkVersion,
+			containerVersion: containerVersion ?? "unknown",
+			versionOutcome: outcome
+		}, { successLevel });
 	}
 	async onStop() {
 		this.logger.debug("Sandbox stopped");
@@ -4345,84 +4283,66 @@ var Sandbox = class Sandbox extends Container {
 		const state = await this.getState();
 		const containerRunning = this.ctx.container?.running;
 		const staleStateDetected = state.status === "healthy" && containerRunning === false;
-		if (state.status !== "healthy" || containerRunning === false) {
-			if (staleStateDetected) this.logger.debug("Stale container state detected: persisted state is healthy but container is not running");
-			try {
-				this.logger.debug("Starting container with configured timeouts", {
-					instanceTimeout: this.containerTimeouts.instanceGetTimeoutMS,
-					portTimeout: this.containerTimeouts.portReadyTimeoutMS
-				});
-				await this.startAndWaitForPorts({
-					ports: port,
-					cancellationOptions: {
-						instanceGetTimeoutMS: this.containerTimeouts.instanceGetTimeoutMS,
-						portReadyTimeoutMS: this.containerTimeouts.portReadyTimeoutMS,
-						waitInterval: this.containerTimeouts.waitIntervalMS,
-						abort: request.signal
+		if (state.status !== "healthy" || containerRunning === false) try {
+			await this.startAndWaitForPorts({
+				ports: port,
+				cancellationOptions: {
+					instanceGetTimeoutMS: this.containerTimeouts.instanceGetTimeoutMS,
+					portReadyTimeoutMS: this.containerTimeouts.portReadyTimeoutMS,
+					waitInterval: this.containerTimeouts.waitIntervalMS,
+					abort: request.signal
+				}
+			});
+		} catch (e) {
+			if (this.isNoInstanceError(e)) {
+				const errorBody$1 = {
+					code: ErrorCode.INTERNAL_ERROR,
+					message: "Container is currently provisioning. This can take several minutes on first deployment.",
+					context: { phase: "provisioning" },
+					httpStatus: 503,
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					suggestion: "This is expected during first deployment. The SDK will retry automatically."
+				};
+				return new Response(JSON.stringify(errorBody$1), {
+					status: 503,
+					headers: {
+						"Content-Type": "application/json",
+						"Retry-After": "10"
 					}
 				});
-			} catch (e) {
-				if (this.isNoInstanceError(e)) {
-					const errorBody$1 = {
-						code: ErrorCode.INTERNAL_ERROR,
-						message: "Container is currently provisioning. This can take several minutes on first deployment.",
-						context: { phase: "provisioning" },
-						httpStatus: 503,
-						timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-						suggestion: "This is expected during first deployment. The SDK will retry automatically."
-					};
-					return new Response(JSON.stringify(errorBody$1), {
-						status: 503,
-						headers: {
-							"Content-Type": "application/json",
-							"Retry-After": "10"
-						}
-					});
-				}
-				if (this.isPermanentStartupError(e)) {
-					this.logger.error("Permanent container startup error, returning 500", e instanceof Error ? e : new Error(String(e)));
-					const errorBody$1 = {
-						code: ErrorCode.INTERNAL_ERROR,
-						message: "Container failed to start due to a permanent error. Check your container configuration.",
-						context: {
-							phase: "startup",
-							error: e instanceof Error ? e.message : String(e)
-						},
-						httpStatus: 500,
-						timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-						suggestion: "This error will not resolve with retries. Check container logs, image name, and resource limits."
-					};
-					return new Response(JSON.stringify(errorBody$1), {
-						status: 500,
-						headers: { "Content-Type": "application/json" }
-					});
-				}
-				if (this.isTransientStartupError(e)) {
-					if (staleStateDetected) {
-						this.logger.warn("Container startup failed after stale state detection, aborting DO for recovery", { error: e instanceof Error ? e.message : String(e) });
-						this.ctx.abort();
-					} else this.logger.debug("Transient container startup error, returning 503", { error: e instanceof Error ? e.message : String(e) });
-					const errorBody$1 = {
-						code: ErrorCode.INTERNAL_ERROR,
-						message: "Container is starting. Please retry in a moment.",
-						context: {
-							phase: "startup",
-							error: e instanceof Error ? e.message : String(e)
-						},
-						httpStatus: 503,
-						timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-						suggestion: "The container is booting. The SDK will retry automatically."
-					};
-					return new Response(JSON.stringify(errorBody$1), {
-						status: 503,
-						headers: {
-							"Content-Type": "application/json",
-							"Retry-After": "3"
-						}
+			}
+			if (this.isPermanentStartupError(e)) {
+				this.logger.error("Permanent container startup error, returning 500", e instanceof Error ? e : new Error(String(e)));
+				const errorBody$1 = {
+					code: ErrorCode.INTERNAL_ERROR,
+					message: "Container failed to start due to a permanent error. Check your container configuration.",
+					context: {
+						phase: "startup",
+						error: e instanceof Error ? e.message : String(e)
+					},
+					httpStatus: 500,
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					suggestion: "This error will not resolve with retries. Check container logs, image name, and resource limits."
+				};
+				return new Response(JSON.stringify(errorBody$1), {
+					status: 500,
+					headers: { "Content-Type": "application/json" }
+				});
+			}
+			if (this.isTransientStartupError(e)) {
+				if (staleStateDetected) {
+					this.logger.warn("container.startup", {
+						outcome: "stale_state_abort",
+						staleStateDetected: true,
+						error: e instanceof Error ? e.message : String(e)
 					});
-				}
-				this.logger.warn("Unrecognized container startup error, returning 503 for retry", { error: e instanceof Error ? e.message : String(e) });
-				const errorBody = {
+					this.ctx.abort();
+				} else this.logger.debug("container.startup", {
+					outcome: "transient_error",
+					staleStateDetected,
+					error: e instanceof Error ? e.message : String(e)
+				});
+				const errorBody$1 = {
 					code: ErrorCode.INTERNAL_ERROR,
 					message: "Container is starting. Please retry in a moment.",
 					context: {
@@ -4431,16 +4351,39 @@ var Sandbox = class Sandbox extends Container {
 					},
 					httpStatus: 503,
 					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-					suggestion: "The SDK will retry automatically. If this persists, the container may need redeployment."
+					suggestion: "The container is booting. The SDK will retry automatically."
 				};
-				return new Response(JSON.stringify(errorBody), {
+				return new Response(JSON.stringify(errorBody$1), {
 					status: 503,
 					headers: {
 						"Content-Type": "application/json",
-						"Retry-After": "5"
+						"Retry-After": "3"
 					}
 				});
 			}
+			this.logger.warn("container.startup", {
+				outcome: "unrecognized_error",
+				staleStateDetected,
+				error: e instanceof Error ? e.message : String(e)
+			});
+			const errorBody = {
+				code: ErrorCode.INTERNAL_ERROR,
+				message: "Container is starting. Please retry in a moment.",
+				context: {
+					phase: "startup",
+					error: e instanceof Error ? e.message : String(e)
+				},
+				httpStatus: 503,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				suggestion: "The SDK will retry automatically. If this persists, the container may need redeployment."
+			};
+			return new Response(JSON.stringify(errorBody), {
+				status: 503,
+				headers: {
+					"Content-Type": "application/json",
+					"Retry-After": "5"
+				}
+			});
 		}
 		return await super.containerFetch(requestOrUrl, portOrInit, portParam);
 	}
@@ -4610,31 +4553,59 @@ var Sandbox = class Sandbox extends Container {
 		return this.execWithSession(command, session, options);
 	}
 	/**
+	* Execute an infrastructure command (backup, mount, env setup, etc.)
+	* tagged with origin: 'internal' so logging demotes it to debug level.
+	*/
+	async execInternal(command) {
+		const session = await this.ensureDefaultSession();
+		return this.execWithSession(command, session, { origin: "internal" });
+	}
+	/**
 	* Internal session-aware exec implementation
 	* Used by both public exec() and session wrappers
 	*/
 	async execWithSession(command, sessionId, options) {
 		const startTime = Date.now();
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		let execOutcome;
+		let execError;
 		try {
 			if (options?.signal?.aborted) throw new Error("Operation was aborted");
 			let result;
 			if (options?.stream && options?.onOutput) result = await this.executeWithStreaming(command, sessionId, options, startTime, timestamp);
 			else {
-				const commandOptions = options && (options.timeout !== void 0 || options.env !== void 0 || options.cwd !== void 0) ? {
+				const commandOptions = options && (options.timeout !== void 0 || options.env !== void 0 || options.cwd !== void 0 || options.origin !== void 0) ? {
 					timeoutMs: options.timeout,
 					env: options.env,
-					cwd: options.cwd
+					cwd: options.cwd,
+					origin: options.origin
 				} : void 0;
 				const response = await this.client.commands.execute(command, sessionId, commandOptions);
 				const duration = Date.now() - startTime;
 				result = this.mapExecuteResponseToExecResult(response, duration, sessionId);
 			}
+			execOutcome = {
+				exitCode: result.exitCode,
+				success: result.success
+			};
 			if (options?.onComplete) options.onComplete(result);
 			return result;
 		} catch (error) {
+			execError = error instanceof Error ? error : new Error(String(error));
 			if (options?.onError && error instanceof Error) options.onError(error);
 			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "sandbox.exec",
+				outcome: execError ? "error" : "success",
+				command,
+				exitCode: execOutcome?.exitCode,
+				durationMs: Date.now() - startTime,
+				sessionId,
+				origin: options?.origin ?? "user",
+				error: execError ?? void 0,
+				errorMessage: execError?.message
+			});
 		}
 	}
 	async executeWithStreaming(command, sessionId, options, startTime, timestamp) {
@@ -4644,7 +4615,8 @@ var Sandbox = class Sandbox extends Container {
 			const stream = await this.client.commands.executeStream(command, sessionId, {
 				timeoutMs: options.timeout,
 				env: options.env,
-				cwd: options.cwd
+				cwd: options.cwd,
+				origin: options.origin
 			});
 			for await (const event of parseSSEStream(stream)) {
 				if (options.signal?.aborted) throw new Error("Operation was aborted");
@@ -5197,41 +5169,78 @@ var Sandbox = class Sandbox extends Container {
 	* // url: https://8080-sandbox-id-my_token_v1.example.com
 	*/
 	async exposePort(port, options) {
-		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
-		if (options.hostname.endsWith(".workers.dev")) throw new CustomDomainRequiredError({
-			code: ErrorCode.CUSTOM_DOMAIN_REQUIRED,
-			message: `Port exposure requires a custom domain. .workers.dev domains do not support wildcard subdomains required for port proxying.`,
-			context: { originalError: options.hostname },
-			httpStatus: 400,
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
-		let token;
-		if (options.token !== void 0) {
-			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());
-		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;
-		await this.ctx.storage.put("portTokens", tokens);
-		return {
-			url: this.constructPreviewUrl(port, this.sandboxName, options.hostname, token),
-			port,
-			name: options?.name
-		};
+		const exposeStartTime = Date.now();
+		let outcome = "error";
+		let caughtError;
+		try {
+			if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
+			if (options.hostname.endsWith(".workers.dev")) throw new CustomDomainRequiredError({
+				code: ErrorCode.CUSTOM_DOMAIN_REQUIRED,
+				message: `Port exposure requires a custom domain. .workers.dev domains do not support wildcard subdomains required for port proxying.`,
+				context: { originalError: options.hostname },
+				httpStatus: 400,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
+			let token;
+			if (options.token !== void 0) {
+				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());
+			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;
+			await this.ctx.storage.put("portTokens", tokens);
+			const url = this.constructPreviewUrl(port, this.sandboxName, options.hostname, token);
+			outcome = "success";
+			return {
+				url,
+				port,
+				name: options?.name
+			};
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "port.expose",
+				outcome,
+				port,
+				durationMs: Date.now() - exposeStartTime,
+				name: options?.name,
+				hostname: options.hostname,
+				error: caughtError
+			});
+		}
 	}
 	async unexposePort(port) {
-		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") || {};
-		if (tokens[port.toString()]) {
-			delete tokens[port.toString()];
-			await this.ctx.storage.put("portTokens", tokens);
+		const unexposeStartTime = Date.now();
+		let outcome = "error";
+		let caughtError;
+		try {
+			if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding 3000 (sandbox control plane).`);
+			const sessionId = await this.ensureDefaultSession();
+			await this.client.ports.unexposePort(port, sessionId);
+			const tokens = await this.ctx.storage.get("portTokens") || {};
+			if (tokens[port.toString()]) {
+				delete tokens[port.toString()];
+				await this.ctx.storage.put("portTokens", tokens);
+			}
+			outcome = "success";
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "port.unexpose",
+				outcome,
+				port,
+				durationMs: Date.now() - unexposeStartTime,
+				error: caughtError
+			});
 		}
 	}
 	async getExposedPorts(hostname) {
@@ -5405,12 +5414,12 @@ var Sandbox = class Sandbox extends Container {
 				try {
 					for (const key of toUnset) {
 						const unsetCommand = `unset ${key}`;
-						const result = await this.client.commands.execute(unsetCommand, sessionId);
+						const result = await this.client.commands.execute(unsetCommand, sessionId, { origin: "internal" });
 						if (result.exitCode !== 0) throw new Error(`Failed to unset ${key}: ${result.stderr || "Unknown error"}`);
 					}
 					for (const [key, value] of Object.entries(toSet)) {
 						const exportCommand = `export ${key}=${shellEscape(value)}`;
-						const result = await this.client.commands.execute(exportCommand, sessionId);
+						const result = await this.client.commands.execute(exportCommand, sessionId, { origin: "internal" });
 						if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
 					}
 				} catch (error) {
@@ -5490,20 +5499,17 @@ var Sandbox = class Sandbox extends Container {
 	}
 	static PRESIGNED_URL_EXPIRY_SECONDS = 3600;
 	/**
-	* Ensure a dedicated session for backup operations exists.
-	* Isolates backup shell commands (curl, stat, rm, mkdir) from user exec()
-	* calls to prevent session state interference and interleaving.
+	* Create a unique, dedicated session for a single backup operation.
+	* Each call produces a fresh session ID so concurrent or sequential
+	* operations never share shell state. Callers must destroy the session
+	* in a finally block via `client.utils.deleteSession()`.
 	*/
 	async ensureBackupSession() {
-		const sessionId = "__sandbox_backup__";
-		try {
-			await this.client.utils.createSession({
-				id: sessionId,
-				cwd: "/"
-			});
-		} catch (error) {
-			if (!(error instanceof SessionAlreadyExistsError)) throw error;
-		}
+		const sessionId = `__sandbox_backup_${crypto.randomUUID()}`;
+		await this.client.utils.createSession({
+			id: sessionId,
+			cwd: "/"
+		});
 		return sessionId;
 	}
 	/**
@@ -5562,11 +5568,6 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async uploadBackupPresigned(archivePath, r2Key, archiveSize, backupId, dir, backupSession) {
 		const presignedUrl = await this.generatePresignedPutUrl(r2Key);
-		this.logger.info("Uploading backup via presigned PUT", {
-			r2Key,
-			archiveSize,
-			backupId
-		});
 		const curlCmd = [
 			"curl -sSf",
 			"-X PUT",
@@ -5578,7 +5579,10 @@ var Sandbox = class Sandbox extends Container {
 			`-T ${shellEscape(archivePath)}`,
 			shellEscape(presignedUrl)
 		].join(" ");
-		const result = await this.execWithSession(curlCmd, backupSession, { timeout: 181e4 });
+		const result = await this.execWithSession(curlCmd, backupSession, {
+			timeout: 181e4,
+			origin: "internal"
+		});
 		if (result.exitCode !== 0) throw new BackupCreateError({
 			message: `Presigned URL upload failed (exit code ${result.exitCode}): ${result.stderr}`,
 			code: ErrorCode.BACKUP_CREATE_FAILED,
@@ -5611,12 +5615,7 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async downloadBackupPresigned(archivePath, r2Key, expectedSize, backupId, dir, backupSession) {
 		const presignedUrl = await this.generatePresignedGetUrl(r2Key);
-		this.logger.info("Downloading backup via presigned GET", {
-			r2Key,
-			expectedSize,
-			backupId
-		});
-		await this.execWithSession("mkdir -p /var/backups", backupSession);
+		await this.execWithSession("mkdir -p /var/backups", backupSession, { origin: "internal" });
 		const tmpPath = `${archivePath}.tmp`;
 		const curlCmd = [
 			"curl -sSf",
@@ -5627,9 +5626,12 @@ var Sandbox = class Sandbox extends Container {
 			`-o ${shellEscape(tmpPath)}`,
 			shellEscape(presignedUrl)
 		].join(" ");
-		const result = await this.execWithSession(curlCmd, backupSession, { timeout: 181e4 });
+		const result = await this.execWithSession(curlCmd, backupSession, {
+			timeout: 181e4,
+			origin: "internal"
+		});
 		if (result.exitCode !== 0) {
-			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession).catch(() => {});
+			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession, { origin: "internal" }).catch(() => {});
 			throw new BackupRestoreError({
 				message: `Presigned URL download failed (exit code ${result.exitCode}): ${result.stderr}`,
 				code: ErrorCode.BACKUP_RESTORE_FAILED,
@@ -5641,10 +5643,10 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 		}
-		const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(tmpPath)}`, backupSession);
+		const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(tmpPath)}`, backupSession, { origin: "internal" });
 		const actualSize = parseInt(sizeCheck.stdout.trim(), 10);
 		if (actualSize !== expectedSize) {
-			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession).catch(() => {});
+			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession, { origin: "internal" }).catch(() => {});
 			throw new BackupRestoreError({
 				message: `Downloaded archive size mismatch: expected ${expectedSize}, got ${actualSize}`,
 				code: ErrorCode.BACKUP_RESTORE_FAILED,
@@ -5656,9 +5658,9 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 		}
-		const mvResult = await this.execWithSession(`mv ${shellEscape(tmpPath)} ${shellEscape(archivePath)}`, backupSession);
+		const mvResult = await this.execWithSession(`mv ${shellEscape(tmpPath)} ${shellEscape(archivePath)}`, backupSession, { origin: "internal" });
 		if (mvResult.exitCode !== 0) {
-			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession).catch(() => {});
+			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession, { origin: "internal" }).catch(() => {});
 			throw new BackupRestoreError({
 				message: `Failed to finalize downloaded archive: ${mvResult.stderr}`,
 				code: ErrorCode.BACKUP_RESTORE_FAILED,
@@ -5713,68 +5715,68 @@ var Sandbox = class Sandbox extends Container {
 		const DEFAULT_TTL_SECONDS = 259200;
 		const MAX_NAME_LENGTH = 256;
 		const { dir, name, ttl = DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
-		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`,
+		const backupStartTime = Date.now();
+		let backupId;
+		let sizeBytes;
+		let outcome = "error";
+		let caughtError;
+		let backupSession;
+		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`,
+					code: ErrorCode.INVALID_BACKUP_CONFIG,
+					httpStatus: 400,
+					context: { reason: `name must be a string of at most ${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: `name must be a string of at most ${MAX_NAME_LENGTH} characters` },
+				context: { reason: "ttl must be a positive number of seconds" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			if (/[\u0000-\u001f\u007f]/.test(name)) throw new InvalidBackupConfigError({
-				message: "BackupOptions.name must not contain control characters",
+			if (typeof gitignore !== "boolean") throw new InvalidBackupConfigError({
+				message: "BackupOptions.gitignore must be a boolean",
 				code: ErrorCode.INVALID_BACKUP_CONFIG,
 				httpStatus: 400,
-				context: { reason: "name must not contain control characters" },
+				context: { reason: "gitignore must be a boolean" },
 				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: "ttl must be a positive number of seconds" },
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		if (typeof gitignore !== "boolean") throw new InvalidBackupConfigError({
-			message: "BackupOptions.gitignore must be a boolean",
-			code: ErrorCode.INVALID_BACKUP_CONFIG,
-			httpStatus: 400,
-			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()
-		});
-		const backupSession = await this.ensureBackupSession();
-		const backupId = crypto.randomUUID();
-		const archivePath = `/var/backups/${backupId}.sqsh`;
-		this.logger.info("Creating backup", {
-			backupId,
-			dir,
-			name,
-			gitignore,
-			excludes
-		});
-		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()
-		});
-		const r2Key = `backups/${backupId}/data.sqsh`;
-		const metaKey = `backups/${backupId}/meta.json`;
-		try {
+			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 = `/var/backups/${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 = `backups/${backupId}/data.sqsh`;
+			const metaKey = `backups/${backupId}/meta.json`;
 			await this.uploadBackupPresigned(archivePath, r2Key, createResult.sizeBytes, backupId, dir, backupSession);
 			const metadata = {
 				id: backupId,
@@ -5785,21 +5787,35 @@ var Sandbox = class Sandbox extends Container {
 				createdAt: (/* @__PURE__ */ new Date()).toISOString()
 			};
 			await bucket.put(metaKey, JSON.stringify(metadata));
-			this.logger.info("Backup uploaded to R2", {
-				backupId,
-				r2Key,
-				sizeBytes: createResult.sizeBytes
-			});
-			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession).catch(() => {});
+			outcome = "success";
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
 			return {
 				id: backupId,
 				dir
 			};
 		} catch (error) {
-			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession).catch(() => {});
-			await bucket.delete(r2Key).catch(() => {});
-			await bucket.delete(metaKey).catch(() => {});
+			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`;
+				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,
+				error: caughtError
+			});
 		}
 	}
 	/**
@@ -5834,77 +5850,77 @@ var Sandbox = class Sandbox extends Container {
 		return this.enqueueBackupOp(() => this.doRestoreBackup(backup));
 	}
 	async doRestoreBackup(backup) {
+		const restoreStartTime = Date.now();
 		const bucket = this.requireBackupBucket();
 		this.requirePresignedUrlSupport();
 		const { id: backupId, dir } = backup;
-		if (!backupId || typeof backupId !== "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(backupId)) 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");
-		this.logger.info("Restoring backup", {
-			backupId,
-			dir
-		});
-		const metaKey = `backups/${backupId}/meta.json`;
-		const metaObject = await bucket.get(metaKey);
-		if (!metaObject) throw new BackupNotFoundError({
-			message: `Backup not found: ${backupId}. Verify the backup ID is correct and the backup has not been deleted.`,
-			code: ErrorCode.BACKUP_NOT_FOUND,
-			httpStatus: 404,
-			context: { backupId },
-			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
-			},
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		const expiresAt = createdAt + metadata.ttl * 1e3;
-		if (Date.now() + TTL_BUFFER_MS > expiresAt) throw new BackupExpiredError({
-			message: `Backup ${backupId} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
-			code: ErrorCode.BACKUP_EXPIRED,
-			httpStatus: 400,
-			context: {
-				backupId,
-				expiredAt: new Date(expiresAt).toISOString()
-			},
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		const r2Key = `backups/${backupId}/data.sqsh`;
-		const archiveHead = await bucket.head(r2Key);
-		if (!archiveHead) throw new BackupNotFoundError({
-			message: `Backup archive not found in R2: ${backupId}. The archive may have been deleted by R2 lifecycle rules.`,
-			code: ErrorCode.BACKUP_NOT_FOUND,
-			httpStatus: 404,
-			context: { backupId },
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		const backupSession = await this.ensureBackupSession();
-		const archivePath = `/var/backups/${backupId}.sqsh`;
+		let outcome = "error";
+		let caughtError;
+		let backupSession;
 		try {
+			if (!backupId || typeof backupId !== "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(backupId)) 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/${backupId}/meta.json`;
+			const metaObject = await bucket.get(metaKey);
+			if (!metaObject) throw new BackupNotFoundError({
+				message: `Backup not found: ${backupId}. Verify the backup ID is correct and the backup has not been deleted.`,
+				code: ErrorCode.BACKUP_NOT_FOUND,
+				httpStatus: 404,
+				context: { backupId },
+				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
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const expiresAt = createdAt + metadata.ttl * 1e3;
+			if (Date.now() + TTL_BUFFER_MS > expiresAt) throw new BackupExpiredError({
+				message: `Backup ${backupId} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
+				code: ErrorCode.BACKUP_EXPIRED,
+				httpStatus: 400,
+				context: {
+					backupId,
+					expiredAt: new Date(expiresAt).toISOString()
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const r2Key = `backups/${backupId}/data.sqsh`;
+			const archiveHead = await bucket.head(r2Key);
+			if (!archiveHead) throw new BackupNotFoundError({
+				message: `Backup archive not found in R2: ${backupId}. The archive may have been deleted by R2 lifecycle rules.`,
+				code: ErrorCode.BACKUP_NOT_FOUND,
+				httpStatus: 404,
+				context: { backupId },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			backupSession = await this.ensureBackupSession();
+			const archivePath = `/var/backups/${backupId}.sqsh`;
 			const mountGlob = `/var/backups/mounts/${backupId}`;
-			await this.execWithSession(`/usr/bin/fusermount3 -uz ${shellEscape(dir)} 2>/dev/null || true`, backupSession).catch(() => {});
-			await this.execWithSession(`for d in ${shellEscape(mountGlob)}_*/lower ${shellEscape(mountGlob)}/lower; do [ -d "$d" ] && /usr/bin/fusermount3 -uz "$d" 2>/dev/null; done; true`, backupSession).catch(() => {});
-			const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(archivePath)} 2>/dev/null || echo 0`, backupSession).catch(() => ({ stdout: "0" }));
+			await this.execWithSession(`/usr/bin/fusermount3 -uz ${shellEscape(dir)} 2>/dev/null || true`, backupSession, { origin: "internal" }).catch(() => {});
+			await this.execWithSession(`for d in ${shellEscape(mountGlob)}_*/lower ${shellEscape(mountGlob)}/lower; do [ -d "$d" ] && /usr/bin/fusermount3 -uz "$d" 2>/dev/null; done; true`, backupSession, { origin: "internal" }).catch(() => {});
+			const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(archivePath)} 2>/dev/null || echo 0`, backupSession, { origin: "internal" }).catch(() => ({ stdout: "0" }));
 			if (Number.parseInt((sizeCheck.stdout ?? "0").trim(), 10) !== archiveHead.size) await this.downloadBackupPresigned(archivePath, r2Key, archiveHead.size, backupId, dir, backupSession);
 			if (!(await this.client.backup.restoreArchive(dir, archivePath, backupSession)).success) throw new BackupRestoreError({
 				message: "Container failed to restore backup archive",
@@ -5916,18 +5932,29 @@ var Sandbox = class Sandbox extends Container {
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			this.logger.info("Backup restored", {
-				backupId,
-				dir
-			});
+			outcome = "success";
 			return {
 				success: true,
 				dir,
 				id: backupId
 			};
 		} catch (error) {
-			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession).catch(() => {});
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			if (backupId && backupSession) {
+				const archivePath = `/var/backups/${backupId}.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,
+				dir,
+				error: caughtError
+			});
 		}
 	}
 };
@@ -6055,5 +6082,5 @@ async function collectFile(stream) {
 }
 
 //#endregion
-export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, BackupRestoreError, BucketMountError, CodeInterpreter, CommandClient, DesktopClient, DesktopInvalidCoordinatesError, DesktopInvalidOptionsError, DesktopNotStartedError, DesktopProcessCrashedError, DesktopStartFailedError, DesktopUnavailableError, FileClient, GitClient, InvalidBackupConfigError, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, BackupRestoreError, BucketMountError, CodeInterpreter, CommandClient, ContainerProxy, DesktopClient, DesktopInvalidCoordinatesError, DesktopInvalidOptionsError, DesktopNotStartedError, DesktopProcessCrashedError, DesktopStartFailedError, DesktopUnavailableError, FileClient, GitClient, InvalidBackupConfigError, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.js.map