@cloudflare/sandbox 0.13.0-next.651.1 → 0.13.0-next.709.1

package/dist/bridge/index.js

@@ -1,6 +1,8 @@
-import "../dist-DF8sudAg.js";
-import "../errors-BG6NZiPD.js";
-import { S as validateTunnelName, r as getSandbox, w as streamFile, x as validatePort, y as SandboxSecurityError } from "../sandbox-BgwMBQ7S.js";
+import "../errors-CXR0xBpw.js";
+import "../errors-QYlSkVGz.js";
+import "../dist-Duor5GbS.js";
+import { g as validateTunnelName, h as validatePort, m as SandboxSecurityError, n as getSandbox$1, x as streamFile } from "../sandbox-Auuwfnur.js";
+import "../extensions-CFB2xHqY.js";
 import { DurableObject, env } from "cloudflare:workers";
 import { Hono } from "hono";
 
@@ -27,16 +29,6 @@ async function primePool(env$1, warmPoolBinding) {
 /**
 * Utility functions used by the bridge routes.
 */
-/**
-* UTF-8-safe base64 encoding.
-* btoa() only handles latin-1; encode to UTF-8 bytes first via TextEncoder.
-*/
-function toBase64(str) {
-	const bytes = new TextEncoder().encode(str);
-	let binary = "";
-	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-	return btoa(binary);
-}
 /** RFC 4648 base32 encoding (lowercase). Returns only [a-z2-7]. */
 function base32Encode(data) {
 	const alphabet = "abcdefghijklmnopqrstuvwxyz234567";
@@ -94,10 +86,10 @@ function resolveWorkspacePath(userPath) {
 	return null;
 }
 /**
-* Validate a session ID. Rejects path traversal, control chars, and excessive length.
+* Validate a terminal ID. Rejects path traversal, control chars, and excessive length.
 * Returns the validated ID or null if invalid.
 */
-function validateSessionId(id) {
+function validateTerminalId(id) {
 	if (!/^[a-zA-Z0-9._-]{1,128}$/.test(id)) return null;
 	if (id.includes("..")) return null;
 	return id;
@@ -108,24 +100,73 @@ function validateSessionId(id) {
 */
 function sseToByteStream(sse) {
 	const encoder = new TextEncoder();
-	return new ReadableStream({ async start(controller) {
-		try {
-			for await (const chunk of streamFile(sse)) controller.enqueue(chunk instanceof Uint8Array ? chunk : encoder.encode(chunk));
-			controller.close();
-		} catch (err) {
-			controller.error(err);
+	const iterator = streamFile(sse)[Symbol.asyncIterator]();
+	let finished = false;
+	async function finish(cancelSource) {
+		if (finished) return;
+		finished = true;
+		if (!cancelSource) return;
+		await iterator.return?.().catch(() => void 0);
+	}
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const result = await iterator.next();
+				if (result.done) {
+					await finish(false);
+					controller.close();
+					return;
+				}
+				controller.enqueue(result.value instanceof Uint8Array ? result.value : encoder.encode(result.value));
+			} catch (error) {
+				await finish(true);
+				controller.error(error);
+			}
+		},
+		async cancel() {
+			await finish(true);
+		}
+	}, { highWaterMark: 0 });
+}
+function withStreamCleanup(source, cleanup) {
+	const reader = source.getReader();
+	let finished = false;
+	async function finish(cancelSource) {
+		if (finished) return;
+		finished = true;
+		if (cancelSource) await reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+		await cleanup().catch(() => void 0);
+	}
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const result = await reader.read();
+				if (result.done) {
+					await finish(false);
+					controller.close();
+					return;
+				}
+				controller.enqueue(result.value);
+			} catch (error) {
+				await finish(true);
+				controller.error(error);
+			}
+		},
+		async cancel() {
+			await finish(true);
 		}
-	} });
+	}, { highWaterMark: 0 });
 }
 
 //#endregion
-//#region src/bridge/openapi.ts
+//#region src/bridge/openapi/common.ts
 /**
 * OpenAPI 3.1 schema for the Cloudflare Sandbox Service API.
 *
 * Served at GET /v1/openapi.json (requires Bearer token auth).
 */
-const OPENAPI_SCHEMA = {
+const OPENAPI_BASE = {
 	openapi: "3.1.0",
 	info: {
 		title: "Cloudflare Sandbox Service API",
@@ -139,7 +180,7 @@ const OPENAPI_SCHEMA = {
 			description: "API token set via `wrangler secret put SANDBOX_API_KEY`. The /openapi.* routes also accept the token as a `?token=` query parameter."
 		} },
 		schemas: {
-			ExecRequest: {
+			ProcessCreateRequest: {
 				type: "object",
 				required: ["argv"],
 				properties: {
@@ -147,25 +188,121 @@ const OPENAPI_SCHEMA = {
 						type: "array",
 						items: { type: "string" },
 						minItems: 1,
-						description: "Argv array — already shell-expanded by the Python layer if shell=True.",
+						description: "Argv array to launch directly.",
 						example: [
 							"sh",
 							"-lc",
 							"echo hello"
 						]
 					},
-					timeout_ms: {
+					timeout: {
 						type: "integer",
-						description: "Per-call timeout in milliseconds.",
+						description: "Remote process lifetime deadline in milliseconds. When reached, the sandbox may stop the process and the process exit outcome reports `timedOut: true`; this is not caller-local observation cancellation.",
 						example: 3e4
 					},
 					cwd: {
 						type: "string",
 						description: "Working directory for the command (defaults to sandbox cwd).",
 						example: "/workspace"
+					},
+					env: {
+						type: "object",
+						additionalProperties: { type: "string" },
+						description: "Environment overrides for the process."
 					}
 				}
 			},
+			ProcessStatus: {
+				oneOf: [
+					{
+						type: "object",
+						required: [
+							"id",
+							"pid",
+							"command",
+							"state",
+							"startedAt"
+						],
+						properties: {
+							id: { type: "string" },
+							pid: { type: "integer" },
+							command: {
+								type: "array",
+								items: { type: "string" }
+							},
+							cwd: { type: "string" },
+							state: { const: "running" },
+							startedAt: { type: "string" }
+						}
+					},
+					{
+						type: "object",
+						required: [
+							"id",
+							"pid",
+							"command",
+							"state",
+							"startedAt",
+							"endedAt",
+							"exit"
+						],
+						properties: {
+							id: { type: "string" },
+							pid: { type: "integer" },
+							command: {
+								type: "array",
+								items: { type: "string" }
+							},
+							cwd: { type: "string" },
+							state: { const: "exited" },
+							startedAt: { type: "string" },
+							endedAt: { type: "string" },
+							exit: {
+								type: "object",
+								required: ["code", "timedOut"],
+								properties: {
+									code: { type: "integer" },
+									signal: { type: "integer" },
+									timedOut: { type: "boolean" }
+								}
+							}
+						}
+					},
+					{
+						type: "object",
+						required: [
+							"id",
+							"pid",
+							"command",
+							"state",
+							"startedAt",
+							"endedAt",
+							"error"
+						],
+						properties: {
+							id: { type: "string" },
+							pid: { type: "integer" },
+							command: {
+								type: "array",
+								items: { type: "string" }
+							},
+							cwd: { type: "string" },
+							state: { const: "error" },
+							startedAt: { type: "string" },
+							endedAt: { type: "string" },
+							error: {
+								type: "object",
+								required: ["code", "message"],
+								properties: {
+									code: { type: "string" },
+									message: { type: "string" }
+								}
+							}
+						}
+					}
+				],
+				discriminator: { propertyName: "state" }
+			},
 			WriteResponse: {
 				type: "object",
 				required: ["ok"],
@@ -339,7 +476,6 @@ const OPENAPI_SCHEMA = {
 							"pool_error",
 							"mount_error",
 							"unmount_error",
-							"session_error",
 							"tunnel_error"
 						]
 					}
@@ -401,459 +537,106 @@ const OPENAPI_SCHEMA = {
 						code: "invalid_request"
 					}
 				} }
+			},
+			NotFound: {
+				description: "Requested resource was not found.",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "Process not found",
+						code: "not_found"
+					}
+				} }
+			},
+			BadGateway: {
+				description: "Sandbox operation failed.",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "process launch failed",
+						code: "process_error"
+					}
+				} }
 			}
 		}
 	},
