@cloudflare/sandbox 0.12.4 → 0.12.5

package/dist/{sandbox-CyqG4jca.js → sandbox-sU3r5LSr.js}

@@ -3,8 +3,8 @@ import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors
 import { Container, ContainerProxy, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 import { RpcSession, RpcTarget } from "capnweb";
+import { RpcTarget as RpcTarget$1, tracing } from "cloudflare:workers";
 import path from "node:path/posix";
-import { RpcTarget as RpcTarget$1 } from "cloudflare:workers";
 
 //#region src/errors/classes.ts
 /**
@@ -769,19 +769,55 @@ function isRetryableWebSocketUpgradeResponse(response) {
 	return RETRYABLE_WEBSOCKET_UPGRADE_STATUSES.has(response.status);
 }
 /**
+* Compute the next backoff delay from the remaining retry budget. Returns null
+* when another attempt should not begin.
+*
+* Delay is limited to the budget left after reserving `minTimeForRetryMs` for
+* the subsequent attempt. An attempt already in progress owns its own
+* per-request timeouts via the caller-provided `fetchResponse` function.
+*/
+function nextRetryDelayMs(attempt, remainingMs, minTimeForRetryMs) {
+	const availableForDelay = remainingMs - minTimeForRetryMs;
+	if (availableForDelay <= 0) return null;
+	const computedDelay = Math.min(DEFAULT_INITIAL_RETRY_DELAY_MS * 2 ** attempt, DEFAULT_MAX_RETRY_DELAY_MS);
+	return Math.min(computedDelay, availableForDelay);
+}
+/**
 * Retry Response-returning operations while their response remains retryable.
-* The retry budget covers the whole operation; each attempt owns any
-* per-request timeout inside the caller-provided `fetchResponse` function.
+*
+* The retry budget decides whether another attempt may begin after a retryable
+* response or thrown error. Each attempt owns any per-request timeout inside
+* the caller-provided `fetchResponse` function. Backoff is limited to the
+* remaining budget after reserving `minTimeForRetryMs` for that next attempt.
 */
 async function fetchWithResponseRetry(fetchResponse, options) {
 	const startTime = Date.now();
 	let attempt = 0;
 	while (true) {
-		const response = await fetchResponse();
+		let response;
+		try {
+			response = await fetchResponse();
+		} catch (error) {
+			if (!options.shouldRetryError?.(error)) throw error;
+			const elapsed$1 = Date.now() - startTime;
+			const remaining$1 = options.retryTimeoutMs - elapsed$1;
+			const delay$1 = nextRetryDelayMs(attempt, remaining$1, options.minTimeForRetryMs);
+			if (delay$1 === null) throw error;
+			options.logger.info(options.retryLogMessage, {
+				attempt: attempt + 1,
+				delayMs: delay$1,
+				remainingSec: Math.floor(remaining$1 / 1e3),
+				error: error instanceof Error ? error.message : String(error)
+			});
+			await new Promise((resolve) => setTimeout(resolve, delay$1));
+			attempt++;
+			continue;
+		}
 		if (!options.shouldRetry(response)) return response;
 		const elapsed = Date.now() - startTime;
 		const remaining = options.retryTimeoutMs - elapsed;
-		if (remaining <= options.minTimeForRetryMs) {
+		const delay = nextRetryDelayMs(attempt, remaining, options.minTimeForRetryMs);
+		if (delay === null) {
 			options.onRetryExhausted?.({
 				attempts: attempt + 1,
 				elapsedMs: elapsed,
@@ -789,7 +825,6 @@ async function fetchWithResponseRetry(fetchResponse, options) {
 			});
 			return response;
 		}
-		const delay = Math.min(DEFAULT_INITIAL_RETRY_DELAY_MS * 2 ** attempt, DEFAULT_MAX_RETRY_DELAY_MS);
 		options.logger.info(options.retryLogMessage, {
 			status: response.status,
 			attempt: attempt + 1,
@@ -2495,6 +2530,52 @@ const DO_STORAGE_STARTUP_RESET_PATTERN = /internal error while starting up durab
 function errorMessageOf(error) {
 	return error instanceof Error ? error.message : typeof error === "string" ? error : "";
 }
+/**
+* Extract a matchable message from any thrown value, reading a `.message`
+* property even when the value is not an `Error` instance. The Containers
+* runtime raises admission failures from the container binding, which may
+* live in a different realm — so `instanceof Error` can be false for a
+* genuine error. Mirrors the base `@cloudflare/containers` `isErrorOfType`
+* helper: coerce to a string, then match case-insensitively.
+*/
+function realmSafeMessageOf(error) {
+	const message = error?.message;
+	return typeof message === "string" ? message : String(error);
+}
+/**
+* Platform messages emitted by the Containers runtime when it cannot admit a
+* container for a Durable Object during startup. Matched case-insensitively as
+* lowercase substrings. Single source of truth for both the RPC connection
+* path (connection.ts) and the HTTP `containerFetch` path (sandbox.ts).
+*/
+const CONTAINER_UNAVAILABLE_SIGNATURES = [
+	{
+		substring: "there is no container instance that can be provided to this durable object",
+		reason: "no_container_instance_available"
+	},
+	{
+		substring: "there is no container instance available at this time",
+		reason: "no_container_instance_available"
+	},
+	{
+		substring: "maximum number of running container instances exceeded",
+		reason: "max_container_instances_exceeded"
+	}
+];
+/**
+* Classify a container-startup error as a platform admission/capacity failure,
+* returning the categorical reason or null. Realm-safe (does not gate on
+* `instanceof Error`), case-insensitive, and walks the `.cause` chain so a
+* wrapped admission failure is still recognized.
+*/
+function matchContainerUnavailable(error) {
+	for (const candidate of selfAndCauses(error)) {
+		const text = realmSafeMessageOf(candidate).toLowerCase();
+		const match = CONTAINER_UNAVAILABLE_SIGNATURES.find((sig) => text.includes(sig.substring));
+		if (match) return match.reason;
+	}
+	return null;
+}
 function* selfAndCauses(error) {
 	let current = error;
 	for (let depth = 0; depth < 8 && current != null; depth += 1) {
@@ -3003,6 +3084,123 @@ var RestoreLifecycleRunner = class {
 	}
 };
 
+//#endregion
+//#region src/container-control/tracing.ts
+/**
+* Thin tracing helper for the RPC control path.
+*
+* Wraps `cloudflare:workers` `tracing.enterSpan` so the connection/client code
+* can emit spans for RPC calls, the connect/disconnect lifecycle, and
+* individual upgrade attempts — without hard-failing in environments where the
+* tracing API is unavailable.
+*
+* Error convention: the Cloudflare trace UI surfaces `error` and `error.stack`
+* span attributes specially (this differs from the OpenTelemetry standard,
+* which uses exception events). We therefore stamp both attributes on the span
+* when the wrapped work throws, so failures are visible in the GUI.
+*
+* Cause chain: the base `@cloudflare/containers` class wraps the true failure
+* inside `new Error(NO_CONTAINER_INSTANCE_ERROR, { cause })`, so the real
+* reason (e.g. "the container is not listening", "Network connection lost", a
+* non-zero exit code) is only visible on `.cause`. Every distinct failure mode
+* therefore collapses to the same generic top-level message in traces. We walk
+* the cause chain and stamp it so a trace names the actual root cause.
+*/
+/** Bound on cause-chain traversal — guards against cycles and runaway depth. */
+const MAX_CAUSE_DEPTH = 8;
+/** Read a string `code` property off an arbitrary value, if present. */
+function stringCode(value) {
+	const code = value?.code;
+	return typeof code === "string" ? code : void 0;
+}
+/** Render any thrown value as a short human-readable message. */
+function messageOf(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+/**
+* Compute the Cloudflare-convention error span attributes for any thrown value,
+* including the wrapped `.cause` chain. Pure and side-effect-free so it can be
+* unit-tested without a live tracer.
+*
+* Emits:
+*   - `error`            — top-level message (or stringified non-Error)
+*   - `error.stack`      — top-level stack, when available
+*   - `error.code`       — top-level string `code`, when available
+*   - `error.cause`      — immediate cause message, when a cause exists
+*   - `error.cause.code` — immediate cause string `code`, when available
+*   - `error.cause_chain`— all nested cause messages joined by " <- "
+*/
+function computeErrorAttributes(error) {
+	const attrs = {};
+	if (error instanceof Error) {
+		attrs.error = error.message;
+		if (typeof error.stack === "string") attrs["error.stack"] = error.stack;
+		const code = stringCode(error);
+		if (code !== void 0) attrs["error.code"] = code;
+	} else {
+		attrs.error = String(error);
+		return attrs;
+	}
+	const chain = [];
+	const seen = new Set([error]);
+	let current = error.cause;
+	let depth = 0;
+	while (current !== void 0 && current !== null && depth < MAX_CAUSE_DEPTH) {
+		if (seen.has(current)) break;
+		seen.add(current);
+		if (depth === 0) {
+			attrs["error.cause"] = messageOf(current);
+			const causeCode = stringCode(current);
+			if (causeCode !== void 0) attrs["error.cause.code"] = causeCode;
+		}
+		chain.push(messageOf(current));
+		current = current instanceof Error ? current.cause : void 0;
+		depth++;
+	}
+	if (chain.length > 0) attrs["error.cause_chain"] = chain.join(" <- ");
+	return attrs;
+}
+/**
+* Stamp the Cloudflare-convention error attributes onto a span. Safe to call
+* with any thrown value.
+*/
+function setErrorAttributes(span, error) {
+	for (const [key, value] of Object.entries(computeErrorAttributes(error))) if (value !== void 0) span.setAttribute(key, value);
+}
+/**
+* Run `fn` inside a span named `name`, applying `attributes` up front and
+* stamping `error`/`error.stack` if it throws. Re-throws the original error.
+*
+* Falls back to running `fn` directly if the tracing API is unavailable, so a
+* missing tracer never changes behavior.
+*/
+async function withSpan(name, attributes, fn) {
+	const enter = tracing?.enterSpan?.bind(tracing);
+	if (typeof enter !== "function") return fn({ setAttribute: () => {} });
+	return enter(name, async (span) => {
+		for (const [key, value] of Object.entries(attributes)) if (value !== void 0) span.setAttribute(key, value);
+		try {
+			return await fn(span);
+		} catch (error) {
+			setErrorAttributes(span, error);
+			throw error;
+		}
+	});
+}
+/**
+* Emit a zero-duration marker span for a lifecycle event (e.g. disconnect).
+* Best-effort: never throws, never changes behavior.
+*/
+function traceEvent(name, attributes) {
+	const enter = tracing?.enterSpan?.bind(tracing);
+	if (typeof enter !== "function") return;
+	try {
+		enter(name, (span) => {
+			for (const [key, value] of Object.entries(attributes)) if (value !== void 0) span.setAttribute(key, value);
+		});
+	} catch {}
+}
+
 //#endregion
 //#region src/container-control/connection.ts
 /**
@@ -3015,14 +3213,14 @@ var RestoreLifecycleRunner = class {
 * holds the original Response.
 */
 async function tryParseContainerUnavailable(response) {
-	if (!(response.headers.get("content-type") ?? "").includes("application/json")) return null;
-	try {
+	if ((response.headers.get("content-type") ?? "").includes("application/json")) 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",
+			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 === "no_container_instance_available" || body.context?.reason === "max_container_instances_exceeded" ? body.context.reason : "container_replaced",
 			retryable: true,
-			...typeof body.context?.retryAfterMs === "number" && { retryAfterMs: body.context.retryAfterMs }
+			...typeof body.context?.retryAfterMs === "number" && { retryAfterMs: body.context.retryAfterMs },
+			...typeof body.context?.originalMessage === "string" && { originalMessage: body.context.originalMessage }
 		};
 		return createErrorFromResponse({
 			code: ErrorCode.CONTAINER_UNAVAILABLE,
@@ -3035,6 +3233,53 @@ async function tryParseContainerUnavailable(response) {
 	} catch {
 		return null;
 	}
+	try {
+		const text = await response.clone().text();
+		const reason = matchContainerUnavailable(text);
+		if (!reason) return null;
+		return buildContainerUnavailableError(reason, text);
+	} catch {
+		return null;
+	}
+}
+/**
+* True when a thrown connection-startup error matches a known platform
+* container-admission failure. These are transient: the platform asks the
+* caller to try again later, so they are safe to retry within the budget.
+* Delegates to the shared matcher in platform-errors.ts.
+*/
+function isPlatformUnavailableError(error) {
+	return matchContainerUnavailable(error) !== null;
+}
+/**
+* Build a typed ContainerUnavailableError for a matched platform
+* container-admission failure, preserving the original message verbatim.
+*/
+function buildContainerUnavailableError(reason, originalMessage, cause) {
+	const context = {
+		reason,
+		retryable: true,
+		originalMessage
+	};
+	return createErrorFromResponse({
+		code: ErrorCode.CONTAINER_UNAVAILABLE,
+		message: originalMessage,
+		context,
+		httpStatus: getHttpStatus(ErrorCode.CONTAINER_UNAVAILABLE),
+		suggestion: getSuggestion(ErrorCode.CONTAINER_UNAVAILABLE, context),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, cause !== void 0 ? { cause } : void 0);
+}
+/**
+* Convert a raw connection-startup error into a typed ContainerUnavailableError
+* when it matches a known platform container-admission failure. Returns null
+* for anything else so the caller preserves the original error.
+*/
+function tryConvertPlatformUnavailable(error) {
+	if (error instanceof SandboxError) return error;
+	const reason = matchContainerUnavailable(error);
+	if (!reason) return null;
+	return buildContainerUnavailableError(reason, error instanceof Error ? error.message : String(error), error);
 }
 const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 const DEFAULT_RETRY_TIMEOUT_MS = 12e4;
@@ -3058,12 +3303,20 @@ var ContainerControlConnection = class {
 	logger;
 	retryTimeoutMs;
 	onClose;
+	onConnectionError;
+	onConnected;
+	startContainer;
+	getSandboxInfo;
 	constructor(options) {
 		this.containerStub = options.stub;
 		this.port = options.port ?? 3e3;
 		this.logger = options.logger ?? createNoOpLogger();
 		this.retryTimeoutMs = options.retryTimeoutMs ?? DEFAULT_RETRY_TIMEOUT_MS;
 		this.onClose = options.onClose;
+		this.onConnectionError = options.onConnectionError;
+		this.onConnected = options.onConnected;
+		this.startContainer = options.startContainer;
+		this.getSandboxInfo = options.getSandboxInfo;
 		this.transport = new DeferredTransport();
 		this.session = new RpcSession(this.transport, options.localMain);
 		this.stub = this.session.getRemoteMain();
@@ -3090,6 +3343,24 @@ var ContainerControlConnection = class {
 	isConnected() {
 		return this.connected;
 	}
+	/**
+	* True while a connection attempt is in progress (upgrade not yet
+	* established and not yet failed). Owners use this to avoid tearing the
+	* connection down mid-attempt.
+	*/
+	isConnecting() {
+		return this.connectPromise !== null;
+	}
+	/**
+	* Resolve once any in-flight connection attempt settles (success or
+	* failure). Resolves immediately when no attempt is in progress. Never
+	* rejects — callers only care that the attempt is done.
+	*/
+	async whenSettled() {
+		const pending = this.connectPromise;
+		if (!pending) return;
+		await pending.catch(() => {});
+	}
 	async connect() {
 		if (this.connected) return;
 		if (this.connectPromise) return this.connectPromise;
@@ -3100,7 +3371,20 @@ var ContainerControlConnection = class {
 			this.connectPromise = null;
 		}
 	}
-	disconnect() {
+	/**
+	* Tear down the connection. `cause` (a lifecycle teardown reason from the
+	* owning DO) is used only for the disconnect trace event here; the owner
+	* is responsible for stamping it as a *weak* connection cause (one that
+	* never overwrites an authoritative failure already captured from a
+	* connection attempt), since a teardown is usually a downstream
+	* consequence of that earlier failure rather than the root cause.
+	*/
+	disconnect(cause) {
+		if (cause !== void 0) traceEvent("sandbox.rpc.disconnect", {
+			...this.spanAttrs(),
+			reason: cause instanceof Error ? cause.message : String(cause)
+		});
+		else traceEvent("sandbox.rpc.disconnect", this.spanAttrs());
 		try {
 			this.stub[Symbol.dispose]?.();
 		} catch {}
@@ -3124,6 +3408,19 @@ var ContainerControlConnection = class {
 		this.retryTimeoutMs = ms;
 	}
 	/**
+	* Base span attributes for this connection: the container port plus the
+	* sandbox identifiers (`sandbox.id` = DO id, `sandbox.name` = user name)
+	* when available.
+	*/
+	spanAttrs() {
+		const info = this.getSandboxInfo?.();
+		return {
+			"sandbox.rpc.port": this.port,
+			"sandbox.id": info?.id,
+			"sandbox.name": info?.name
+		};
+	}
+	/**
 	* Run the owner-provided `onClose` callback exactly once per call,
 	* swallowing any errors so a buggy listener can't keep the connection
 	* object in a half-torn-down state.
@@ -3137,6 +3434,18 @@ var ContainerControlConnection = class {
 		}
 	}
 	/**
+	* Run the owner-provided `onConnectionError` callback, swallowing any
+	* listener errors.
+	*/
+	fireConnectionError(error) {
+		if (!this.onConnectionError) return;
+		try {
+			this.onConnectionError(error);
+		} catch (err) {
+			this.logger.warn("ContainerControlConnection onConnectionError handler threw", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	/**
 	* WebSocket `close` listener. Defined as a bound arrow field so the
 	* same reference can be passed to both `addEventListener` and
 	* `removeEventListener` — a fresh anonymous lambda would silently
@@ -3160,6 +3469,9 @@ var ContainerControlConnection = class {
 		if (wasConnected) this.fireOnClose();
 	};
 	async doConnect() {
+		return withSpan("sandbox.rpc.connect", this.spanAttrs(), () => this.doConnectInner());
+	}
+	async doConnectInner() {
 		try {
 			const response = await this.fetchUpgradeWithRetry();
 			if (response.status !== 101) {
@@ -3186,13 +3498,20 @@ var ContainerControlConnection = class {
 			this.ws = ws;
 			this.transport.activate(ws);
 			this.connected = true;
+			try {
+				this.onConnected?.();
+			} catch (err) {
+				this.logger.warn("ContainerControlConnection onConnected handler threw", { error: err instanceof Error ? err.message : String(err) });
+			}
 			this.logger.debug("ContainerControlConnection established", { port: this.port });
 		} catch (error) {
 			this.connected = false;
-			this.transport.abort(error);
+			const connectionError = tryConvertPlatformUnavailable(error) ?? error;
+			this.fireConnectionError(connectionError);
+			this.transport.abort(connectionError);
 			this.fireOnClose();
-			this.logger.error("ContainerControlConnection failed", error instanceof Error ? error : new Error(String(error)));
-			throw error;
+			this.logger.error("ContainerControlConnection failed", connectionError instanceof Error ? connectionError : new Error(String(connectionError)));
+			throw connectionError;
 		}
 	}
 	/**
@@ -3206,30 +3525,56 @@ var ContainerControlConnection = class {
 			minTimeForRetryMs: MIN_TIME_FOR_RETRY_MS,
 			logger: this.logger,
 			retryLogMessage: "ContainerControlConnection upgrade returned retryable status, retrying",
-			shouldRetry: isRetryableWebSocketUpgradeResponse
+			shouldRetry: isRetryableWebSocketUpgradeResponse,
+			shouldRetryError: isPlatformUnavailableError
 		});
 	}
 	/**
-	* Single WebSocket-upgrade fetch attempt. Owns its own AbortController so
-	* each retry gets a fresh per-attempt connect timeout independent of the
-	* total retry budget.
+	* Single WebSocket-upgrade fetch attempt.
+	*
+	* Container start and the upgrade fetch have deliberately separate timeout
+	* scopes:
+	*
+	*   - `startContainer()` runs under the base `Container` class's own
+	*     instance-get / port-ready budget. It must NOT be cut short by the
+	*     per-attempt connect timeout: the base class only emits the
+	*     classifiable `NO_CONTAINER_INSTANCE_ERROR` after its internal budget
+	*     is exhausted, and it checks its abort signal *before* that throw
+	*     (see @cloudflare/containers `doStartContainer`). Aborting it early
+	*     yields a generic "Aborted waiting for container to start" error that
+	*     we can't classify — which is what masked the real cause as
+	*     OPERATION_INTERRUPTED. Letting it run its own budget means the
+	*     platform capacity failure throws here, in our retry loop, where
+	*     `shouldRetryError` retries it and `doConnect`'s catch converts it to
+	*     a typed ContainerUnavailableError.
+	*
+	*   - The WebSocket upgrade fetch gets its own fresh AbortController so
+	*     each retry has an independent connect timeout for the *upgrade only*.
 	*/
 	async fetchUpgradeAttempt() {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), DEFAULT_CONNECT_TIMEOUT_MS);
-		try {
-			const url = `http://localhost:${this.port}/rpc`;
-			const request = new Request(url, {
-				headers: {
-					Upgrade: "websocket",
-					Connection: "Upgrade"
-				},
-				signal: controller.signal
-			});
-			return await this.containerStub.fetch(request);
-		} finally {
-			clearTimeout(timeout);
-		}
+		return withSpan("sandbox.rpc.connect.attempt", this.spanAttrs(), async () => {
+			if (this.startContainer) try {
+				await this.startContainer();
+			} catch (error) {
+				this.fireConnectionError(tryConvertPlatformUnavailable(error) ?? error);
+				throw error;
+			}
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), DEFAULT_CONNECT_TIMEOUT_MS);
+			try {
+				const url = `http://localhost:${this.port}/rpc`;
+				const request = new Request(url, {
+					headers: {
+						Upgrade: "websocket",
+						Connection: "Upgrade"
+					},
+					signal: controller.signal
+				});
+				return await this.containerStub.fetch(request);
+			} finally {
+				clearTimeout(timeout);
+			}
+		});
 	}
 };
 /**
@@ -3350,6 +3695,9 @@ function translateRPCError(error, context = {}) {
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
 		const transportResponse = buildTransportErrorResponse(error);
+		const captured = maybePreferConnectionError(transportResponse, context);
+		if (captured) throw captured;
+		if (context.sessionEstablished === false) throw createErrorFromResponse(buildNeverConnectedUnavailableResponse(transportResponse, context) ?? transportResponse, { cause: error });
 		throw createErrorFromResponse(buildInterruptedOperationResponse(transportResponse, context) ?? transportResponse, { cause: error });
 	}
 	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
@@ -3398,6 +3746,146 @@ function buildTransportErrorResponse(error) {
 		timestamp: (/* @__PURE__ */ new Date()).toISOString()
 	};
 }
+/**
+* Extract a recognized structured error shape from a captured connection cause.
+* Accepts both same-realm SandboxError instances and plain error-like objects
+* that carry a known `code` plus either `context` or `details`.
+*/
+function extractCapturedErrorShape(captured) {
+	if (captured instanceof SandboxError) return {
+		code: captured.code,
+		message: captured.message,
+		context: captured.context ?? {}
+	};
+	const shape = captured;
+	if (!shape || typeof shape.code !== "string" || !Object.hasOwn(ErrorCode, shape.code)) return null;
+	const code = shape.code;
+	const structured = shape.context && typeof shape.context === "object" ? shape.context : shape.details && typeof shape.details === "object" ? shape.details : {};
+	return {
+		code,
+		message: typeof shape.message === "string" ? shape.message : code,
+		context: structured
+	};
+}
+const OPERATION_INTERRUPTED_REASONS = new Set([
+	"runtime_replaced",
+	"transport_disposed",
+	"sandbox_lifetime_changed",
+	"recovery_exhausted"
+]);
+function asOperationInterruptedReason(value) {
+	return typeof value === "string" && OPERATION_INTERRUPTED_REASONS.has(value) ? value : null;
+}
+function asInterruptedAdmitted(value) {
+	if (typeof value === "boolean" || value === "unknown") return value;
+}
+/**
+* Lifecycle disconnect causes are stamped with a generic connection-level
+* operation identity. When they interrupt a concrete RPC method, rebind the
+* public interruption context onto that method while preserving the lifecycle
+* reason, retryability, and stop metadata.
+*/
+function rebindInterruptedOperationContext(shape, context, cause) {
+	if (shape.code !== ErrorCode.OPERATION_INTERRUPTED || typeof context.operation !== "string" || context.operation.length === 0) return createErrorFromResponse({
+		code: shape.code,
+		message: shape.message,
+		context: shape.context,
+		httpStatus: getHttpStatus(shape.code),
+		suggestion: getSuggestion(shape.code, shape.context),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, { cause });
+	const reason = asOperationInterruptedReason(shape.context.reason) ?? "transport_disposed";
+	const admitted = context.sessionEstablished === true ? true : context.sessionEstablished === false ? false : asInterruptedAdmitted(shape.context.admitted) ?? "unknown";
+	const retryable = typeof shape.context.retryable === "boolean" ? shape.context.retryable : false;
+	const interruptedContext = {
+		reason,
+		operation: context.operation,
+		phase: "rpc_call",
+		admitted,
+		retryable,
+		...typeof shape.context.recoveryAttempts === "number" && { recoveryAttempts: shape.context.recoveryAttempts },
+		...typeof shape.context.maxRecoveryAttempts === "number" && { maxRecoveryAttempts: shape.context.maxRecoveryAttempts },
+		...typeof shape.context.containerExitCode === "number" && { containerExitCode: shape.context.containerExitCode },
+		...typeof shape.context.stopReason === "string" && { stopReason: shape.context.stopReason }
+	};
+	return new OperationInterruptedError({
+		code: ErrorCode.OPERATION_INTERRUPTED,
+		message: shape.message,
+		context: interruptedContext,
+		httpStatus: getHttpStatus(ErrorCode.OPERATION_INTERRUPTED),
+		suggestion: getSuggestion(ErrorCode.OPERATION_INTERRUPTED, interruptedContext),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	}, { cause });
+}
+/**
+* When a queued RPC call rejects with a transport error that a connection
+* abort could have caused (session disposed, connection failed, upgrade
+* failed, or peer closed), and the connection captured a real startup or
+* lifecycle error, return that captured error in preference to the masking
+* transport error.
+*
+* The captured error is accepted whether it is:
+*   - a same-realm `SandboxError`, or
+*   - any structured, error-like value carrying a recognized `code` — e.g. a
+*     raw or cross-realm error decorated with `code: 'CONTAINER_UNAVAILABLE'`
+*     and optional `context`/`details`/`message`. Such values are rehydrated
+*     via `createErrorFromResponse` into a typed SandboxError.
+*
+* Lifecycle interruption causes are rebound onto the pending RPC method so the
+* public error names that operation and keeps the lifecycle reason,
+* retryability, and stop metadata.
+*
+* Anything without a recognized code is ignored so the caller falls back to
+* normal transport classification.
+*/
+function maybePreferConnectionError(transportResponse, context) {
+	const captured = context.connectionError;
+	if (!captured) return null;
+	const { kind } = transportResponse.context;
+	if (kind !== "session_disposed" && kind !== "connection_failed" && kind !== "upgrade_failed" && kind !== "peer_closed") return null;
+	const shape = extractCapturedErrorShape(captured);
+	if (!shape) return null;
+	return rebindInterruptedOperationContext(shape, context, captured);
+}
+/**
+* When the session never established a live connection and a queued RPC call
+* rejects with a teardown-family transport error (disposed / connection
+* failed / peer closed), surface a clean, retryable `ContainerUnavailableError`
+* instead of the raw capnweb string (e.g. "RPC session was shut down by
+* disposing the main stub").
+*
+* Reaching this point means: the container never became reachable (so no
+* OPERATION_INTERRUPTED — nothing was admitted) AND no structured connection
+* error was captured (so `maybePreferConnectionError` didn't fire). That's the
+* Durable Object being torn down/evicted mid-startup under capacity pressure
+* before `doConnect` recorded a cause — which is, from the caller's view, the
+* container being unavailable. Retryable, with the raw transport message
+* preserved as `originalMessage` for diagnostics.
+*
+* `upgrade_failed` is intentionally excluded here. Unlike disposal/close
+* during startup, an HTTP upgrade failure with no captured structured cause can
+* be a permanent configuration or routing error (for example, a 404 on `/rpc`),
+* so the generic transport classification is more accurate than retryable
+* container unavailability.
+*/
+function buildNeverConnectedUnavailableResponse(transportResponse, context) {
+	if (context.sessionEstablished !== false) return null;
+	const { kind } = transportResponse.context;
+	if (kind !== "session_disposed" && kind !== "connection_failed" && kind !== "peer_closed") return null;
+	const ctx = {
+		reason: "container_unreachable",
+		retryable: true,
+		originalMessage: transportResponse.context.originalMessage
+	};
+	return {
+		code: ErrorCode.CONTAINER_UNAVAILABLE,
+		message: "The sandbox container was unavailable: the connection was torn down before it became reachable. Retry the operation.",
+		context: ctx,
+		httpStatus: getHttpStatus(ErrorCode.CONTAINER_UNAVAILABLE),
+		suggestion: getSuggestion(ErrorCode.CONTAINER_UNAVAILABLE, ctx),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
 function buildInterruptedOperationResponse(transportResponse, context) {
 	if (!context.operation) return null;
 	const { kind } = transportResponse.context;
@@ -3406,7 +3894,7 @@ function buildInterruptedOperationResponse(transportResponse, context) {
 		reason: kind === "session_disposed" ? "transport_disposed" : "runtime_replaced",
 		operation: context.operation,
 		phase: "rpc_call",
-		admitted: "unknown",
+		admitted: context.sessionEstablished === true ? true : context.sessionEstablished === false ? false : "unknown",
 		retryable: false
 	};
 	const action = kind === "session_disposed" ? "was closing" : "closed unexpectedly";
@@ -3424,17 +3912,18 @@ function buildInterruptedOperationResponse(transportResponse, context) {
 * from the JSON wire format into typed SandboxError instances and signals
 * activity at call start.
 *
-* `onCallStarted` fires synchronously when an RPC method is invoked. The
-* 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.
+* `onCallStarted` fires synchronously when an RPC method is invoked, and
+* `onCallSettled` fires when the returned promise settles. The
+* ContainerControlClient uses these hooks to keep the session marked busy
+* even if capnweb stats briefly report the bootstrap baseline while a call is
+* still pending.
 *
-* Note: there is no `onCallSettled` hook. A method whose returned promise
-* resolves with a `ReadableStream` is *not* finished when the promise
-* settles — capnweb keeps the export alive until the stream ends. The
-* busy/idle poll on `getStats()` is the source of truth for that.
+* A method whose returned promise resolves with a `ReadableStream` is *not*
+* finished when the promise settles — capnweb keeps the export alive until
+* the stream ends. The busy/idle poll on `getStats()` remains the source of
+* truth for stream lifetimes after the initial RPC promise settles.
 */
-function wrapStub(stub, domain, onCallStarted) {
+function wrapStub(stub, domain, onCallStarted, onCallSettled, getConnectionError, getSessionEstablished, getSpanAttrs) {
 	return new Proxy(stub, { get(target, prop, receiver) {
 		const value = Reflect.get(target, prop, receiver);
 		if (typeof value !== "function") return value;
@@ -3443,10 +3932,23 @@ function wrapStub(stub, domain, 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((err) => translateRPCError(err, { operation }));
+				if (result != null && typeof result.then === "function") return withSpan(`sandbox.rpc.call ${operation}`, {
+					...getSpanAttrs(),
+					operation
+				}, () => result.catch((err) => translateRPCError(err, {
+					operation,
+					connectionError: getConnectionError(),
+					sessionEstablished: getSessionEstablished()
+				}))).finally(onCallSettled);
+				onCallSettled();
 				return result;
 			} catch (err) {
-				translateRPCError(err, { operation });
+				onCallSettled();
+				translateRPCError(err, {
+					operation,
+					connectionError: getConnectionError(),
+					sessionEstablished: getSessionEstablished()
+				});
 			}
 		};
 	} });
@@ -3473,8 +3975,34 @@ var ContainerControlClient = class {
 	onSessionBusy;
 	onSessionIdle;
 	conn = null;
+	/**
+	* Real cause captured by the connection during startup failure (e.g. a
+	* platform container-allocation error). Preferred over the generic capnweb
+	* disposal error when translating queued RPC rejections. Cleared each time a
+	* fresh connection is created.
+	*/
+	lastConnectionError = null;
+	/**
+	* Whether `lastConnectionError` was captured from an actual connection
+	* attempt failure (authoritative root cause) rather than a lifecycle
+	* teardown reason (weak). A weak teardown cause — e.g. `onStop` firing
+	* `runtime_replaced` — is usually a downstream *consequence* of the real
+	* failure, so it must not overwrite an authoritative cause already
+	* captured from the connect attempt.
+	*/
+	connectionErrorIsAuthoritative = false;
+	/**
+	* Whether the current connection ever established a live session to a
+	* running container. Set true by the connection's `onConnected` callback,
+	* reset when a fresh connection is created. Lets `translateRPCError`
+	* distinguish a true interruption (established, then dropped) from a
+	* never-connected failure (container never started).
+	*/
+	sessionEstablished = false;
 	idleTimer = null;
 	busyPollTimer = null;
+	/** Number of RPC method promises that have started but not settled. */
+	activeCalls = 0;
 	/** Tracks whether we currently believe the session is busy. */
 	busy = false;
 	constructor(options) {
@@ -3484,8 +4012,19 @@ var ContainerControlClient = class {
 			localMain: options.localMain,
 			logger: options.logger,
 			retryTimeoutMs: options.retryTimeoutMs,
+			getSandboxInfo: options.getSandboxInfo,
+			startContainer: options.startContainer,
+			onConnected: () => {
+				this.sessionEstablished = true;
+				this.lastConnectionError = null;
+				this.connectionErrorIsAuthoritative = false;
+			},
 			onClose: () => {
 				if (this.conn) this.destroyConnection();
+			},
+			onConnectionError: (error) => {
+				this.lastConnectionError = error;
+				this.connectionErrorIsAuthoritative = true;
 			}
 		};
 		this.idleDisconnectMs = options.idleDisconnectMs ?? DEFAULT_IDLE_DISCONNECT_MS;
@@ -3501,18 +4040,103 @@ var ContainerControlClient = class {
 	*/
 	getConnection() {
 		if (!this.conn) {
+			this.lastConnectionError = null;
+			this.connectionErrorIsAuthoritative = false;
+			this.sessionEstablished = false;
 			this.conn = new ContainerControlConnection(this.connOptions);
 			this.startBusyPoll();
 		}
 		return this.conn;
 	}
 	/**
+	* Stamp a *weak* connection cause (a lifecycle teardown reason). Only takes
+	* effect if no authoritative connect-attempt failure has been captured, so
+	* a teardown consequence never masks the real root cause.
+	*/
+	stampWeakConnectionCause(cause) {
+		if (cause === void 0) return;
+		if (this.connectionErrorIsAuthoritative) return;
+		this.lastConnectionError = cause;
+	}
+	fireUserCallback(name, callback) {
+		if (!callback) return;
+		try {
+			callback();
+		} catch (error) {
+			this.logger.warn("ContainerControlClient callback threw", {
+				callback: name,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	fireActivity() {
+		this.fireUserCallback("onActivity", this.onActivity);
+	}
+	fireSessionBusy() {
+		this.fireUserCallback("onSessionBusy", this.onSessionBusy);
+	}
+	fireSessionIdle() {
+		this.fireUserCallback("onSessionIdle", this.onSessionIdle);
+	}
+	markBusy() {
+		if (!this.busy) {
+			this.busy = true;
+			this.fireSessionBusy();
+		}
+		this.clearIdleTimer();
+	}
+	isSessionBusy(conn) {
+		const { imports, exports } = conn.getStats();
+		return this.activeCalls > 0 || imports > IDLE_IMPORT_THRESHOLD || exports > IDLE_EXPORT_THRESHOLD;
+	}
+	maybeTransitionIdle() {
+		const conn = this.conn;
+		if (!conn) return;
+		if (!conn.isConnected()) return;
+		this.transitionIdleIfReady(conn);
+	}
+	transitionIdleIfReady(conn) {
+		if (this.isSessionBusy(conn)) {
+			this.markBusy();
+			return;
+		}
+		if (this.busy) {
+			this.busy = false;
+			this.fireSessionIdle();
+			this.scheduleIdleDisconnect();
+		} else if (!this.idleTimer) this.scheduleIdleDisconnect();
+	}
+	/**
 	* Called synchronously at the start of each RPC method invocation.
 	* Renews the DO activity timeout so the sleepAfter alarm is pushed
-	* forward before the container processes the call.
+	* forward before the container processes the call, and pins the RPC
+	* WebSocket as busy until the method's promise settles.
+	*/
+	recordCallStarted = () => {
+		this.activeCalls++;
+		this.markBusy();
+		this.fireActivity();
+	};
+	recordCallSettled = () => {
+		this.activeCalls = Math.max(0, this.activeCalls - 1);
+		this.maybeTransitionIdle();
+	};
+	/** Return the last connection-startup error captured, if any. */
+	getLastConnectionError = () => this.lastConnectionError;
+	/** Whether the current connection ever established a live session. */
+	getSessionEstablished = () => this.sessionEstablished;
+	/**
+	* Base span attributes for RPC-call spans: sandbox identifiers plus the
+	* container port. Mirrors the connection's `spanAttrs()` so all
+	* `sandbox.rpc.*` spans share a consistent shape.
 	*/
-	renewActivity = () => {
-		this.onActivity?.();
+	getSpanAttrs = () => {
+		const info = this.connOptions.getSandboxInfo?.();
+		return {
+			"sandbox.id": info?.id,
+			"sandbox.name": info?.name,
+			"sandbox.rpc.port": this.connOptions.port !== void 0 ? String(this.connOptions.port) : void 0
+		};
 	};
 	/**
 	* Sample `getStats()` and update busy/idle state. While busy, renews the
@@ -3529,19 +4153,12 @@ var ContainerControlClient = class {
 		const conn = this.conn;
 		if (!conn) return;
 		if (!conn.isConnected()) return;
-		const { imports, exports } = conn.getStats();
-		if (imports > IDLE_IMPORT_THRESHOLD || exports > IDLE_EXPORT_THRESHOLD) {
-			if (!this.busy) {
-				this.busy = true;
-				this.onSessionBusy?.();
-			}
-			this.onActivity?.();
-			this.clearIdleTimer();
-		} else if (this.busy) {
-			this.busy = false;
-			this.onSessionIdle?.();
-			this.scheduleIdleDisconnect();
-		} else if (!this.idleTimer) this.scheduleIdleDisconnect();
+		if (this.isSessionBusy(conn)) {
+			this.markBusy();
+			this.fireActivity();
+			return;
+		}
+		this.transitionIdleIfReady(conn);
 	};
 	startBusyPoll() {
 		if (this.busyPollTimer) return;
@@ -3559,8 +4176,7 @@ var ContainerControlClient = class {
 			this.idleTimer = null;
 			const conn = this.conn;
 			if (!conn || !conn.isConnected()) return;
-			const { imports, exports } = conn.getStats();
-			if (imports <= IDLE_IMPORT_THRESHOLD && exports <= IDLE_EXPORT_THRESHOLD) {
+			if (!this.isSessionBusy(conn)) {
 				this.logger.debug("Disconnecting idle RPC connection");
 				this.destroyConnection();
 			}
@@ -3572,47 +4188,49 @@ var ContainerControlClient = class {
 			this.idleTimer = null;
 		}
 	}
-	destroyConnection() {
+	destroyConnection(cause) {
 		this.stopBusyPoll();
 		this.clearIdleTimer();
+		this.activeCalls = 0;
 		if (this.busy) {
 			this.busy = false;
-			this.onSessionIdle?.();
+			this.fireSessionIdle();
 		}
 		if (this.conn) {
-			this.conn.disconnect();
+			this.stampWeakConnectionCause(cause);
+			this.conn.disconnect(cause);
 			this.conn = null;
 		}
 	}
 	get commands() {
-		return wrapStub(this.getConnection().rpc().commands, "commands", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().commands, "commands", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get files() {
-		return wrapStub(this.getConnection().rpc().files, "files", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().files, "files", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get processes() {
-		return wrapStub(this.getConnection().rpc().processes, "processes", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().processes, "processes", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get ports() {
-		return wrapStub(this.getConnection().rpc().ports, "ports", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().ports, "ports", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get git() {
-		return wrapStub(this.getConnection().rpc().git, "git", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().git, "git", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get utils() {
-		return wrapStub(this.getConnection().rpc().utils, "utils", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().utils, "utils", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get backup() {
-		return wrapStub(this.getConnection().rpc().backup, "backup", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().backup, "backup", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get watch() {
-		return wrapStub(this.getConnection().rpc().watch, "watch", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().watch, "watch", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get tunnels() {
-		return wrapStub(this.getConnection().rpc().tunnels, "tunnels", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().tunnels, "tunnels", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	get interpreter() {
-		return wrapStub(this.getConnection().rpc().interpreter, "interpreter", this.renewActivity);
+		return wrapStub(this.getConnection().rpc().interpreter, "interpreter", this.recordCallStarted, this.recordCallSettled, this.getLastConnectionError, this.getSessionEstablished, this.getSpanAttrs);
 	}
 	/**
 	* Update the upgrade retry budget. Applies to the current connection
@@ -3632,8 +4250,42 @@ var ContainerControlClient = class {
 	async connect() {
 		await this.getConnection().connect();
 	}
-	disconnect() {
-		this.destroyConnection();
+	/**
+	* Tear down the active connection.
+	*
+	* When a connection attempt is still in progress, the teardown is deferred
+	* until that attempt settles — so a lifecycle disconnect (e.g. the DO's
+	* alarm firing `onStop`) cannot rip the transport out from under an
+	* in-flight connect and reject queued calls with a generic disposal error.
+	* The provided `cause` is stamped immediately so that if the attempt fails,
+	* queued calls surface it; if the attempt succeeds, the (now-established)
+	* connection is then torn down cleanly with the cause.
+	*
+	* During this deferral window `this.conn` still points at the connecting
+	* transport so queued calls can keep their original connection context.
+	* Container lifecycle code treats `disconnect()` as terminal and does not
+	* issue more RPC calls after requesting it.
+	*
+	* `cause` should be a typed `SandboxError` describing why the connection is
+	* being torn down (sandbox stopping, lifetime change, transport switch).
+	*/
+	disconnect(cause) {
+		const conn = this.conn;
+		if (conn?.isConnecting()) {
+			this.stopBusyPoll();
+			this.clearIdleTimer();
+			this.activeCalls = 0;
+			if (this.busy) {
+				this.busy = false;
+				this.fireSessionIdle();
+			}
+			this.stampWeakConnectionCause(cause);
+			conn.whenSettled().then(() => {
+				if (this.conn === conn) this.destroyConnection(cause);
+			});
+			return;
+		}
+		this.destroyConnection(cause);
 	}
 };
 
@@ -6487,7 +7139,7 @@ function createTunnelsHandler(host) {
 * 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.4";
+const SDK_VERSION = "0.12.5";
 
 //#endregion
 //#region src/sandbox.ts
@@ -6540,6 +7192,22 @@ const R2_DEFAULT_S3FS_OPTIONS = {
 const R2_DEFAULT_S3FS_OPTION_ENTRIES = Object.entries(R2_DEFAULT_S3FS_OPTIONS).map(([key, value]) => value === true ? key : `${key}=${value}`);
 const S3FS_DISABLE_EXPECT_HEADER_CONFIG = " Expect:\n";
 const BACKUP_DEFAULT_TTL_SECONDS = 259200;
+/**
+* Instance-get budget (ms) for the RPC transport's explicit container-start
+* hook, independent of the user-facing `containerTimeouts.instanceGetTimeoutMS`
+* (which still governs the HTTP path's `containerFetch`).
+*
+* Shorter than the SDK's user-facing 30s default, but long enough to match
+* the Containers platform's own 8s instance-get default. This keeps one RPC
+* start attempt from burning the full 30s under capacity pressure while still
+* letting ordinary 4-8s cold provisions succeed on the first attempt instead
+* of always paying the first backoff delay. The RPC control connection's own
+* retry loop (`fetchWithResponseRetry`, ~2 min budget with exponential
+* backoff) still owns cross-attempt retries. Once an instance exists,
+* `portReadyTimeoutMS` still governs app boot on the next attempt (the base
+* fast-path returns immediately when the container is already running).
+*/
+const RPC_START_INSTANCE_GET_TIMEOUT_MS = 8e3;
 const BACKUP_MAX_NAME_LENGTH = 256;
 const BACKUP_CONTAINER_DIR = "/var/backups";
 const BACKUP_STORAGE_PREFIX = "backups";
@@ -6949,6 +7617,11 @@ var Sandbox = class Sandbox extends Container {
 				port: 3e3,
 				logger: this.logger,
 				retryTimeoutMs: this.computeRetryTimeoutMs(),
+				getSandboxInfo: () => ({
+					id: this.ctx.id.toString(),
+					name: this.sandboxName ?? void 0
+				}),
+				startContainer: () => this.startContainerForRPC(),
 				localMain: this.controlCallback,
 				onActivity: () => {
 					this.renewActivityTimeout();
@@ -7069,7 +7742,7 @@ var Sandbox = class Sandbox extends Container {
 				this.tunnelsHandler = null;
 				this.tunnelExitHandler = null;
 				this.destroyAllTunnels = null;
-				previousClient.disconnect();
+				previousClient.disconnect(this.buildDisconnectCause("runtime_replaced", "The sandbox transport was switched while the operation was pending."));
 			}
 			if (storedTransport) this.hasStoredTransport = true;
 			const storedLabels = await this.ctx.storage.get("labels");
@@ -7154,7 +7827,7 @@ var Sandbox = class Sandbox extends Container {
 		this.tunnelsHandler = null;
 		this.tunnelExitHandler = null;
 		this.destroyAllTunnels = null;
-		previousClient.disconnect();
+		previousClient.disconnect(this.buildDisconnectCause("runtime_replaced", "The sandbox transport was switched while the operation was pending."));
 		this.renewActivityTimeout();
 		this.logger.debug("Transport updated", { transport });
 	}
@@ -7844,9 +8517,14 @@ var Sandbox = class Sandbox extends Container {
 			}
 			await this.ctx.storage.delete("tunnels");
 			await this.ctx.storage.delete("tunnels:meta");
-			this.client.disconnect();
+			this.client.disconnect(this.buildDisconnectCause("sandbox_lifetime_changed", "The sandbox was destroyed while the operation was pending."));
 			outcome = "success";
-			await super.destroy();
+			try {
+				await super.destroy();
+			} catch (error) {
+				if (!this.isNoInstanceError(error)) throw error;
+				this.logger.debug("super.destroy() reported no container instance; treating as no-op");
+			}
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
 			throw error;
@@ -7937,8 +8615,11 @@ var Sandbox = class Sandbox extends Container {
 			versionOutcome: outcome
 		}, { successLevel });
 	}
-	async onStop() {
-		this.logger.debug("Sandbox stopped");
+	async onStop(params) {
+		this.logger.debug("Sandbox stopped", {
+			exitCode: params?.exitCode,
+			reason: params?.reason
+		});
 		this.containerGeneration++;
 		this.defaultSession = null;
 		this.defaultSessionInit = null;
@@ -7949,7 +8630,7 @@ var Sandbox = class Sandbox extends Container {
 		} catch (error) {
 			this.logger.error("Failed to reconcile tunnel storage after container stop", error instanceof Error ? error : new Error(String(error)));
 		}
-		this.client.disconnect();
+		this.client.disconnect(this.buildDisconnectCause("runtime_replaced", "The sandbox container stopped while the operation was pending.", params));
 		let hadR2EgressMount = false;
 		let hadCredentialProxyMount = false;
 		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
@@ -7987,14 +8668,21 @@ var Sandbox = class Sandbox extends Container {
 				}
 			});
 		} catch (e) {
-			if (this.isNoInstanceError(e)) {
+			const admissionReason = matchContainerUnavailable(e);
+			if (admissionReason) {
+				const originalMessage = e instanceof Error ? e.message : String(e);
+				const context = {
+					reason: admissionReason,
+					retryable: true,
+					originalMessage
+				};
 				const errorBody$1 = {
-					code: ErrorCode.INTERNAL_ERROR,
-					message: "Container is currently provisioning. This can take several minutes on first deployment.",
-					context: { phase: "provisioning" },
+					code: ErrorCode.CONTAINER_UNAVAILABLE,
+					message: originalMessage,
+					context,
 					httpStatus: 503,
 					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-					suggestion: "This is expected during first deployment. The SDK will retry automatically."
+					suggestion: getSuggestion(ErrorCode.CONTAINER_UNAVAILABLE, context)
 				};
 				return new Response(JSON.stringify(errorBody$1), {
 					status: 503,
@@ -8085,7 +8773,105 @@ var Sandbox = class Sandbox extends Container {
 	* This indicates the container VM is still being provisioned.
 	*/
 	isNoInstanceError(error) {
-		return error instanceof Error && error.message.toLowerCase().includes("no container instance");
+		return matchContainerUnavailable(error) !== null;
+	}
+	/**
+	* Explicit container-start hook for the RPC transport.
+	*
+	* Runs `startAndWaitForPorts` under a short instance-get budget
+	* ({@link RPC_START_INSTANCE_GET_TIMEOUT_MS}) so a single attempt fails fast
+	* under capacity pressure — the base class throws the classifiable
+	* `NO_CONTAINER_INSTANCE_ERROR` once that budget is exhausted, and the RPC
+	* control connection's own retry loop (with backoff) owns cross-attempt
+	* retries. Port readiness still uses the full `portReadyTimeoutMS` so a
+	* genuinely-booting app isn't cut short once an instance exists.
+	*
+	* Always throws a typed `SandboxError` on failure so the control connection
+	* never surfaces a raw capnweb/transport string to the caller:
+	*   - container-admission/capacity failures → retryable
+	*     `ContainerUnavailableError` (preserving the platform message so the
+	*     connection's `shouldRetryError` still recognizes and retries it);
+	*   - anything else (platform-transient DO reset, network loss, unexpected
+	*     startup failure) → `INTERNAL_ERROR`-coded SandboxError carrying the
+	*     original message.
+	*/
+	async startContainerForRPC() {
+		try {
+			await this.startAndWaitForPorts({
+				ports: 3e3,
+				cancellationOptions: {
+					instanceGetTimeoutMS: RPC_START_INSTANCE_GET_TIMEOUT_MS,
+					portReadyTimeoutMS: this.containerTimeouts.portReadyTimeoutMS,
+					waitInterval: this.containerTimeouts.waitIntervalMS
+				}
+			});
+		} catch (error) {
+			throw this.toContainerStartError(error);
+		}
+	}
+	/**
+	* Convert a container-start failure into a typed SandboxError. Preserves an
+	* existing SandboxError as-is; maps platform admission/capacity failures to
+	* a retryable ContainerUnavailableError; and wraps everything else as an
+	* INTERNAL_ERROR carrying the original message (never a raw transport
+	* string).
+	*/
+	toContainerStartError(error) {
+		if (error instanceof SandboxError) return error;
+		const originalMessage = error instanceof Error ? error.message : String(error);
+		const admissionReason = matchContainerUnavailable(error);
+		if (admissionReason) {
+			const context$1 = {
+				reason: admissionReason,
+				retryable: true,
+				originalMessage
+			};
+			return createErrorFromResponse({
+				code: ErrorCode.CONTAINER_UNAVAILABLE,
+				message: originalMessage,
+				context: context$1,
+				httpStatus: getHttpStatus(ErrorCode.CONTAINER_UNAVAILABLE),
+				suggestion: getSuggestion(ErrorCode.CONTAINER_UNAVAILABLE, context$1),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			}, { cause: error });
+		}
+		const context = {
+			phase: "startup",
+			error: originalMessage
+		};
+		return createErrorFromResponse({
+			code: ErrorCode.INTERNAL_ERROR,
+			message: `Container failed to start: ${originalMessage}`,
+			context,
+			httpStatus: getHttpStatus(ErrorCode.INTERNAL_ERROR),
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		}, { cause: error });
+	}
+	/**
+	* Build a typed lifecycle cause to stamp on the RPC transport when the DO
+	* tears the connection down for its own reasons (container stopped, sandbox
+	* destroyed, transport switched). Handed to `client.disconnect(cause)` so
+	* any RPC calls queued on the transport reject with this actionable reason
+	* instead of the generic capnweb "disposing the main stub" message.
+	*/
+	buildDisconnectCause(reason, detail, stopParams) {
+		const context = {
+			reason,
+			operation: "rpc.connect",
+			phase: "connection",
+			admitted: "unknown",
+			retryable: reason === "runtime_replaced",
+			...stopParams?.exitCode !== void 0 && { containerExitCode: stopParams.exitCode },
+			...stopParams?.reason !== void 0 && { stopReason: stopParams.reason }
+		};
+		return new OperationInterruptedError({
+			code: ErrorCode.OPERATION_INTERRUPTED,
+			message: detail,
+			context,
+			httpStatus: getHttpStatus(ErrorCode.OPERATION_INTERRUPTED),
+			suggestion: getSuggestion(ErrorCode.OPERATION_INTERRUPTED, context),
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	/**
 	* Helper: Check if error is a transient startup error that should trigger retry
@@ -10734,4 +11520,4 @@ var Sandbox = class Sandbox extends Container {
 
 //#endregion
 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-CyqG4jca.js.map
+//# sourceMappingURL=sandbox-sU3r5LSr.js.map