@cloudflare/sandbox 0.12.1 → 0.12.3

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

@@ -1,5 +1,5 @@
 import { _ as GitLogger, b as getEnvString, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as DEFAULT_GIT_CLONE_TIMEOUT_MS, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, p as logCanonicalEvent, r as isWSResponse, t as generateRequestId, u as createLogger, v as extractRepoName, x as partitionEnvVars, y as filterEnvVars } from "./dist-B_eXrP83.js";
-import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-aRUdk9K8.js";
+import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-CpkKPbWC.js";
 import { Container, ContainerProxy, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import { RpcSession, RpcTarget } from "capnweb";
@@ -630,6 +630,26 @@ var BackupRestoreError = class extends SandboxError {
 	}
 };
 /**
+* Raised when the sandbox container cannot accept an incoming RPC connection.
+* The container may be starting up, temporarily unhealthy, or was replaced
+* while the connection attempt was in progress.
+*
+* Always retryable: the operation that triggered the connection attempt can
+* be retried once the container is ready.
+*/
+var ContainerUnavailableError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ContainerUnavailableError";
+	}
+	get reason() {
+		return this.context.reason;
+	}
+	get retryAfterMs() {
+		return this.context.retryAfterMs;
+	}
+};
+/**
 * 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
@@ -653,6 +673,20 @@ var RPCTransportError = class extends SandboxError {
 		return this.errorResponse.context.originalMessage;
 	}
 };
+/**
+* Raised when a sandbox-owned operation was interrupted by a runtime
+* replacement or sandbox lifetime change after the operation was admitted.
+* The caller can retry the full operation when `context.retryable` is true.
+*/
+var OperationInterruptedError = class extends SandboxError {
+	constructor(errorResponse, options) {
+		super(errorResponse, options);
+		this.name = "OperationInterruptedError";
+	}
+	get reason() {
+		return this.context.reason;
+	}
+};
 
 //#endregion
 //#region src/errors/adapter.ts
@@ -710,6 +744,8 @@ function createErrorFromResponse(errorResponse, options) {
 		case ErrorCode.INTERPRETER_NOT_READY: return new InterpreterNotReadyError(errorResponse);
 		case ErrorCode.CONTEXT_NOT_FOUND: return new ContextNotFoundError(errorResponse);
 		case ErrorCode.CODE_EXECUTION_ERROR: return new CodeExecutionError(errorResponse);
+		case ErrorCode.OPERATION_INTERRUPTED: return new OperationInterruptedError(errorResponse, options);
+		case ErrorCode.CONTAINER_UNAVAILABLE: return new ContainerUnavailableError(errorResponse);
 		case ErrorCode.RPC_TRANSPORT_ERROR: return new RPCTransportError(errorResponse, options);
 		case ErrorCode.VALIDATION_FAILED: return new ValidationFailedError(errorResponse);
 		case ErrorCode.INVALID_JSON_RESPONSE:
@@ -2451,6 +2487,52 @@ function createTunnelsNotImplemented() {
 	} });
 }
 