-	security: [{ BearerAuth: [] }],
-	paths: {
-		"/v1/sandbox": { post: {
-			operationId: "createSandbox",
-			summary: "Create a new sandbox session",
-			description: "Generates a new unique sandbox ID. Use this ID with all `/v1/sandbox/{id}/*` routes.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/sandbox \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			responses: {
-				"200": {
-					description: "New sandbox session created.",
-					content: { "application/json": { schema: {
-						type: "object",
-						required: ["id"],
-						properties: { id: {
-							type: "string",
-							description: "Unique sandbox ID for use with `/v1/sandbox/{id}/*` routes.",
-							example: "mfrggzdfmy2tqnrzgezdgnbv"
-						} }
-					} } }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" }
-			}
-		} },
-		"/v1/sandbox/{id}/exec": { post: {
-			operationId: "execCommand",
-			summary: "Execute a command in the sandbox",
-			description: "Runs a shell command inside the named sandbox and streams output as Server-Sent Events (SSE). Events: `stdout` (base64 chunk), `stderr` (base64 chunk), `exit` (JSON with exit_code), `error` (JSON with error and code). The stream terminates after an `exit` or `error` event.",
+	security: [{ BearerAuth: [] }]
+};
+
+//#endregion
+//#region src/bridge/openapi/files.ts
+const FILESPaths = {
+	"/v1/sandbox/{id}/file/{path}": {
+		get: {
+			operationId: "readFile",
+			summary: "Read a file from the sandbox filesystem",
 			"x-codeSamples": [{
 				lang: "curl",
 				label: "cURL",
-				source: "curl -N -X POST https://$HOST/v1/sandbox/my-sandbox/exec \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"argv\":[\"sh\",\"-lc\",\"echo hello\"]}'"
+				source: "curl -X GET https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -o main.py"
 			}],
 			parameters: [{
 				name: "id",
 				in: "path",
 				required: true,
 				schema: { type: "string" },
-				description: "Sandbox instance name (maps to a Durable Object key)."
+				description: "Sandbox instance name."
 			}, {
-				name: "Session-Id",
-				in: "header",
-				required: false,
-				schema: {
-					type: "string",
-					pattern: "^[a-zA-Z0-9._-]{1,128}$"
-				},
-				description: "Scope this operation to a specific session. Uses the default session if omitted."
-			}],
-			requestBody: {
+				name: "path",
+				in: "path",
 				required: true,
-				content: { "application/json": { schema: { $ref: "#/components/schemas/ExecRequest" } } }
-			},
+				schema: { type: "string" },
+				description: "File path inside the sandbox, without leading slash (e.g. workspace/main.py). Must resolve within /workspace."
+			}],
 			responses: {
 				"200": {
-					description: "SSE stream of command output. Events:\n- `event: stdout` — data is a base64-encoded chunk of stdout\n- `event: stderr` — data is a base64-encoded chunk of stderr\n- `event: exit` — data is JSON `{\"exit_code\": N}` (terminal)\n- `event: error` — data is JSON `{\"error\": \"...\", \"code\": \"...\"}` (terminal)",
-					content: { "text/event-stream": { schema: { type: "string" } } }
+					description: "Raw file bytes.",
+					content: { "application/octet-stream": { schema: {
+						type: "string",
+						format: "binary"
+					} } }
 				},
 				"400": { $ref: "#/components/responses/InvalidRequest" },
 				"401": { $ref: "#/components/responses/Unauthorized" },
 				"403": {
-					description: "cwd resolves outside /workspace.",
+					description: "Path resolves outside /workspace.",
 					content: { "application/json": {
 						schema: { $ref: "#/components/schemas/ErrorResponse" },
 						example: {
-							error: "cwd must resolve to a location within /workspace",
+							error: "path must resolve to a location within /workspace",
 							code: "invalid_request"
 						}
 					} }
 				},
-				"502": {
-					description: "SDK transport error before the SSE stream could be established. Once the stream is open, errors are delivered as `event: error` SSE events instead.",
-					content: { "application/json": {
-						schema: { $ref: "#/components/schemas/ErrorResponse" },
-						example: {
-							error: "exec failed: connection reset",
-							code: "exec_transport_error"
-						}
-					} }
-				}
-			}
-		} },
-		"/v1/sandbox/{id}/tunnel/{port}": {
-			post: {
-				operationId: "createTunnel",
-				summary: "Create or reuse a tunnel for a sandbox port",
-				description: "Returns an existing tunnel for the port when one is already recorded, or provisions one when needed. The service must already be listening inside the sandbox. Omit `name` for an ephemeral `*.trycloudflare.com` tunnel, or pass `name` to choose the subdomain prefix for a named tunnel. Use a value such as `app`, not a full hostname.",
-				"x-codeSamples": [{
-					lang: "curl",
-					label: "Ephemeral tunnel",
-					source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-				}, {
-					lang: "curl",
-					label: "Named tunnel",
-					source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"app\"}'"
-				}],
-				parameters: [{
-					name: "id",
-					in: "path",
-					required: true,
-					schema: { type: "string" },
-					description: "Sandbox instance name."
-				}, {
-					name: "port",
-					in: "path",
-					required: true,
-					schema: {
-						type: "integer",
-						minimum: 1024,
-						maximum: 65535
-					},
-					description: "Container port to tunnel. Port 3000 is reserved."
-				}],
-				requestBody: {
-					required: false,
-					content: { "application/json": { schema: { $ref: "#/components/schemas/TunnelRequest" } } }
-				},
-				responses: {
-					"200": {
-						description: "Tunnel created or reused.",
-						content: { "application/json": { schema: { $ref: "#/components/schemas/Tunnel" } } }
-					},
-					"400": { $ref: "#/components/responses/InvalidRequest" },
-					"401": { $ref: "#/components/responses/Unauthorized" },
-					"502": {
-						description: "Tunnel creation failed.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "tunnel failed: cloudflared could not be found",
-								code: "tunnel_error"
-							}
-						} }
-					}
-				}
-			},
-			delete: {
-				operationId: "deleteTunnel",
-				summary: "Delete the tunnel for a sandbox port",
-				description: "Stops the tunnel process for the port and removes any named-tunnel Cloudflare resources tracked by the sandbox.",
-				"x-codeSamples": [{
-					lang: "curl",
-					label: "Delete tunnel",
-					source: "curl -X DELETE https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-				}],
-				parameters: [{
-					name: "id",
-					in: "path",
-					required: true,
-					schema: { type: "string" },
-					description: "Sandbox instance name."
-				}, {
-					name: "port",
-					in: "path",
-					required: true,
-					schema: {
-						type: "integer",
-						minimum: 1024,
-						maximum: 65535
-					},
-					description: "Container port whose tunnel should be deleted. Port 3000 is reserved."
-				}],
-				responses: {
-					"204": { description: "Tunnel deleted or already absent." },
-					"400": { $ref: "#/components/responses/InvalidRequest" },
-					"401": { $ref: "#/components/responses/Unauthorized" },
-					"502": {
-						description: "Tunnel deletion failed.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "tunnel failed: cleanup failed",
-								code: "tunnel_error"
-							}
-						} }
-					}
-				}
-			}
-		},
-		"/v1/sandbox/{id}/file/{path}": {
-			get: {
-				operationId: "readFile",
-				summary: "Read a file from the sandbox filesystem",
-				"x-codeSamples": [{
-					lang: "curl",
-					label: "cURL",
-					source: "curl -X GET https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -o main.py"
-				}],
-				parameters: [
-					{
-						name: "id",
-						in: "path",
-						required: true,
-						schema: { type: "string" },
-						description: "Sandbox instance name."
-					},
-					{
-						name: "path",
-						in: "path",
-						required: true,
-						schema: { type: "string" },
-						description: "File path inside the sandbox, without leading slash (e.g. workspace/main.py). Must resolve within /workspace."
-					},
-					{
-						name: "Session-Id",
-						in: "header",
-						required: false,
-						schema: {
-							type: "string",
-							pattern: "^[a-zA-Z0-9._-]{1,128}$"
-						},
-						description: "Scope this operation to a specific session. Uses the default session if omitted."
-					}
-				],
-				responses: {
-					"200": {
-						description: "Raw file bytes.",
-						content: { "application/octet-stream": { schema: {
-							type: "string",
-							format: "binary"
-						} } }
-					},
-					"400": { $ref: "#/components/responses/InvalidRequest" },
-					"401": { $ref: "#/components/responses/Unauthorized" },
-					"403": {
-						description: "Path resolves outside /workspace.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "path must resolve to a location within /workspace",
-								code: "invalid_request"
-							}
-						} }
-					},
-					"404": {
-						description: "File not found in the sandbox.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "File not found: /workspace/foo.txt",
-								code: "workspace_read_not_found"
-							}
-						} }
-					},
-					"502": {
-						description: "SDK read call failed.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "read failed: connection reset",
-								code: "exec_transport_error"
-							}
-						} }
-					}
-				}
-			},
-			put: {
-				operationId: "writeFile",
-				summary: "Write a file into the sandbox filesystem",
-				"x-codeSamples": [{
-					lang: "curl",
-					label: "cURL",
-					source: "curl -X PUT https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @main.py"
-				}],
-				parameters: [
-					{
-						name: "id",
-						in: "path",
-						required: true,
-						schema: { type: "string" },
-						description: "Sandbox instance name."
-					},
-					{
-						name: "path",
-						in: "path",
-						required: true,
-						schema: { type: "string" },
-						description: "File path inside the sandbox, without leading slash (e.g. workspace/main.py). Must resolve within /workspace."
-					},
-					{
-						name: "Session-Id",
-						in: "header",
-						required: false,
-						schema: {
-							type: "string",
-							pattern: "^[a-zA-Z0-9._-]{1,128}$"
-						},
-						description: "Scope this operation to a specific session. Uses the default session if omitted."
-					}
-				],
-				requestBody: {
-					required: true,
-					description: "Raw file content to write.",
-					content: { "application/octet-stream": { schema: {
-						type: "string",
-						format: "binary"
-					} } }
-				},
-				responses: {
-					"200": {
-						description: "File written successfully.",
-						content: { "application/json": { schema: { $ref: "#/components/schemas/WriteResponse" } } }
-					},
-					"400": { $ref: "#/components/responses/InvalidRequest" },
-					"401": { $ref: "#/components/responses/Unauthorized" },
-					"403": {
-						description: "Path resolves outside /workspace.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "path must resolve to a location within /workspace",
-								code: "invalid_request"
-							}
-						} }
-					},
-					"502": {
-						description: "SDK write call failed.",
-						content: { "application/json": {
-							schema: { $ref: "#/components/schemas/ErrorResponse" },
-							example: {
-								error: "write failed: connection reset",
-								code: "workspace_archive_write_error"
-							}
-						} }
-					}
-				}
-			}
-		},
-		"/v1/sandbox/{id}/pty": { get: {
-			operationId: "ptyTerminal",
-			summary: "Open a PTY terminal session via WebSocket",
-			description: "Upgrades the HTTP connection to a WebSocket and proxies it to a PTY shell inside the sandbox.\n\n**WebSocket frame protocol:**\n\n| Direction | Frame type | Content |\n|-----------|------------|--------------------------------------------------|\n| Client → Server | Binary | UTF-8 encoded keystrokes / input |\n| Server → Client | Binary | Terminal output (including ANSI escape sequences) |\n| Client → Server | Text (JSON) | Control messages, e.g. `{\"type\":\"resize\",\"cols\":120,\"rows\":30}` |\n| Server → Client | Text (JSON) | Status messages: `ready`, `exit`, `error` |\n\n**Status messages (server → client):**\n- `{\"type\":\"ready\"}` — PTY is accepting input\n- `{\"type\":\"exit\",\"code\":0,\"signal\":\"SIGTERM\"}` — PTY exited\n- `{\"type\":\"error\",\"message\":\"...\"}` — error occurred\n\nIf the client disconnects, the PTY stays alive; reconnecting replays buffered output.",
-			"x-codeSamples": [{
-				lang: "JavaScript",
-				label: "WebSocket",
-				source: "const ws = new WebSocket(\"wss://$HOST/v1/sandbox/my-sandbox/pty?cols=120&rows=30\");\nws.binaryType = \"arraybuffer\";\nws.onmessage = (e) => { /* handle binary output or JSON status */ };"
-			}],
-			parameters: [
-				{
-					name: "id",
-					in: "path",
-					required: true,
-					schema: { type: "string" },
-					description: "Sandbox instance name."
-				},
-				{
-					name: "cols",
-					in: "query",
-					required: false,
-					schema: {
-						type: "integer",
-						default: 80
-					},
-					description: "Terminal width in columns."
-				},
-				{
-					name: "rows",
-					in: "query",
-					required: false,
-					schema: {
-						type: "integer",
-						default: 24
-					},
-					description: "Terminal height in rows."
-				},
-				{
-					name: "shell",
-					in: "query",
-					required: false,
-					schema: { type: "string" },
-					description: "Shell binary to run (e.g. `/bin/bash`). Uses the container default if omitted."
-				},
-				{
-					name: "session",
-					in: "query",
-					required: false,
-					schema: { type: "string" },
-					description: "SDK session ID. If provided, the PTY is scoped to this session."
-				},
-				{
-					name: "Session-Id",
-					in: "header",
-					required: false,
-					schema: {
-						type: "string",
-						pattern: "^[a-zA-Z0-9._-]{1,128}$"
-					},
-					description: "Scope this operation to a specific session. Uses the default session if omitted."
-				}
-			],
-			responses: {
-				"101": { description: "WebSocket upgrade successful. Binary and text frames flow bidirectionally as described above." },
-				"400": {
-					description: "Missing `Upgrade: websocket` header or invalid query parameters.",
+				"404": {
+					description: "File not found in the sandbox.",
 					content: { "application/json": {
 						schema: { $ref: "#/components/schemas/ErrorResponse" },
 						example: {
-							error: "WebSocket upgrade required",
-							code: "invalid_request"
+							error: "File not found: /workspace/foo.txt",
+							code: "workspace_read_not_found"
 						}
 					} }
 				},
-				"401": { $ref: "#/components/responses/Unauthorized" },
 				"502": {
-					description: "SDK terminal() call failed.",
+					description: "SDK read call failed.",
 					content: { "application/json": {
 						schema: { $ref: "#/components/schemas/ErrorResponse" },
 						example: {
-							error: "terminal failed: connection reset",
+							error: "read failed: connection reset",
 							code: "exec_transport_error"
 						}
 					} }
 				}
 			}
-		} },
-		"/v1/sandbox/{id}/running": { get: {
-			operationId: "isSandboxRunning",
-			summary: "Check whether the sandbox container is alive",
-			description: "Executes a no-op command inside the sandbox. Always returns HTTP 200; inspect the `running` field.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X GET https://$HOST/v1/sandbox/my-sandbox/running \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			parameters: [{
-				name: "id",
-				in: "path",
-				required: true,
-				schema: { type: "string" },
-				description: "Sandbox instance name."
-			}],
-			responses: {
-				"200": {
-					description: "Liveness status (always returned, even when not running).",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/RunningResponse" } } }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" }
-			}
-		} },
-		"/v1/sandbox/{id}/persist": { post: {
-			operationId: "persistWorkspace",
-			summary: "Serialize the sandbox workspace to a tar archive",
-			description: "Archives the /workspace directory inside the sandbox and streams the resulting tar back as raw bytes.",
+		},
+		put: {
+			operationId: "writeFile",
+			summary: "Write a file into the sandbox filesystem",
 			"x-codeSamples": [{
 				lang: "curl",
 				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/persist \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -o workspace.tar"
+				source: "curl -X PUT https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @main.py"
 			}],
 			parameters: [{
 				name: "id",
@@ -862,63 +645,15 @@ const OPENAPI_SCHEMA = {
 				schema: { type: "string" },
 				description: "Sandbox instance name."
 			}, {
-				name: "excludes",
-				in: "query",
-				required: false,
-				schema: { type: "string" },
-				description: "Comma-separated list of relative paths to exclude from the archive.",
-				example: "__pycache__,.venv"
-			}],
-			responses: {
-				"200": {
-					description: "Raw tar archive bytes.",
-					content: { "application/octet-stream": { schema: {
-						type: "string",
-						format: "binary"
-					} } }
-				},
-				"400": {
-					description: "Invalid exclude paths (e.g. path traversal).",
-					content: { "application/json": {
-						schema: { $ref: "#/components/schemas/ErrorResponse" },
-						example: {
-							error: "exclude paths must not contain \"..\"",
-							code: "invalid_request"
-						}
-					} }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" },
-				"502": {
-					description: "tar command failed inside the sandbox.",
-					content: { "application/json": {
-						schema: { $ref: "#/components/schemas/ErrorResponse" },
-						example: {
-							error: "tar failed (exit 1): ...",
-							code: "workspace_archive_read_error"
-						}
-					} }
-				}
-			}
-		} },
-		"/v1/sandbox/{id}/hydrate": { post: {
-			operationId: "hydrateWorkspace",
-			summary: "Populate the sandbox workspace from a tar archive",
-			description: "Accepts a raw tar archive as the request body and extracts it into /workspace inside the sandbox.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/hydrate \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @workspace.tar"
-			}],
-			parameters: [{
-				name: "id",
+				name: "path",
 				in: "path",
 				required: true,
 				schema: { type: "string" },
-				description: "Sandbox instance name."
+				description: "File path inside the sandbox, without leading slash (e.g. workspace/main.py). Must resolve within /workspace."
 			}],
 			requestBody: {
 				required: true,
-				description: "Raw tar archive bytes.",
+				description: "Raw file content to write.",
 				content: { "application/octet-stream": { schema: {
 					type: "string",
 					format: "binary"
@@ -926,310 +661,707 @@ const OPENAPI_SCHEMA = {
 			},
 			responses: {
 				"200": {
-					description: "Archive extracted successfully.",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+					description: "File written successfully.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/WriteResponse" } } }
 				},
 				"400": { $ref: "#/components/responses/InvalidRequest" },
 				"401": { $ref: "#/components/responses/Unauthorized" },
-				"502": {
-					description: "tar extract failed inside the sandbox.",
+				"403": {
+					description: "Path resolves outside /workspace.",
 					content: { "application/json": {
 						schema: { $ref: "#/components/schemas/ErrorResponse" },
 						example: {
-							error: "tar extract failed (exit 1): ...",
-							code: "workspace_archive_write_error"
+							error: "path must resolve to a location within /workspace",
+							code: "invalid_request"
 						}
 					} }
-				}
-			}
-		} },
-		"/v1/sandbox/{id}/mount": { post: {
-			operationId: "mountBucket",
-			summary: "Mount an S3-compatible bucket into the container",
-			description: "Mounts an S3-compatible bucket (R2, S3, GCS, etc.) as a local directory via s3fs-FUSE. Credentials are optional — the SDK auto-detects from Worker secrets when omitted.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/mount \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"bucket\":\"my-bucket\",\"mountPath\":\"/mnt/data\",\"options\":{\"endpoint\":\"https://ACCT.r2.cloudflarestorage.com\"}}'"
-			}],
-			parameters: [{
-				name: "id",
-				in: "path",
-				required: true,
-				schema: { type: "string" },
-				description: "Sandbox instance name."
-			}],
-			requestBody: {
-				required: true,
-				content: { "application/json": { schema: { $ref: "#/components/schemas/MountBucketRequest" } } }
-			},
-			responses: {
-				"200": {
-					description: "Bucket mounted successfully.",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
 				},
-				"400": { $ref: "#/components/responses/InvalidRequest" },
-				"401": { $ref: "#/components/responses/Unauthorized" },
 				"502": {
-					description: "SDK mount call failed (invalid config, duplicate mount, or s3fs error).",
+					description: "SDK write call failed.",
 					content: { "application/json": {
 						schema: { $ref: "#/components/schemas/ErrorResponse" },
 						example: {
-							error: "mount failed: Mount path already in use",
-							code: "mount_error"
+							error: "write failed: connection reset",
+							code: "workspace_archive_write_error"
 						}
 					} }
 				}
 			}
-		} },
-		"/v1/sandbox/{id}/unmount": { post: {
-			operationId: "unmountBucket",
-			summary: "Unmount a previously mounted bucket",
-			description: "Unmounts a bucket filesystem that was previously mounted via `/v1/sandbox/{id}/mount`.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/unmount \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mountPath\":\"/mnt/data\"}'"
-			}],
-			parameters: [{
-				name: "id",
-				in: "path",
-				required: true,
-				schema: { type: "string" },
-				description: "Sandbox instance name."
-			}],
+		}
+	},
+	"/v1/sandbox/{id}/persist": { post: {
+		operationId: "persistWorkspace",
+		summary: "Serialize the sandbox workspace to a tar archive",
+		description: "Archives the /workspace directory inside the sandbox and streams the resulting tar back as raw bytes.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/persist \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -o workspace.tar"
+		}],
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Sandbox instance name."
+		}, {
+			name: "excludes",
+			in: "query",
+			required: false,
+			schema: { type: "string" },
+			description: "Comma-separated list of relative paths to exclude from the archive.",
+			example: "__pycache__,.venv"
+		}],
+		responses: {
+			"200": {
+				description: "Raw tar archive bytes.",
+				content: { "application/octet-stream": { schema: {
+					type: "string",
+					format: "binary"
+				} } }
+			},
+			"400": {
+				description: "Invalid exclude paths (e.g. path traversal).",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "exclude paths must not contain \"..\"",
+						code: "invalid_request"
+					}
+				} }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"502": {
+				description: "tar command failed inside the sandbox.",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "tar failed (exit 1): ...",
+						code: "workspace_archive_read_error"
+					}
+				} }
+			}
+		}
+	} },
+	"/v1/sandbox/{id}/hydrate": { post: {
+		operationId: "hydrateWorkspace",
+		summary: "Populate the sandbox workspace from a tar archive",
+		description: "Accepts a raw tar archive as the request body and extracts it into /workspace inside the sandbox.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/hydrate \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @workspace.tar"
+		}],
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Sandbox instance name."
+		}],
+		requestBody: {
+			required: true,
+			description: "Raw tar archive bytes.",
+			content: { "application/octet-stream": { schema: {
+				type: "string",
+				format: "binary"
+			} } }
+		},
+		responses: {
+			"200": {
+				description: "Archive extracted successfully.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+			},
+			"400": { $ref: "#/components/responses/InvalidRequest" },
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"502": {
+				description: "tar extract failed inside the sandbox.",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "tar extract failed (exit 1): ...",
+						code: "workspace_archive_write_error"
+					}
+				} }
+			}
+		}
+	} },
+	"/v1/sandbox/{id}/mount": { post: {
+		operationId: "mountBucket",
+		summary: "Mount an S3-compatible bucket into the container",
+		description: "Mounts an S3-compatible bucket (R2, S3, GCS, etc.) as a local directory via s3fs-FUSE. Credentials are optional — the SDK auto-detects from Worker secrets when omitted.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/mount \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"bucket\":\"my-bucket\",\"mountPath\":\"/mnt/data\",\"options\":{\"endpoint\":\"https://ACCT.r2.cloudflarestorage.com\"}}'"
+		}],
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Sandbox instance name."
+		}],
+		requestBody: {
+			required: true,
+			content: { "application/json": { schema: { $ref: "#/components/schemas/MountBucketRequest" } } }
+		},
+		responses: {
+			"200": {
+				description: "Bucket mounted successfully.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+			},
+			"400": { $ref: "#/components/responses/InvalidRequest" },
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"502": {
+				description: "SDK mount call failed (invalid config, duplicate mount, or s3fs error).",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "mount failed: Mount path already in use",
+						code: "mount_error"
+					}
+				} }
+			}
+		}
+	} },
+	"/v1/sandbox/{id}/unmount": { post: {
+		operationId: "unmountBucket",
+		summary: "Unmount a previously mounted bucket",
+		description: "Unmounts a bucket filesystem that was previously mounted via `/v1/sandbox/{id}/mount`.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/unmount \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mountPath\":\"/mnt/data\"}'"
+		}],
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Sandbox instance name."
+		}],
+		requestBody: {
+			required: true,
+			content: { "application/json": { schema: { $ref: "#/components/schemas/UnmountBucketRequest" } } }
+		},
+		responses: {
+			"200": {
+				description: "Bucket unmounted successfully.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+			},
+			"400": { $ref: "#/components/responses/InvalidRequest" },
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"502": {
+				description: "SDK unmount call failed (no active mount or unmount error).",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "unmount failed: No active mount found",
+						code: "unmount_error"
+					}
+				} }
+			}
+		}
+	} }
+};
+
+//#endregion
+//#region src/bridge/openapi/lifecycle.ts
+const LIFECYCLEPaths = {
+	"/v1/sandbox": { post: {
+		operationId: "createSandbox",
+		summary: "Create a new sandbox",
+		description: "Generates a new unique sandbox ID. Use this ID with all `/v1/sandbox/{id}/*` routes.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/sandbox \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+		}],
+		responses: {
+			"200": {
+				description: "New sandbox created.",
+				content: { "application/json": { schema: {
+					type: "object",
+					required: ["id"],
+					properties: { id: {
+						type: "string",
+						description: "Unique sandbox ID for use with `/v1/sandbox/{id}/*` routes.",
+						example: "mfrggzdfmy2tqnrzgezdgnbv"
+					} }
+				} } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} },
+	"/v1/sandbox/{id}": { delete: {
+		operationId: "deleteSandbox",
+		summary: "Destroy a sandbox instance (best-effort)",
+		description: "Calls destroy() on the sandbox Durable Object to release container resources. Best-effort: unknown sandbox IDs return 204 without allocating a container.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X DELETE https://$HOST/v1/sandbox/my-sandbox \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+		}],
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Sandbox instance name."
+		}],
+		responses: {
+			"204": { description: "Sandbox destroyed (best-effort). Container resources are released." },
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} },
+	"/health": { get: {
+		operationId: "healthCheck",
+		summary: "Worker health check",
+		description: "Simple liveness probe. Not protected by authentication.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl https://$HOST/health"
+		}],
+		security: [],
+		responses: { "200": {
+			description: "Worker is up.",
+			content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+		} }
+	} },
+	"/v1/openapi.json": { get: {
+		operationId: "getOpenApiSchema",
+		summary: "OpenAPI schema",
+		description: "Returns this OpenAPI 3.1 schema document.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl https://$HOST/v1/openapi.json \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+		}],
+		responses: {
+			"200": {
+				description: "OpenAPI schema document.",
+				content: { "application/json": { schema: { type: "object" } } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} },
+	"/v1/pool/stats": { get: {
+		operationId: "getPoolStats",
+		summary: "Pool statistics",
+		description: "Returns current warm pool statistics including warm/assigned counts and configuration.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl https://$HOST/v1/pool/stats \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+		}],
+		responses: {
+			"200": {
+				description: "Pool statistics.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/PoolStats" } } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} },
+	"/v1/pool/shutdown-prewarmed": { post: {
+		operationId: "shutdownPrewarmed",
+		summary: "Shutdown pre-warmed containers",
+		description: "Destroys all idle (unassigned) warm containers. Does not affect containers assigned to sandbox instances.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/pool/shutdown-prewarmed \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+		}],
+		responses: {
+			"200": {
+				description: "All pre-warmed containers destroyed.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} },
+	"/v1/pool/prime": { post: {
+		operationId: "primePool",
+		summary: "Prime the warm pool",
+		description: "Pushes the current pool configuration and starts the alarm loop. Called automatically by the cron trigger; can also be called manually after deploy.",
+		"x-codeSamples": [{
+			lang: "curl",
+			label: "cURL",
+			source: "curl -X POST https://$HOST/v1/pool/prime \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+		}],
+		responses: {
+			"200": {
+				description: "Pool primed successfully.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} }
+};
+
+//#endregion
+//#region src/bridge/openapi/processes.ts
+const sandboxIdParameter$1 = {
+	name: "id",
+	in: "path",
+	required: true,
+	schema: { type: "string" },
+	description: "Sandbox instance name."
+};
+const processIdParameter = {
+	name: "processId",
+	in: "path",
+	required: true,
+	schema: { type: "string" }
+};
+const processStatusResponse = {
+	description: "Process status.",
+	content: { "application/json": { schema: { $ref: "#/components/schemas/ProcessStatus" } } }
+};
+const PROCESSESPaths = {
+	"/v1/sandbox/{id}/processes": {
+		post: {
+			operationId: "createProcess",
+			summary: "Launch a sandbox process",
+			parameters: [sandboxIdParameter$1],
 			requestBody: {
 				required: true,
-				content: { "application/json": { schema: { $ref: "#/components/schemas/UnmountBucketRequest" } } }
+				content: { "application/json": { schema: { $ref: "#/components/schemas/ProcessCreateRequest" } } }
 			},
 			responses: {
-				"200": {
-					description: "Bucket unmounted successfully.",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
-				},
+				"200": processStatusResponse,
 				"400": { $ref: "#/components/responses/InvalidRequest" },
 				"401": { $ref: "#/components/responses/Unauthorized" },
-				"502": {
-					description: "SDK unmount call failed (no active mount or unmount error).",
-					content: { "application/json": {
-						schema: { $ref: "#/components/schemas/ErrorResponse" },
-						example: {
-							error: "unmount failed: No active mount found",
-							code: "unmount_error"
-						}
-					} }
-				}
+				"403": { $ref: "#/components/responses/InvalidRequest" },
+				"502": { $ref: "#/components/responses/BadGateway" }
 			}
-		} },
-		"/v1/sandbox/{id}": { delete: {
-			operationId: "deleteSandbox",
-			summary: "Destroy a sandbox instance (best-effort)",
-			description: "Calls destroy() on the sandbox Durable Object to release container resources. Best-effort: unknown sandbox IDs return 204 without allocating a container.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X DELETE https://$HOST/v1/sandbox/my-sandbox \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			parameters: [{
-				name: "id",
+		},
+		get: {
+			operationId: "listProcesses",
+			summary: "List sandbox processes",
+			parameters: [sandboxIdParameter$1],
+			responses: {
+				"200": {
+					description: "Process statuses.",
+					content: { "application/json": { schema: {
+						type: "array",
+						items: { $ref: "#/components/schemas/ProcessStatus" }
+					} } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		}
+	},
+	"/v1/sandbox/{id}/processes/{processId}": { get: {
+		operationId: "getProcess",
+		summary: "Get a sandbox process",
+		parameters: [sandboxIdParameter$1, processIdParameter],
+		responses: {
+			"200": processStatusResponse,
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"404": { $ref: "#/components/responses/NotFound" }
+		}
+	} },
+	"/v1/sandbox/{id}/processes/{processId}/logs": { get: {
+		operationId: "readProcessLogs",
+		summary: "Stream sandbox process logs",
+		description: "Returns Server-Sent Events. stdout/stderr event data is base64-encoded at the bridge boundary only.",
+		parameters: [
+			sandboxIdParameter$1,
+			processIdParameter,
+			{
+				name: "since",
+				in: "query",
+				schema: { type: "string" }
+			},
+			{
+				name: "replay",
+				in: "query",
+				schema: { type: "boolean" }
+			},
+			{
+				name: "follow",
+				in: "query",
+				schema: { type: "boolean" }
+			}
+		],
+		responses: {
+			"200": {
+				description: "SSE stream of process log events.",
+				content: { "text/event-stream": { schema: { type: "string" } } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"404": { $ref: "#/components/responses/NotFound" }
+		}
+	} },
+	"/v1/sandbox/{id}/processes/{processId}/kill": { post: {
+		operationId: "signalSandboxProcess",
+		summary: "Signal a sandbox process",
+		parameters: [sandboxIdParameter$1, processIdParameter],
+		requestBody: {
+			required: false,
+			content: { "application/json": { schema: {
+				type: "object",
+				properties: { signal: {
+					type: "integer",
+					minimum: 1,
+					maximum: 64,
+					default: 15
+				} }
+			} } }
+		},
+		responses: {
+			"204": { description: "Signal sent." },
+			"400": { $ref: "#/components/responses/InvalidRequest" },
+			"401": { $ref: "#/components/responses/Unauthorized" },
+			"404": { $ref: "#/components/responses/NotFound" }
+		}
+	} },
+	"/v1/sandbox/{id}/tunnel/{port}": {
+		post: {
+			operationId: "createTunnel",
+			summary: "Create or reuse a tunnel for a sandbox port",
+			parameters: [sandboxIdParameter$1, {
+				name: "port",
 				in: "path",
 				required: true,
-				schema: { type: "string" },
-				description: "Sandbox instance name."
+				schema: {
+					type: "integer",
+					minimum: 1024,
+					maximum: 65535
+				}
 			}],
 			responses: {
-				"204": { description: "Sandbox destroyed (best-effort). Container resources are released." },
-				"401": { $ref: "#/components/responses/Unauthorized" }
+				"200": { description: "Tunnel created or reused." },
+				"400": { $ref: "#/components/responses/InvalidRequest" },
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": { $ref: "#/components/responses/BadGateway" }
 			}
-		} },
-		"/v1/sandbox/{id}/session": { post: {
-			operationId: "createSession",
-			summary: "Create an execution session",
-			description: "Sessions isolate working directory and environment variables across commands. The returned session ID is used with the `Session-Id` header on exec, file, and PTY endpoints.",
-			parameters: [{
-				name: "id",
+		},
+		delete: {
+			operationId: "deleteTunnel",
+			summary: "Delete the tunnel for a sandbox port",
+			parameters: [sandboxIdParameter$1, {
+				name: "port",
 				in: "path",
 				required: true,
-				schema: { type: "string" },
-				description: "Sandbox instance name."
+				schema: {
+					type: "integer",
+					minimum: 1024,
+					maximum: 65535
+				}
 			}],
+			responses: {
+				"204": { description: "Tunnel deleted or already absent." },
+				"400": { $ref: "#/components/responses/InvalidRequest" },
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": { $ref: "#/components/responses/BadGateway" }
+			}
+		}
+	},
+	"/v1/sandbox/{id}/running": { get: {
+		operationId: "isSandboxRunning",
+		summary: "Check whether the sandbox container is alive",
+		parameters: [sandboxIdParameter$1],
+		responses: {
+			"200": {
+				description: "Liveness status.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/RunningResponse" } } }
+			},
+			"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	} }
+};
+
+//#endregion
+//#region src/bridge/openapi/terminals.ts
+const terminalSnapshotSchema = {
+	type: "object",
+	required: [
+		"id",
+		"command",
+		"status"
+	],
+	properties: {
+		id: { type: "string" },
+		pid: { type: "integer" },
+		command: {
+			type: "array",
+			items: { type: "string" }
+		},
+		cwd: { type: "string" },
+		status: {
+			type: "string",
+			enum: ["running", "exited"]
+		},
+		exit: {
+			type: "object",
+			properties: {
+				code: {
+					type: "integer",
+					nullable: true
+				},
+				signal: { oneOf: [{ type: "string" }, { type: "integer" }] },
+				timedOut: { type: "boolean" }
+			}
+		}
+	}
+};
+const terminalIdParameter = {
+	name: "terminalId",
+	in: "path",
+	required: true,
+	schema: {
+		type: "string",
+		pattern: "^[a-zA-Z0-9._-]{1,128}$"
+	}
+};
+const sandboxIdParameter = {
+	name: "id",
+	in: "path",
+	required: true,
+	schema: { type: "string" },
+	description: "Sandbox instance name."
+};
+const terminalErrorResponses = {
+	"400": {
+		description: "Invalid request.",
+		content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } }
+	},
+	"401": { $ref: "#/components/responses/Unauthorized" },
+	"502": {
+		description: "Terminal operation failed.",
+		content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } }
+	}
+};
+const TERMINALSPaths = {
+	"/v1/sandbox/{id}/terminals": {
+		post: {
+			operationId: "createTerminal",
+			summary: "Create a terminal",
 			requestBody: {
-				required: false,
+				required: true,
 				content: { "application/json": { schema: {
 					type: "object",
+					required: ["argv"],
 					properties: {
-						id: {
-							type: "string",
-							description: "Custom session ID. Auto-generated if omitted."
-						},
-						cwd: {
-							type: "string",
-							description: "Initial working directory for the session."
+						argv: {
+							type: "array",
+							items: { type: "string" },
+							minItems: 1
 						},
+						cwd: { type: "string" },
 						env: {
 							type: "object",
-							additionalProperties: { type: "string" },
-							description: "Environment variables scoped to this session."
-						}
+							additionalProperties: { type: "string" }
+						},
+						cols: { type: "integer" },
+						rows: { type: "integer" }
 					}
 				} } }
 			},
+			parameters: [sandboxIdParameter],
 			responses: {
 				"200": {
-					description: "Session created.",
-					content: { "application/json": { schema: {
-						type: "object",
-						required: ["id"],
-						properties: { id: {
-							type: "string",
-							description: "Session ID to pass via `Session-Id` header."
-						} }
-					} } }
+					description: "Terminal created with a generated ID.",
+					content: { "application/json": { schema: terminalSnapshotSchema } }
 				},
-				"401": { $ref: "#/components/responses/Unauthorized" },
-				"502": {
-					description: "Session creation failed.",
-					content: { "application/json": {
-						schema: { $ref: "#/components/schemas/ErrorResponse" },
-						example: {
-							error: "session creation failed",
-							code: "session_error"
-						}
-					} }
-				}
+				...terminalErrorResponses
 			}
-		} },
-		"/v1/sandbox/{id}/session/{sid}": { delete: {
-			operationId: "deleteSession",
-			summary: "Delete an execution session",
-			description: "Removes a named session. The default session cannot be deleted.",
-			parameters: [{
-				name: "id",
-				in: "path",
-				required: true,
-				schema: { type: "string" },
-				description: "Sandbox instance name."
-			}, {
-				name: "sid",
-				in: "path",
-				required: true,
-				schema: { type: "string" },
-				description: "Session ID to delete."
-			}],
+		},
+		get: {
+			operationId: "listTerminals",
+			summary: "List terminals",
+			parameters: [sandboxIdParameter],
 			responses: {
 				"200": {
-					description: "Session deleted.",
+					description: "Terminal snapshots.",
 					content: { "application/json": { schema: {
-						type: "object",
-						required: ["success", "sessionId"],
-						properties: {
-							success: {
-								type: "boolean",
-								description: "`true` if the session was deleted."
-							},
-							sessionId: {
-								type: "string",
-								description: "ID of the deleted session."
-							}
-						}
+						type: "array",
+						items: terminalSnapshotSchema
 					} } }
 				},
-				"401": { $ref: "#/components/responses/Unauthorized" },
-				"502": {
-					description: "Session deletion failed (e.g. cannot delete default session).",
-					content: { "application/json": {
-						schema: { $ref: "#/components/schemas/ErrorResponse" },
-						example: {
-							error: "cannot delete the default session",
-							code: "session_error"
-						}
-					} }
-				}
-			}
-		} },
-		"/health": { get: {
-			operationId: "healthCheck",
-			summary: "Worker health check",
-			description: "Simple liveness probe. Not protected by authentication.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl https://$HOST/health"
-			}],
-			security: [],
-			responses: { "200": {
-				description: "Worker is up.",
-				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
-			} }
-		} },
-		"/v1/openapi.json": { get: {
-			operationId: "getOpenApiSchema",
-			summary: "OpenAPI schema",
-			description: "Returns this OpenAPI 3.1 schema document.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl https://$HOST/v1/openapi.json \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			responses: {
-				"200": {
-					description: "OpenAPI schema document.",
-					content: { "application/json": { schema: { type: "object" } } }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" }
-			}
-		} },
-		"/v1/pool/stats": { get: {
-			operationId: "getPoolStats",
-			summary: "Pool statistics",
-			description: "Returns current warm pool statistics including warm/assigned counts and configuration.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl https://$HOST/v1/pool/stats \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			responses: {
-				"200": {
-					description: "Pool statistics.",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/PoolStats" } } }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" }
+				...terminalErrorResponses
 			}
-		} },
-		"/v1/pool/shutdown-prewarmed": { post: {
-			operationId: "shutdownPrewarmed",
-			summary: "Shutdown pre-warmed containers",
-			description: "Stops all idle (unassigned) warm containers. Does not affect containers assigned to sandbox sessions.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/pool/shutdown-prewarmed \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			responses: {
-				"200": {
-					description: "All pre-warmed containers stopped.",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" }
-			}
-		} },
-		"/v1/pool/prime": { post: {
-			operationId: "primePool",
-			summary: "Prime the warm pool",
-			description: "Pushes the current pool configuration and starts the alarm loop. Called automatically by the cron trigger; can also be called manually after deploy.",
-			"x-codeSamples": [{
-				lang: "curl",
-				label: "cURL",
-				source: "curl -X POST https://$HOST/v1/pool/prime \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
-			}],
-			responses: {
-				"200": {
-					description: "Pool primed successfully.",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
-				},
-				"401": { $ref: "#/components/responses/Unauthorized" }
+		}
+	},
+	"/v1/sandbox/{id}/terminals/{terminalId}": { get: {
+		operationId: "getTerminal",
+		summary: "Get a terminal snapshot",
+		parameters: [sandboxIdParameter, terminalIdParameter],
+		responses: {
+			"200": {
+				description: "Terminal snapshot.",
+				content: { "application/json": { schema: terminalSnapshotSchema } }
+			},
+			"404": { description: "Terminal not found." },
+			...terminalErrorResponses
+		}
+	} },
+	"/v1/sandbox/{id}/terminals/{terminalId}/connect": { get: {
+		operationId: "connectTerminal",
+		summary: "Connect to a terminal WebSocket",
+		description: "WebSocket binary client frames are terminal input bytes. JSON client controls are resize, interrupt, and terminate. Server output is a JSON chunk control immediately followed by one binary frame. Cursor advances after the binary frame is consumed.",
+		parameters: [
+			sandboxIdParameter,
+			terminalIdParameter,
+			{
+				name: "cursor",
+				in: "query",
+				required: false,
+				schema: { type: "string" }
+			},
+			{
+				name: "cols",
+				in: "query",
+				required: false,
+				schema: { type: "integer" }
+			},
+			{
+				name: "rows",
+				in: "query",
+				required: false,
+				schema: { type: "integer" }
 			}
-		} }
+		],
+		responses: {
+			"101": { description: "WebSocket upgrade successful." },
+			"404": { description: "Terminal not found." },
+			...terminalErrorResponses
+		}
+	} },
+	"/v1/sandbox/{id}/terminals/{terminalId}/interrupt": { post: {
+		operationId: "interruptTerminal",
+		summary: "Interrupt a terminal",
+		parameters: [sandboxIdParameter, terminalIdParameter],
+		responses: {
+			"204": { description: "Interrupt signal sent." },
+			"404": { description: "Terminal not found." },
+			...terminalErrorResponses
+		}
+	} },
+	"/v1/sandbox/{id}/terminals/{terminalId}/terminate": { post: {
+		operationId: "terminateTerminal",
+		summary: "Terminate a terminal",
+		parameters: [sandboxIdParameter, terminalIdParameter],
+		responses: {
+			"204": { description: "Terminate signal sent." },
+			"404": { description: "Terminal not found." },
+			...terminalErrorResponses
+		}
+	} }
+};
+
+//#endregion
+//#region src/bridge/openapi.ts
+const OPENAPI_SCHEMA = {
+	...OPENAPI_BASE,
+	paths: {
+		...LIFECYCLEPaths,
+		...PROCESSESPaths,
+		...FILESPaths,
+		...TERMINALSPaths
 	}
 };
 
@@ -1762,10 +1894,20 @@ function esc(s) {
 }
 
 //#endregion
-//#region src/bridge/routes.ts
-/** Typed wrapper around the SDK's getSandbox() that returns a BridgeSandbox. */
-function getSandbox$1(ns, containerUUID) {
-	return getSandbox(ns, containerUUID);
+//#region src/bridge/routes/common.ts
+function getSandbox(ns, containerUUID) {
+	return getSandbox$1(ns, containerUUID);
+}
+function getSandboxNs(env$1, sandboxBinding) {
+	return env$1[sandboxBinding];
+}
+function getWarmPoolNs(env$1, warmPoolBinding) {
+	return env$1[warmPoolBinding];
+}
+function getWarmPoolStub(env$1, warmPoolBinding) {
+	const poolNs = getWarmPoolNs(env$1, warmPoolBinding);
+	const poolId = poolNs.idFromName("global-pool");
+	return poolNs.get(poolId);
 }
 function hasEndpoint(options) {
 	return "endpoint" in options && typeof options.endpoint === "string";
@@ -1810,171 +1952,36 @@ function validateMountOptions(options, binding) {
 	return null;
 }
 function resolveMountBucketName(body) {
-	if (hasEndpoint(body.options)) {
-		if (body.bucket && typeof body.bucket === "string") return body.bucket;
-		return errorJson("bucket must be a non-empty string for remote mounts", "invalid_request", 400);
-	}
-	if (body.binding !== void 0) return body.binding;
-	return errorJson("binding must be a non-empty string for R2 binding mounts", "invalid_request", 400);
-}
-function toSDKMountOptions(options) {
-	if (hasEndpoint(options)) {
-		const remoteOptions = { endpoint: options.endpoint };
-		if (options.readOnly !== void 0) remoteOptions.readOnly = options.readOnly;
-		if (options.prefix !== void 0) remoteOptions.prefix = options.prefix;
-		if (hasCredentials(options)) remoteOptions.credentials = {
-			accessKeyId: options.credentials.accessKeyId,
-			secretAccessKey: options.credentials.secretAccessKey
-		};
-		if (options.s3fsOptions !== void 0) remoteOptions.s3fsOptions = options.s3fsOptions;
-		if ("credentialProxy" in options && typeof options.credentialProxy === "boolean") remoteOptions.credentialProxy = options.credentialProxy;
-		return remoteOptions;
-	}
-	const r2BindingOptions = {};
-	if (options.readOnly !== void 0) r2BindingOptions.readOnly = options.readOnly;
-	if (options.prefix !== void 0) r2BindingOptions.prefix = options.prefix;
-	if (options.s3fsOptions !== void 0) r2BindingOptions.s3fsOptions = options.s3fsOptions;
-	return r2BindingOptions;
-}
-function createBridgeApp(config) {
-	const app = new Hono();
-	const { sandboxBinding, warmPoolBinding, apiPrefix } = config;
-	function getSandboxNs(env$1) {
-		return env$1[sandboxBinding];
-	}
-	function getWarmPoolNs(env$1) {
-		return env$1[warmPoolBinding];
-	}
-	app.use(`${apiPrefix}/sandbox/*`, async (c, next) => {
-		const sandboxId = new URL(c.req.url).pathname.split("/")[apiPrefix.split("/").filter(Boolean).length + 2];
-		if (sandboxId && !/^[a-z2-7]{1,128}$/.test(sandboxId)) return errorJson("Invalid sandbox ID format", "invalid_request", 400);
-		const token = c.env.SANDBOX_API_KEY;
-		if (token) {
-			const authHeader = c.req.header("Authorization") ?? "";
-			if ((authHeader.toLowerCase().startsWith("bearer ") ? authHeader.slice(7) : "") !== token) return errorJson("Unauthorized", "unauthorized", 401);
-		}
-		return next();
-	});
-	app.post(`${apiPrefix}/sandbox`, async (c) => {
-		const token = c.env.SANDBOX_API_KEY;
-		if (token) {
-			const authHeader = c.req.header("Authorization") ?? "";
-			if ((authHeader.toLowerCase().startsWith("bearer ") ? authHeader.slice(7) : "") !== token) return errorJson("Unauthorized", "unauthorized", 401);
-		}
-		const bytes = new Uint8Array(16);
-		crypto.getRandomValues(bytes);
-		const id = base32Encode(bytes);
-		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
-			});
-			const containerUUID = await poolStub.getContainer(sandboxId);
-			c.set("containerUUID", containerUUID);
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			if (msg.includes("instance limit reached")) return errorJson(msg, "capacity_exceeded", 503);
-			return errorJson(`pool error: ${msg}`, "pool_error", 502);
-		}
-		return next();
-	});
-	app.use(`${apiPrefix}/sandbox/:id`, async (c, next) => {
-		if (c.req.method !== "DELETE") return next();
-		const sandboxId = c.req.param("id");
-		const poolNs = getWarmPoolNs(c.env);
-		const poolId = poolNs.idFromName("global-pool");
-		const poolStub = poolNs.get(poolId);
-		try {
-			const containerUUID = await poolStub.lookupContainer(sandboxId);
-			if (!containerUUID) return new Response(null, { status: 204 });
-			c.set("containerUUID", containerUUID);
-		} catch (err) {
-			return errorJson(`pool error: ${err instanceof Error ? err.message : String(err)}`, "pool_error", 502);
-		}
-		return next();
-	});
-	app.post(`${apiPrefix}/sandbox/:id/exec`, async (c) => {
-		let body;
-		try {
-			body = await c.req.json();
-		} catch {
-			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);
-		const sandbox = getSandbox$1(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);
-			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.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;
-		}
-		const { readable, writable } = new TransformStream();
-		const writer = writable.getWriter();
-		const encoder = new TextEncoder();
-		let closed = false;
-		let lastWrite = Promise.resolve();
-		/** Write a single SSE event. Chains on the previous write to respect backpressure. */
-		function writeSSE(event, data) {
-			if (closed) return;
-			const payload = data.split("\n").map((line) => `data: ${line}`).join("\n");
-			lastWrite = lastWrite.then(() => writer.write(encoder.encode(`event: ${event}\n${payload}\n\n`)));
-		}
-		function closeStream() {
-			if (closed) return;
-			closed = true;
-			lastWrite.then(() => writer.close()).catch(() => {});
-		}
-		executor.exec(command, {
-			...opts,
-			stream: true,
-			onOutput(stream, data) {
-				writeSSE(stream, toBase64(data));
-			},
-			onComplete(result) {
-				writeSSE("exit", JSON.stringify({ exit_code: result.exitCode }));
-				closeStream();
-			},
-			onError(err) {
-				writeSSE("error", JSON.stringify({
-					error: err.message,
-					code: "exec_error"
-				}));
-				closeStream();
-			}
-		}).catch((err) => {
-			const msg = err instanceof Error ? err.message : String(err);
-			writeSSE("error", JSON.stringify({
-				error: `exec failed: ${msg}`,
-				code: "exec_transport_error"
-			}));
-			closeStream();
-		});
-		return new Response(readable, {
-			status: 200,
-			headers: {
-				"Content-Type": "text/event-stream",
-				"Cache-Control": "no-cache"
-			}
-		});
-	});
+	if (hasEndpoint(body.options)) {
+		if (body.bucket && typeof body.bucket === "string") return body.bucket;
+		return errorJson("bucket must be a non-empty string for remote mounts", "invalid_request", 400);
+	}
+	if (body.binding !== void 0) return body.binding;
+	return errorJson("binding must be a non-empty string for R2 binding mounts", "invalid_request", 400);
+}
+function toSDKMountOptions(options) {
+	if (hasEndpoint(options)) {
+		const remoteOptions = { endpoint: options.endpoint };
+		if (options.readOnly !== void 0) remoteOptions.readOnly = options.readOnly;
+		if (options.prefix !== void 0) remoteOptions.prefix = options.prefix;
+		if (hasCredentials(options)) remoteOptions.credentials = {
+			accessKeyId: options.credentials.accessKeyId,
+			secretAccessKey: options.credentials.secretAccessKey
+		};
+		if (options.s3fsOptions !== void 0) remoteOptions.s3fsOptions = options.s3fsOptions;
+		if ("credentialProxy" in options && typeof options.credentialProxy === "boolean") remoteOptions.credentialProxy = options.credentialProxy;
+		return remoteOptions;
+	}
+	const r2BindingOptions = {};
+	if (options.readOnly !== void 0) r2BindingOptions.readOnly = options.readOnly;
+	if (options.prefix !== void 0) r2BindingOptions.prefix = options.prefix;
+	if (options.s3fsOptions !== void 0) r2BindingOptions.s3fsOptions = options.s3fsOptions;
+	return r2BindingOptions;
+}
+
+//#endregion
+//#region src/bridge/routes/files.ts
+function registerFileRoutes(app, apiPrefix, sandboxBinding) {
 	app.get(`${apiPrefix}/sandbox/:id/file/*`, async (c) => {
 		const sandboxId = c.req.param("id");
 		const fullPath = c.req.path;
@@ -1983,16 +1990,9 @@ 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);
-		const sandbox = getSandbox$1(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);
-			executor = await sandbox.getSession(sessionId);
-		}
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
 		try {
-			const stream = await executor.readFileStream(resolvedPath);
+			const stream = await sandbox.readFileStream(resolvedPath);
 			return new Response(sseToByteStream(stream), {
 				status: 200,
 				headers: { "Content-Type": "application/octet-stream" }
@@ -2010,14 +2010,7 @@ 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);
-		const sandbox = getSandbox$1(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);
-			executor = await sandbox.getSession(sessionId);
-		}
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
 		try {
 			const buffer = await c.req.arrayBuffer();
 			const MAX_WRITE_BYTES = 32 * 1024 * 1024;
@@ -2026,87 +2019,43 @@ function createBridgeApp(config) {
 			let b64 = "";
 			const CHUNK = 6144;
 			for (let i = 0; i < bytes.length; i += CHUNK) b64 += btoa(String.fromCharCode(...bytes.subarray(i, i + CHUNK)));
-			await executor.writeFile(resolvedPath, b64, { encoding: "base64" });
+			await sandbox.writeFile(resolvedPath, b64, { encoding: "base64" });
 			return c.json({ ok: true });
 		} 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) => {
-		const port = Number(c.req.param("port"));
-		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
-		const options = parseTunnelOptions(await c.req.text());
-		if (options instanceof Response) return options;
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		try {
-			const tunnel = await sandbox.tunnels.get(port, options);
-			return c.json(tunnel);
-		} 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) => {
-		const port = Number(c.req.param("port"));
-		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		try {
-			await sandbox.tunnels.destroy(port);
-			return c.body(null, 204);
-		} catch (err) {
-			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
-		}
-	});
-	app.get(`${apiPrefix}/sandbox/:id/running`, async (c) => {
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		try {
-			await sandbox.exec("true");
-			return c.json({ running: true });
-		} catch {
-			return c.json({ running: false });
-		}
-	});
-	app.get(`${apiPrefix}/sandbox/:id/pty`, async (c) => {
-		const upgrade = c.req.header("Upgrade");
-		if (!upgrade || upgrade.toLowerCase() !== "websocket") return errorJson("WebSocket upgrade required", "invalid_request", 400);
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		const colsParam = c.req.query("cols");
-		const rowsParam = c.req.query("rows");
-		const shell = c.req.query("shell");
-		const sessionId = c.req.header("Session-Id") || c.req.query("session");
-		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);
-		const opts = {
-			cols,
-			rows
-		};
-		if (shell) opts.shell = shell;
-		try {
-			if (sessionId) {
-				const validatedId = validateSessionId(sessionId);
-				if (!validatedId) return errorJson("Invalid session ID format", "invalid_request", 400);
-				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);
-		}
+}
+
+//#endregion
+//#region src/bridge/routes/lifecycle.ts
+function registerLifecycleRoutes(app, apiPrefix, healthPath, sandboxBinding, warmPoolBinding) {
+	app.post(`${apiPrefix}/sandbox`, (c) => {
+		const bytes = new Uint8Array(15);
+		crypto.getRandomValues(bytes);
+		return c.json({ id: base32Encode(bytes) });
 	});
 	app.post(`${apiPrefix}/sandbox/:id/persist`, async (c) => {
 		const root = "/workspace";
 		const excludesParam = c.req.query("excludes") ?? "";
 		const excludes = excludesParam ? excludesParam.split(",").filter((s) => s.length > 0) : [];
 		for (const ex of excludes) if (ex.includes("..")) return errorJson("exclude paths must not contain \"..\"", "invalid_request", 400);
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		const tmpPath = `/tmp/sandbox-persist-${Date.now()}.tar`;
-		const excludeArgs = excludes.map((rel) => `--exclude ${shellQuote(`./${rel.replace(/^\.\//, "")}`)}`).join(" ");
-		const tarCmd = excludeArgs ? `tar cf ${shellQuote(tmpPath)} ${excludeArgs} -C ${shellQuote(root)} .` : `tar cf ${shellQuote(tmpPath)} -C ${shellQuote(root)} .`;
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
 		try {
-			const result = await sandbox.exec(tarCmd);
-			if (result.exitCode !== 0) return errorJson(`tar failed (exit ${result.exitCode}): ${result.stderr}`, "workspace_archive_read_error", 502);
-			const stream = await sandbox.readFileStream(tmpPath);
-			sandbox.exec(`rm -f ${shellQuote(tmpPath)}`).catch(() => {});
-			return new Response(sseToByteStream(stream), {
+			const archivePath = await sandbox.createWorkspaceArchive({
+				root,
+				excludes
+			});
+			let stream;
+			try {
+				stream = await sandbox.readFileStream(archivePath);
+			} catch (error) {
+				await sandbox.cleanupWorkspaceArchive(archivePath).catch(() => void 0);
+				throw error;
+			}
+			const cleanupPath = archivePath;
+			const responseStream = withStreamCleanup(sseToByteStream(stream), () => sandbox.cleanupWorkspaceArchive(cleanupPath));
+			return new Response(responseStream, {
 				status: 200,
 				headers: { "Content-Type": "application/octet-stream" }
 			});
@@ -2116,7 +2065,7 @@ function createBridgeApp(config) {
 	});
 	app.post(`${apiPrefix}/sandbox/:id/hydrate`, async (c) => {
 		const root = "/workspace";
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
 		let tarBytes;
 		try {
 			const buffer = await c.req.arrayBuffer();
@@ -2127,18 +2076,21 @@ function createBridgeApp(config) {
 		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);
+		const tmpPath = `/tmp/sandbox-hydrate-${Date.now()}-${crypto.randomUUID()}.tar`;
 		try {
-			await sandbox.exec(`mkdir -p ${shellQuote(root)}`);
-			const tmpPath = `/tmp/sandbox-hydrate-${Date.now()}.tar`;
 			let b64 = "";
 			const CHUNK = 6144;
 			for (let i = 0; i < tarBytes.length; i += CHUNK) b64 += btoa(String.fromCharCode(...tarBytes.subarray(i, i + CHUNK)));
 			await sandbox.writeFile(tmpPath, b64, { encoding: "base64" });
-			const extractResult = await sandbox.exec(`tar xf ${shellQuote(tmpPath)} -C ${shellQuote(root)} && rm -f ${shellQuote(tmpPath)}`);
-			if (extractResult.exitCode !== 0) return errorJson(`tar extract failed (exit ${extractResult.exitCode}): ${extractResult.stderr}`, "workspace_archive_write_error", 502);
+			await sandbox.extractWorkspaceArchive({
+				root,
+				archivePath: tmpPath
+			});
 			return c.json({ ok: true });
 		} catch (err) {
 			return errorJson(`hydrate failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
+		} finally {
+			await sandbox.cleanupWorkspaceArchive(tmpPath).catch(() => void 0);
 		}
 	});
 	app.post(`${apiPrefix}/sandbox/:id/mount`, async (c) => {
@@ -2156,7 +2108,7 @@ function createBridgeApp(config) {
 		if (optionsError) return optionsError;
 		const bucketName = resolveMountBucketName(body);
 		if (bucketName instanceof Response) return bucketName;
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
 		const sdkOptions = toSDKMountOptions(body.options);
 		try {
 			await sandbox.mountBucket(bucketName, body.mountPath, sdkOptions);
@@ -2176,55 +2128,29 @@ 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);
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
 		try {
 			await sandbox.unmountBucket(normalizedPath);
-			const quoted = shellQuote(normalizedPath);
 			try {
-				await sandbox.exec(`mountpoint -q ${quoted} || rmdir ${quoted}`);
+				await sandbox.cleanupMountDirectory(normalizedPath);
 			} catch {}
 			return c.json({ ok: true });
 		} catch (err) {
 			return errorJson(`unmount failed: ${err instanceof Error ? err.message : String(err)}`, "unmount_error", 502);
 		}
 	});
-	app.post(`${apiPrefix}/sandbox/:id/session`, async (c) => {
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		let body = {};
-		try {
-			body = await c.req.json();
-		} catch {}
-		try {
-			const session = await sandbox.createSession(body);
-			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) => {
-		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
-		const sid = c.req.param("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) => {
 		const containerUUID = c.get("containerUUID");
-		const sandbox = getSandbox$1(getSandboxNs(c.env), containerUUID);
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), containerUUID);
 		try {
 			await sandbox.destroy();
 		} catch {}
 		try {
-			const poolNs = getWarmPoolNs(c.env);
-			const poolId = poolNs.idFromName("global-pool");
-			await poolNs.get(poolId).reportStopped(containerUUID);
+			await getWarmPoolStub(c.env, warmPoolBinding).reportStopped(containerUUID);
 		} catch {}
 		return new Response(null, { status: 204 });
 	});
-	app.get(config.healthPath, (c) => {
+	app.get(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}".`);
 		if (!c.env[warmPoolBinding]) errors.push(`Missing required Durable Object binding "${warmPoolBinding}". Ensure your wrangler.jsonc has a binding named "${warmPoolBinding}".`);
@@ -2245,9 +2171,7 @@ function createBridgeApp(config) {
 	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;
-		const poolNs = getWarmPoolNs(c.env);
-		const poolId = poolNs.idFromName("global-pool");
-		const poolStub = poolNs.get(poolId);
+		const poolStub = getWarmPoolStub(c.env, warmPoolBinding);
 		try {
 			await poolStub.configure({
 				warmTarget,
@@ -2260,9 +2184,7 @@ function createBridgeApp(config) {
 	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;
-		const poolNs = getWarmPoolNs(c.env);
-		const poolId = poolNs.idFromName("global-pool");
-		const poolStub = poolNs.get(poolId);
+		const poolStub = getWarmPoolStub(c.env, warmPoolBinding);
 		try {
 			await poolStub.configure({
 				warmTarget,
@@ -2276,6 +2198,399 @@ function createBridgeApp(config) {
 		await primePool(c.env, warmPoolBinding);
 		return c.json({ ok: true });
 	});
+}
+
+//#endregion
+//#region src/bridge/routes/processes.ts
+function registerProcessRoutes(app, apiPrefix, sandboxBinding) {
+	app.post(`${apiPrefix}/sandbox/:id/processes`, async (c) => {
+		const body = await parseProcessRequest(c.req.raw);
+		if (body instanceof Response) return body;
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		const options = processOptions(body);
+		if (options instanceof Response) return options;
+		try {
+			const process = await sandbox.exec(body.argv, options);
+			return c.json(await process.status());
+		} catch (err) {
+			return errorJson(`process launch failed: ${err instanceof Error ? err.message : String(err)}`, "process_error", 502);
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/processes`, async (c) => {
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		return c.json(await sandbox.listProcesses());
+	});
+	app.get(`${apiPrefix}/sandbox/:id/processes/:processId`, async (c) => {
+		const process = await getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID")).getProcess(c.req.param("processId"));
+		if (!process) return errorJson("Process not found", "not_found", 404);
+		return c.json(await process.status());
+	});
+	app.get(`${apiPrefix}/sandbox/:id/processes/:processId/logs`, async (c) => {
+		const process = await getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID")).getProcess(c.req.param("processId"));
+		if (!process) return errorJson("Process not found", "not_found", 404);
+		const replay = parseBoolean(c.req.query("replay"));
+		const follow = parseBoolean(c.req.query("follow"));
+		const logs = await process.logs({
+			since: c.req.query("since"),
+			replay,
+			follow
+		});
+		return new Response(processLogsToSSE(logs), { headers: {
+			"Content-Type": "text/event-stream",
+			"Cache-Control": "no-cache"
+		} });
+	});
+	app.post(`${apiPrefix}/sandbox/:id/processes/:processId/kill`, async (c) => {
+		const process = await getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID")).getProcess(c.req.param("processId"));
+		if (!process) return errorJson("Process not found", "not_found", 404);
+		const signal = await parseKillRequest(c.req.raw);
+		if (signal instanceof Response) return signal;
+		await process.kill(signal);
+		return c.body(null, 204);
+	});
+	app.post(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+		const port = Number(c.req.param("port"));
+		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		const options = parseTunnelOptions(await c.req.text());
+		if (options instanceof Response) return options;
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const tunnel = await sandbox.tunnels.get(port, options);
+			return c.json(tunnel);
+		} 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) => {
+		const port = Number(c.req.param("port"));
+		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			await sandbox.tunnels.destroy(port);
+			return c.body(null, 204);
+		} catch (err) {
+			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/running`, async (c) => {
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const response = { running: await sandbox.isRuntimeActive() };
+			return c.json(response);
+		} catch {
+			return c.json({ running: false });
+		}
+	});
+}
+async function parseProcessRequest(request) {
+	let body;
+	try {
+		body = await request.json();
+	} catch {
+		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);
+	if (body.argv.some((item) => typeof item !== "string")) return errorJson("argv items must be strings", "invalid_request", 400);
+	if (body.argv[0].length === 0) return errorJson("argv executable must be non-empty", "invalid_request", 400);
+	return body;
+}
+function processOptions(body) {
+	const options = {};
+	if (body.timeout !== void 0) {
+		if (typeof body.timeout !== "number" || !Number.isFinite(body.timeout) || body.timeout <= 0) return errorJson("timeout must be a positive finite number", "invalid_request", 400);
+		options.timeout = body.timeout;
+	}
+	if (typeof body.cwd === "string") {
+		const cwd = resolveWorkspacePath(body.cwd);
+		if (!cwd) return errorJson("cwd must resolve to a location within /workspace", "invalid_request", 403);
+		options.cwd = cwd;
+	}
+	if ("env" in body && body.env !== void 0) {
+		if (!isStringRecord(body.env)) return errorJson("env must be an object of strings", "invalid_request", 400);
+		options.env = body.env;
+	}
+	return options;
+}
+async function parseKillRequest(request) {
+	if (!request.headers.get("content-type")) return 15;
+	let body;
+	try {
+		body = await request.json();
+	} catch {
+		return errorJson("Invalid JSON body", "invalid_request", 400);
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return errorJson("Request body must be an object", "invalid_request", 400);
+	const signal = body.signal;
+	if (signal === void 0) return 15;
+	if (typeof signal !== "number" || !Number.isInteger(signal) || signal < 1 || signal > 64) return errorJson("signal must be an integer between 1 and 64", "invalid_request", 400);
+	return signal;
+}
+function parseBoolean(value) {
+	if (value === void 0) return void 0;
+	return value === "true" || value === "1";
+}
+function isStringRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string");
+}
+function processLogsToSSE(logs) {
+	const reader = logs.getReader();
+	const encoder = new TextEncoder();
+	let finished = false;
+	async function finish(cancelSource) {
+		if (finished) return;
+		finished = true;
+		if (cancelSource) await reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+	}
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const result = await reader.read();
+				if (result.done) {
+					await finish(false);
+					controller.close();
+					return;
+				}
+				const event = result.value;
+				const data = event.type === "stdout" || event.type === "stderr" ? {
+					type: event.type,
+					cursor: event.cursor,
+					timestamp: event.timestamp,
+					data: bytesToBase64(event.data)
+				} : event;
+				controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
+			} catch (error) {
+				await finish(true);
+				controller.error(error);
+			}
+		},
+		async cancel() {
+			await finish(true);
+		}
+	}, { highWaterMark: 0 });
+}
+function bytesToBase64(data) {
+	let binary = "";
+	for (const byte of data) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+
+//#endregion
+//#region src/bridge/routes/terminals.ts
+function parsePositiveInteger(value, name) {
+	if (value === void 0) return void 0;
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) return errorJson(`${name} must be a positive integer`, "invalid_request", 400);
+	return parsed;
+}
+function isSandboxCommand(value) {
+	return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string");
+}
+function parseCreateTerminalBody(rawBody) {
+	let body;
+	try {
+		body = JSON.parse(rawBody);
+	} catch {
+		return errorJson("Invalid JSON body", "invalid_request", 400);
+	}
+	if (!body || typeof body !== "object" || Array.isArray(body)) return errorJson("Request body must be an object", "invalid_request", 400);
+	const record = body;
+	const argv = record.argv;
+	if (!isSandboxCommand(argv)) return errorJson("argv must be a non-empty string array", "invalid_request", 400);
+	const options = { command: argv };
+	if (record.cwd !== void 0) {
+		if (typeof record.cwd !== "string") return errorJson("cwd must be a string", "invalid_request", 400);
+		options.cwd = record.cwd;
+	}
+	if (record.env !== void 0) {
+		if (!record.env || typeof record.env !== "object" || Array.isArray(record.env)) return errorJson("env must be an object", "invalid_request", 400);
+		const env$1 = {};
+		for (const [key, value] of Object.entries(record.env)) {
+			if (typeof value !== "string") return errorJson("env values must be strings", "invalid_request", 400);
+			env$1[key] = value;
+		}
+		options.env = env$1;
+	}
+	if (record.cols !== void 0) {
+		if (typeof record.cols !== "number" || !Number.isInteger(record.cols) || record.cols <= 0) return errorJson("cols must be a positive integer", "invalid_request", 400);
+		options.cols = record.cols;
+	}
+	if (record.rows !== void 0) {
+		if (typeof record.rows !== "number" || !Number.isInteger(record.rows) || record.rows <= 0) return errorJson("rows must be a positive integer", "invalid_request", 400);
+		options.rows = record.rows;
+	}
+	return options;
+}
+function terminalError(error) {
+	return errorJson(`terminal failed: ${error instanceof Error ? error.message : String(error)}`, "exec_transport_error", 502);
+}
+function registerTerminalRoutes(app, apiPrefix, sandboxBinding) {
+	app.post(`${apiPrefix}/sandbox/:id/terminals`, async (c) => {
+		const parsed = parseCreateTerminalBody(await c.req.text());
+		if (parsed instanceof Response) return parsed;
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const terminal = await sandbox.createTerminal(parsed);
+			return c.json(await terminal.getSnapshot());
+		} catch (error) {
+			return terminalError(error);
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/terminals`, async (c) => {
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const terminals = await sandbox.listTerminals();
+			return c.json(await Promise.all(terminals.map((terminal) => terminal.getSnapshot())));
+		} catch (error) {
+			return terminalError(error);
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/terminals/:terminalId`, async (c) => {
+		const terminalId = validateTerminalId(c.req.param("terminalId"));
+		if (!terminalId) return errorJson("Invalid terminal ID format", "invalid_request", 400);
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const terminal = await sandbox.getTerminal(terminalId);
+			if (!terminal) return errorJson("Terminal not found", "not_found", 404);
+			return c.json(await terminal.getSnapshot());
+		} catch (error) {
+			return terminalError(error);
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/terminals/:terminalId/connect`, async (c) => {
+		const upgrade = c.req.header("Upgrade");
+		if (!upgrade || upgrade.toLowerCase() !== "websocket") return errorJson("WebSocket upgrade required", "invalid_request", 400);
+		const terminalId = validateTerminalId(c.req.param("terminalId"));
+		if (!terminalId) return errorJson("Invalid terminal ID format", "invalid_request", 400);
+		const cols = parsePositiveInteger(c.req.query("cols"), "cols");
+		if (cols instanceof Response) return cols;
+		const rows = parsePositiveInteger(c.req.query("rows"), "rows");
+		if (rows instanceof Response) return rows;
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const terminal = await sandbox.getTerminal(terminalId);
+			if (!terminal) return errorJson("Terminal not found", "not_found", 404);
+			return await terminal.connect(c.req.raw, {
+				cursor: c.req.query("cursor"),
+				cols,
+				rows
+			});
+		} catch (error) {
+			return terminalError(error);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/terminals/:terminalId/interrupt`, async (c) => {
+		const terminalId = validateTerminalId(c.req.param("terminalId"));
+		if (!terminalId) return errorJson("Invalid terminal ID format", "invalid_request", 400);
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const terminal = await sandbox.getTerminal(terminalId);
+			if (!terminal) return errorJson("Terminal not found", "not_found", 404);
+			await terminal.interrupt();
+			return new Response(null, { status: 204 });
+		} catch (error) {
+			return terminalError(error);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/terminals/:terminalId/terminate`, async (c) => {
+		const terminalId = validateTerminalId(c.req.param("terminalId"));
+		if (!terminalId) return errorJson("Invalid terminal ID format", "invalid_request", 400);
+		const sandbox = getSandbox(getSandboxNs(c.env, sandboxBinding), c.get("containerUUID"));
+		try {
+			const terminal = await sandbox.getTerminal(terminalId);
+			if (!terminal) return errorJson("Terminal not found", "not_found", 404);
+			await terminal.terminate();
+			return new Response(null, { status: 204 });
+		} catch (error) {
+			return terminalError(error);
+		}
+	});
+}
+
+//#endregion
+//#region src/bridge/routes.ts
+function sandboxRoutePoolMode(method, routePath) {
+	if (method === "GET" && routePath === "/running") return "lookup";
+	if (method === "GET" && (routePath === "/processes" || /^\/processes\/[^/]+(?:\/logs)?$/.test(routePath))) return "lookup";
+	if (method === "POST" && /^\/processes\/[^/]+\/kill$/.test(routePath)) return "lookup";
+	if (method === "GET" && (routePath === "/terminals" || /^\/terminals\/[^/]+(?:\/connect)?$/.test(routePath))) return "lookup";
+	if (method === "POST" && /^\/terminals\/[^/]+\/(interrupt|terminate)$/.test(routePath)) return "lookup";
+	if (method === "POST" && [
+		"/processes",
+		"/terminals",
+		"/persist",
+		"/hydrate",
+		"/mount",
+		"/unmount"
+	].includes(routePath)) return "allocate";
+	if ((method === "GET" || method === "PUT") && routePath.startsWith("/file/")) return "allocate";
+	if ((method === "POST" || method === "DELETE") && /^\/tunnel\/[^/]+$/.test(routePath)) return "allocate";
+	return "unmatched";
+}
+function missingRuntimeResponse(routePath) {
+	if (routePath === "/running") return Response.json({ running: false });
+	if (routePath === "/processes" || routePath === "/terminals") return Response.json([]);
+	if (routePath.startsWith("/terminals/")) return errorJson("Terminal not found", "not_found", 404);
+	return errorJson("Process not found", "not_found", 404);
+}
+function createBridgeApp(config) {
+	const app = new Hono();
+	const { sandboxBinding, warmPoolBinding, apiPrefix } = config;
+	app.use(`${apiPrefix}/sandbox/*`, async (c, next) => {
+		const sandboxId = new URL(c.req.url).pathname.split("/")[apiPrefix.split("/").filter(Boolean).length + 2];
+		if (sandboxId && !/^[a-z2-7]{1,128}$/.test(sandboxId)) return errorJson("Invalid sandbox ID format", "invalid_request", 400);
+		const token = c.env.SANDBOX_API_KEY;
+		if (token) {
+			const authHeader = c.req.header("Authorization") ?? "";
+			if ((authHeader.toLowerCase().startsWith("bearer ") ? authHeader.slice(7) : "") !== token) return errorJson("Unauthorized", "unauthorized", 401);
+		}
+		return next();
+	});
+	app.use(`${apiPrefix}/sandbox/:id/*`, async (c, next) => {
+		const url = new URL(c.req.url);
+		const sandboxId = c.req.param("id");
+		const routePath = url.pathname.slice(`${apiPrefix}/sandbox/${sandboxId}`.length);
+		const poolMode = sandboxRoutePoolMode(c.req.method, routePath);
+		if (poolMode === "unmatched") return next();
+		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 poolStub = getWarmPoolStub(c.env, warmPoolBinding);
+		try {
+			await poolStub.configure({
+				warmTarget,
+				refreshInterval
+			});
+			const containerUUID = poolMode === "lookup" ? await poolStub.lookupContainer(sandboxId) : await poolStub.getContainer(sandboxId);
+			if (!containerUUID) return missingRuntimeResponse(routePath);
+			c.set("containerUUID", containerUUID);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (msg.includes("instance limit reached")) return errorJson(msg, "capacity_exceeded", 503);
+			return errorJson(`pool error: ${msg}`, "pool_error", 502);
+		}
+		return next();
+	});
+	app.use(`${apiPrefix}/sandbox/:id`, async (c, next) => {
+		if (c.req.method !== "DELETE") return next();
+		const sandboxId = c.req.param("id");
+		const poolStub = getWarmPoolStub(c.env, warmPoolBinding);
+		try {
+			const containerUUID = await poolStub.lookupContainer(sandboxId);
+			if (!containerUUID) return new Response(null, { status: 204 });
+			c.set("containerUUID", containerUUID);
+		} catch (err) {
+			return errorJson(`pool error: ${err instanceof Error ? err.message : String(err)}`, "pool_error", 502);
+		}
+		return next();
+	});
+	registerLifecycleRoutes(app, apiPrefix, config.healthPath, sandboxBinding, warmPoolBinding);
+	registerProcessRoutes(app, apiPrefix, sandboxBinding);
+	registerFileRoutes(app, apiPrefix, sandboxBinding);
+	registerTerminalRoutes(app, apiPrefix, sandboxBinding);
+	registerOpenApiRoutes(app, apiPrefix);
+	return app;
+}
+function registerOpenApiRoutes(app, apiPrefix) {
 	const openapiAuth = async (c, next) => {
 		const token = c.env.SANDBOX_API_KEY;
 		if (token) {
@@ -2290,7 +2605,6 @@ function createBridgeApp(config) {
 	app.get(`${apiPrefix}/openapi.json`, openapiAuth, (c) => c.json(OPENAPI_SCHEMA));
 	app.get(`${apiPrefix}/openapi.html`, openapiAuth, openapiHtmlHandler);
 	app.get(`${apiPrefix}/openapi`, openapiAuth, openapiHtmlHandler);
-	return app;
 }
 
 //#endregion
@@ -2298,12 +2612,9 @@ function createBridgeApp(config) {
 /**
 * WarmPool — Durable Object that maintains a pool of pre-started sandbox containers.
 *
-* Adapted from https://github.com/mikenomitch/cf-container-warm-pool
-* Inlined and tailored for the @cloudflare/sandbox SDK.
-*
-* The pool keeps N idle containers standing by so new sandbox sessions boot
-* instantly.  Once a container is assigned to a sandbox ID it is consumed and
-* never returned to the pool.
+* The pool keeps N idle containers standing by so new sandboxes boot instantly.
+* Once a container is assigned to a sandbox ID, it is consumed and never returned
+* to the pool.
 *
 * Configuration is pushed in via `configure()` on every request (idempotent)
 * so changes to wrangler vars take effect without manual intervention.
@@ -2405,11 +2716,11 @@ var WarmPool = class extends DurableObject {
 	async shutdownPrewarmed() {
 		await this.init();
 		for (const containerUUID of [...this.warmContainers]) try {
-			await this.getSandboxStub(containerUUID).stop();
+			await this.getSandboxStub(containerUUID).destroy();
 			this.warmContainers.delete(containerUUID);
 		} catch (error) {
 			console.error({
-				message: "Failed to stop container",
+				message: "Failed to destroy container",
 				component: "warm-pool",
 				containerUUID,
 				error
@@ -2589,22 +2900,22 @@ var WarmPool = class extends DurableObject {
 			console.info({
 				message: "Scaling down pool",
 				component: "warm-pool",
-				stopping: excess
+				destroying: excess
 			});
-			const toStop = [...this.warmContainers].slice(0, excess);
-			const stopped = [];
-			for (const uuid of toStop) try {
-				await this.getSandboxStub(uuid).stop();
-				stopped.push(uuid);
+			const toDestroy = [...this.warmContainers].slice(0, excess);
+			const destroyed = [];
+			for (const uuid of toDestroy) try {
+				await this.getSandboxStub(uuid).destroy();
+				destroyed.push(uuid);
 			} catch (error) {
 				console.error({
-					message: "Failed to stop container",
+					message: "Failed to destroy container",
 					component: "warm-pool",
 					containerUUID: uuid,
 					error
 				});
 			}
-			for (const uuid of stopped) this.warmContainers.delete(uuid);
+			for (const uuid of destroyed) this.warmContainers.delete(uuid);
 			await this.persist();
 		}
 	}