@cloudflare/sandbox 0.9.1 → 0.9.3

package/dist/{sandbox-PAYx1CcU.js → sandbox-BAuU-2a0.js}

@@ -1,5 +1,5 @@
 import { _ as GitLogger, b as getEnvString, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as DEFAULT_GIT_CLONE_TIMEOUT_MS, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, p as logCanonicalEvent, r as isWSResponse, t as generateRequestId, u as createLogger, v as extractRepoName, x as partitionEnvVars, y as filterEnvVars } from "./dist-B_eXrP83.js";
-import { n as ErrorCode, t as getHttpStatus } from "./errors-LE3HHcRb.js";
+import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-CBi-O-pF.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import { RpcSession } from "capnweb";
@@ -11,8 +11,8 @@ import path from "node:path/posix";
 * Preserves all error information from container
 */
 var SandboxError = class extends Error {
-	constructor(errorResponse) {
-		super(errorResponse.message);
+	constructor(errorResponse, options) {
+		super(errorResponse.message, options);
 		this.errorResponse = errorResponse;
 		this.name = "SandboxError";
 	}
@@ -664,6 +664,30 @@ var DesktopInvalidCoordinatesError = class extends SandboxError {
 		this.name = "DesktopInvalidCoordinatesError";
 	}
 };
+/**
+* Raised when the capnweb WebSocket session itself fails on the SDK side.
+* Unlike the rest of the SandboxError tree, the container never produces
+* this error — it is synthesised by `translateRPCError` from the plain
+* Errors capnweb / DeferredTransport raise when the connection dies.
+*
+* `kind` distinguishes the failure mode (peer close, upgrade failed, etc.)
+* so callers can branch on a structured code instead of substring-matching
+* on the message.
+*
+* Always retryable: the SDK opens a fresh connection on the next call.
+*/
+var RPCTransportError = class extends SandboxError {
+	constructor(errorResponse, options) {
+		super(errorResponse, options);
+		this.name = "RPCTransportError";
+	}
+	get kind() {
+		return this.errorResponse.context.kind;
+	}
+	get originalMessage() {
+		return this.errorResponse.context.originalMessage;
+	}
+};
 
 //#endregion
 //#region src/errors/adapter.ts
@@ -671,7 +695,7 @@ var DesktopInvalidCoordinatesError = class extends SandboxError {
 * Convert ErrorResponse to appropriate Error class
 * Simple switch statement - we trust the container sends correct context
 */
-function createErrorFromResponse(errorResponse) {
+function createErrorFromResponse(errorResponse, options) {
 	switch (errorResponse.code) {
 		case ErrorCode.FILE_NOT_FOUND: return new FileNotFoundError(errorResponse);
 		case ErrorCode.FILE_EXISTS: return new FileExistsError(errorResponse);
@@ -727,6 +751,7 @@ function createErrorFromResponse(errorResponse) {
 		case ErrorCode.DESKTOP_PROCESS_CRASHED: return new DesktopProcessCrashedError(errorResponse);
 		case ErrorCode.DESKTOP_INVALID_OPTIONS: return new DesktopInvalidOptionsError(errorResponse);
 		case ErrorCode.DESKTOP_INVALID_COORDINATES: return new DesktopInvalidCoordinatesError(errorResponse);
+		case ErrorCode.RPC_TRANSPORT_ERROR: return new RPCTransportError(errorResponse, options);
 		case ErrorCode.VALIDATION_FAILED: return new ValidationFailedError(errorResponse);
 		case ErrorCode.INVALID_JSON_RESPONSE:
 		case ErrorCode.UNKNOWN_ERROR:
@@ -1470,10 +1495,10 @@ var WebSocketTransport = class extends BaseTransport {
 //#endregion
 //#region src/clients/transport/factory.ts
 /**
-* Create a transport instance based on mode
+* Create a route-based compatibility transport instance based on mode.
 *
-* This is the primary API for creating transports. It handles
-* the selection of HTTP or WebSocket transport based on the mode.
+* Selects the HTTP or custom WebSocket transport for the route-based client
+* layer.
 *
 * @example
 * ```typescript
@@ -1492,23 +1517,23 @@ var WebSocketTransport = class extends BaseTransport {
 */
 function createTransport(options) {
 	switch (options.mode) {
+		case "http": return new HttpTransport(options);
 		case "websocket": return new WebSocketTransport(options);
-		default: return new HttpTransport(options);
 	}
 }
 
 //#endregion
 //#region src/clients/base-client.ts
 /**
-* Abstract base class providing common HTTP/WebSocket functionality for all domain clients
+* Abstract base class for route-based HTTP/WebSocket compatibility clients.
 *
-* All requests go through the Transport abstraction layer, which handles:
-* - HTTP and WebSocket modes transparently
-* - Automatic retry for 503 errors (container starting)
-* - Streaming responses
+* Requests go through the Transport abstraction layer, which handles:
+* - HTTP and WebSocket route-based modes transparently
+* - Automatic retry for 503 errors while the container is starting
+* - Streaming responses for the existing route API
 *
-* WebSocket mode is useful when running inside Workers/Durable Objects
-* where sub-request limits apply.
+* DO-to-container control-channel capabilities live in `container-control/`.
+* This layer supports the route-based compatibility API.
 */
 var BaseHttpClient = class {
 	options;
@@ -1629,7 +1654,7 @@ var BaseHttpClient = class {
 	/**
 	* Stream request handler
 	*
-	* For HTTP mode, uses doFetch + handleStreamResponse to get proper error typing.
+	* HTTP mode uses doFetch + handleStreamResponse for typed error handling.
 	* For WebSocket mode, uses Transport's streaming support.
 	*
 	* @param path - The API path to call
@@ -1673,6 +1698,7 @@ var BackupClient = class extends BaseHttpClient {
 			archivePath,
 			gitignore: options?.gitignore ?? false,
 			excludes: options?.excludes ?? [],
+			compression: options?.compression,
 			sessionId
 		};
 		return await this.post("/api/backup/create", data);
@@ -1691,6 +1717,12 @@ var BackupClient = class extends BaseHttpClient {
 		};
 		return await this.post("/api/backup/restore", data);
 	}
+	async uploadParts(request, sessionId) {
+		return this.post("/api/backup/upload-parts", {
+			...request,
+			sessionId: sessionId ?? request.sessionId
+		});
+	}
 };
 
 //#endregion
@@ -2593,13 +2625,13 @@ var WatchClient = class extends BaseHttpClient {
 //#endregion
 //#region src/clients/sandbox-client.ts
 /**
-* Main sandbox client that composes all domain-specific clients.
-* Provides organized access to all sandbox functionality.
+* Route-based compatibility sandbox client that composes all domain-specific
+* HTTP API clients.
 *
-* Supports two transport modes:
-* - HTTP (default): Each request is a separate HTTP call
-* - WebSocket: All requests multiplexed over a single connection,
-*   reducing sub-request count inside Workers/Durable Objects
+* This client supports the route-based HTTP and custom WebSocket transports.
+* The primary DO-to-container control path is ContainerControlClient under
+* `container-control/`. This client supports route-based compatibility,
+* debugging, local development, and fallback behavior.
 */
 var SandboxClient = class {
 	backup;
@@ -2676,9 +2708,9 @@ var SandboxClient = class {
 	/**
 	* Stream a file directly to the container over a binary RPC channel.
 	*
-	* Requires the capnweb transport (`useWebSocket: 'rpc'`). Calling this
-	* method with the HTTP or WebSocket transports throws an error because those
-	* transports do not support binary streaming.
+	* Requires the container-control path (`transport: 'rpc'`). Calling this
+	* method with the HTTP or WebSocket route transports throws an error because
+	* those transports do not support binary streaming.
 	*/
 	writeFileStream(_path, _content, _sessionId) {
 		throw new Error("writeFileStream requires the RPC transport. Enable it with transport: \"rpc\" in sandbox options.");
@@ -2712,9 +2744,17 @@ const BACKUP_ALLOWED_PREFIXES = [
 	"/var/tmp",
 	"/app"
 ];
+function normalizeBackupExcludePattern(pattern) {
+	let normalized = pattern;
+	while (normalized.startsWith("**/")) normalized = normalized.slice(3);
+	while (normalized.includes("/**/")) normalized = normalized.replace(/\/\*\*\//g, "/");
+	if (normalized.endsWith("/**")) normalized = normalized.slice(0, -3);
+	if (!normalized || normalized === "**") return null;
+	return normalized;
+}
 
 //#endregion
-//#region src/container-connection.ts
+//#region src/container-control/connection.ts
 const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 /**
 * Manages a capnweb WebSocket RPC session to the container.
@@ -2723,7 +2763,7 @@ const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 * transport. Calls made before `connect()` completes are queued in the
 * transport and flushed once the WebSocket is established.
 */
-var ContainerConnection = class {
+var ContainerControlConnection = class {
 	stub;
 	session;
 	transport;
@@ -2807,7 +2847,7 @@ var ContainerConnection = class {
 			ws.addEventListener("close", () => {
 				this.connected = false;
 				this.ws = null;
-				this.logger.debug("ContainerConnection WebSocket closed");
+				this.logger.debug("ContainerControlConnection WebSocket closed");
 			});
 			ws.addEventListener("error", () => {
 				this.connected = false;
@@ -2816,12 +2856,12 @@ var ContainerConnection = class {
 			this.ws = ws;
 			this.transport.activate(ws);
 			this.connected = true;
-			this.logger.debug("ContainerConnection established", { port: this.port });
+			this.logger.debug("ContainerControlConnection established", { port: this.port });
 		} catch (error) {
 			clearTimeout(timeout);
 			this.connected = false;
 			this.transport.abort(error);
-			this.logger.error("ContainerConnection failed", error instanceof Error ? error : new Error(String(error)));
+			this.logger.error("ContainerControlConnection failed", error instanceof Error ? error : new Error(String(error)));
 			throw error;
 		}
 	}
@@ -2847,12 +2887,13 @@ var DeferredTransport = class {
 				this.#receiveResolver = void 0;
 				this.#receiveRejecter = void 0;
 			} else this.#receiveQueue.push(event.data);
+			else this.#fail(/* @__PURE__ */ new TypeError("Received non-string message from WebSocket."));
 		});
 		ws.addEventListener("close", (event) => {
 			this.#fail(/* @__PURE__ */ new Error(`Peer closed WebSocket: ${event.code} ${event.reason}`));
 		});
 		ws.addEventListener("error", () => {
-			this.#fail(/* @__PURE__ */ new Error("WebSocket connection failed"));
+			this.#fail(/* @__PURE__ */ new Error("WebSocket connection failed."));
 		});
 		for (const msg of this.#sendQueue) ws.send(msg);
 		this.#sendQueue = [];
@@ -2886,7 +2927,7 @@ var DeferredTransport = class {
 };
 
 //#endregion
-//#region src/clients/rpc-sandbox-client.ts
+//#region src/container-control/client.ts
 /** Close the idle capnweb WebSocket promptly so the DO can sleep. */
 const DEFAULT_IDLE_DISCONNECT_MS = 1e3;
 /**
@@ -2924,19 +2965,65 @@ const IDLE_EXPORT_THRESHOLD = 1;
 * string: `{"code":"...","message":"...","context":{...}}`.
 */
 function translateRPCError(error) {
-	if (error instanceof Error) try {
-		const payload = JSON.parse(error.message);
-		if (typeof payload.code === "string" && typeof payload.message === "string") throw createErrorFromResponse({
+	if (error instanceof Error) {
+		let payload;
+		try {
+			payload = JSON.parse(error.message);
+		} catch {}
+		if (payload && typeof payload.code === "string" && typeof payload.message === "string") throw createErrorFromResponse({
 			code: payload.code,
 			message: payload.message,
 			context: payload.context ?? {},
 			httpStatus: getHttpStatus(payload.code),
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
-	} catch (e) {
-		if (e instanceof Error && e !== error) throw e;
+		throw createErrorFromResponse(buildTransportErrorResponse(error), { cause: error });
 	}
-	throw error;
+	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
+}
+/**
+* Inspect a transport-level Error's message and produce the ErrorResponse
+* that becomes an RPCTransportError. Pattern strings are pinned to the exact
+* messages emitted by capnweb's WebSocketTransport (see capnweb's
+* src/websocket.ts) and our DeferredTransport in container-control/connection.ts —
+* notably the trailing period in `WebSocket connection failed.` matches
+* capnweb verbatim. The DeferredTransport tests in
+* tests/container-connection.test.ts pin the literal strings.
+*/
+function buildTransportErrorResponse(error) {
+	const message = error.message;
+	const errorName = error.name;
+	let kind = "unknown";
+	let closeCode;
+	let closeReason;
+	if (errorName === "TypeError") kind = "invalid_frame";
+	else if (errorName === "SyntaxError") kind = "protocol_error";
+	else {
+		const peerCloseMatch = message.match(/^Peer closed WebSocket: (\d+) ?(.*)$/);
+		if (peerCloseMatch) {
+			kind = "peer_closed";
+			closeCode = Number(peerCloseMatch[1]);
+			closeReason = peerCloseMatch[2] || void 0;
+		} else if (message === "WebSocket connection failed.") kind = "connection_failed";
+		else if (message.startsWith("WebSocket upgrade failed")) kind = "upgrade_failed";
+		else if (message === "No WebSocket in upgrade response") kind = "upgrade_failed";
+		else if (message === "RPC session was shut down by disposing the main stub" || message === "RPC was canceled because the RpcPromise was disposed.") kind = "session_disposed";
+	}
+	const context = {
+		kind,
+		originalMessage: message,
+		errorName,
+		...closeCode !== void 0 ? { closeCode } : {},
+		...closeReason !== void 0 ? { closeReason } : {}
+	};
+	return {
+		code: ErrorCode.RPC_TRANSPORT_ERROR,
+		message,
+		context,
+		httpStatus: getHttpStatus(ErrorCode.RPC_TRANSPORT_ERROR),
+		suggestion: getSuggestion(ErrorCode.RPC_TRANSPORT_ERROR, context),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
 }
 /**
 * Wrap a capnweb RPC stub so that every method call translates errors
@@ -2944,7 +3031,7 @@ function translateRPCError(error) {
 * activity at call start.
 *
 * `onCallStarted` fires synchronously when an RPC method is invoked. The
-* RPCSandboxClient uses this to renew the DO's activity timeout
+* ContainerControlClient uses this to renew the DO's activity timeout
 * immediately, so even a call that completes entirely between two
 * busy-poll ticks still pushes the sleepAfter deadline forward.
 *
@@ -2970,20 +3057,19 @@ function wrapStub(stub, onCallStarted) {
 	} });
 }
 /**
-* SandboxClient backed by direct capnweb RPC.
+* SandboxClient-compatible facade backed by direct capnweb RPC.
 *
-* Drop-in replacement for SandboxClient when the capnweb transport is active.
-* All operations call the container's SandboxRPCAPI directly over capnweb,
-* bypassing the HTTP handler/router layer entirely.
+* All operations call the container's SandboxAPI control interface directly
+* over capnweb, bypassing the HTTP handler/router layer entirely.
 *
-* Manages its own WebSocket lifecycle: a fresh `ContainerConnection` is
+* Manages its own WebSocket lifecycle: a fresh `ContainerControlConnection` is
 * created on demand and torn down after `idleDisconnectMs` of inactivity.
 * Busy/idle detection relies on `RpcSession.getStats()` which tracks all
 * in-flight RPC calls and stream exports — including long-lived streaming
 * RPCs that would be invisible to a simple per-call request counter (see
 * the file-level comment for the full rationale).
 */
-var RPCSandboxClient = class {
+var ContainerControlClient = class {
 	connOptions;
 	idleDisconnectMs;
 	busyPollIntervalMs;
@@ -3017,13 +3103,12 @@ var RPCSandboxClient = class {
 		this.onSessionIdle = options.onSessionIdle;
 	}
 	/**
-	* Return the current connection, creating a new one if none exists or the
-	* previous one was torn down by an idle disconnect. Starts the busy-poll
-	* timer the first time a connection is materialized.
+	* Return the current connection, creating one when the client is disconnected.
+	* Starts the busy-poll timer the first time a connection is materialized.
 	*/
 	getConnection() {
 		if (!this.conn) {
-			this.conn = new ContainerConnection(this.connOptions);
+			this.conn = new ContainerControlConnection(this.connOptions);
 			this.startBusyPoll();
 		}
 		return this.conn;
@@ -4111,7 +4196,7 @@ function isLocalhostPattern(hostname) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.9.1";
+const SDK_VERSION = "0.9.3";
 
 //#endregion
 //#region src/sandbox.ts
@@ -4122,6 +4207,63 @@ 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";
+const BACKUP_DEFAULT_COMPRESSION = "lz4";
+const BACKUP_DEFAULT_COMPRESS_THREADS = 8;
+const BACKUP_MULTIPART_MIN_SIZE = 10 * 1024 * 1024;
+const BACKUP_MULTIPART_TARGET_PARTS = 16;
+const BACKUP_MULTIPART_MIN_PART_SIZE = 5 * 1024 * 1024;
+const BACKUP_MULTIPART_MAX_PARTS = 64;
+const BACKUP_DOWNLOAD_PARALLEL_PARTS = 8;
+const BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE = 10 * 1024 * 1024;
+const BACKUP_DOWNLOAD_MAX_PARTS = 64;
+/**
+* Calculate the optimal number of parts for multipart upload/download
+* based on archive size. Larger archives benefit from more parallelism.
+*/
+function calculatePartCount(sizeBytes, defaultParts, maxParts) {
+	if (sizeBytes < 100 * 1024 * 1024) return defaultParts;
+	if (sizeBytes < 1024 * 1024 * 1024) return Math.min(32, defaultParts * 2);
+	return maxParts;
+}
+/**
+* Tagged template literal that shell-escapes every interpolated value.
+* Use for composing in-container scripts where the template body is
+* trusted shell and the interpolations are untrusted strings.
+*/
+function sh(strings, ...values) {
+	let out = strings[0];
+	for (let i = 0; i < values.length; i++) out += shellEscape(String(values[i])) + strings[i + 1];
+	return out;
+}
+/**
+* Hex string of `bytes` random bytes (length = bytes * 2). Used for short
+* non-cryptographic identifiers — e.g. tempfile suffixes.
+*/
+function randomHex(bytes) {
+	const buf = new Uint8Array(bytes);
+	crypto.getRandomValues(buf);
+	return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Parse an array of `key=value` / bare-flag s3fs options into a Record.
+* Bare flags become `{ flag: true }`. Later entries overwrite earlier ones.
+*/
+function parseS3fsOptions(entries) {
+	const result = {};
+	for (const entry of entries) {
+		const eq = entry.indexOf("=");
+		if (eq === -1) result[entry] = true;
+		else result[entry.slice(0, eq)] = entry.slice(eq + 1);
+	}
+	return result;
+}
+/**
+* Serialise an s3fs options Record into the comma-separated `-o` argument.
+* Boolean true emits the bare flag; false drops it.
+*/
+function serializeS3fsOptions(options) {
+	return Object.entries(options).filter(([, v]) => v !== false).map(([k, v]) => v === true ? k : `${k}=${v}`).join(",");
+}
 function getNamespaceConfigurationCache(namespace) {
 	const existing = sandboxConfigurationCache.get(namespace);
 	if (existing) return existing;
@@ -4357,7 +4499,8 @@ var Sandbox = class Sandbox extends Container {
 		return Math.max(12e4, startupBudgetMs + 3e4);
 	}
 	/**
-	* Create a SandboxClient with current transport settings
+	* Create the route-based compatibility client with current HTTP/WebSocket
+	* transport settings.
 	*/
 	createSandboxClient() {
 		return new SandboxClient({
@@ -4373,12 +4516,15 @@ var Sandbox = class Sandbox extends Container {
 		});
 	}
 	/**
-	* Create the appropriate client for a given transport protocol.
+	* Create the appropriate client for the configured control path.
+	*
+	* `rpc` currently selects the primary container-control client. `http` and
+	* `websocket` select the route-based compatibility client.
 	*/
 	createClientForTransport(transport) {
 		if (transport === "rpc") {
 			const self = this;
-			return new RPCSandboxClient({
+			return new ContainerControlClient({
 				stub: this,
 				port: 3e3,
 				logger: this.logger,
@@ -4663,6 +4809,7 @@ var Sandbox = class Sandbox extends Container {
 		let mountError;
 		let passwordFilePath;
 		let provider = null;
+		let dirExisted = true;
 		try {
 			this.validateMountOptions(bucket, mountPath, {
 				...options,
@@ -4694,6 +4841,7 @@ var Sandbox = class Sandbox extends Container {
 			};
 			this.activeMounts.set(mountPath, mountInfo);
 			await this.createPasswordFile(passwordFilePath, bucket, credentials);
+			dirExisted = (await this.execInternal(`test -d ${shellEscape(mountPath)}`)).exitCode === 0;
 			await this.execInternal(`mkdir -p ${shellEscape(mountPath)}`);
 			await this.executeS3FSMount(s3fsSource, mountPath, options, provider, passwordFilePath);
 			mountInfo.mounted = true;
@@ -4701,6 +4849,12 @@ var Sandbox = class Sandbox extends Container {
 		} catch (error) {
 			mountError = error instanceof Error ? error : new Error(String(error));
 			if (passwordFilePath) await this.deletePasswordFile(passwordFilePath);
+			try {
+				await this.execInternal(`mountpoint -q ${shellEscape(mountPath)} && fusermount -u ${shellEscape(mountPath)}`);
+			} catch {}
+			if (!dirExisted) try {
+				await this.execInternal(`rmdir ${shellEscape(mountPath)} 2>/dev/null`);
+			} catch {}
 			this.activeMounts.delete(mountPath);
 			throw error;
 		} finally {
@@ -4817,16 +4971,31 @@ var Sandbox = class Sandbox extends Container {
 	* Execute S3FS mount command
 	*/
 	async executeS3FSMount(bucket, mountPath, options, provider, passwordFilePath, sessionId) {
-		const resolvedOptions = resolveS3fsOptions(provider, options.s3fsOptions);
-		const s3fsArgs = [];
-		s3fsArgs.push(`passwd_file=${passwordFilePath}`);
-		s3fsArgs.push(...resolvedOptions);
-		if (options.readOnly) s3fsArgs.push("ro");
-		s3fsArgs.push(`url=${options.endpoint}`);
-		const optionsStr = shellEscape(s3fsArgs.join(","));
-		const mountCmd = `s3fs ${shellEscape(bucket)} ${shellEscape(mountPath)} -o ${optionsStr}`;
-		const result = sessionId ? await this.execWithSession(mountCmd, sessionId, { origin: "internal" }) : await this.execInternal(mountCmd);
-		if (result.exitCode !== 0) throw new S3FSMountError(`S3FS mount failed: ${result.stderr || result.stdout || "Unknown error"}`);
+		const s3fsOptions = {
+			logfile: `/tmp/.s3fs-log-${randomHex(4)}`,
+			...parseS3fsOptions(resolveS3fsOptions(provider)),
+			...parseS3fsOptions(options.s3fsOptions ?? []),
+			passwd_file: passwordFilePath,
+			url: options.endpoint,
+			...options.readOnly ? { ro: true } : {}
+		};
+		const logFile = s3fsOptions.logfile;
+		const script = sh`(
+      s3fs ${bucket} ${mountPath} -o ${serializeS3fsOptions(s3fsOptions)} >${logFile} 2>&1
+      rc=$?
+      if [ "$rc" -ne 0 ]; then tail -n 20 ${logFile} 2>/dev/null || true; exit 2; fi
+      for _ in $(seq 1 60); do
+        if mountpoint -q ${mountPath}; then exit 0; fi
+        sleep 0.1
+      done
+      tail -n 20 ${logFile} 2>/dev/null || true
+      exit 3
+    )`;
+		const result = await (sessionId ? (cmd) => this.execWithSession(cmd, sessionId, { origin: "internal" }) : (cmd) => this.execInternal(cmd))(script);
+		if (result.exitCode === 0) return;
+		const detail = result.stdout?.trim() || result.stderr?.trim() || "";
+		if (result.exitCode === 2) throw new S3FSMountError(`S3FS mount failed: ${detail || "Unknown error"}`);
+		throw new S3FSMountError(`S3FS mount failed: FUSE filesystem never appeared at ${mountPath}. ${detail ? `s3fs log: ${detail}` : "No s3fs log output captured. The s3fs daemon may have exited before writing logs."}`);
 	}
 	/**
 	* In-flight `destroy()` promise. While set, concurrent callers coalesce
@@ -6362,6 +6531,58 @@ var Sandbox = class Sandbox extends Container {
 		});
 		return this.backupBucket;
 	}
+	normalizeBackupExcludes(excludes) {
+		const normalizedExcludes = [];
+		for (const pattern of excludes) {
+			const normalized = normalizeBackupExcludePattern(pattern);
+			if (normalized === null) {
+				this.logger.warn("Exclude pattern reduced to empty after globstar normalization; skipping", { original: pattern });
+				continue;
+			}
+			if (normalized !== pattern) this.logger.warn("Exclude pattern contained ** (globstar) which mksquashfs does not support; normalized automatically", {
+				original: pattern,
+				normalized
+			});
+			normalizedExcludes.push(normalized);
+		}
+		return normalizedExcludes;
+	}
+	resolveBackupCompression(compression) {
+		if (compression !== void 0) {
+			if (typeof compression !== "object" || compression === null) throw new InvalidBackupConfigError({
+				message: "BackupOptions.compression must be an object",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "compression must be an object" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		const compressionOptions = compression;
+		const format = compressionOptions?.format ?? BACKUP_DEFAULT_COMPRESSION;
+		const threads = compressionOptions?.threads ?? BACKUP_DEFAULT_COMPRESS_THREADS;
+		if (typeof format !== "string" || ![
+			"gzip",
+			"lz4",
+			"zstd"
+		].includes(format)) throw new InvalidBackupConfigError({
+			message: "BackupOptions.compression.format must be one of: gzip, lz4, zstd",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "compression.format must be one of: gzip, lz4, zstd" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (typeof threads !== "number" || !Number.isInteger(threads) || threads < 1) throw new InvalidBackupConfigError({
+			message: "BackupOptions.compression.threads must be a positive integer",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "compression.threads must be a positive integer" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			format,
+			threads
+		};
+	}
 	static PRESIGNED_URL_EXPIRY_SECONDS = 3600;
 	/**
 	* Create a unique, dedicated session for a single backup operation.
@@ -6403,6 +6624,18 @@ 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.
 	*/
@@ -6462,51 +6695,248 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	/**
-	* Mount a backup archive from R2 via s3fs so squashfuse can read it lazily.
+	* Generate a presigned PUT URL for a single part in a multipart upload.
 	*/
-	async mountBackupR2(mountPath, prefix, backupSession) {
-		const { accountId, bucketName } = this.requirePresignedUrlSupport();
-		const endpoint = `https://${accountId}.r2.cloudflarestorage.com`;
-		const normalizedPrefix = prefix.startsWith("/") ? prefix : `/${prefix}`;
-		const options = {
-			endpoint,
-			provider: "r2",
-			readOnly: true,
-			prefix: normalizedPrefix,
-			s3fsOptions: ["use_path_request_style"]
-		};
-		const passwordFilePath = this.generatePasswordFilePath();
-		const s3fsSource = buildS3fsSource(bucketName, normalizedPrefix);
-		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
+	async generatePresignedPartUrl(r2Key, uploadId, partNumber) {
+		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));
+		url.searchParams.set("partNumber", String(partNumber));
+		url.searchParams.set("uploadId", uploadId);
+		return (await client.sign(new Request(url, { method: "PUT" }), { aws: { signQuery: true } })).url;
+	}
+	/**
+	* Upload a backup archive to R2 using parallel multipart upload.
+	* Uses the S3-compatible API exclusively for create/complete/abort so that
+	* the uploadId is in the same namespace as the presigned part PUT URLs.
+	*/
+	async uploadBackupMultipart(archivePath, r2Key, sizeBytes, backupId, dir, backupSession) {
+		const targetParts = calculatePartCount(sizeBytes, BACKUP_MULTIPART_TARGET_PARTS, BACKUP_MULTIPART_MAX_PARTS);
+		const numParts = Math.min(targetParts, Math.floor(sizeBytes / BACKUP_MULTIPART_MIN_PART_SIZE));
+		if (numParts <= 1) return this.uploadBackupPresigned(archivePath, r2Key, sizeBytes, backupId, dir, backupSession);
+		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
+		const objectUrl = `https://${accountId}.r2.cloudflarestorage.com/${encodeURIComponent(bucketName)}/${r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/")}`;
+		const createResp = await client.fetch(`${objectUrl}?uploads`, { method: "POST" });
+		if (!createResp.ok) throw new BackupCreateError({
+			message: `Failed to initiate multipart upload: HTTP ${createResp.status}`,
+			code: ErrorCode.BACKUP_CREATE_FAILED,
+			httpStatus: 500,
+			context: {
+				dir,
+				backupId
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const uploadId = (await createResp.text()).match(/<UploadId>([^<]+)<\/UploadId>/)?.[1];
+		if (!uploadId) throw new BackupCreateError({
+			message: "Multipart upload response did not contain an UploadId",
+			code: ErrorCode.BACKUP_CREATE_FAILED,
+			httpStatus: 500,
+			context: {
+				dir,
+				backupId
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		const mountInfo = {
-			mountType: "fuse",
-			bucket: s3fsSource,
-			mountPath,
-			endpoint,
-			provider: "r2",
-			passwordFilePath,
-			mounted: false
+		const abortMultipart = async () => {
+			await client.fetch(`${objectUrl}?uploadId=${encodeURIComponent(uploadId)}`, { method: "DELETE" }).catch(() => {});
 		};
-		this.activeMounts.set(mountPath, mountInfo);
 		try {
-			await this.createPasswordFile(passwordFilePath, bucketName, credentials);
-			await this.execWithSession(`mkdir -p ${shellEscape(mountPath)}`, backupSession, { origin: "internal" });
-			await this.executeS3FSMount(s3fsSource, mountPath, options, "r2", passwordFilePath, backupSession);
-			mountInfo.mounted = true;
+			const partSize = Math.ceil(sizeBytes / numParts);
+			const parts = await Promise.all(Array.from({ length: numParts }, (_, i) => ({
+				partNumber: i + 1,
+				url: "",
+				offset: i * partSize,
+				size: i === numParts - 1 ? sizeBytes - i * partSize : partSize
+			})).map(async (part) => ({
+				...part,
+				url: await this.generatePresignedPartUrl(r2Key, uploadId, part.partNumber)
+			})));
+			let uploadResult;
+			try {
+				uploadResult = await this.client.backup.uploadParts({
+					archivePath,
+					parts,
+					sessionId: backupSession
+				});
+			} catch (err) {
+				if (err instanceof SandboxError && err.errorResponse.httpStatus === 404) {
+					await abortMultipart();
+					return this.uploadBackupPresigned(archivePath, r2Key, sizeBytes, backupId, dir, backupSession);
+				}
+				throw err;
+			}
+			if (!uploadResult.success || uploadResult.parts.length !== numParts) throw new BackupCreateError({
+				message: `Multipart upload returned ${uploadResult.parts.length} of ${numParts} parts`,
+				code: ErrorCode.BACKUP_CREATE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const completeXml = [
+				"<CompleteMultipartUpload>",
+				...uploadResult.parts.map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${p.etag}</ETag></Part>`),
+				"</CompleteMultipartUpload>"
+			].join("");
+			const completeResp = await client.fetch(`${objectUrl}?uploadId=${encodeURIComponent(uploadId)}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/xml" },
+				body: completeXml
+			});
+			if (!completeResp.ok) {
+				const body = await completeResp.text().catch(() => "");
+				throw new BackupCreateError({
+					message: `Multipart upload completion failed: HTTP ${completeResp.status} ${body}`,
+					code: ErrorCode.BACKUP_CREATE_FAILED,
+					httpStatus: 500,
+					context: {
+						dir,
+						backupId
+					},
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			const head = await this.requireBackupBucket().head(r2Key);
+			if (!head || head.size !== sizeBytes) throw new BackupCreateError({
+				message: `Multipart upload verification failed: expected ${sizeBytes} bytes, got ${head?.size ?? 0}`,
+				code: ErrorCode.BACKUP_CREATE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
 		} catch (error) {
-			await this.deletePasswordFile(passwordFilePath);
-			this.activeMounts.delete(mountPath);
+			await abortMultipart();
 			throw error;
 		}
 	}
 	/**
+	* Download a backup archive from R2 via presigned GET URL.
+	* For archives >= BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE, uses BACKUP_DOWNLOAD_PARALLEL_PARTS
+	* concurrent curl processes (each downloading a byte-range) to maximise both
+	* network and disk-write throughput. Parts are written into a pre-sized file
+	* with dd using byte offsets, then atomically moved to the final path.
+	*/
+	async downloadBackupParallel(archivePath, r2Key, expectedSize, backupId, dir, backupSession) {
+		const presignedUrl = await this.generatePresignedGetUrl(r2Key);
+		await this.execWithSession(`mkdir -p ${BACKUP_CONTAINER_DIR}`, backupSession, { origin: "internal" });
+		const tmpPath = `${archivePath}.tmp`;
+		if (expectedSize < BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE) {
+			const curlCmd = [
+				"curl -sSf",
+				"--connect-timeout 10",
+				"--max-time 1800",
+				"--retry 2",
+				"--retry-max-time 60",
+				`-o ${shellEscape(tmpPath)}`,
+				shellEscape(presignedUrl)
+			].join(" ");
+			const result = await this.execWithSession(curlCmd, backupSession, {
+				timeout: 181e4,
+				origin: "internal"
+			});
+			if (result.exitCode !== 0) {
+				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,
+					httpStatus: 500,
+					context: {
+						dir,
+						backupId
+					},
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+		} else {
+			const numParts = calculatePartCount(expectedSize, BACKUP_DOWNLOAD_PARALLEL_PARTS, BACKUP_DOWNLOAD_MAX_PARTS);
+			const partSize = Math.floor(expectedSize / numParts);
+			const startLines = Array.from({ length: numParts }, (_, i) => {
+				const start = i * partSize;
+				return {
+					start,
+					range: `${start}-${i < numParts - 1 ? start + partSize - 1 : expectedSize - 1}`
+				};
+			}).map(({ start, range }) => [
+				"curl -sSf",
+				"--connect-timeout 10",
+				"--max-time 1800",
+				`-H ${shellEscape(`Range: bytes=${range}`)}`,
+				shellEscape(presignedUrl),
+				"|",
+				"dd",
+				`of=${shellEscape(tmpPath)}`,
+				"oflag=seek_bytes",
+				`seek=${start}`,
+				"conv=notrunc",
+				"2>/dev/null"
+			].join(" ")).map((cmd, i) => `(set -o pipefail; ${cmd}) & J${i}=$!`);
+			const waitLines = Array.from({ length: numParts }, (_, i) => `wait $J${i}; E${i}=$?`);
+			const exitVars = Array.from({ length: numParts }, (_, i) => `$E${i}`);
+			const script = [
+				`rm -f ${shellEscape(tmpPath)}`,
+				`truncate -s ${expectedSize} ${shellEscape(tmpPath)}`,
+				...startLines,
+				...waitLines,
+				`FAILED=$(( ${exitVars.join(" + ")} ))`,
+				`if [ "$FAILED" -ne 0 ]; then rm -f ${shellEscape(tmpPath)}; exit 1; fi`
+			].join("; ");
+			const result = await this.execWithSession(script, backupSession, {
+				timeout: 181e4,
+				origin: "internal"
+			});
+			if (result.exitCode !== 0) {
+				await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession, { origin: "internal" }).catch(() => {});
+				throw new BackupRestoreError({
+					message: `Parallel download failed (exit code ${result.exitCode}): ${result.stderr}`,
+					code: ErrorCode.BACKUP_RESTORE_FAILED,
+					httpStatus: 500,
+					context: {
+						dir,
+						backupId
+					},
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+		}
+		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, { origin: "internal" }).catch(() => {});
+			throw new BackupRestoreError({
+				message: `Downloaded archive size mismatch: expected ${expectedSize}, got ${actualSize}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		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, { origin: "internal" }).catch(() => {});
+			throw new BackupRestoreError({
+				message: `Failed to finalize downloaded archive: ${mvResult.stderr}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	}
+	/**
 	* Serialize backup operations on this sandbox instance.
 	* Concurrent backup/restore calls are queued so the multi-step
 	* create-archive → read → upload (or mount → extract) flow
@@ -6546,7 +6976,7 @@ var Sandbox = class Sandbox extends Container {
 	async doCreateBackup(options) {
 		const bucket = this.requireBackupBucket();
 		this.requirePresignedUrlSupport();
-		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
+		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [], compression, multipart = true } = options;
 		const backupStartTime = Date.now();
 		let backupId;
 		let sizeBytes;
@@ -6592,12 +7022,15 @@ var Sandbox = class Sandbox extends Container {
 				context: { reason: "excludes must be an array of strings" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
+			const resolvedCompression = this.resolveBackupCompression(compression);
+			const normalizedExcludes = this.normalizeBackupExcludes(excludes);
 			backupSession = await this.ensureBackupSession();
 			backupId = crypto.randomUUID();
 			const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
 			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, {
 				gitignore,
-				excludes
+				excludes: normalizedExcludes,
+				compression: resolvedCompression
 			});
 			if (!createResult.success) throw new BackupCreateError({
 				message: "Container failed to create backup archive",
@@ -6612,7 +7045,8 @@ var Sandbox = class Sandbox extends Container {
 			sizeBytes = createResult.sizeBytes;
 			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);
+			if (multipart && createResult.sizeBytes >= BACKUP_MULTIPART_MIN_SIZE) await this.uploadBackupMultipart(archivePath, r2Key, createResult.sizeBytes, backupId, dir, backupSession);
+			else await this.uploadBackupPresigned(archivePath, r2Key, createResult.sizeBytes, backupId, dir, backupSession);
 			const metadata = {
 				id: backupId,
 				dir,
@@ -6659,7 +7093,7 @@ var Sandbox = class Sandbox extends Container {
 	* Archive format is identical to production (squashfs + meta.json).
 	*/
 	async doCreateBackupLocal(options) {
-		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [] } = options;
+		const { dir, name, ttl = BACKUP_DEFAULT_TTL_SECONDS, gitignore = false, excludes = [], compression } = options;
 		const backupStartTime = Date.now();
 		let backupId;
 		let sizeBytes;
@@ -6713,12 +7147,15 @@ var Sandbox = class Sandbox extends Container {
 				context: { reason: "excludes must be an array of strings" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
+			const resolvedCompression = this.resolveBackupCompression(compression);
+			const normalizedExcludes = this.normalizeBackupExcludes(excludes);
 			backupSession = await this.ensureBackupSession();
 			backupId = crypto.randomUUID();
 			const archivePath = `${BACKUP_CONTAINER_DIR}/${backupId}.sqsh`;
 			const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession, {
 				gitignore,
-				excludes
+				excludes: normalizedExcludes,
+				compression: resolvedCompression
 			});
 			if (!createResult.success) throw new BackupCreateError({
 				message: "Container failed to create backup archive",
@@ -6884,7 +7321,8 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			const r2Key = `${BACKUP_STORAGE_PREFIX}/${id}/${BACKUP_ARCHIVE_OBJECT_NAME}`;
-			if (!await bucket.head(r2Key)) throw new BackupNotFoundError({
+			const archiveHead = await bucket.head(r2Key);
+			if (!archiveHead) 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,
@@ -6892,19 +7330,12 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			backupSession = await this.ensureBackupSession();
-			const r2MountPath = `${BACKUP_CONTAINER_DIR}/r2mount/${id}`;
-			const archivePath = `${r2MountPath}/data.sqsh`;
-			const mountGlob = `/var/backups/mounts/r2mount/${id}/data`;
+			const archivePath = `${BACKUP_CONTAINER_DIR}/${id}.sqsh`;
+			const mountGlob = `${BACKUP_CONTAINER_DIR}/mounts/${id}`;
 			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(() => {});
-			await this.execWithSession(`/usr/bin/fusermount3 -u ${shellEscape(r2MountPath)} 2>/dev/null; /usr/bin/fusermount3 -uz ${shellEscape(r2MountPath)} 2>/dev/null; true`, backupSession, { origin: "internal" }).catch(() => {});
-			const previousBackupMount = this.activeMounts.get(r2MountPath);
-			if (previousBackupMount?.mountType === "fuse") {
-				previousBackupMount.mounted = false;
-				this.activeMounts.delete(r2MountPath);
-				await this.deletePasswordFile(previousBackupMount.passwordFilePath);
-			}
-			await this.mountBackupR2(r2MountPath, `backups/${id}/`, backupSession);
+			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.downloadBackupParallel(archivePath, r2Key, archiveHead.size, id, dir, backupSession);
 			if (!(await this.client.backup.restoreArchive(dir, archivePath, backupSession)).success) throw new BackupRestoreError({
 				message: "Container failed to restore backup archive",
 				code: ErrorCode.BACKUP_RESTORE_FAILED,
@@ -6923,6 +7354,10 @@ var Sandbox = class Sandbox extends Container {
 			};
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
+			if (id && backupSession) {
+				const cleanupPath = `${BACKUP_CONTAINER_DIR}/${id}.sqsh`;
+				await this.execWithSession(`rm -f ${shellEscape(cleanupPath)}`, backupSession, { origin: "internal" }).catch(() => {});
+			}
 			throw error;
 		} finally {
 			if (backupSession) await this.client.utils.deleteSession(backupSession).catch(() => {});
@@ -7070,5 +7505,5 @@ var Sandbox = class Sandbox extends Container {
 };
 
 //#endregion
-export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, SessionTerminatedError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y };
-//# sourceMappingURL=sandbox-PAYx1CcU.js.map
+export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, RPCTransportError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y, SessionTerminatedError as z };
+//# sourceMappingURL=sandbox-BAuU-2a0.js.map