+//#endregion
+//#region src/platform-errors.ts
+const SUPERSEDED_ISOLATE_PATTERN = /reset because its code was updated|this script has been upgraded/i;
+const CONNECTION_LOST_PATTERN = /network connection lost/i;
+const DO_STORAGE_STARTUP_RESET_PATTERN = /internal error while starting up durable object storage caused object to be reset/i;
+function errorMessageOf(error) {
+	return error instanceof Error ? error.message : typeof error === "string" ? error : "";
+}
+function* selfAndCauses(error) {
+	let current = error;
+	for (let depth = 0; depth < 8 && current != null; depth += 1) {
+		yield current;
+		current = typeof current === "object" ? current.cause : void 0;
+	}
+}
+function isErrorRetryable(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const message = String(error);
+	const typed = error;
+	return typed.retryable === true && typed.overloaded !== true && !message.includes("Durable Object is overloaded");
+}
+/**
+* Whether an error was raised because the current Durable Object isolate was
+* superseded by a deploy/code update. In-process retries are futile for this
+* class because the invocation keeps running on the old isolate; callers
+* should return control to the platform or retry from a fresh request.
+*/
+function isDurableObjectCodeUpdateReset(error) {
+	for (const candidate of selfAndCauses(error)) if (SUPERSEDED_ISOLATE_PATTERN.test(errorMessageOf(candidate))) return true;
+	return false;
+}
+/**
+* Whether an error represents a transient platform lifecycle/storage failure,
+* not an application-level sandbox failure.
+*/
+function isPlatformTransientError(error) {
+	for (const candidate of selfAndCauses(error)) {
+		const message = errorMessageOf(candidate);
+		if (SUPERSEDED_ISOLATE_PATTERN.test(message)) return true;
+		if (CONNECTION_LOST_PATTERN.test(message)) return true;
+		if (DO_STORAGE_STARTUP_RESET_PATTERN.test(message)) return true;
+		if (isErrorRetryable(candidate)) return true;
+	}
+	return false;
+}
+
 //#endregion
 //#region ../shared/src/backup.ts
 /**
@@ -2476,8 +2558,484 @@ function normalizeBackupExcludePattern(pattern) {
 //#region ../shared/src/internal.ts
 const DISABLE_SESSION_TOKEN = "__DISABLE_SESSION__";
 
+//#endregion
+//#region src/current-runtime-identity.ts
+const CURRENT_RUNTIME_IDENTITY_STORAGE_KEY = "currentRuntimeIdentity";
+var RuntimeIdentityInactiveError = class extends Error {
+	constructor() {
+		super("Runtime identity is no longer active");
+		this.name = "RuntimeIdentityInactiveError";
+	}
+};
+var RuntimeIdentity = class {
+	id;
+	constructor(record) {
+		this.id = record.id;
+	}
+	owns(record) {
+		return record.runtimeIdentityID === this.id;
+	}
+	scope(value) {
+		return {
+			...value,
+			runtimeIdentityID: this.id
+		};
+	}
+};
+var CurrentRuntimeIdentity = class {
+	/**
+	* Runtime identity is stored in Durable Object storage so a reconstructed DO
+	* can still recognize the live container runtime it owns. In-memory state is
+	* only a cache and cannot define runtime-scoped correctness.
+	*/
+	constructor(storage, getContainerState, isContainerRunning) {
+		this.storage = storage;
+		this.getContainerState = getContainerState;
+		this.isContainerRunning = isContainerRunning;
+	}
+	async get() {
+		const status = await this.getStatus();
+		return status.status === "active" ? status.runtime : null;
+	}
+	async getStatus() {
+		const state = await this.getContainerState();
+		if (state.status !== "healthy") return {
+			status: "inactive",
+			reason: "runtime-not-healthy",
+			containerStatus: state.status
+		};
+		if (!this.isContainerRunning()) return {
+			status: "inactive",
+			reason: "runtime-not-running",
+			containerStatus: state.status
+		};
+		const runtime = await this.getStored();
+		if (!runtime) return {
+			status: "inactive",
+			reason: "missing-runtime-id",
+			containerStatus: state.status
+		};
+		return {
+			status: "active",
+			runtime,
+			containerStatus: state.status
+		};
+	}
+	async getStored(storage = this.storage) {
+		const record = await storage.get(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY) ?? null;
+		return record ? new RuntimeIdentity(record) : null;
+	}
+	async markStarted() {
+		const record = { id: crypto.randomUUID() };
+		await this.storage.put(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY, record);
+		return new RuntimeIdentity(record);
+	}
+	async clear() {
+		await this.storage.delete(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY);
+	}
+	async isActive(runtime) {
+		return (await this.get())?.id === runtime.id;
+	}
+	async assertActive(runtime) {
+		if (!await this.isActive(runtime)) throw new RuntimeIdentityInactiveError();
+	}
+};
+
+//#endregion
+//#region src/sandbox-lifetime.ts
+const SANDBOX_LIFETIME_STORAGE_KEY = "sandbox:lifetime";
+var SandboxLifetimeChangedError = class extends Error {
+	constructor() {
+		super("Sandbox lifetime is no longer current");
+		this.name = "SandboxLifetimeChangedError";
+	}
+};
+var SandboxLifetime = class {
+	id;
+	generation;
+	createdAt;
+	updatedAt;
+	constructor(record) {
+		this.record = record;
+		this.id = record.id;
+		this.generation = record.generation;
+		this.createdAt = record.createdAt;
+		this.updatedAt = record.updatedAt;
+	}
+	owns(record) {
+		return record.sandboxLifetimeID === this.id;
+	}
+	scope(value) {
+		return {
+			...value,
+			sandboxLifetimeID: this.id
+		};
+	}
+};
+var CurrentSandboxLifetime = class {
+	constructor(storage) {
+		this.storage = storage;
+	}
+	async get() {
+		const record = await this.storage.get(SANDBOX_LIFETIME_STORAGE_KEY) ?? null;
+		return record ? new SandboxLifetime(record) : null;
+	}
+	/**
+	* Returns the current lifetime if one exists, or creates and persists a new
+	* one. The id is stable for the lifetime of the sandbox — it only changes
+	* when `rotate()` is called (on `destroy()`).
+	*/
+	async getOrCreate() {
+		const existing = await this.get();
+		if (existing) return existing;
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const record = {
+			id: crypto.randomUUID(),
+			generation: 1,
+			createdAt: now,
+			updatedAt: now
+		};
+		await this.storage.put(SANDBOX_LIFETIME_STORAGE_KEY, record);
+		return new SandboxLifetime(record);
+	}
+	/**
+	* Creates and persists a new lifetime id, incrementing the generation
+	* counter. Called during `sandbox.destroy()` before runtime state is
+	* cleared so in-flight operations can detect the lifetime change.
+	*/
+	async rotate() {
+		const existing = await this.get();
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const record = {
+			id: crypto.randomUUID(),
+			generation: (existing?.generation ?? 0) + 1,
+			createdAt: now,
+			updatedAt: now
+		};
+		await this.storage.put(SANDBOX_LIFETIME_STORAGE_KEY, record);
+		return new SandboxLifetime(record);
+	}
+	async isCurrent(lifetime) {
+		return (await this.get())?.id === lifetime.id;
+	}
+	/**
+	* Throws `SandboxLifetimeChangedError` if the given lifetime is no longer
+	* the current one. Used by operation runners to abort operations that
+	* started before a `destroy()` call.
+	*/
+	async assertCurrent(lifetime) {
+		if (!await this.isCurrent(lifetime)) throw new SandboxLifetimeChangedError();
+	}
+};
+
+//#endregion
+//#region src/backup/restore-operation-store.ts
+const OPERATION_STORAGE_PREFIX = "operations:";
+function backupRestoreOperationKey(backupId, dir) {
+	return `restore:${backupId}:${dir}`;
+}
+function createBackupRestoreOperationRecord(params) {
+	return {
+		operationKey: backupRestoreOperationKey(params.backupId, params.dir),
+		kind: "backup.restore",
+		sandboxLifetimeID: params.sandboxLifetimeID,
+		phase: "validating",
+		status: "running",
+		payload: {
+			backupId: params.backupId,
+			dir: params.dir
+		},
+		createdAt: params.now,
+		updatedAt: params.now
+	};
+}
+var BackupRestoreOperationStore = class {
+	constructor(storage) {
+		this.storage = storage;
+	}
+	async get(operationKey) {
+		return await this.storage.get(this.storageKey(operationKey)) ?? null;
+	}
+	async put(record) {
+		await this.storage.put(this.storageKey(record.operationKey), record);
+	}
+	storageKey(operationKey) {
+		return `${OPERATION_STORAGE_PREFIX}${operationKey}`;
+	}
+};
+
+//#endregion
+//#region src/backup/restore-lifecycle.ts
+const BACKUP_RESTORE_MAX_RECOVERY_ATTEMPTS = 2;
+var RestoreLifecycleRunner = class {
+	operationRecords;
+	constructor(deps) {
+		this.deps = deps;
+		this.operationRecords = new BackupRestoreOperationStore(deps.storage);
+	}
+	async execute(params) {
+		return await this.runWithRecovery(async () => {
+			const { lifetime, operation } = await this.startOperation(params.backupId, params.dir);
+			let currentOperation = operation;
+			let runtime;
+			const context = {
+				lifetime,
+				runtimeReady: async () => {
+					try {
+						runtime = await this.captureRuntime();
+						await this.deps.currentLifetime.assertCurrent(lifetime);
+					} catch (error) {
+						throw await this.translateFenceError(error, currentOperation, "validating", "unknown") ?? error;
+					}
+					currentOperation = await this.markRuntimeReady(currentOperation, runtime);
+					return {
+						runtime,
+						operation: currentOperation
+					};
+				},
+				archiveReady: async (archiveSize) => {
+					if (!runtime) throw new Error("Backup restore archiveReady requires runtimeReady()");
+					try {
+						await this.assertFences(runtime, lifetime);
+					} catch (error) {
+						throw await this.translateFenceError(error, currentOperation, currentOperation.phase, true) ?? error;
+					}
+					currentOperation = await this.markArchiveReady(currentOperation, runtime, archiveSize);
+					return {
+						runtime,
+						operation: currentOperation
+					};
+				},
+				verify: async (result) => {
+					if (!runtime) throw new Error("Backup restore verification requires runtimeReady()");
+					try {
+						await this.assertFences(runtime, lifetime);
+					} catch (error) {
+						throw await this.translateFenceError(error, currentOperation, "archive_ready", true) ?? error;
+					}
+					currentOperation = await this.markVerified(currentOperation, runtime, result);
+					return currentOperation;
+				}
+			};
+			try {
+				return await params.attempt(context);
+			} catch (error) {
+				const translatedRPC = await this.translateRPCError(error, currentOperation);
+				if (translatedRPC) throw translatedRPC;
+				const translatedFence = await this.translateFenceError(error, currentOperation, currentOperation.phase, "unknown");
+				if (translatedFence) throw translatedFence;
+				if (!(error instanceof OperationInterruptedError)) await this.markFailed(currentOperation, error);
+				throw error;
+			}
+		});
+	}
+	async runWithRecovery(attempt) {
+		let recoveryAttempts = 0;
+		while (true) try {
+			return await attempt();
+		} catch (error) {
+			if (!(error instanceof OperationInterruptedError)) throw error;
+			if (!error.context.retryable) throw error;
+			if (recoveryAttempts >= BACKUP_RESTORE_MAX_RECOVERY_ATTEMPTS) throw this.createRecoveryExhaustedError(error, recoveryAttempts);
+			recoveryAttempts++;
+		}
+	}
+	async startOperation(backupId, dir) {
+		const lifetime = await this.deps.currentLifetime.getOrCreate();
+		const operation = createBackupRestoreOperationRecord({
+			sandboxLifetimeID: lifetime.id,
+			backupId,
+			dir,
+			now: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		await this.operationRecords.put(operation);
+		return {
+			lifetime,
+			operation
+		};
+	}
+	async captureRuntime() {
+		const runtime = await this.deps.currentRuntime.get() ?? await this.deps.currentRuntime.markStarted();
+		await this.deps.currentRuntime.assertActive(runtime);
+		return runtime;
+	}
+	async assertFences(runtime, lifetime) {
+		await this.deps.currentRuntime.assertActive(runtime);
+		await this.deps.currentLifetime.assertCurrent(lifetime);
+	}
+	async markRuntimeReady(operation, runtime) {
+		const next = {
+			...operation,
+			phase: "runtime_ready",
+			runtimeIdentityID: runtime.id,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await this.operationRecords.put(next);
+		return next;
+	}
+	async markArchiveReady(operation, runtime, archiveSize) {
+		const next = {
+			...operation,
+			phase: "archive_ready",
+			runtimeIdentityID: runtime.id,
+			payload: {
+				...operation.payload,
+				...archiveSize !== void 0 && { archiveSize }
+			},
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await this.operationRecords.put(next);
+		return next;
+	}
+	async markVerified(operation, runtime, result) {
+		const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const next = {
+			...operation,
+			phase: "verified",
+			status: "committed",
+			runtimeIdentityID: runtime.id,
+			result,
+			completedAt,
+			updatedAt: completedAt
+		};
+		await this.operationRecords.put(next);
+		return next;
+	}
+	async markFailed(operation, error) {
+		const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const message = error instanceof Error ? error.message : String(error);
+		const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : "UNKNOWN";
+		const next = {
+			...operation,
+			phase: "failed",
+			status: "failed",
+			error: {
+				code,
+				message,
+				retryable: false
+			},
+			completedAt,
+			updatedAt: completedAt
+		};
+		await this.operationRecords.put(next);
+		return next;
+	}
+	async markInterrupted(operation, message, retryable) {
+		const next = {
+			...operation,
+			phase: "interrupted",
+			status: "interrupted",
+			error: {
+				code: ErrorCode.OPERATION_INTERRUPTED,
+				message,
+				retryable
+			},
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await this.operationRecords.put(next);
+		return next;
+	}
+	async translateFenceError(error, operation, phase, admitted) {
+		if (!(error instanceof RuntimeIdentityInactiveError || error instanceof SandboxLifetimeChangedError)) return null;
+		const reason = error instanceof RuntimeIdentityInactiveError ? "runtime_replaced" : "sandbox_lifetime_changed";
+		const retryable = reason !== "sandbox_lifetime_changed";
+		const message = "Backup restore was interrupted before completion could be verified";
+		const interrupted = await this.markInterrupted(operation, message, retryable);
+		return this.createInterruptedError({
+			reason,
+			phase,
+			admitted,
+			retryable,
+			message,
+			operation: interrupted
+		});
+	}
+	async translateRPCError(error, operation) {
+		if (!(error instanceof RPCTransportError)) return null;
+		const message = "Backup restore was interrupted before completion could be verified";
+		const interruptedPhase = operation.phase;
+		const interrupted = await this.markInterrupted(operation, message, true);
+		return this.createInterruptedError({
+			reason: "transport_disposed",
+			phase: interruptedPhase,
+			admitted: "unknown",
+			retryable: true,
+			message,
+			operation: interrupted
+		});
+	}
+	createInterruptedError(params) {
+		return new OperationInterruptedError({
+			message: params.message,
+			code: ErrorCode.OPERATION_INTERRUPTED,
+			httpStatus: 409,
+			context: {
+				reason: params.reason,
+				operation: "backup.restore",
+				phase: params.phase,
+				admitted: params.admitted,
+				retryable: params.retryable
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			suggestion: this.suggestionFor(params.retryable)
+		});
+	}
+	createRecoveryExhaustedError(error, recoveryAttempts) {
+		return new OperationInterruptedError({
+			message: "Backup restore recovery attempts were exhausted",
+			code: ErrorCode.OPERATION_INTERRUPTED,
+			httpStatus: 409,
+			context: {
+				reason: "recovery_exhausted",
+				operation: error.context.operation,
+				phase: "interrupted",
+				admitted: error.context.admitted,
+				retryable: false,
+				recoveryAttempts,
+				maxRecoveryAttempts: BACKUP_RESTORE_MAX_RECOVERY_ATTEMPTS
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			suggestion: this.suggestionFor(false)
+		});
+	}
+	suggestionFor(retryable) {
+		return retryable ? "Retry restoreBackup() with the same backup handle so the SDK can reconcile the restore operation." : "Start a new restoreBackup() call only if restoring this backup is still desired for the current sandbox.";
+	}
+};
+
 //#endregion
 //#region src/container-control/connection.ts
+/**
+* Attempt to parse a structured CONTAINER_UNAVAILABLE JSON body from a
+* non-101 upgrade response. Returns a typed ContainerUnavailableError when
+* the body contains a recognized code, or null if the response is not
+* JSON / not a container availability error.
+*
+* The response body is consumed only once via `clone()` so the caller still
+* holds the original Response.
+*/
+async function tryParseContainerUnavailable(response) {
+	if (!(response.headers.get("content-type") ?? "").includes("application/json")) return null;
+	try {
+		const body = await response.clone().json();
+		if (body.code !== ErrorCode.CONTAINER_UNAVAILABLE) return null;
+		const context = {
+			reason: body.context?.reason === "container_starting" || body.context?.reason === "container_unhealthy" || body.context?.reason === "container_replaced" || body.context?.reason === "rpc_upgrade_failed" ? body.context.reason : "container_replaced",
+			retryable: true,
+			...typeof body.context?.retryAfterMs === "number" && { retryAfterMs: body.context.retryAfterMs }
+		};
+		return createErrorFromResponse({
+			code: ErrorCode.CONTAINER_UNAVAILABLE,
+			message: body.message ?? "Container is unavailable",
+			context,
+			httpStatus: getHttpStatus(ErrorCode.CONTAINER_UNAVAILABLE),
+			suggestion: getSuggestion(ErrorCode.CONTAINER_UNAVAILABLE, context),
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	} catch {
+		return null;
+	}
+}
 const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 const DEFAULT_RETRY_TIMEOUT_MS = 12e4;
 const MIN_TIME_FOR_RETRY_MS = 15e3;
@@ -2604,7 +3162,22 @@ var ContainerControlConnection = class {
 	async doConnect() {
 		try {
 			const response = await this.fetchUpgradeWithRetry();
-			if (response.status !== 101) throw new Error(`WebSocket upgrade failed: ${response.status} ${response.statusText}`);
+			if (response.status !== 101) {
+				const structured = await tryParseContainerUnavailable(response);
+				if (structured) throw structured;
+				if (isRetryableWebSocketUpgradeResponse(response)) throw createErrorFromResponse({
+					code: ErrorCode.CONTAINER_UNAVAILABLE,
+					message: `Container was unavailable after exhausting upgrade retry budget (status ${response.status})`,
+					context: {
+						reason: "rpc_upgrade_failed",
+						retryable: true
+					},
+					httpStatus: getHttpStatus(ErrorCode.CONTAINER_UNAVAILABLE),
+					suggestion: getSuggestion(ErrorCode.CONTAINER_UNAVAILABLE, {}),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				});
+				throw new Error(`WebSocket upgrade failed: ${response.status} ${response.statusText}`);
+			}
 			const ws = response.webSocket;
 			if (!ws) throw new Error("No WebSocket in upgrade response");
 			ws.accept();
@@ -2617,6 +3190,7 @@ var ContainerControlConnection = class {
 		} catch (error) {
 			this.connected = false;
 			this.transport.abort(error);
+			this.fireOnClose();
 			this.logger.error("ContainerControlConnection failed", error instanceof Error ? error : new Error(String(error)));
 			throw error;
 		}
@@ -2749,32 +3323,17 @@ const BUSY_POLL_INTERVAL_MS = 1e3;
 */
 const IDLE_IMPORT_THRESHOLD = 1;
 const IDLE_EXPORT_THRESHOLD = 1;
-/**
-* Translate a capnweb-propagated error into a typed SandboxError.
-*
-* Two wire formats are supported for backward compatibility with older
-* container images:
-*
-*  1. Propagated error properties (capnweb >= 0.8.0). The container throws a
-*     `ServiceError`-shaped object with own enumerable `code` and `details`
-*     properties. capnweb walks `Object.keys()` and reconstructs those fields
-*     on the SDK side.
-*  2. Legacy JSON-encoded message. Older containers encoded the structured
-*     payload as a JSON string in `error.message`.
-*
-* The JSON-fallback branch can be removed once all older container images are
-* no longer in service.
-*/
-function translateRPCError(error) {
+function translateRPCError(error, context = {}) {
+	if (error instanceof SandboxError) throw error;
 	if (error instanceof Error) {
 		const propagated = error;
 		if (typeof propagated.code === "string" && Object.hasOwn(ErrorCode, propagated.code)) {
 			const code = propagated.code;
-			const context = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
+			const context$1 = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
 			throw createErrorFromResponse({
 				code,
 				message: error.message,
-				context,
+				context: context$1,
 				httpStatus: getHttpStatus(code),
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
@@ -2790,7 +3349,8 @@ function translateRPCError(error) {
 			httpStatus: getHttpStatus(payload.code),
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		throw createErrorFromResponse(buildTransportErrorResponse(error), { cause: error });
+		const transportResponse = buildTransportErrorResponse(error);
+		throw createErrorFromResponse(buildInterruptedOperationResponse(transportResponse, context) ?? transportResponse, { cause: error });
 	}
 	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
 }
@@ -2838,6 +3398,27 @@ function buildTransportErrorResponse(error) {
 		timestamp: (/* @__PURE__ */ new Date()).toISOString()
 	};
 }
+function buildInterruptedOperationResponse(transportResponse, context) {
+	if (!context.operation) return null;
+	const { kind } = transportResponse.context;
+	if (kind !== "session_disposed" && kind !== "peer_closed" && kind !== "connection_failed") return null;
+	const interruptedContext = {
+		reason: kind === "session_disposed" ? "transport_disposed" : "runtime_replaced",
+		operation: context.operation,
+		phase: "rpc_call",
+		admitted: "unknown",
+		retryable: false
+	};
+	const action = kind === "session_disposed" ? "was closing" : "closed unexpectedly";
+	return {
+		code: ErrorCode.OPERATION_INTERRUPTED,
+		message: `Sandbox operation ${context.operation} was interrupted while the runtime connection ${action}`,
+		context: interruptedContext,
+		httpStatus: getHttpStatus(ErrorCode.OPERATION_INTERRUPTED),
+		suggestion: getSuggestion(ErrorCode.OPERATION_INTERRUPTED, interruptedContext),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
 /**
 * Wrap a capnweb RPC stub so that every method call translates errors
 * from the JSON wire format into typed SandboxError instances and signals
@@ -2853,18 +3434,19 @@ function buildTransportErrorResponse(error) {
 * settles — capnweb keeps the export alive until the stream ends. The
 * busy/idle poll on `getStats()` is the source of truth for that.
 */
-function wrapStub(stub, onCallStarted) {
+function wrapStub(stub, domain, onCallStarted) {
 	return new Proxy(stub, { get(target, prop, receiver) {
 		const value = Reflect.get(target, prop, receiver);
 		if (typeof value !== "function") return value;
 		return (...args) => {
 			onCallStarted();
+			const operation = typeof prop === "string" ? `${domain}.${prop}` : domain;
 			try {
 				const result = Reflect.apply(value, target, args);
-				if (result != null && typeof result.then === "function") return result.catch(translateRPCError);
+				if (result != null && typeof result.then === "function") return result.catch((err) => translateRPCError(err, { operation }));
 				return result;
 			} catch (err) {
-				translateRPCError(err);
+				translateRPCError(err, { operation });
 			}
 		};
 	} });
@@ -3003,34 +3585,34 @@ var ContainerControlClient = class {
 		}
 	}
 	get commands() {
-		return wrapStub(this.getConnection().rpc().commands, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().commands, "commands", this.renewActivity);
 	}
 	get files() {
-		return wrapStub(this.getConnection().rpc().files, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().files, "files", this.renewActivity);
 	}
 	get processes() {
-		return wrapStub(this.getConnection().rpc().processes, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().processes, "processes", this.renewActivity);
 	}
 	get ports() {
-		return wrapStub(this.getConnection().rpc().ports, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().ports, "ports", this.renewActivity);
 	}
 	get git() {
-		return wrapStub(this.getConnection().rpc().git, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().git, "git", this.renewActivity);
 	}
 	get utils() {
-		return wrapStub(this.getConnection().rpc().utils, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().utils, "utils", this.renewActivity);
 	}
 	get backup() {
-		return wrapStub(this.getConnection().rpc().backup, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().backup, "backup", this.renewActivity);
 	}
 	get watch() {
-		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().watch, "watch", this.renewActivity);
 	}
 	get tunnels() {
-		return wrapStub(this.getConnection().rpc().tunnels, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().tunnels, "tunnels", this.renewActivity);
 	}
 	get interpreter() {
-		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
+		return wrapStub(this.getConnection().rpc().interpreter, "interpreter", this.renewActivity);
 	}
 	/**
 	* Update the upgrade retry budget. Applies to the current connection
@@ -3055,89 +3637,6 @@ var ContainerControlClient = class {
 	}
 };
 
-//#endregion
-//#region src/current-runtime-identity.ts
-const CURRENT_RUNTIME_IDENTITY_STORAGE_KEY = "currentRuntimeIdentity";
-var RuntimeIdentityInactiveError = class extends Error {
-	constructor() {
-		super("Runtime identity is no longer active");
-		this.name = "RuntimeIdentityInactiveError";
-	}
-};
-var RuntimeIdentity = class {
-	id;
-	constructor(record) {
-		this.id = record.id;
-	}
-	owns(record) {
-		return record.runtimeIdentityID === this.id;
-	}
-	scope(value) {
-		return {
-			...value,
-			runtimeIdentityID: this.id
-		};
-	}
-};
-var CurrentRuntimeIdentity = class {
-	/**
-	* Runtime identity is stored in Durable Object storage so a reconstructed DO
-	* can still recognize the live container runtime it owns. In-memory state is
-	* only a cache and cannot define runtime-scoped correctness.
-	*/
-	constructor(storage, getContainerState, isContainerRunning) {
-		this.storage = storage;
-		this.getContainerState = getContainerState;
-		this.isContainerRunning = isContainerRunning;
-	}
-	async get() {
-		const status = await this.getStatus();
-		return status.status === "active" ? status.runtime : null;
-	}
-	async getStatus() {
-		const state = await this.getContainerState();
-		if (state.status !== "healthy") return {
-			status: "inactive",
-			reason: "runtime-not-healthy",
-			containerStatus: state.status
-		};
-		if (!this.isContainerRunning()) return {
-			status: "inactive",
-			reason: "runtime-not-running",
-			containerStatus: state.status
-		};
-		const runtime = await this.getStored();
-		if (!runtime) return {
-			status: "inactive",
-			reason: "missing-runtime-id",
-			containerStatus: state.status
-		};
-		return {
-			status: "active",
-			runtime,
-			containerStatus: state.status
-		};
-	}
-	async getStored(storage = this.storage) {
-		const record = await storage.get(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY) ?? null;
-		return record ? new RuntimeIdentity(record) : null;
-	}
-	async markStarted() {
-		const record = { id: crypto.randomUUID() };
-		await this.storage.put(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY, record);
-		return new RuntimeIdentity(record);
-	}
-	async clear() {
-		await this.storage.delete(CURRENT_RUNTIME_IDENTITY_STORAGE_KEY);
-	}
-	async isActive(runtime) {
-		return (await this.get())?.id === runtime.id;
-	}
-	async assertActive(runtime) {
-		if (!await this.isActive(runtime)) throw new RuntimeIdentityInactiveError();
-	}
-};
-
 //#endregion
 //#region src/file-stream.ts
 /**
@@ -4143,6 +4642,18 @@ async function proxyTerminal(stub, sessionId, request, options) {
 	return stub.fetch(switchPort(ptyRequest, 3e3));
 }
 
+//#endregion
+//#region src/session-init.ts
+var SessionInitInvalidatedError = class extends Error {
+	constructor() {
+		super("Default session initialization was invalidated by a container stop");
+		this.name = "SessionInitInvalidatedError";
+	}
+};
+function isSessionInitInvalidated(error) {
+	return error instanceof SessionInitInvalidatedError;
+}
+
 //#endregion
 //#region src/storage-mount/r2-egress-handler.ts
 const XML_NS = "xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"";
@@ -5058,17 +5569,18 @@ var SandboxControlCallbackImpl = class extends RpcTarget {
 		this.getHandler = getHandler;
 		this.logger = logger;
 	}
-	async onTunnelExit(id, port, exitCode) {
+	async onTunnelExit(id, port, exitCode, runId) {
 		const handler = this.getHandler();
 		if (!handler) {
 			this.logger.debug("onTunnelExit: no handler bound; ignoring", {
 				id,
 				port,
-				exitCode
+				exitCode,
+				runId
 			});
 			return;
 		}
-		await handler(id, port, exitCode);
+		await handler(id, port, exitCode, runId);
 	}
 };
 
@@ -5295,6 +5807,111 @@ async function deleteDNSRecord(args) {
 	});
 }
 
+//#endregion
+//#region src/tunnels/random-id.ts
+const ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/**
+* Generate a URL- and DNS-safe random id. The default 20 characters give
+* ~100 bits of entropy, which keeps collisions negligible at any realistic
+* volume without a uniqueness retry loop. 32 divides 256 evenly, so masking
+* the low 5 bits of each random byte stays uniform.
+*/
+function randomId(size = 20) {
+	const bytes = new Uint8Array(size);
+	crypto.getRandomValues(bytes);
+	let id = "";
+	for (let i = 0; i < size; i += 1) id += ID_ALPHABET[bytes[i] & 31];
+	return id;
+}
+
+//#endregion
+//#region src/tunnels/lifecycle.ts
+const TUNNEL_GET_MAX_RECOVERY_ATTEMPTS = 2;
+function runtimeRunId() {
+	return `run-${randomId()}`;
+}
+function createTunnelInterruptedError(params) {
+	return new OperationInterruptedError({
+		message: params.reason === "recovery_exhausted" ? "Tunnel recovery attempts were exhausted" : "Tunnel operation was interrupted by a sandbox runtime change",
+		code: ErrorCode.OPERATION_INTERRUPTED,
+		httpStatus: 409,
+		context: {
+			reason: params.reason,
+			operation: "tunnel.get",
+			phase: params.phase,
+			admitted: params.admitted,
+			retryable: params.retryable,
+			...params.recoveryAttempts !== void 0 && { recoveryAttempts: params.recoveryAttempts },
+			...params.maxRecoveryAttempts !== void 0 && { maxRecoveryAttempts: params.maxRecoveryAttempts }
+		},
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		suggestion: params.retryable ? "Retry tunnels.get() for the same port so the SDK can establish a fresh tunnel run." : "Start a new tunnels.get() call only if this tunnel is still desired for the current sandbox."
+	});
+}
+function translateTunnelInterruption(error, phase, admitted) {
+	if (error instanceof OperationInterruptedError) return error;
+	if (error instanceof RuntimeIdentityInactiveError) return createTunnelInterruptedError({
+		reason: "runtime_replaced",
+		phase,
+		admitted,
+		retryable: true
+	});
+	if (error instanceof SandboxLifetimeChangedError) return createTunnelInterruptedError({
+		reason: "sandbox_lifetime_changed",
+		phase,
+		admitted,
+		retryable: false
+	});
+	if (error instanceof RPCTransportError) return createTunnelInterruptedError({
+		reason: "transport_disposed",
+		phase,
+		admitted: "unknown",
+		retryable: true
+	});
+	return null;
+}
+
+//#endregion
+//#region src/tunnels/storage.ts
+const STORAGE_KEY = "tunnels";
+const META_STORAGE_KEY = "tunnels:meta";
+async function readMap(storage) {
+	return await storage.get(STORAGE_KEY) ?? {};
+}
+async function readMetaMap(storage) {
+	return await storage.get(META_STORAGE_KEY) ?? {};
+}
+function computeOptionsHash(options) {
+	if (!options || !options.name) return "v1:quick";
+	return `v1:named:${options.name}`;
+}
+function normaliseHash(hash) {
+	return hash.startsWith("v1:") ? hash.slice(3) : hash;
+}
+function optionsHashesEqual(a, b) {
+	return normaliseHash(a) === normaliseHash(b);
+}
+
+//#endregion
+//#region src/tunnels/restart.ts
+async function pruneTunnelsForRestart(storage) {
+	await storage.transaction(async (txn) => {
+		const map = await readMap(txn);
+		const meta = await readMetaMap(txn);
+		const nextMap = {};
+		const nextMeta = {};
+		for (const [portKey, info] of Object.entries(map)) if (info.name) {
+			nextMap[portKey] = info;
+			nextMeta[portKey] = {
+				...meta[portKey] ?? { optionsHash: `v1:named:${info.name}` },
+				needsRespawn: true
+			};
+		}
+		await txn.put(STORAGE_KEY, nextMap);
+		await txn.put(META_STORAGE_KEY, nextMeta);
+	});
+}
+
 //#endregion
 //#region src/tunnels/tunnels-handler.ts
 /**
@@ -5302,21 +5919,11 @@ async function deleteDNSRecord(args) {
 * `createTunnelsHandler(host)` and exposed as `sandbox.tunnels`.
 *
 * Storage is the source of truth. The DO holds a `Record<portString, TunnelInfo>`
-* under the `tunnels` storage key. `Sandbox.onStart()` clears the key on every
-* container restart so any record in storage is by construction backed by a
-* running `cloudflared` process; the handler never needs to verify that
-* separately against the container.
-*/
-/** DO storage key for the `port → TunnelInfo` map. */
-const STORAGE_KEY = "tunnels";
-/**
-* Sidecar storage key for per-port metadata the handler needs but the
-* public `TunnelInfo` shape does not carry: the options hash used to
-* detect divergent retries, and (for named tunnels) the DNS record id
-* needed for cleanup. Kept under a separate key so the existing
-* `tunnels` shape remains a clean `Record<port, TunnelInfo>`.
+* under the `tunnels` storage key, with internal lifecycle metadata under
+* `tunnels:meta`. Container restarts drop quick tunnel records and mark named
+* tunnels for respawn, so public list/get calls only return records that are
+* usable for the current runtime.
 */
-const META_STORAGE_KEY = "tunnels:meta";
 function validateTunnelPort(port) {
 	if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding reserved ports.`);
 }
@@ -5332,9 +5939,9 @@ function shortId() {
 * the nested `errorResponse.code`. Used for the few error codes the SDK
 * recognises and recovers from (TUNNEL_NOT_FOUND, TUNNEL_ALREADY_RUNNING).
 *
-* Previous versions matched by substring on `error.message`, which
-* false-positived on any error whose message merely quoted the literal
-* code token.
+* Message strings may quote error-code tokens for diagnostics, so matching
+* only structured fields keeps recovery branches tied to explicit error
+* contracts.
 */
 function hasErrorCode(error, code) {
 	if (!error || typeof error !== "object") return false;
@@ -5349,35 +5956,6 @@ function isTunnelNotFoundError(error) {
 function isTunnelAlreadyRunningError(error) {
 	return hasErrorCode(error, "TUNNEL_ALREADY_RUNNING");
 }
-async function readMap(storage) {
-	return await storage.get(STORAGE_KEY) ?? {};
-}
-async function readMetaMap(storage) {
-	return await storage.get(META_STORAGE_KEY) ?? {};
-}
-/**
-* Stable hash of `options`. Empty/undefined options collapse to the same
-* hash so `get(port)`, `get(port, {})`, and `get(port, { name: undefined })`
-* all hit the same cache entry. Named tunnels hash on `name` alone (the
-* only option today).
-*
-* The `v1:` prefix exists so a future addition of a second option (e.g.
-* `subdomain`) can change the canonical form without colliding with an
-* older record's hash. Comparison goes through `optionsHashesEqual`, which
-* normalises legacy unversioned hashes (`quick`, `named:foo`) to their v1
-* form before equality, so upgrading does not invalidate cached records.
-*/
-function computeOptionsHash(options) {
-	if (!options || !options.name) return "v1:quick";
-	return `v1:named:${options.name}`;
-}
-/** Strip the optional `v1:` prefix so legacy hashes compare equal. */
-function normaliseHash(hash) {
-	return hash.startsWith("v1:") ? hash.slice(3) : hash;
-}
-function optionsHashesEqual(a, b) {
-	return normaliseHash(a) === normaliseHash(b);
-}
 /**
 * Concrete `TunnelsHandler` implementation.
 *
@@ -5442,11 +6020,15 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 			validateTunnelPort(port);
 			if (options?.name !== void 0) validateTunnelName(options.name);
 			const requestedHash = computeOptionsHash(options);
-			const info = await this.#withPortLock(port, async () => {
+			const info = await this.#withPortLock(port, () => this.#getWithRecovery(port, options, async (recovery) => {
 				const existing = (await readMap(this.#host.storage))[port.toString()];
 				if (existing) {
 					const metaEntry = (await readMetaMap(this.#host.storage))[port.toString()];
 					if (!optionsHashesEqual(metaEntry?.optionsHash ?? (existing.name ? `v1:named:${existing.name}` : "v1:quick"), requestedHash)) throw new Error(`Tunnel on port ${port} was created with different options. Call destroy(${port}) before changing tunnel options.`);
+					if (!existing.name && await this.#quickTunnelRecordIsStale(metaEntry)) {
+						await this.#stopStaleQuickTunnel(existing, metaEntry);
+						return await this.#provisionQuickTunnel(port, recovery);
+					}
 					if (metaEntry?.needsRespawn && existing.name) return await this.#provisionNamedTunnel(port, existing.name);
 					if (existing.name && this.#host.getNamedTunnelConfig) {
 						const currentConfig = await this.#host.getNamedTunnelConfig();
@@ -5461,8 +6043,8 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 					return existing;
 				}
 				if (options?.name) return await this.#provisionNamedTunnel(port, options.name);
-				return await this.#provisionQuickTunnel(port);
-			});
+				return await this.#provisionQuickTunnel(port, recovery);
+			}));
 			outcome = "success";
 			return info;
 		} catch (error) {
@@ -5479,6 +6061,58 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 			});
 		}
 	}
+	async #getWithRecovery(port, options, run) {
+		let recoveryAttempts = 0;
+		const recovery = {};
+		while (true) try {
+			return await run(recovery);
+		} catch (error) {
+			const interrupted = translateTunnelInterruption(error, "provisioning", "unknown");
+			if (!interrupted || options?.name || !interrupted.context.retryable) throw error;
+			if (recoveryAttempts >= TUNNEL_GET_MAX_RECOVERY_ATTEMPTS) {
+				await this.#clearQuickTunnelStorage(port);
+				throw createTunnelInterruptedError({
+					reason: "recovery_exhausted",
+					phase: "interrupted",
+					admitted: interrupted.context.admitted,
+					retryable: false,
+					recoveryAttempts,
+					maxRecoveryAttempts: TUNNEL_GET_MAX_RECOVERY_ATTEMPTS
+				});
+			}
+			recoveryAttempts++;
+			if (interrupted.context.reason === "runtime_replaced") recovery.quickRun = void 0;
+			await this.#clearQuickTunnelStorage(port);
+		}
+	}
+	async #clearQuickTunnelStorage(port) {
+		await this.#host.storage.transaction(async (txn) => {
+			const map = await readMap(txn);
+			delete map[port.toString()];
+			await txn.put(STORAGE_KEY, map);
+			const meta = await readMetaMap(txn);
+			delete meta[port.toString()];
+			await txn.put(META_STORAGE_KEY, meta);
+		});
+	}
+	async #quickTunnelRecordIsStale(metaEntry) {
+		if (!this.#host.currentRuntime || !this.#host.currentLifetime) return false;
+		if (!metaEntry?.runtimeIdentityID || !metaEntry.sandboxLifetimeID) return true;
+		const runtime = await this.#host.currentRuntime.get();
+		const lifetime = await this.#host.currentLifetime.getOrCreate();
+		return runtime?.id !== metaEntry.runtimeIdentityID || lifetime.id !== metaEntry.sandboxLifetimeID;
+	}
+	async #stopStaleQuickTunnel(existing, metaEntry) {
+		try {
+			if (metaEntry?.tunnelRunId) await this.#host.client.tunnels.stopTunnelRun({
+				tunnelId: existing.id,
+				runId: metaEntry.tunnelRunId
+			});
+			else await this.#host.client.tunnels.destroyTunnel(existing.id);
+		} catch (error) {
+			if (!isTunnelNotFoundError(error)) throw error;
+		}
+	}
 	/**
 	* Provision a fresh quick tunnel and persist it. Caller holds the
 	* per-port lock.
@@ -5490,7 +6124,8 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 	* surfacing the confusing error — the retry budget caps the loop so a
 	* persistent failure still surfaces.
 	*/
-	async #provisionQuickTunnel(port) {
+	async #provisionQuickTunnel(port, recovery) {
+		if (this.#host.currentRuntime && this.#host.currentLifetime) return await this.#provisionQuickTunnelRun(port, recovery);
 		const MAX_ID_RETRIES = 3;
 		let lastError;
 		for (let attempt = 0; attempt < MAX_ID_RETRIES; attempt += 1) {
@@ -5513,6 +6148,65 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 		}
 		throw lastError ?? /* @__PURE__ */ new Error("Failed to mint a unique quick-tunnel id");
 	}
+	async #provisionQuickTunnelRun(port, recovery) {
+		if (!this.#host.currentRuntime || !this.#host.currentLifetime) throw new Error("Quick tunnel runtime fences are not configured");
+		const lifetime = await this.#host.currentLifetime.getOrCreate();
+		const runtimeBeforeAdmission = await this.#host.currentRuntime.get();
+		try {
+			await this.#host.currentLifetime.assertCurrent(lifetime);
+		} catch (error) {
+			throw translateTunnelInterruption(error, "runtime_ready", "unknown") ?? error;
+		}
+		recovery.quickRun ??= {
+			tunnelId: `quick-${randomId()}`,
+			runId: runtimeRunId()
+		};
+		const { tunnelId, runId } = recovery.quickRun;
+		let ensureResult;
+		let runtime = runtimeBeforeAdmission;
+		try {
+			ensureResult = await this.#host.client.tunnels.ensureTunnelRun({
+				tunnelId,
+				runId,
+				mode: "quick",
+				port
+			});
+			runtime ??= await this.#host.currentRuntime.get() ?? await this.#host.currentRuntime.markStarted();
+			await this.#host.currentRuntime.assertActive(runtime);
+			await this.#host.currentLifetime.assertCurrent(lifetime);
+		} catch (error) {
+			throw translateTunnelInterruption(error, "runtime_ready", "unknown") ?? error;
+		}
+		const { run } = ensureResult;
+		if (!run.url || !run.hostname) throw new Error("Quick tunnel run did not produce a public URL");
+		const spawned = {
+			id: run.tunnelId,
+			port: run.port,
+			url: run.url,
+			hostname: run.hostname,
+			createdAt: run.startedAt
+		};
+		await this.#host.storage.transaction(async (txn) => {
+			const nextMap = await readMap(txn);
+			nextMap[port.toString()] = spawned;
+			await txn.put(STORAGE_KEY, nextMap);
+			const nextMeta = await readMetaMap(txn);
+			nextMeta[port.toString()] = {
+				optionsHash: "v1:quick",
+				runtimeIdentityID: runtime.id,
+				sandboxLifetimeID: lifetime.id,
+				tunnelRunId: run.runId
+			};
+			await txn.put(META_STORAGE_KEY, nextMeta);
+		});
+		try {
+			await this.#host.currentRuntime.assertActive(runtime);
+			await this.#host.currentLifetime.assertCurrent(lifetime);
+		} catch (error) {
+			throw translateTunnelInterruption(error, "storage_committed", true) ?? error;
+		}
+		return spawned;
+	}
 	/**
 	* Provision a named tunnel end-to-end:
 	*   1. resolve credentials + zone name
@@ -5623,7 +6317,11 @@ var TunnelsRpcTarget = class extends RpcTarget$1 {
 					await txn.put(META_STORAGE_KEY, currentMeta);
 				});
 				try {
-					await this.#host.client.tunnels.destroyTunnel(existing.id);
+					if (metaBefore?.tunnelRunId) await this.#host.client.tunnels.stopTunnelRun({
+						tunnelId: existing.id,
+						runId: metaBefore.tunnelRunId
+					});
+					else await this.#host.client.tunnels.destroyTunnel(existing.id);
 				} catch (error) {
 					if (isTunnelNotFoundError(error)) {} else if (metaBefore?.dnsRecordId) this.#host.logger.warn("tunnel.destroy: container tunnel cleanup failed", {
 						port,
@@ -5704,7 +6402,7 @@ function createTunnelsHandler(host) {
 		return next;
 	};
 	const tunnels = new TunnelsRpcTarget(host, withPortLock);
-	const handleTunnelExit = async (id, port, exitCode) => {
+	const handleTunnelExit = async (id, port, exitCode, runId) => {
 		const startTime = Date.now();
 		let outcome = "error";
 		let caughtError;
@@ -5714,19 +6412,20 @@ function createTunnelsHandler(host) {
 					const map = await readMap(txn);
 					const existing = map[port.toString()];
 					if (existing?.id !== id) return;
+					const meta = await readMetaMap(txn);
+					const metaEntry = meta[port.toString()];
+					if (runId && metaEntry?.tunnelRunId && metaEntry.tunnelRunId !== runId) return;
 					if (existing.name) {
-						const meta$1 = await readMetaMap(txn);
-						meta$1[port.toString()] = {
-							...meta$1[port.toString()],
-							optionsHash: meta$1[port.toString()]?.optionsHash ?? `v1:named:${existing.name}`,
+						meta[port.toString()] = {
+							...metaEntry,
+							optionsHash: metaEntry?.optionsHash ?? `v1:named:${existing.name}`,
 							needsRespawn: true
 						};
-						await txn.put(META_STORAGE_KEY, meta$1);
+						await txn.put(META_STORAGE_KEY, meta);
 						return;
 					}
 					delete map[port.toString()];
 					await txn.put(STORAGE_KEY, map);
-					const meta = await readMetaMap(txn);
 					delete meta[port.toString()];
 					await txn.put(META_STORAGE_KEY, meta);
 				});
@@ -5780,52 +6479,6 @@ function createTunnelsHandler(host) {
 		destroyAll
 	};
 }
-/**
-* Reconcile storage with a fresh container.
-*
-* Called from `Sandbox.onStart()` after every container restart. The
-* `cloudflared` processes the container was running all died with it, so
-* any stored record is *not* currently backed by a running tunnel.
-*
-* Two tunnel flavours, two recovery stories:
-*
-*   - Quick tunnels: the `*.trycloudflare.com` URL is bound to the dead
-*     `cloudflared` process. Nothing on Cloudflare's side outlives the
-*     container, and the URL is unrecoverable. Drop the record from both
-*     maps so the next `get(port)` takes the miss branch and mints a new
-*     URL.
-*   - Named tunnels: the Cloudflare-side tunnel + DNS record survive.
-*     The hostname is stable, the DNS still resolves to
-*     `<tunnelId>.cfargotunnel.com`, and the next caller can reuse both
-*     by walking the same `findTunnelByName` / `upsertCNAME` path the
-*     SDK uses for retries. Keep the record in storage and mark the
-*     meta entry `needsRespawn: true`; the next `get(port, { name })`
-*     cache hit falls through to `#provisionNamedTunnel` to respawn
-*     `cloudflared`.
-*
-* Crucially, named-tunnel metadata (including `dnsRecordId`) is
-* preserved so `destroy(port)` and `sandbox.destroy()` can still clean
-* up the Cloudflare-side resources after a restart. Wiping meta
-* unconditionally — the previous behaviour — silently leaked the tunnel
-* and DNS record on every restart.
-*/
-async function pruneTunnelsForRestart(storage) {
-	await storage.transaction(async (txn) => {
-		const map = await readMap(txn);
-		const meta = await readMetaMap(txn);
-		const nextMap = {};
-		const nextMeta = {};
-		for (const [portKey, info] of Object.entries(map)) if (info.name) {
-			nextMap[portKey] = info;
-			nextMeta[portKey] = {
-				...meta[portKey] ?? { optionsHash: `v1:named:${info.name}` },
-				needsRespawn: true
-			};
-		}
-		await txn.put(STORAGE_KEY, nextMap);
-		await txn.put(META_STORAGE_KEY, nextMeta);
-	});
-}
 
 //#endregion
 //#region src/version.ts
@@ -5834,7 +6487,7 @@ async function pruneTunnelsForRestart(storage) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.12.1";
+const SDK_VERSION = "0.12.3";
 
 //#endregion
 //#region src/sandbox.ts
@@ -5997,6 +6650,38 @@ function applySandboxConfiguration(stub, configuration) {
 	if (configuration.transport !== void 0) operations.push(stub.setTransport?.(configuration.transport) ?? Promise.resolve());
 	return Promise.all(operations).then(() => void 0);
 }
+function createPlatformInterruptedError(error, operation) {
+	if (!isPlatformTransientError(error)) return null;
+	const context = {
+		reason: "runtime_replaced",
+		operation,
+		phase: "durable_object_call",
+		admitted: "unknown",
+		retryable: false
+	};
+	return new OperationInterruptedError({
+		code: ErrorCode.OPERATION_INTERRUPTED,
+		message: `Sandbox operation ${operation} was interrupted while the platform was updating the sandbox runtime`,
+		context,
+		httpStatus: getHttpStatus(ErrorCode.OPERATION_INTERRUPTED),
+		suggestion: getSuggestion(ErrorCode.OPERATION_INTERRUPTED, context),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, { cause: error });
+}
+function translatePlatformInterruption(error, operation) {
+	throw createPlatformInterruptedError(error, operation) ?? error;
+}
+function withSandboxOperationContext(operation, fn) {
+	return (...args) => {
+		try {
+			const result = fn(...args);
+			if (result != null && typeof result.then === "function") return result.catch((error) => translatePlatformInterruption(error, operation));
+			return result;
+		} catch (error) {
+			translatePlatformInterruption(error, operation);
+		}
+	};
+}
 function getSandbox(ns, id, options) {
 	const sanitizedId = sanitizeSandboxId(id);
 	const effectiveId = options?.normalizeId ? sanitizedId.toLowerCase() : sanitizedId;
@@ -6079,11 +6764,15 @@ function getSandbox(ns, id, options) {
 		wsConnect: connect(stub),
 		tunnels: new Proxy({}, { get: (_, method) => {
 			if (typeof method !== "string" || method === "then") return void 0;
-			return (...args) => stub.callTunnels(method, args);
+			return withSandboxOperationContext(`sandbox.tunnels.${method}`, (...args) => stub.callTunnels(method, args));
 		} })
 	};
 	return new Proxy(stub, { get(target, prop) {
-		if (typeof prop === "string" && prop in enhancedMethods) return enhancedMethods[prop];
+		if (typeof prop === "string" && prop in enhancedMethods) {
+			const method = enhancedMethods[prop];
+			if (typeof method === "function") return withSandboxOperationContext(`sandbox.${prop}`, method);
+			return method;
+		}
 		return target[prop];
 	} });
 }
@@ -6120,6 +6809,7 @@ var Sandbox = class Sandbox extends Container {
 	activeMounts = /* @__PURE__ */ new Map();
 	mountOperationQueue = Promise.resolve();
 	currentRuntime;
+	currentLifetime;
 	transport = "http";
 	/**
 	* True once transport has been written to storage at least once (either
@@ -6271,6 +6961,7 @@ var Sandbox = class Sandbox extends Container {
 			sandboxId: this.ctx.id.toString()
 		});
 		this.currentRuntime = new CurrentRuntimeIdentity(this.ctx.storage, () => this.getState(), () => this.ctx.container?.running === true);
+		this.currentLifetime = new CurrentSandboxLifetime(this.ctx.storage);
 		const transportEnv = envObj?.SANDBOX_TRANSPORT;
 		if (transportEnv === "websocket" || transportEnv === "rpc") this.transport = transportEnv;
 		else if (transportEnv != null && transportEnv !== "http") this.logger.warn(`Invalid SANDBOX_TRANSPORT value: "${transportEnv}". Must be "http", "websocket", or "rpc". Defaulting to "http".`);
@@ -7096,6 +7787,7 @@ var Sandbox = class Sandbox extends Container {
 		try {
 			await this.ctx.storage.delete(PORT_TOKENS_STORAGE_KEY);
 			await this.clearActivePreviewPorts();
+			await this.currentLifetime.rotate();
 			await this.currentRuntime.clear();
 			for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
 				mountsProcessed++;
@@ -7610,6 +8302,14 @@ var Sandbox = class Sandbox extends Container {
 		this.defaultSessionInit = init;
 		try {
 			return await promise;
+		} catch (err) {
+			if (isSessionInitInvalidated(err)) {
+				if (this.defaultSession === sessionId) return this.defaultSession;
+				const freshPending = this.defaultSessionInit;
+				if (freshPending != null && freshPending !== init && freshPending.sessionId === sessionId && freshPending.generation === this.containerGeneration) return freshPending.promise;
+				return await this.initializeDefaultSession(sessionId, this.containerGeneration);
+			}
+			throw err;
 		} finally {
 			if (this.defaultSessionInit === init) this.defaultSessionInit = null;
 		}
@@ -7627,7 +8327,7 @@ var Sandbox = class Sandbox extends Container {
 			placementId = error.containerPlacementId;
 			this.logger.debug("Session exists in container but not in DO state, syncing", { sessionId });
 		}
-		if (generation !== this.containerGeneration) throw new Error("Default session initialization was invalidated by a container stop");
+		if (generation !== this.containerGeneration) throw new SessionInitInvalidatedError();
 		await this.ctx.storage.put("defaultSession", sessionId);
 		await this.capturePlacementId(placementId);
 		this.defaultSession = sessionId;
@@ -8499,6 +9199,8 @@ var Sandbox = class Sandbox extends Container {
 			storage: this.ctx.storage,
 			logger: this.logger,
 			sandboxId: this.ctx.id.toString(),
+			currentRuntime: this.currentRuntime,
+			currentLifetime: this.currentLifetime,
 			getNamedTunnelConfig: async () => {
 				const envObj = this.env;
 				const token = getEnvString(envObj, "CLOUDFLARE_API_TOKEN");
@@ -9665,11 +10367,24 @@ var Sandbox = class Sandbox extends Container {
 	* Concurrent backup/restore calls on the same sandbox are serialized.
 	*/
 	async restoreBackup(backup) {
-		if (backup.localBucket) return await this.enqueueBackupOp(() => this.doRestoreBackupLocal(backup));
-		this.requireBackupBucket();
-		return await this.enqueueBackupOp(() => this.doRestoreBackup(backup));
+		if (!backup.localBucket) this.requireBackupBucket();
+		return await this.enqueueBackupOp(() => this.doRestoreBackupWithRecovery(backup));
+	}
+	async doRestoreBackupWithRecovery(backup) {
+		return await new RestoreLifecycleRunner({
+			storage: this.ctx.storage,
+			currentRuntime: this.currentRuntime,
+			currentLifetime: this.currentLifetime
+		}).execute({
+			backupId: backup.id,
+			dir: backup.dir,
+			attempt: async (lifecycle) => {
+				if (backup.localBucket) return await this.doRestoreBackupLocal(backup, lifecycle);
+				return await this.doRestoreBackup(backup, lifecycle);
+			}
+		});
 	}
-	async doRestoreBackup(backup) {
+	async doRestoreBackup(backup, lifecycle) {
 		const restoreStartTime = Date.now();
 		const bucket = this.requireBackupBucket();
 		this.requirePresignedURLSupport();
@@ -9736,12 +10451,14 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			backupSession = await this.ensureBackupSession();
+			await lifecycle.runtimeReady();
 			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(() => {});
 			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);
+			await lifecycle.archiveReady(archiveHead.size);
 			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,
@@ -9752,12 +10469,14 @@ var Sandbox = class Sandbox extends Container {
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			outcome = "success";
-			return {
+			const result = {
 				success: true,
 				dir,
 				id
 			};
+			await lifecycle.verify(result);
+			outcome = "success";
+			return result;
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
 			if (id && backupSession) {
@@ -9782,7 +10501,7 @@ var Sandbox = class Sandbox extends Container {
 	* Uses the R2 binding directly instead of presigned URLs, and
 	* unsquashfs for extraction instead of squashfuse + fuse-overlayfs.
 	*/
-	async doRestoreBackupLocal(backup) {
+	async doRestoreBackupLocal(backup, lifecycle) {
 		const restoreStartTime = Date.now();
 		const { id, dir } = backup;
 		let outcome = "error";
@@ -9854,7 +10573,9 @@ var Sandbox = class Sandbox extends Container {
 				context: { backupId: id },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
+			const archiveSize = metadata.sizeBytes;
 			backupSession = await this.ensureBackupSession();
+			await lifecycle.runtimeReady();
 			const archivePath = `${BACKUP_CONTAINER_DIR}/${id}.sqsh`;
 			await this.execWithSession(`mkdir -p ${BACKUP_CONTAINER_DIR}`, backupSession, { origin: "internal" });
 			if (this.transport === "rpc") {
@@ -9885,6 +10606,7 @@ var Sandbox = class Sandbox extends Container {
 					timestamp: (/* @__PURE__ */ new Date()).toISOString()
 				});
 			}
+			await lifecycle.archiveReady(archiveSize);
 			const extractResult = await this.execWithSession(`/usr/bin/unsquashfs -f -d ${shellEscape(dir)} ${shellEscape(archivePath)}`, backupSession, { origin: "internal" });
 			if (extractResult.exitCode !== 0) throw new BackupRestoreError({
 				message: `unsquashfs extraction failed (exit code ${extractResult.exitCode}): ${extractResult.stderr}`,
@@ -9896,13 +10618,15 @@ var Sandbox = class Sandbox extends Container {
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
-			outcome = "success";
-			return {
+			const result = {
 				success: true,
 				dir,
 				id
 			};
+			await lifecycle.verify(result);
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
+			outcome = "success";
+			return result;
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
 			if (id && backupSession) {
@@ -9984,5 +10708,5 @@ var Sandbox = class Sandbox extends Container {
 };
 
 //#endregion
-export { FileClient as A, RPCTransportError as B, collectFile as C, ProcessClient as D, UtilityClient as E, BackupNotFoundError as F, BackupRestoreError as I, InvalidBackupConfigError as L, BackupClient as M, BackupCreateError as N, PortClient as O, BackupExpiredError as P, ProcessExitedBeforeReadyError as R, validateTunnelName as S, SandboxClient as T, SessionTerminatedError as V, responseToAsyncIterable as _, PREVIEW_PROXY_HEADER as a, sanitizeSandboxId as b, PREVIEW_PROXY_SANDBOX_ID_HEADER as c, BucketUnmountError as d, InvalidMountConfigError as f, parseSSEStream as g, asyncIterableToSSEStream as h, proxyTerminal as i, CommandClient as j, GitClient as k, PREVIEW_PROXY_TOKEN_HEADER as l, S3FSMountError as m, Sandbox as n, PREVIEW_PROXY_HEADERS as o, MissingCredentialsError as p, getSandbox as r, PREVIEW_PROXY_PORT_HEADER as s, ContainerProxy$1 as t, BucketMountError as u, CodeInterpreter as v, streamFile as w, validatePort as x, SandboxSecurityError as y, ProcessReadyTimeoutError as z };
-//# sourceMappingURL=sandbox-DKG3H156.js.map
+export { PortClient as A, InvalidBackupConfigError as B, collectFile as C, SandboxClient as D, isPlatformTransientError as E, BackupCreateError as F, SessionTerminatedError as G, ProcessExitedBeforeReadyError as H, BackupExpiredError as I, BackupNotFoundError as L, FileClient as M, CommandClient as N, UtilityClient as O, BackupClient as P, BackupRestoreError as R, validateTunnelName as S, isDurableObjectCodeUpdateReset as T, ProcessReadyTimeoutError as U, OperationInterruptedError as V, RPCTransportError as W, responseToAsyncIterable as _, PREVIEW_PROXY_HEADER as a, sanitizeSandboxId as b, PREVIEW_PROXY_SANDBOX_ID_HEADER as c, BucketUnmountError as d, InvalidMountConfigError as f, parseSSEStream as g, asyncIterableToSSEStream as h, proxyTerminal as i, GitClient as j, ProcessClient as k, PREVIEW_PROXY_TOKEN_HEADER as l, S3FSMountError as m, Sandbox as n, PREVIEW_PROXY_HEADERS as o, MissingCredentialsError as p, getSandbox as r, PREVIEW_PROXY_PORT_HEADER as s, ContainerProxy$1 as t, BucketMountError as u, CodeInterpreter as v, streamFile as w, validatePort as x, SandboxSecurityError as y, ContainerUnavailableError as z };
+//# sourceMappingURL=sandbox-DI6suZAc.js.map