@cloudflare/sandbox 0.12.4 → 0.12.6

package/dist/bridge/index.d.ts

@@ -49,6 +49,8 @@ interface BridgeEnv {
   SANDBOX_API_KEY?: string;
   WARM_POOL_TARGET?: string;
   WARM_POOL_REFRESH_INTERVAL?: string;
+  WARM_POOL_MAX_INSTANCES?: string;
+  WARM_POOL_SCALE_BATCH_SIZE?: string;
   [key: string]: unknown;
 }
 //#endregion
@@ -75,6 +77,20 @@ interface WarmPoolConfig {
   warmTarget?: number;
   /** How often to check and replenish warm containers (ms). @default 10000 */
   refreshInterval?: number;
+  /**
+   * Operator-declared max_instances ceiling, mirroring
+   * `containers[].max_instances` in wrangler.jsonc. Seeds the pool's capacity
+   * math so it never blindly attempts doomed starts. 0/undefined = auto-learn
+   * the ceiling reactively from platform errors (legacy behaviour).
+   * @default 0
+   */
+  maxInstances?: number;
+  /**
+   * Number of containers to start in parallel per scale-up batch. Higher
+   * values fill the pool faster but risk the platform throttling a cold-start
+   * stampede. Clamped to [1, MAX_BATCH_SIZE]. @default 5
+   */
+  scaleBatchSize?: number;
 }
 interface PoolStats {
   /** Number of warm (unassigned) containers ready for use */
@@ -109,6 +125,13 @@ declare class WarmPool extends DurableObject<WarmPoolEnv> {
   private knownMaxInstances;
   private capacityExhausted;
   private initialized;
+  /** Guards against overlapping eager refills triggered by concurrent pops. */
+  private refillInFlight;
+  /**
+   * The currently in-flight eager refill, or null. Exposed for tests to await
+   * the otherwise fire-and-forget refill deterministically.
+   */
+  private refillPromise;
   /**
    * Get a container UUID for the given sandbox ID.
    * - If this ID already has an assigned container that's still running, return it.
@@ -139,6 +162,13 @@ declare class WarmPool extends DurableObject<WarmPoolEnv> {
    * Does not affect containers that are assigned to sandbox IDs.
    */
   shutdownPrewarmed(): Promise<void>;
+  /**
+   * Kick a non-blocking refill toward warmTarget. Debounced via refillInFlight
+   * so a burst of concurrent pops triggers at most one adjustPool sweep at a
+   * time; capacity is respected because adjustPool clamps to remainingCapacity.
+   * Errors are swallowed so a failed refill never rejects the triggering call.
+   */
+  private requestRefill;
   alarm(): Promise<void>;
   private init;
   private persist;

package/dist/bridge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bridge/types.ts","../../src/bridge/helpers.ts","../../src/bridge/warm-pool.ts","../../src/bridge/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AA6DgB,UAvCC,YAAA,CAuCD;EAEP;;;AAaT;;;;ICJgB,OAAA,CAAA,EAAU,MAAA;IAyBV;;;;AC7EhB;AAOA;AAWC;AA6CD;EAA4C,cAAA,CAAA,EAAA,MAAA;EA2BH;;;;;EAiFf,WAAA,CAAA,EAAA,MAAA;;;;;;;;UFzIT,cAAA;EGgCD,KAAA,EAAA,OAAM,EH9BT,OG8BS,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH5Bb,gBG4Ba,CAAA,EH3BjB,QG2BiB,GH3BN,OG2BM,CH3BE,QG2BF,CAAA;EACZ,SAAA,EAAA,UAAA,EH1BM,mBG0BN,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EHxBD,gBGwBC,CAAA,EAAA,IAAA,GHvBE,OGuBF,CAAA,IAAA,CAAA;EACC,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHZM,SAAA;;;;;;;;;;;AAAjB;;;;ACJA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAOA;AAmDU,iBDmBM,oBAAA,CClBL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFHhB,UExDA,cAAA,CFwDS;;;;ECJV,eAAU,CAAA,EAAA,MAAA;AAyB1B;UCtEiB,SAAA;;;EAPA;EAOA,QAAA,EAAA,MAAS;EAmDhB;EAKG,KAAA,EAAA,MAAS;EAAsB;EA2BH,MAAA,EA3E/B,QA2E+B,CA3EtB,cA2EsB,CAAA;EA6CG;EAYE,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UAzFpC,WAAA,CAKoB;EAAa,OAAA,EAJhC,sBAIgC;;;cAA9B,QAAA,SAAiB,cAAc;ECG5B,QAAA,MAAM;EACZ;EACC,QAAA,cAAA;EACQ;EAAhB,QAAA,WAAA;EAAe;;;;;;;;;;;mCDqBuB;;;;;;sCA6CG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBAUd;WAyBZ;;;;;;;;;;;;;;;;;;;;;;;;AAvMjB;AAWC;AA6CD;;;;;;;;;;AA+IiB,iBC5ID,MAAA,CD4IC,MAAA,EC3IP,cD2IO,EAAA,MAAA,CAAA,EC1IN,YD0IM,CAAA,ECzId,eDyIc,CCzIE,SDyIF,CAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bridge/types.ts","../../src/bridge/helpers.ts","../../src/bridge/warm-pool.ts","../../src/bridge/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AA6DgB,UAvCC,YAAA,CAuCD;EAEP;;;AAaT;;;;ICJgB,OAAA,CAAA,EAAU,MAAA;IAyBV;;;;AC7EhB;AAqBA;AAWC;AAoDD;EAA4C,cAAA,CAAA,EAAA,MAAA;EAoCH;;;;;EAqFf,WAAA,CAAA,EAAA,MAAA;;;;;;;;UF3KT,cAAA;EGgCD,KAAA,EAAA,OAAM,EH9BT,OG8BS,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH5Bb,gBG4Ba,CAAA,EH3BjB,QG2BiB,GH3BN,OG2BM,CH3BE,QG2BF,CAAA;EACZ,SAAA,EAAA,UAAA,EH1BM,mBG0BN,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EHxBD,gBGwBC,CAAA,EAAA,IAAA,GHvBE,OGuBF,CAAA,IAAA,CAAA;EACC,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHZM,SAAA;;;;;;;;;;;;;AAAjB;;;;ACJA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAqBA;AA0DU,iBDFM,oBAAA,CCGL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFxBhB,UExDA,cAAA,CFwDS;;;;ECJV,eAAU,CAAA,EAAA,MAAA;EAyBV;;;;AC7EhB;AAqBA;AAWC;EAoDY,YAAS,CAAA,EAAA,MAAA;EAAsB;;;;;EA0GxB,cAAA,CAAA,EAAA,MAAA;;AAeuB,UAxL1B,SAAA,CAwL0B;EA+Bd;EAyDZ,IAAA,EAAA,MAAA;EAjNa;EAAa,QAAA,EAAA,MAAA;;;;EClB3B,MAAA,EDrCN,QCqCY,CDrCH,cCqCG,CAAA;EACZ;EACC,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UDWD,WAAA;WACC;;;cAIE,QAAA,SAAiB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;mCAoCH;;;;;;sCAiDG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBA+Bd;;;;;;;;WAyDZ;;;;;;;;;;;;;;;;;;;;;;;;AAhRjB;AAWC;AAoDD;;;;;;;;;;AAiNiB,iBCnOD,MAAA,CDmOC,MAAA,EClOP,cDkOO,EAAA,MAAA,CAAA,ECjON,YDiOM,CAAA,EChOd,eDgOc,CChOE,SDgOF,CAAA"}

package/dist/bridge/index.js

@@ -1,25 +1,35 @@
 import "../dist-B_eXrP83.js";
 import "../errors-CpkKPbWC.js";
-import { S as validateTunnelName, r as getSandbox, w as streamFile, x as validatePort, y as SandboxSecurityError } from "../sandbox-CyqG4jca.js";
-import { DurableObject, env } from "cloudflare:workers";
+import { S as validateTunnelName, r as getSandbox, w as streamFile, x as validatePort, y as SandboxSecurityError } from "../sandbox-FBmZ9mj1.js";
+import { DurableObject, env, tracing } from "cloudflare:workers";
 import { Hono } from "hono";
 
 //#region src/bridge/pool.ts
 /**
+* Parse warm-pool configuration from bridge env vars.
+*
+* `WARM_POOL_MAX_INSTANCES` should match `containers[].max_instances` in
+* wrangler.jsonc. 0/unset means auto-learn the ceiling reactively.
+*/
+function parsePoolConfig(env$1) {
+	return {
+		warmTarget: Number.parseInt(env$1.WARM_POOL_TARGET || "0", 10) || 0,
+		refreshInterval: Number.parseInt(env$1.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4,
+		maxInstances: Number.parseInt(env$1.WARM_POOL_MAX_INSTANCES || "0", 10) || 0,
+		scaleBatchSize: Number.parseInt(env$1.WARM_POOL_SCALE_BATCH_SIZE || "5", 10) || 5
+	};
+}
+/**
 * Prime the warm pool — pushes current configuration to the WarmPool
 * Durable Object so it starts its alarm loop.
 *
 * Called by the scheduled() handler and by POST /pool/prime.
 */
 async function primePool(env$1, warmPoolBinding) {
-	const warmTarget = Number.parseInt(env$1.WARM_POOL_TARGET || "0", 10) || 0;
-	const refreshInterval = Number.parseInt(env$1.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+	const config = parsePoolConfig(env$1);
 	const ns = env$1[warmPoolBinding];
 	const poolId = ns.idFromName("global-pool");
-	await ns.get(poolId).configure({
-		warmTarget,
-		refreshInterval
-	});
+	await ns.get(poolId).configure(config);
 }
 
 //#endregion
@@ -1761,6 +1771,51 @@ function esc(s) {
 	return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+//#endregion
+//#region src/bridge/tracing.ts
+/**
+* Custom span instrumentation for the bridge API.
+*
+* Wraps each Hono route handler in a Cloudflare custom span
+* (`tracing.enterSpan`) named `bridge.<operation>`, seeding common attributes
+* (sandbox ID, container UUID, HTTP method/route, response status) and exposing
+* the active span so handlers can attach operation-specific metadata.
+*
+* See https://developers.cloudflare.com/workers/observability/traces/custom-spans/
+*/
+/** True when the runtime exposes the custom-span API. */
+function tracingAvailable() {
+	return typeof tracing === "object" && tracing !== null && typeof tracing.enterSpan === "function";
+}
+/**
+* Wrap a route handler in a `bridge.<name>` span. Seeds common attributes and
+* stashes the span on the context for `annotate()`. When tracing is
+* unavailable the handler runs unchanged.
+*/
+function traced(name, handler) {
+	if (!tracingAvailable()) return handler;
+	return (c) => tracing.enterSpan(`bridge.${name}`, async (span) => {
+		span.setAttribute("bridge.operation", name);
+		span.setAttribute("http.request.method", c.req.method);
+		span.setAttribute("http.route", c.req.routePath);
+		const sandboxId = c.req.param("id");
+		if (sandboxId) span.setAttribute("sandbox.id", sandboxId);
+		const containerUUID = c.get("containerUUID");
+		if (containerUUID) span.setAttribute("sandbox.container_uuid", containerUUID);
+		c.set("span", span);
+		const response = await handler(c);
+		span.setAttribute("http.response.status_code", response.status);
+		return response;
+	});
+}
+/**
+* Attach an attribute to the active bridge span, if any. No-op when tracing is
+* disabled or the request is not sampled.
+*/
+function annotate(c, key, value) {
+	c.get("span")?.setAttribute(key, value);
+}
+
 //#endregion
 //#region src/bridge/routes.ts
 /** Typed wrapper around the SDK's getSandbox() that returns a BridgeSandbox. */
@@ -1859,7 +1914,7 @@ function createBridgeApp(config) {
 		}
 		return next();
 	});
-	app.post(`${apiPrefix}/sandbox`, async (c) => {
+	app.post(`${apiPrefix}/sandbox`, traced("create_sandbox", async (c) => {
 		const token = c.env.SANDBOX_API_KEY;
 		if (token) {
 			const authHeader = c.req.header("Authorization") ?? "";
@@ -1868,20 +1923,16 @@ function createBridgeApp(config) {
 		const bytes = new Uint8Array(16);
 		crypto.getRandomValues(bytes);
 		const id = base32Encode(bytes);
+		annotate(c, "sandbox.id", id);
 		return c.json({ id });
-	});
+	}));
 	app.use(`${apiPrefix}/sandbox/:id/*`, async (c, next) => {
 		const sandboxId = c.req.param("id");
-		const warmTarget = Number.parseInt(c.env.WARM_POOL_TARGET || "0", 10) || 0;
-		const refreshInterval = Number.parseInt(c.env.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
 		const poolNs = getWarmPoolNs(c.env);
 		const poolId = poolNs.idFromName("global-pool");
 		const poolStub = poolNs.get(poolId);
 		try {
-			await poolStub.configure({
-				warmTarget,
-				refreshInterval
-			});
+			await poolStub.configure(parsePoolConfig(c.env));
 			const containerUUID = await poolStub.getContainer(sandboxId);
 			c.set("containerUUID", containerUUID);
 		} catch (err) {
@@ -1906,7 +1957,7 @@ function createBridgeApp(config) {
 		}
 		return next();
 	});
-	app.post(`${apiPrefix}/sandbox/:id/exec`, async (c) => {
+	app.post(`${apiPrefix}/sandbox/:id/exec`, traced("exec", async (c) => {
 		let body;
 		try {
 			body = await c.req.json();
@@ -1914,21 +1965,28 @@ function createBridgeApp(config) {
 			return errorJson("Invalid JSON body", "invalid_request", 400);
 		}
 		if (!Array.isArray(body.argv) || body.argv.length === 0) return errorJson("argv must be a non-empty array", "invalid_request", 400);
+		annotate(c, "exec.argv_count", body.argv.length);
+		if (body.argv[0]) annotate(c, "exec.command", body.argv[0]);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		const rawSessionId = c.req.header("Session-Id");
 		let executor = sandbox;
 		if (rawSessionId) {
 			const sessionId = validateSessionId(rawSessionId);
 			if (!sessionId) return errorJson("Invalid session ID format", "invalid_request", 400);
+			annotate(c, "session.id", sessionId);
 			executor = await sandbox.getSession(sessionId);
 		}
 		const command = body.argv.map(shellQuote).join(" ");
 		const opts = {};
-		if (typeof body.timeout_ms === "number") opts.timeout = body.timeout_ms;
+		if (typeof body.timeout_ms === "number") {
+			opts.timeout = body.timeout_ms;
+			annotate(c, "exec.timeout_ms", body.timeout_ms);
+		}
 		if (typeof body.cwd === "string") {
 			const resolvedCwd = resolveWorkspacePath(body.cwd);
 			if (!resolvedCwd) return errorJson("cwd must resolve to a location within /workspace", "invalid_request", 403);
 			opts.cwd = resolvedCwd;
+			annotate(c, "exec.cwd", resolvedCwd);
 		}
 		const { readable, writable } = new TransformStream();
 		const writer = writable.getWriter();
@@ -1978,8 +2036,8 @@ function createBridgeApp(config) {
 				"Cache-Control": "no-cache"
 			}
 		});
-	});
-	app.get(`${apiPrefix}/sandbox/:id/file/*`, async (c) => {
+	}));
+	app.get(`${apiPrefix}/sandbox/:id/file/*`, traced("read_file", async (c) => {
 		const sandboxId = c.req.param("id");
 		const fullPath = c.req.path;
 		const marker = `${apiPrefix}/sandbox/${sandboxId}/file/`;
@@ -1987,12 +2045,14 @@ function createBridgeApp(config) {
 		if (!relativePath) return errorJson("file path must not be empty", "invalid_request", 400);
 		const resolvedPath = resolveWorkspacePath(`/${relativePath}`);
 		if (!resolvedPath) return errorJson("path must resolve to a location within /workspace", "invalid_request", 403);
+		annotate(c, "file.path", resolvedPath);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		const rawSessionId = c.req.header("Session-Id");
 		let executor = sandbox;
 		if (rawSessionId) {
 			const sessionId = validateSessionId(rawSessionId);
 			if (!sessionId) return errorJson("Invalid session ID format", "invalid_request", 400);
+			annotate(c, "session.id", sessionId);
 			executor = await sandbox.getSession(sessionId);
 		}
 		try {
@@ -2005,8 +2065,8 @@ function createBridgeApp(config) {
 			if (err.code === "FILE_NOT_FOUND") return errorJson(`File not found: ${resolvedPath}`, "workspace_read_not_found", 404);
 			return errorJson(`read failed: ${err instanceof Error ? err.message : String(err)}`, "exec_transport_error", 502);
 		}
-	});
-	app.put(`${apiPrefix}/sandbox/:id/file/*`, async (c) => {
+	}));
+	app.put(`${apiPrefix}/sandbox/:id/file/*`, traced("write_file", async (c) => {
 		const sandboxId = c.req.param("id");
 		const fullPath = c.req.path;
 		const marker = `${apiPrefix}/sandbox/${sandboxId}/file/`;
@@ -2014,16 +2074,19 @@ function createBridgeApp(config) {
 		if (!relativePath) return errorJson("file path must not be empty", "invalid_request", 400);
 		const resolvedPath = resolveWorkspacePath(`/${relativePath}`);
 		if (!resolvedPath) return errorJson("path must resolve to a location within /workspace", "invalid_request", 403);
+		annotate(c, "file.path", resolvedPath);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		const rawSessionId = c.req.header("Session-Id");
 		let executor = sandbox;
 		if (rawSessionId) {
 			const sessionId = validateSessionId(rawSessionId);
 			if (!sessionId) return errorJson("Invalid session ID format", "invalid_request", 400);
+			annotate(c, "session.id", sessionId);
 			executor = await sandbox.getSession(sessionId);
 		}
 		try {
 			const buffer = await c.req.arrayBuffer();
+			annotate(c, "file.size_bytes", buffer.byteLength);
 			const MAX_WRITE_BYTES = 32 * 1024 * 1024;
 			if (buffer.byteLength > MAX_WRITE_BYTES) return errorJson(`payload too large: ${buffer.byteLength} bytes exceeds the ${MAX_WRITE_BYTES}-byte limit`, "payload_too_large", 413);
 			const bytes = new Uint8Array(buffer);
@@ -2035,12 +2098,14 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`write failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
 		}
-	});
-	app.post(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/sandbox/:id/tunnel/:port`, traced("tunnel_create", async (c) => {
 		const port = Number(c.req.param("port"));
 		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		annotate(c, "tunnel.port", port);
 		const options = parseTunnelOptions(await c.req.text());
 		if (options instanceof Response) return options;
+		if (options?.name) annotate(c, "tunnel.name", options.name);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		try {
 			const tunnel = await sandbox.tunnels.get(port, options);
@@ -2048,10 +2113,11 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
 		}
-	});
-	app.delete(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+	}));
+	app.delete(`${apiPrefix}/sandbox/:id/tunnel/:port`, traced("tunnel_destroy", async (c) => {
 		const port = Number(c.req.param("port"));
 		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		annotate(c, "tunnel.port", port);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		try {
 			await sandbox.tunnels.destroy(port);
@@ -2059,17 +2125,19 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
 		}
-	});
-	app.get(`${apiPrefix}/sandbox/:id/running`, async (c) => {
+	}));
+	app.get(`${apiPrefix}/sandbox/:id/running`, traced("running", async (c) => {
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		try {
 			await sandbox.exec("true");
+			annotate(c, "sandbox.running", true);
 			return c.json({ running: true });
 		} catch {
+			annotate(c, "sandbox.running", false);
 			return c.json({ running: false });
 		}
-	});
-	app.get(`${apiPrefix}/sandbox/:id/pty`, async (c) => {
+	}));
+	app.get(`${apiPrefix}/sandbox/:id/pty`, traced("pty", async (c) => {
 		const upgrade = c.req.header("Upgrade");
 		if (!upgrade || upgrade.toLowerCase() !== "websocket") return errorJson("WebSocket upgrade required", "invalid_request", 400);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
@@ -2080,26 +2148,33 @@ function createBridgeApp(config) {
 		const cols = colsParam ? Number(colsParam) : 80;
 		const rows = rowsParam ? Number(rowsParam) : 24;
 		if (Number.isNaN(cols) || Number.isNaN(rows)) return errorJson("cols and rows must be valid numbers", "invalid_request", 400);
+		annotate(c, "pty.cols", cols);
+		annotate(c, "pty.rows", rows);
 		const opts = {
 			cols,
 			rows
 		};
-		if (shell) opts.shell = shell;
+		if (shell) {
+			opts.shell = shell;
+			annotate(c, "pty.shell", shell);
+		}
 		try {
 			if (sessionId) {
 				const validatedId = validateSessionId(sessionId);
 				if (!validatedId) return errorJson("Invalid session ID format", "invalid_request", 400);
+				annotate(c, "session.id", validatedId);
 				return await (await sandbox.getSession(validatedId)).terminal(c.req.raw, opts);
 			}
 			return await sandbox.terminal(c.req.raw, opts);
 		} catch (err) {
 			return errorJson(`terminal failed: ${err instanceof Error ? err.message : String(err)}`, "exec_transport_error", 502);
 		}
-	});
-	app.post(`${apiPrefix}/sandbox/:id/persist`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/sandbox/:id/persist`, traced("persist", async (c) => {
 		const root = "/workspace";
 		const excludesParam = c.req.query("excludes") ?? "";
 		const excludes = excludesParam ? excludesParam.split(",").filter((s) => s.length > 0) : [];
+		annotate(c, "persist.exclude_count", excludes.length);
 		for (const ex of excludes) if (ex.includes("..")) return errorJson("exclude paths must not contain \"..\"", "invalid_request", 400);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		const tmpPath = `/tmp/sandbox-persist-${Date.now()}.tar`;
@@ -2117,8 +2192,8 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`persist failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_read_error", 502);
 		}
-	});
-	app.post(`${apiPrefix}/sandbox/:id/hydrate`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/sandbox/:id/hydrate`, traced("hydrate", async (c) => {
 		const root = "/workspace";
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		let tarBytes;
@@ -2128,6 +2203,7 @@ function createBridgeApp(config) {
 		} catch {
 			return errorJson("Could not read request body", "invalid_request", 400);
 		}
+		annotate(c, "hydrate.size_bytes", tarBytes.byteLength);
 		if (tarBytes.byteLength === 0) return errorJson("Empty tar payload", "invalid_request", 400);
 		const MAX_HYDRATE_BYTES = 32 * 1024 * 1024;
 		if (tarBytes.byteLength > MAX_HYDRATE_BYTES) return errorJson(`tar payload too large: ${tarBytes.byteLength} bytes exceeds the ${MAX_HYDRATE_BYTES}-byte limit`, "invalid_request", 400);
@@ -2144,8 +2220,8 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`hydrate failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
 		}
-	});
-	app.post(`${apiPrefix}/sandbox/:id/mount`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/sandbox/:id/mount`, traced("mount", async (c) => {
 		let body;
 		try {
 			body = await c.req.json();
@@ -2160,6 +2236,8 @@ function createBridgeApp(config) {
 		if (optionsError) return optionsError;
 		const bucketName = resolveMountBucketName(body);
 		if (bucketName instanceof Response) return bucketName;
+		annotate(c, "mount.bucket", bucketName);
+		annotate(c, "mount.path", body.mountPath);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		const sdkOptions = toSDKMountOptions(body.options);
 		try {
@@ -2168,8 +2246,8 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`mount failed: ${err instanceof Error ? err.message : String(err)}`, "mount_error", 502);
 		}
-	});
-	app.post(`${apiPrefix}/sandbox/:id/unmount`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/sandbox/:id/unmount`, traced("unmount", async (c) => {
 		let body;
 		try {
 			body = await c.req.json();
@@ -2180,6 +2258,7 @@ function createBridgeApp(config) {
 		if (!body.mountPath.startsWith("/")) return errorJson("mountPath must be an absolute path (start with /)", "invalid_request", 400);
 		const normalizedPath = new URL(body.mountPath, "file:///").pathname;
 		if (normalizedPath === "/") return errorJson("mountPath must not resolve to / (filesystem root)", "invalid_request", 400);
+		annotate(c, "mount.path", normalizedPath);
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), c.get("containerUUID"));
 		try {
 			await sandbox.unmountBucket(normalizedPath);
@@ -2191,31 +2270,35 @@ function createBridgeApp(config) {
 		} catch (err) {
 			return errorJson(`unmount failed: ${err instanceof Error ? err.message : String(err)}`, "unmount_error", 502);
 		}
-	});
-	app.post(`${apiPrefix}/sandbox/:id/session`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/sandbox/:id/session`, traced("session_create", async (c) => {
 		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
 		let body = {};
 		try {
 			body = await c.req.json();
 		} catch {}
+		if (body.cwd) annotate(c, "session.cwd", body.cwd);
 		try {
 			const session = await sandbox.createSession(body);
+			annotate(c, "session.id", session.id);
 			return c.json({ id: session.id });
 		} catch (err) {
 			return errorJson(`session create failed: ${err instanceof Error ? err.message : String(err)}`, "session_error", 502);
 		}
-	});
-	app.delete(`${apiPrefix}/sandbox/:id/session/:sid`, async (c) => {
+	}));
+	app.delete(`${apiPrefix}/sandbox/:id/session/:sid`, traced("session_delete", async (c) => {
 		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
 		const sid = c.req.param("sid");
+		if (!sid) return errorJson("session ID must not be empty", "invalid_request", 400);
+		annotate(c, "session.id", sid);
 		try {
 			const result = await sandbox.deleteSession(sid);
 			return c.json(result);
 		} catch (err) {
 			return errorJson(`session delete failed: ${err instanceof Error ? err.message : String(err)}`, "session_error", 502);
 		}
-	});
-	app.delete(`${apiPrefix}/sandbox/:id`, async (c) => {
+	}));
+	app.delete(`${apiPrefix}/sandbox/:id`, traced("destroy_sandbox", async (c) => {
 		const containerUUID = c.get("containerUUID");
 		const sandbox = getSandboxWithoutDefaultSession(getSandboxNs(c.env), containerUUID);
 		try {
@@ -2227,7 +2310,7 @@ function createBridgeApp(config) {
 			await poolNs.get(poolId).reportStopped(containerUUID);
 		} catch {}
 		return new Response(null, { status: 204 });
-	});
+	}));
 	app.get(config.healthPath, (c) => {
 		const errors = [];
 		if (!c.env[sandboxBinding]) errors.push(`Missing required Durable Object binding "${sandboxBinding}". Ensure your wrangler.jsonc has a binding named "${sandboxBinding}".`);
@@ -2246,40 +2329,34 @@ function createBridgeApp(config) {
 		}
 		return next();
 	});
-	app.get(`${apiPrefix}/pool/stats`, async (c) => {
-		const warmTarget = Number.parseInt(c.env.WARM_POOL_TARGET || "0", 10) || 0;
-		const refreshInterval = Number.parseInt(c.env.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+	app.get(`${apiPrefix}/pool/stats`, traced("pool_stats", async (c) => {
 		const poolNs = getWarmPoolNs(c.env);
 		const poolId = poolNs.idFromName("global-pool");
 		const poolStub = poolNs.get(poolId);
 		try {
-			await poolStub.configure({
-				warmTarget,
-				refreshInterval
-			});
+			await poolStub.configure(parsePoolConfig(c.env));
 		} catch {}
 		const stats = await poolStub.getStats();
+		annotate(c, "pool.warm", stats.warm);
+		annotate(c, "pool.assigned", stats.assigned);
+		annotate(c, "pool.total", stats.total);
+		if (stats.maxInstances !== null) annotate(c, "pool.max_instances", stats.maxInstances);
 		return c.json(stats);
-	});
-	app.post(`${apiPrefix}/pool/shutdown-prewarmed`, async (c) => {
-		const warmTarget = Number.parseInt(c.env.WARM_POOL_TARGET || "0", 10) || 0;
-		const refreshInterval = Number.parseInt(c.env.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+	}));
+	app.post(`${apiPrefix}/pool/shutdown-prewarmed`, traced("pool_shutdown_prewarmed", async (c) => {
 		const poolNs = getWarmPoolNs(c.env);
 		const poolId = poolNs.idFromName("global-pool");
 		const poolStub = poolNs.get(poolId);
 		try {
-			await poolStub.configure({
-				warmTarget,
-				refreshInterval
-			});
+			await poolStub.configure(parsePoolConfig(c.env));
 		} catch {}
 		await poolStub.shutdownPrewarmed();
 		return c.json({ ok: true });
-	});
-	app.post(`${apiPrefix}/pool/prime`, async (c) => {
+	}));
+	app.post(`${apiPrefix}/pool/prime`, traced("pool_prime", async (c) => {
 		await primePool(c.env, warmPoolBinding);
 		return c.json({ ok: true });
-	});
+	}));
 	const openapiAuth = async (c, next) => {
 		const token = c.env.SANDBOX_API_KEY;
 		if (token) {
@@ -2312,9 +2389,14 @@ function createBridgeApp(config) {
 * Configuration is pushed in via `configure()` on every request (idempotent)
 * so changes to wrangler vars take effect without manual intervention.
 */
+const DEFAULT_BATCH_SIZE = 5;
+/** Upper bound on parallel starts per batch to avoid a cold-start stampede. */
+const MAX_BATCH_SIZE = 20;
 const DEFAULT_CONFIG = {
 	warmTarget: 0,
-	refreshInterval: 1e4
+	refreshInterval: 1e4,
+	maxInstances: 0,
+	scaleBatchSize: DEFAULT_BATCH_SIZE
 };
 var WarmPool = class extends DurableObject {
 	config = { ...DEFAULT_CONFIG };
@@ -2328,6 +2410,13 @@ var WarmPool = class extends DurableObject {
 	knownMaxInstances = null;
 	capacityExhausted = false;
 	initialized = false;
+	/** Guards against overlapping eager refills triggered by concurrent pops. */
+	refillInFlight = false;
+	/**
+	* The currently in-flight eager refill, or null. Exposed for tests to await
+	* the otherwise fire-and-forget refill deterministically.
+	*/
+	refillPromise = null;
 	/**
 	* Get a container UUID for the given sandbox ID.
 	* - If this ID already has an assigned container that's still running, return it.
@@ -2346,6 +2435,7 @@ var WarmPool = class extends DurableObject {
 			this.warmContainers.delete(containerUUID$1);
 			this.assignments.set(sandboxId, containerUUID$1);
 			await this.persist();
+			this.requestRefill();
 			return containerUUID$1;
 		}
 		if (this.remainingCapacity() <= 0) this.throwCapacityError();
@@ -2353,6 +2443,7 @@ var WarmPool = class extends DurableObject {
 		if (containerUUID) {
 			this.assignments.set(sandboxId, containerUUID);
 			await this.persist();
+			this.requestRefill();
 			return containerUUID;
 		}
 		if (this.capacityExhausted) this.throwCapacityError();
@@ -2400,6 +2491,11 @@ var WarmPool = class extends DurableObject {
 			...DEFAULT_CONFIG,
 			...config
 		};
+		this.config.scaleBatchSize = Math.min(MAX_BATCH_SIZE, Math.max(1, this.config.scaleBatchSize || DEFAULT_BATCH_SIZE));
+		if (this.config.maxInstances > 0) {
+			this.knownMaxInstances = this.knownMaxInstances === null ? this.config.maxInstances : Math.min(this.knownMaxInstances, this.config.maxInstances);
+			await this.ctx.storage.put("knownMaxInstances", this.knownMaxInstances);
+		}
 		await this.ctx.storage.put("config", this.config);
 	}
 	/**
@@ -2421,6 +2517,32 @@ var WarmPool = class extends DurableObject {
 		}
 		await this.persist();
 	}
+	/**
+	* Kick a non-blocking refill toward warmTarget. Debounced via refillInFlight
+	* so a burst of concurrent pops triggers at most one adjustPool sweep at a
+	* time; capacity is respected because adjustPool clamps to remainingCapacity.
+	* Errors are swallowed so a failed refill never rejects the triggering call.
+	*/
+	requestRefill() {
+		if (this.refillInFlight) return;
+		if (this.warmContainers.size >= this.config.warmTarget) return;
+		if (this.remainingCapacity() <= 0) return;
+		this.refillInFlight = true;
+		this.refillPromise = (async () => {
+			try {
+				await this.adjustPool();
+			} catch (error) {
+				console.error({
+					message: "Eager refill failed",
+					component: "warm-pool",
+					error
+				});
+			} finally {
+				this.refillInFlight = false;
+			}
+		})();
+		this.ctx.waitUntil(this.refillPromise);
+	}
 	async alarm() {
 		await this.init();
 		this.capacityExhausted = false;
@@ -2569,25 +2691,22 @@ var WarmPool = class extends DurableObject {
 				});
 				return;
 			}
+			const batchSize = this.config.scaleBatchSize;
 			console.info({
 				message: "Scaling up pool",
 				component: "warm-pool",
 				starting: toStart,
 				needed: diff,
-				capacity: this.remainingCapacity()
+				capacity: this.remainingCapacity(),
+				batchSize
 			});
-			for (let i = 0; i < toStart; i++) {
-				if (this.capacityExhausted) {
-					console.log({
-						message: "Capacity exhausted mid-loop, stopping further starts",
-						component: "warm-pool"
-					});
-					break;
-				}
-				const uuid = await this.startContainer();
-				if (uuid) this.warmContainers.add(uuid);
+			for (let i = 0; i < toStart && !this.capacityExhausted; i += batchSize) {
+				const n = Math.min(batchSize, toStart - i);
+				const results = await Promise.all(Array.from({ length: n }, () => this.startContainer()));
+				for (const uuid of results) if (uuid) this.warmContainers.add(uuid);
+				if (this.capacityExhausted) this.knownMaxInstances = this.warmContainers.size + this.assignments.size;
+				await this.persist();
 			}
-			await this.persist();
 		} else if (diff < 0) {
 			const excess = -diff;
 			console.info({