@multiplayer-app/sandbox 2.0.0-wip-yjs-state-changes.0 → 3.0.0-wip-yjs-state-changes.0

package/dist/cli.js

@@ -1,105 +1,3019 @@
 #!/usr/bin/env node
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable no-console -- console output is the CLI's user interface */
-// Worker CLI. Published as the global `sandbox` executable and also available locally via
-// `pnpm --filter @multiplayer-app/sandbox run cli -- <args>`.
-require("dotenv/config");
-const commander_1 = require("commander");
-const package_json_1 = require("../package.json");
-const config_1 = require("./config");
-const executor_1 = require("./executor");
-const detect_1 = require("./executor/detect");
-const images_1 = require("./images");
-const socket_client_1 = require("./socket-client");
-const console_relays_1 = require("./console-relays");
-const program = new commander_1.Command();
-program
-    .name('sandbox')
-    .description('Run and manage a Multiplayer sandbox worker')
-    .version(package_json_1.version);
-program
-    .command('start')
-    .description('start a worker and connect it to the sandbox control plane')
-    .option('--token <token>', 'worker authentication token (env: WORKER_TOKEN)')
-    .option('--worker-id <id>', 'stable worker ID (env: WORKER_ID; default: hostname)')
-    .option('--sandbox-url <url>', 'control-plane URL (env: SANDBOX_URL; default: https://api.sandbox.filingramp.com)')
-    .option('--max-vms <count>', 'maximum concurrent VMs (env: MAX_VMS)')
-    .action(async (opts) => {
-    const config = (0, config_1.loadWorkerConfigFromEnv)({
-        ...process.env,
-        ...(opts.token ? { WORKER_TOKEN: opts.token } : {}),
-        ...(opts.workerId ? { WORKER_ID: opts.workerId } : {}),
-        ...(opts.sandboxUrl ? { SANDBOX_URL: opts.sandboxUrl } : {}),
-        ...(opts.maxVms ? { MAX_VMS: opts.maxVms } : {}),
-    });
-    const executor = (0, executor_1.createExecutor)(config);
-    const socket = (0, socket_client_1.connectToSandbox)(config, executor);
-    (0, console_relays_1.attachConsoleRelays)(executor, socket);
-    let stopping = false;
-    const stop = async (signal) => {
-        if (stopping)
-            return;
-        stopping = true;
-        console.log(`\n${signal} received; shutting down sandbox worker...`);
-        socket.disconnect();
-        const results = await Promise.allSettled(executor.list().map((vm) => executor.destroy(vm.vmId)));
-        const failed = results.filter((result) => result.status === 'rejected');
-        if (failed.length)
-            console.error(`Failed to destroy ${failed.length} VM(s) during shutdown`);
-        process.exit(failed.length ? 1 : 0);
-    };
-    process.once('SIGINT', () => { void stop('SIGINT'); });
-    process.once('SIGTERM', () => { void stop('SIGTERM'); });
-    console.log(`Starting sandbox worker ${config.workerId} → ${config.sandboxUrl}`);
-    // Socket.IO's reconnect timers keep the process alive until a termination signal arrives.
-});
-program
-    .command('detect')
-    .description('probe this host and report which micro-VM engines it can run')
-    .action(() => {
-    const probes = (0, detect_1.probeEngines)((0, config_1.loadWorkerConfigFromEnv)({ ...process.env, WORKER_ID: '-', WORKER_TOKEN: '-' }));
-    for (const probe of probes) {
-        const status = probe.available ? 'available' : `unavailable — ${probe.reason}`;
-        console.log(`${probe.engine.padEnd(15)} ${status}`);
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_config5 = require("dotenv/config");
+var import_commander = require("commander");
+
+// package.json
+var version = "3.0.0-wip-yjs-state-changes.0";
+
+// src/config.ts
+var import_os2 = __toESM(require("os"));
+var import_path2 = __toESM(require("path"));
+
+// src/images.ts
+var import_fs = __toESM(require("fs"));
+var import_os = __toESM(require("os"));
+var import_path = __toESM(require("path"));
+var import_promises = require("stream/promises");
+var import_stream = require("stream");
+
+// ../builder-types/src/vm.ts
+var VM_STACKS = ["generic", "node", "python", "static"];
+
+// ../builder-types/src/events.ts
+var WorkerEvent = {
+  // worker → sandbox
+  HEARTBEAT: "worker:heartbeat",
+  // sandbox → worker, once right after auth on every (re)connect — the VMs sandbox's
+  // records say this workerId owns, so the worker can try to reattach before its first
+  // heartbeat. Always sent, even with an empty array, as a handshake signal.
+  REATTACH: "worker:reattach",
+  // sandbox → worker (VM lifecycle commands)
+  VM_CREATE: "vm:create",
+  VM_PAUSE: "vm:pause",
+  VM_RESUME: "vm:resume",
+  VM_STOP: "vm:stop",
+  VM_RESTORE: "vm:restore",
+  VM_DESTROY: "vm:destroy",
+  // sandbox / gateway → worker (HTTP proxy)
+  PROXY_HTTP: "proxy:http",
+  // sandbox → worker (guest workspace commands)
+  VM_EXEC: "vm:exec",
+  VM_WRITE_FILES: "vm:write-files",
+  // worker → sandbox (VNC/terminal media relay)
+  VNC_INIT: "vnc:init",
+  VNC_FRAME: "vnc:frame",
+  VNC_COPY_FRAME: "vnc:copy-frame",
+  TERMINAL_DATA: "terminal:data",
+  // sandbox → worker (browser input forwarded downstream)
+  VNC_MOUSE: "vnc:mouse",
+  VNC_KEYBOARD: "vnc:keyboard",
+  TERMINAL_INPUT: "terminal:input"
+};
+var VM_ACTION_EVENTS = {
+  pause: WorkerEvent.VM_PAUSE,
+  resume: WorkerEvent.VM_RESUME,
+  stop: WorkerEvent.VM_STOP,
+  restore: WorkerEvent.VM_RESTORE
+};
+
+// src/images.ts
+var IMAGE_FILES = ["vmlinuz", "initramfs.img"];
+function hostArch() {
+  switch (process.arch) {
+    case "arm64":
+      return "aarch64";
+    case "x64":
+      return "x86_64";
+    default:
+      return process.arch;
+  }
+}
+function defaultImagesDir(arch = hostArch()) {
+  return import_path.default.join(import_os.default.homedir(), ".multiplayer", "vm-images", arch);
+}
+function resolveStackImages(imagesDir, stack) {
+  const kernelPath = import_path.default.join(imagesDir, stack, "vmlinuz");
+  const initrdPath = import_path.default.join(imagesDir, stack, "initramfs.img");
+  return import_fs.default.existsSync(kernelPath) && import_fs.default.existsSync(initrdPath) ? { kernelPath, initrdPath } : void 0;
+}
+function availableStacks(imagesDir) {
+  return VM_STACKS.filter((stack) => resolveStackImages(imagesDir, stack) !== void 0);
+}
+function parseS3Uri(uri) {
+  const match = /^s3:\/\/([^/]+)\/?(.*)$/.exec(uri);
+  if (!match) throw new Error(`invalid S3 URI "${uri}" \u2014 expected s3://bucket[/prefix]`);
+  return { bucket: match[1], prefix: match[2].replace(/\/+$/, "") };
+}
+function s3Key(prefix, arch, stack, file) {
+  return [prefix, arch, stack, file].filter(Boolean).join("/");
+}
+async function makeS3Client(endpoint) {
+  const { S3Client } = await import("@aws-sdk/client-s3");
+  return new S3Client({
+    ...endpoint ? { endpoint, forcePathStyle: true } : {},
+    ...process.env.AWS_REGION ? {} : { region: "us-east-1" },
+    // aws-chunked checksum streaming breaks older S3-compatible stores (MinIO)
+    requestChecksumCalculation: "WHEN_REQUIRED"
+  });
+}
+async function downloadFromS3(opts, stack, file, dest) {
+  const { GetObjectCommand } = await import("@aws-sdk/client-s3");
+  const { bucket, prefix } = parseS3Uri(opts.location);
+  const client = await makeS3Client(opts.endpoint);
+  const key = s3Key(prefix, opts.arch, stack, file);
+  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+  if (!response.Body) throw new Error(`empty response for s3://${bucket}/${key}`);
+  await (0, import_promises.pipeline)(response.Body, import_fs.default.createWriteStream(dest));
+}
+async function downloadFromHttp(opts, stack, file, dest) {
+  const url = `${opts.location.replace(/\/+$/, "")}/${opts.arch}/${stack}/${file}`;
+  const response = await fetch(url);
+  if (!response.ok || !response.body) {
+    throw new Error(`GET ${url} failed: ${response.status} ${response.statusText}`);
+  }
+  await (0, import_promises.pipeline)(import_stream.Readable.fromWeb(response.body), import_fs.default.createWriteStream(dest));
+}
+async function pullImages(opts, destDir) {
+  const isS3 = opts.location.startsWith("s3://");
+  const downloaded = [];
+  for (const stack of opts.stacks ?? VM_STACKS) {
+    const stackDir = import_path.default.join(destDir, stack);
+    import_fs.default.mkdirSync(stackDir, { recursive: true });
+    for (const file of IMAGE_FILES) {
+      const dest = import_path.default.join(stackDir, file);
+      const partial = `${dest}.partial`;
+      if (isS3) await downloadFromS3(opts, stack, file, partial);
+      else await downloadFromHttp(opts, stack, file, partial);
+      import_fs.default.renameSync(partial, dest);
+      downloaded.push(dest);
+    }
+  }
+  return downloaded;
+}
+async function pushImages(opts, srcDir) {
+  const { PutObjectCommand } = await import("@aws-sdk/client-s3");
+  const { bucket, prefix } = parseS3Uri(opts.location);
+  const client = await makeS3Client(opts.endpoint);
+  const uploaded = [];
+  const stacks = opts.stacks ?? availableStacks(srcDir);
+  if (!stacks.length) {
+    throw new Error(`no stack images found under ${srcDir} \u2014 run scripts/setup-vm-images.sh first`);
+  }
+  for (const stack of stacks) {
+    for (const file of IMAGE_FILES) {
+      const src = import_path.default.join(srcDir, stack, file);
+      if (!import_fs.default.existsSync(src)) {
+        throw new Error(`${src} not found \u2014 run scripts/setup-vm-images.sh first`);
+      }
+      const key = s3Key(prefix, opts.arch, stack, file);
+      await client.send(new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        Body: import_fs.default.readFileSync(src)
+      }));
+      uploaded.push(`s3://${bucket}/${key}`);
+    }
+  }
+  return uploaded;
+}
+
+// src/config.ts
+function parseStackMap(raw) {
+  const map = {};
+  if (!raw) return map;
+  for (const pair of raw.split(",")) {
+    const idx = pair.indexOf(":");
+    if (idx === -1) continue;
+    const stack = pair.slice(0, idx).trim();
+    const arn = pair.slice(idx + 1).trim();
+    if (stack && arn) map[stack] = arn;
+  }
+  return map;
+}
+function parseArnList(raw) {
+  if (!raw) return void 0;
+  const arns = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return arns.length ? arns : void 0;
+}
+function loadWorkerConfigFromEnv(env = process.env) {
+  const workerId = env.WORKER_ID?.trim() || import_os2.default.hostname();
+  const token = env.WORKER_TOKEN;
+  if (!token) {
+    throw new Error("WORKER_TOKEN is required");
+  }
+  return {
+    workerId,
+    token,
+    sandboxUrl: env.SANDBOX_URL ?? "https://api.sandbox.filingramp.com",
+    workerSocketPath: env.WORKER_SOCKET_PATH ?? "/v0/sapi/workers/ws",
+    maxVms: Number(env.MAX_VMS) || 10,
+    region: env.WORKER_REGION,
+    remote: {
+      // No default: an unset AGENT_URL means the remote engine is not configured on this worker
+      agentUrl: env.AGENT_URL ?? "",
+      authToken: env.AGENT_TOKEN
+    },
+    firecracker: {
+      bin: env.FIRECRACKER_BIN ?? "firecracker",
+      // Per-stack base images (<imagesDir>/<stack>/vmlinuz + initramfs.img) from
+      // `worker-cli images pull` / setup-vm-images.sh; engine detection checks
+      // existence, so missing images just disable the engine.
+      imagesDir: env.FIRECRACKER_IMAGES_DIR ?? env.VM_IMAGES_DIR ?? defaultImagesDir(),
+      // Explicit single-image override, applied to every stack when both are set
+      kernelPath: env.FIRECRACKER_KERNEL,
+      initrdPath: env.FIRECRACKER_INITRD,
+      vmDataPath: env.FIRECRACKER_VM_DATA ?? import_path2.default.join(import_os2.default.tmpdir(), "firecracker-vms")
+    },
+    lambdaMicrovm: {
+      region: env.MICROVM_AWS_REGION ?? env.AWS_REGION,
+      imageArn: env.MICROVM_IMAGE_ARN ?? "",
+      stackImageArns: parseStackMap(env.MICROVM_STACK_IMAGE_ARNS),
+      ingressConnectorArns: parseArnList(env.MICROVM_INGRESS_CONNECTORS),
+      egressConnectorArns: parseArnList(env.MICROVM_EGRESS_CONNECTORS),
+      executionRoleArn: env.MICROVM_EXECUTION_ROLE_ARN,
+      // 0 disables auto-suspend; the sandbox drives pause/resume explicitly by default
+      maxIdleSeconds: Number(env.MICROVM_MAX_IDLE_SECONDS ?? 900),
+      suspendedDurationSeconds: Number(env.MICROVM_SUSPENDED_DURATION_SECONDS ?? 28800),
+      maximumDurationInSeconds: Number(env.MICROVM_MAX_DURATION_SECONDS ?? 28800)
+    },
+    fargate: {
+      region: env.FARGATE_AWS_REGION ?? env.AWS_REGION,
+      cluster: env.FARGATE_CLUSTER ?? "",
+      taskDefinition: env.FARGATE_TASK_DEFINITION,
+      // Per-stack task definitions: "node:builder-node:3,python:builder-python:1"
+      stackTaskDefinitions: parseStackMap(env.FARGATE_STACK_TASK_DEFS),
+      subnets: env.FARGATE_SUBNETS?.split(",").map((s) => s.trim()).filter(Boolean) ?? [],
+      securityGroups: env.FARGATE_SECURITY_GROUPS?.split(",").map((s) => s.trim()).filter(Boolean),
+      // ENABLED when the worker runs outside the task VPC (proxies to the task's public IP)
+      assignPublicIp: env.FARGATE_ASSIGN_PUBLIC_IP === "true",
+      guestPort: Number(env.FARGATE_GUEST_PORT) || 8080,
+      startTimeoutMs: Number(env.FARGATE_START_TIMEOUT_MS) || 18e4
+    },
+    docker: {
+      bin: env.DOCKER_BIN ?? "docker",
+      // Local images from `scripts/setup-docker-images.sh`: <imagePrefix>-<stack>:<imageTag>
+      imagePrefix: env.DOCKER_IMAGE_PREFIX ?? "multiplayer-builder-vm",
+      imageTag: env.DOCKER_IMAGE_TAG ?? "local",
+      stackImages: parseStackMap(env.DOCKER_STACK_IMAGES),
+      network: env.DOCKER_NETWORK,
+      portRangeStart: Number(env.DOCKER_PORT_MIN) || 9100,
+      portRangeEnd: Number(env.DOCKER_PORT_MAX) || 9199,
+      guestPort: Number(env.DOCKER_GUEST_PORT) || 8080
+    },
+    dockerSandbox: {
+      bin: env.SBX_BIN ?? "sbx",
+      // Bridged from the same local images `docker` (imagePrefix-imageTag) already uses —
+      // `docker save` + `sbx template load`, see docker-sandbox-executor.ts.
+      imagePrefix: env.SBX_IMAGE_PREFIX ?? "multiplayer-builder-vm",
+      imageTag: env.SBX_IMAGE_TAG ?? "local",
+      stackTemplates: parseStackMap(env.SBX_STACK_TEMPLATES),
+      // `sbx create shell` doesn't run the image's own CMD, so the engine launches
+      // it explicitly — defaults match each Dockerfile's own WORKDIR /app + CMD.
+      stackAgentCommands: {
+        node: "node app.js",
+        python: "python app.py",
+        static: "node app.js",
+        ...parseStackMap(env.SBX_STACK_AGENT_COMMANDS)
+      },
+      workspaceRoot: env.SBX_WORKSPACE_DIR ?? import_path2.default.join(import_os2.default.tmpdir(), "sbx-vms"),
+      portRangeStart: Number(env.SBX_PORT_MIN) || 9200,
+      portRangeEnd: Number(env.SBX_PORT_MAX) || 9299,
+      guestPort: Number(env.SBX_GUEST_PORT) || 8080,
+      // sbx rejects sandboxes below 1 GiB memory.
+      minMemoryMib: Number(env.SBX_MIN_MEMORY_MIB) || 1024
+    },
+    qemu: {
+      bin: env.QEMU_BIN ?? "qemu-system-aarch64",
+      // Per-stack base images (<imagesDir>/<stack>/vmlinuz + initramfs.img) from
+      // `worker-cli images pull` / setup-vm-images.sh; engine detection checks
+      // existence, so missing images just disable the engine.
+      imagesDir: env.QEMU_IMAGES_DIR ?? env.VM_IMAGES_DIR ?? defaultImagesDir(),
+      // Explicit single-image override, applied to every stack when both are set
+      kernelPath: env.QEMU_KERNEL,
+      initrdPath: env.QEMU_INITRD,
+      vmDataPath: env.QEMU_VM_DATA ?? import_path2.default.join(import_os2.default.tmpdir(), "qemu-vms"),
+      portRangeStart: Number(env.QEMU_PORT_MIN) || 9e3,
+      portRangeEnd: Number(env.QEMU_PORT_MAX) || 9999,
+      // Accelerator: hvf (macOS host), kvm (Linux + /dev/kvm), tcg (software, any host — slow)
+      accel: env.QEMU_ACCEL ?? (process.platform === "darwin" ? "hvf" : "kvm"),
+      // CPU model: host requires hvf/kvm; max is best for tcg on aarch64; qemu64 for tcg x86_64
+      cpu: env.QEMU_CPU ?? "host",
+      // Machine type: virt (aarch64), q35 (x86_64)
+      machine: env.QEMU_MACHINE ?? "virt"
+    }
+  };
+}
+
+// ../logger/src/logger.ts
+var import_bunyan = __toESM(require("bunyan"));
+var import_os3 = require("os");
+
+// ../logger/src/config.ts
+var NODE_ENV = process.env.NODE_ENV || "development";
+var isProduction = NODE_ENV === "production";
+var APP_NAME = process.env.npm_package_name?.split("/").pop() || "tests";
+var LOG_LEVEL = process.env.LOG_LEVEL || (isProduction ? "info" : "debug");
+
+// ../logger/src/logger.ts
+var HOST_NAME = (0, import_os3.hostname)();
+var loggerOptions = {
+  name: APP_NAME,
+  level: LOG_LEVEL,
+  hostname: HOST_NAME,
+  serializers: import_bunyan.default.stdSerializers
+};
+var logger = import_bunyan.default.createLogger(loggerOptions);
+
+// ../logger/src/kafkajs-logger-creator.ts
+var import_bunyan2 = __toESM(require("bunyan"));
+var import_os4 = require("os");
+var HOST_NAME2 = (0, import_os4.hostname)();
+
+// ../logger/src/index.ts
+var src_default = logger;
+
+// src/executor/mock-executor.ts
+var import_child_process = require("child_process");
+var import_promises2 = __toESM(require("fs/promises"));
+var import_http = __toESM(require("http"));
+var import_os5 = __toESM(require("os"));
+var import_path3 = __toESM(require("path"));
+var DEFAULT_EXEC_TIMEOUT_MS = 6e4;
+var MAX_EXEC_TIMEOUT_MS = 3e5;
+var MAX_OUTPUT_BYTES = 1024 * 1024;
+var MAX_FILE_BYTES = 5 * 1024 * 1024;
+var CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/plain; charset=utf-8"
+};
+function resolveWorkspacePath(workspaceDir, relativePath) {
+  const normalized = import_path3.default.normalize(relativePath).replace(/^([/\\])+/, "");
+  const resolved = import_path3.default.resolve(workspaceDir, normalized);
+  if (resolved !== workspaceDir && !resolved.startsWith(workspaceDir + import_path3.default.sep)) {
+    throw new Error(`Path escapes the VM workspace: ${relativePath}`);
+  }
+  return resolved;
+}
+function startStandInServer(spec, workspaceDir) {
+  const server = import_http.default.createServer((req, res) => {
+    void (async () => {
+      const requestPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
+      const relative = requestPath === "/" ? "index.html" : requestPath;
+      try {
+        const filePath = resolveWorkspacePath(workspaceDir, relative);
+        const content = await import_promises2.default.readFile(filePath);
+        res.writeHead(200, { "content-type": CONTENT_TYPES[import_path3.default.extname(filePath).toLowerCase()] ?? "application/octet-stream" });
+        res.end(content);
+      } catch {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end(`mock vm ${spec.vmId} (${spec.stack}) \u2014 session ${spec.sessionId} \u2014 ${req.method} ${req.url}
+`);
+      }
+    })();
+  });
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      resolve({ server, port: server.address().port });
+    });
+  });
+}
+var MockExecutor = class {
+  constructor() {
+    this.vms = /* @__PURE__ */ new Map();
+  }
+  async create(spec) {
+    const workspaceDir = await import_promises2.default.mkdtemp(import_path3.default.join(import_os5.default.tmpdir(), `mock-vm-${spec.vmId}-`));
+    const { server, port } = await startStandInServer(spec, workspaceDir);
+    const handle = {
+      vmId: spec.vmId,
+      sessionId: spec.sessionId,
+      stack: spec.stack,
+      resources: spec.resources,
+      running: true
+    };
+    this.vms.set(spec.vmId, { handle, server, port, workspaceDir });
+    src_default.info({ vmId: spec.vmId, port, workspaceDir }, "mock vm created");
+    return handle;
+  }
+  async pause(vmId) {
+    return this.setRunning(vmId, false);
+  }
+  async resume(vmId) {
+    return this.setRunning(vmId, true);
+  }
+  async stop(vmId) {
+    return this.setRunning(vmId, false);
+  }
+  async restore(vmId) {
+    return this.setRunning(vmId, true);
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    await new Promise((resolve) => vm.server.close(() => resolve()));
+    await import_promises2.default.rm(vm.workspaceDir, { recursive: true, force: true });
+    this.vms.delete(vmId);
+    src_default.info({ vmId }, "mock vm destroyed");
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  list() {
+    return [...this.vms.values()].map((vm) => vm.handle);
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.requireRunningVm(vmId);
+    return new Promise((resolve, reject) => {
+      const proxyReq = import_http.default.request(
+        {
+          host: "127.0.0.1",
+          port: vm.port,
+          method: request.method,
+          path: request.path,
+          headers: request.headers
+        },
+        (proxyRes) => {
+          const chunks = [];
+          proxyRes.on("data", (chunk) => chunks.push(chunk));
+          proxyRes.on("end", () => {
+            resolve({
+              statusCode: proxyRes.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(proxyRes.headers).map(([key, value]) => [key, Array.isArray(value) ? value.join(", ") : value ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            });
+          });
+        }
+      );
+      proxyReq.on("error", reject);
+      if (request.body) proxyReq.write(request.body);
+      proxyReq.end();
+    });
+  }
+  async writeFiles(vmId, files) {
+    const vm = this.requireRunningVm(vmId);
+    const written = [];
+    for (const file of files) {
+      const buffer = Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8");
+      if (buffer.byteLength > MAX_FILE_BYTES) {
+        throw new Error(`File too large (${buffer.byteLength} bytes, max ${MAX_FILE_BYTES}): ${file.path}`);
+      }
+      const filePath = resolveWorkspacePath(vm.workspaceDir, file.path);
+      await import_promises2.default.mkdir(import_path3.default.dirname(filePath), { recursive: true });
+      await import_promises2.default.writeFile(filePath, buffer);
+      written.push({ path: import_path3.default.relative(vm.workspaceDir, filePath), bytes: buffer.byteLength });
+    }
+    src_default.info({ vmId, files: written.length }, "mock vm files written");
+    return { written };
+  }
+  async exec(vmId, request) {
+    const vm = this.requireRunningVm(vmId);
+    const cwd = request.cwd ? resolveWorkspacePath(vm.workspaceDir, request.cwd) : vm.workspaceDir;
+    const timeoutMs = Math.min(request.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS, MAX_EXEC_TIMEOUT_MS);
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+      (0, import_child_process.execFile)(
+        "/bin/sh",
+        ["-c", request.command],
+        {
+          cwd,
+          timeout: timeoutMs,
+          maxBuffer: MAX_OUTPUT_BYTES,
+          env: { ...process.env, HOME: vm.workspaceDir }
+        },
+        (error, stdout, stderr) => {
+          const failed = error;
+          const timedOut = Boolean(failed?.killed);
+          const truncated = failed?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+          resolve({
+            exitCode: typeof failed?.code === "number" ? failed.code : failed ? 1 : 0,
+            stdout: stdout.slice(0, MAX_OUTPUT_BYTES),
+            stderr: stderr.slice(0, MAX_OUTPUT_BYTES),
+            durationMs: Date.now() - startedAt,
+            truncated: Boolean(truncated),
+            timedOut
+          });
+        }
+      );
+    });
+  }
+  requireRunningVm(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm || !vm.handle.running) {
+      throw new Error(`vm ${vmId} is not running`);
+    }
+    return vm;
+  }
+  setRunning(vmId, running) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    vm.handle = { ...vm.handle, running };
+    return vm.handle;
+  }
+};
+
+// src/executor/qemu-executor.ts
+var import_child_process2 = require("child_process");
+var import_net = __toESM(require("net"));
+var import_path4 = __toESM(require("path"));
+var import_promises3 = __toESM(require("fs/promises"));
+var import_os6 = __toESM(require("os"));
+
+// src/executor/reattach-utils.ts
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms))
+  ]);
+}
+
+// src/executor/qemu-executor.ts
+var QemuExecutor = class {
+  constructor(config) {
+    this.config = config;
+    this.vms = /* @__PURE__ */ new Map();
+    this.usedHttpPorts = /* @__PURE__ */ new Set();
+    this.usedDisplays = /* @__PURE__ */ new Set();
+    // VNC display indices
+    this.usedSerialPorts = /* @__PURE__ */ new Set();
+    this.bin = config.bin ?? "qemu-system-aarch64";
+    this.vmDataPath = config.vmDataPath ?? import_path4.default.join(import_os6.default.tmpdir(), "qemu-vms");
+    this.httpPortStart = config.httpPortRangeStart ?? 9e3;
+    this.httpPortEnd = config.httpPortRangeEnd ?? 9099;
+    this.vncBasePort = config.vncBasePort ?? 5900;
+    this.serialBasePort = config.serialBasePort ?? 8e3;
+    this.accel = config.accel ?? "hvf";
+    this.cpu = config.cpu ?? "host";
+    this.machine = config.machine ?? "virt";
+  }
+  allocateHttpPort() {
+    for (let p = this.httpPortStart; p <= this.httpPortEnd; p++) {
+      if (!this.usedHttpPorts.has(p)) {
+        this.usedHttpPorts.add(p);
+        return p;
+      }
+    }
+    throw new Error("no free HTTP ports in QEMU port range");
+  }
+  allocateVncDisplay() {
+    for (let d = 1; d <= 99; d++) {
+      if (!this.usedDisplays.has(d)) {
+        this.usedDisplays.add(d);
+        return d;
+      }
+    }
+    throw new Error("no free VNC displays");
+  }
+  allocateSerialPort() {
+    for (let p = this.serialBasePort; p <= this.serialBasePort + 99; p++) {
+      if (!this.usedSerialPorts.has(p)) {
+        this.usedSerialPorts.add(p);
+        return p;
+      }
+    }
+    throw new Error("no free serial ports");
+  }
+  /** Explicit kernel/initrd override wins; otherwise the stack's base image, falling back to generic. */
+  resolveImages(stack) {
+    if (this.config.kernelPath && this.config.initrdPath) {
+      return { kernelPath: this.config.kernelPath, initrdPath: this.config.initrdPath };
+    }
+    const resolved = this.config.imagesDir ? resolveStackImages(this.config.imagesDir, stack) ?? resolveStackImages(this.config.imagesDir, "generic") : void 0;
+    if (!resolved) {
+      throw new Error(`no base image for stack "${stack}" under ${this.config.imagesDir} \u2014 run "worker-cli images pull"`);
+    }
+    return resolved;
+  }
+  async create(spec) {
+    const { kernelPath, initrdPath } = this.resolveImages(spec.stack);
+    const hostPort = this.allocateHttpPort();
+    const vncDisplay = this.allocateVncDisplay();
+    const serialPort = this.allocateSerialPort();
+    const vncPort = this.vncBasePort + vncDisplay;
+    const vmDir = import_path4.default.join(this.vmDataPath, spec.vmId);
+    await import_promises3.default.mkdir(vmDir, { recursive: true });
+    const qmpSocketPath = import_path4.default.join(vmDir, "qmp.sock");
+    const args = [
+      "-machine",
+      this.machine,
+      "-cpu",
+      this.cpu,
+      "-accel",
+      this.accel,
+      "-smp",
+      String(spec.resources.vcpuCount),
+      "-m",
+      String(spec.resources.memMib),
+      "-kernel",
+      kernelPath,
+      "-initrd",
+      initrdPath,
+      // console=tty0 sends output to VGA framebuffer (VNC); ttyAMA0 to serial.
+      // APP_URL_B64: base64-encoded presigned artifact URL — kernel cmdline params are
+      // space-separated, so the raw URL (query string, &) can't be passed directly.
+      "-append",
+      [
+        `console=tty0 console=ttyAMA0 net.ifnames=0 init=/init VM_ID=${spec.vmId} STACK=${spec.stack}`,
+        spec.sessionId ? `SESSION_ID=${spec.sessionId}` : "",
+        spec.appUrl ? `APP_URL_B64=${Buffer.from(spec.appUrl).toString("base64")}` : ""
+      ].filter(Boolean).join(" "),
+      // Networking
+      "-netdev",
+      `user,id=net0,hostfwd=tcp::${hostPort}-:8080`,
+      "-device",
+      "virtio-net-pci,netdev=net0",
+      // Display: virtio-gpu-pci works on both aarch64 and x86_64; virtio-vga is x86-only
+      "-device",
+      "virtio-gpu-pci",
+      "-display",
+      "none",
+      "-vnc",
+      `127.0.0.1:${vncDisplay}`,
+      // Serial console via TCP (xterm.js connects here)
+      "-serial",
+      `tcp:127.0.0.1:${serialPort},server,nowait`,
+      // Control
+      "-no-reboot",
+      "-qmp",
+      `unix:${qmpSocketPath},server,nowait`
+    ];
+    src_default.info({ vmId: spec.vmId, bin: this.bin, args }, "spawning qemu");
+    const proc = (0, import_child_process2.spawn)(this.bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    proc.stdout?.on("data", (d) => src_default.info({ vmId: spec.vmId }, d.toString().trimEnd()));
+    proc.stderr?.on("data", (d) => src_default.error({ vmId: spec.vmId }, d.toString().trimEnd()));
+    proc.on("exit", (code, signal) => {
+      const log = code === 0 || code === null ? src_default.info.bind(src_default) : src_default.error.bind(src_default);
+      log({ vmId: spec.vmId, code, signal }, "qemu process exited");
+      const vm2 = this.vms.get(spec.vmId);
+      if (vm2) {
+        this.usedHttpPorts.delete(vm2.hostPort);
+        this.usedDisplays.delete(vm2.vncDisplay);
+        this.usedSerialPorts.delete(vm2.serialPort);
+        this.vms.delete(spec.vmId);
+      }
+    });
+    const metadata = { hostPort, qmpSocketPath, vncDisplay, serialPort, pid: proc.pid };
+    const handle = {
+      vmId: spec.vmId,
+      sessionId: spec.sessionId,
+      stack: spec.stack,
+      resources: spec.resources,
+      running: true,
+      vncPort,
+      serialPort,
+      metadata
+    };
+    const vm = { handle, process: proc, pid: proc.pid, hostPort, qmpSocketPath, vncDisplay, serialPort };
+    this.vms.set(spec.vmId, vm);
+    await waitForQmp(qmpSocketPath);
+    src_default.info({ vmId: spec.vmId, hostPort, vncPort, serialPort }, "qemu vm ready");
+    return handle;
+  }
+  async pause(vmId) {
+    await this.qmp(vmId, "stop");
+    return this.setRunning(vmId, false);
+  }
+  async resume(vmId) {
+    await this.qmp(vmId, "cont");
+    return this.setRunning(vmId, true);
+  }
+  async stop(vmId) {
+    await this.qmp(vmId, "stop");
+    return this.setRunning(vmId, false);
+  }
+  async restore(vmId) {
+    await this.qmp(vmId, "cont");
+    return this.setRunning(vmId, true);
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    try {
+      await this.qmp(vmId, "quit");
+    } catch {
+      this.killVm(vm);
+    }
+    if (vm.process) {
+      const proc = vm.process;
+      await new Promise((resolve) => {
+        if (proc.exitCode !== null) return resolve();
+        proc.once("exit", resolve);
+        setTimeout(() => {
+          this.killVm(vm);
+          resolve();
+        }, 3e3);
+      });
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+      this.killVm(vm);
+    }
+    this.usedHttpPorts.delete(vm.hostPort);
+    this.usedDisplays.delete(vm.vncDisplay);
+    this.usedSerialPorts.delete(vm.serialPort);
+    this.vms.delete(vmId);
+    await import_promises3.default.rm(import_path4.default.join(this.vmDataPath, vmId), { recursive: true, force: true });
+    src_default.info({ vmId }, "qemu vm destroyed");
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  list() {
+    return [...this.vms.values()].map((v) => v.handle);
+  }
+  /**
+   * Recover a QEMU VM after a worker restart: the process may well have survived (it's not
+   * killed just because its Node parent exited), so probe its QMP socket — if it answers,
+   * lifecycle control and HTTP proxying resume normally. There's no live ChildProcess to
+   * reattach to, so destroy() falls back to killing the stored pid.
+   */
+  async reattach(record) {
+    const meta = record.runtimeMetadata;
+    if (!meta?.qmpSocketPath || meta.hostPort === void 0 || meta.vncDisplay === void 0 || meta.serialPort === void 0) {
+      return void 0;
+    }
+    try {
+      await withTimeout(sendQmpCommand(meta.qmpSocketPath, "query-status"), 5e3);
+    } catch {
+      return void 0;
+    }
+    const handle = {
+      vmId: record.vmId,
+      sessionId: record.sessionId,
+      stack: record.stack,
+      resources: record.resources,
+      running: record.state === "running",
+      vncPort: this.vncBasePort + meta.vncDisplay,
+      serialPort: meta.serialPort,
+      metadata: meta
+    };
+    this.usedHttpPorts.add(meta.hostPort);
+    this.usedDisplays.add(meta.vncDisplay);
+    this.usedSerialPorts.add(meta.serialPort);
+    this.vms.set(record.vmId, {
+      handle,
+      pid: meta.pid,
+      hostPort: meta.hostPort,
+      qmpSocketPath: meta.qmpSocketPath,
+      vncDisplay: meta.vncDisplay,
+      serialPort: meta.serialPort
+    });
+    src_default.info({ vmId: record.vmId }, "qemu vm reattached");
+    return handle;
+  }
+  killVm(vm) {
+    if (vm.process) {
+      vm.process.kill("SIGKILL");
+      return;
+    }
+    if (vm.pid) {
+      try {
+        process.kill(vm.pid, "SIGKILL");
+      } catch {
+      }
+    }
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.vms.get(vmId);
+    if (!vm?.handle.running) throw new Error(`vm ${vmId} is not running`);
+    const { default: http7 } = await import("http");
+    return new Promise((resolve, reject) => {
+      const req = http7.request(
+        { host: "127.0.0.1", port: vm.hostPort, method: request.method, path: request.path, headers: request.headers },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on(
+            "end",
+            () => resolve({
+              statusCode: res.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            })
+          );
+        }
+      );
+      req.on("error", reject);
+      if (request.body) req.write(request.body);
+      req.end();
+    });
+  }
+  setRunning(vmId, running) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    vm.handle = { ...vm.handle, running };
+    return vm.handle;
+  }
+  async qmp(vmId, execute) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    await sendQmpCommand(vm.qmpSocketPath, execute);
+  }
+};
+function waitForQmp(socketPath, timeoutMs = 3e4) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const attempt = () => {
+      if (Date.now() > deadline) return reject(new Error(`timed out waiting for QMP socket at ${socketPath}`));
+      const sock = import_net.default.createConnection(socketPath);
+      sock.once("connect", () => {
+        sock.destroy();
+        resolve();
+      });
+      sock.once("error", () => setTimeout(attempt, 500));
+    };
+    attempt();
+  });
+}
+async function sendQmpCommand(socketPath, execute) {
+  return new Promise((resolve, reject) => {
+    const sock = import_net.default.createConnection(socketPath);
+    let buf = "";
+    let ready = false;
+    const send = (obj) => sock.write(JSON.stringify(obj) + "\r\n");
+    sock.on("data", (data) => {
+      buf += data.toString();
+      let idx;
+      while ((idx = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, idx).trim();
+        buf = buf.slice(idx + 1);
+        if (!line) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (msg["QMP"]) {
+          send({ execute: "qmp_capabilities" });
+        } else if (!ready && "return" in msg) {
+          ready = true;
+          send({ execute });
+        } else if (ready && "return" in msg) {
+          sock.destroy();
+          resolve();
+        } else if (msg["error"]) {
+          sock.destroy();
+          reject(new Error(`QMP error for "${execute}": ${JSON.stringify(msg["error"])}`));
+        }
+      }
+    });
+    sock.on("error", (e) => {
+      if (execute === "quit") resolve();
+      else reject(e);
+    });
+    sock.on("close", () => resolve());
+  });
+}
+
+// src/executor/firecracker-executor.ts
+var import_child_process3 = require("child_process");
+var import_child_process4 = require("child_process");
+var import_util = require("util");
+var import_http2 = __toESM(require("http"));
+var import_net2 = __toESM(require("net"));
+var import_path5 = __toESM(require("path"));
+var import_promises4 = __toESM(require("fs/promises"));
+var import_os7 = __toESM(require("os"));
+var execAsync = (0, import_util.promisify)(import_child_process4.exec);
+var FirecrackerExecutor = class {
+  constructor(config) {
+    this.config = config;
+    this.vms = /* @__PURE__ */ new Map();
+    this.usedSubnets = /* @__PURE__ */ new Set();
+    this.tapCounter = 0;
+    this.networkReady = false;
+    this.bin = config.bin ?? "firecracker";
+    this.vmDataPath = config.vmDataPath ?? import_path5.default.join(import_os7.default.tmpdir(), "firecracker-vms");
+  }
+  allocateSubnet() {
+    for (let s = 1; s <= 254; s++) {
+      if (!this.usedSubnets.has(s)) {
+        this.usedSubnets.add(s);
+        return s;
+      }
+    }
+    throw new Error("no free TAP subnets (max 254 concurrent VMs)");
+  }
+  // Called once before the first VM; sets up host-level IP forwarding + masquerade.
+  async ensureNetworking() {
+    if (this.networkReady) return;
+    await execAsync("sysctl -w net.ipv4.ip_forward=1");
+    const alreadySet = await execAsync(
+      "iptables -t nat -C POSTROUTING -s 172.16.0.0/12 ! -d 172.16.0.0/12 -j MASQUERADE"
+    ).catch(() => null);
+    if (!alreadySet) {
+      await execAsync("iptables -t nat -A POSTROUTING -s 172.16.0.0/12 ! -d 172.16.0.0/12 -j MASQUERADE");
+    }
+    this.networkReady = true;
+  }
+  /** Explicit kernel/initrd override wins; otherwise the stack's base image, falling back to generic. */
+  resolveImages(stack) {
+    if (this.config.kernelPath && this.config.initrdPath) {
+      return { kernelPath: this.config.kernelPath, initrdPath: this.config.initrdPath };
+    }
+    const resolved = this.config.imagesDir ? resolveStackImages(this.config.imagesDir, stack) ?? resolveStackImages(this.config.imagesDir, "generic") : void 0;
+    if (!resolved) {
+      throw new Error(`no base image for stack "${stack}" under ${this.config.imagesDir} \u2014 run "worker-cli images pull"`);
+    }
+    return resolved;
+  }
+  async create(spec) {
+    const { kernelPath, initrdPath } = this.resolveImages(spec.stack);
+    await this.ensureNetworking();
+    const subnet = this.allocateSubnet();
+    const tapName = `fctap${++this.tapCounter}`;
+    const hostIp = `172.16.${subnet}.1`;
+    const guestIp = `172.16.${subnet}.2`;
+    const vmDir = import_path5.default.join(this.vmDataPath, spec.vmId);
+    await import_promises4.default.mkdir(vmDir, { recursive: true });
+    const apiSocketPath = import_path5.default.join(vmDir, "api.sock");
+    await import_promises4.default.rm(apiSocketPath, { force: true });
+    await execAsync(`ip tuntap add dev ${tapName} mode tap`);
+    await execAsync(`ip addr add ${hostIp}/30 dev ${tapName}`);
+    await execAsync(`ip link set ${tapName} up`);
+    const proc = (0, import_child_process3.spawn)(this.bin, ["--api-sock", apiSocketPath], {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    proc.stdout?.on("data", (d) => src_default.debug({ vmId: spec.vmId }, d.toString().trimEnd()));
+    proc.stderr?.on("data", (d) => src_default.debug({ vmId: spec.vmId }, d.toString().trimEnd()));
+    proc.on("exit", (code, signal) => {
+      src_default.info({ vmId: spec.vmId, code, signal }, "firecracker process exited");
+      const vm = this.vms.get(spec.vmId);
+      if (vm) {
+        this.usedSubnets.delete(vm.subnet);
+        this.vms.delete(spec.vmId);
+      }
+      execAsync(`ip link del ${tapName}`).catch(() => {
+      });
+    });
+    await waitForSocket(apiSocketPath);
+    const macHex = (n) => n.toString(16).padStart(2, "0");
+    await fcRequest(apiSocketPath, "PUT", "/machine-config", {
+      vcpu_count: spec.resources.vcpuCount,
+      mem_size_mib: spec.resources.memMib
+    });
+    await fcRequest(apiSocketPath, "PUT", "/boot-source", {
+      kernel_image_path: kernelPath,
+      initrd_path: initrdPath,
+      boot_args: [
+        "console=ttyS0",
+        "reboot=k",
+        "panic=1",
+        "pci=off",
+        "net.ifnames=0",
+        "init=/init",
+        `VM_ID=${spec.vmId}`,
+        ...spec.sessionId ? [`SESSION_ID=${spec.sessionId}`] : [],
+        `STACK=${spec.stack}`,
+        // base64: kernel cmdline is space-separated, raw presigned URLs are not safe
+        ...spec.appUrl ? [`APP_URL_B64=${Buffer.from(spec.appUrl).toString("base64")}`] : [],
+        `GUEST_IP=${guestIp}`,
+        `HOST_IP=${hostIp}`
+      ].join(" ")
+    });
+    await fcRequest(apiSocketPath, "PUT", "/network-interfaces/eth0", {
+      iface_id: "eth0",
+      // AA = locally-administered unicast; encode subnet as last two bytes
+      guest_mac: `AA:FC:00:00:${macHex(subnet >> 8)}:${macHex(subnet & 255)}`,
+      host_dev_name: tapName
+    });
+    await fcRequest(apiSocketPath, "PUT", "/actions", { action_type: "InstanceStart" });
+    await waitForHttp(guestIp, 8080);
+    const metadata = { apiSocketPath, tapName, subnet, guestIp, pid: proc.pid };
+    const handle = {
+      vmId: spec.vmId,
+      sessionId: spec.sessionId,
+      stack: spec.stack,
+      resources: spec.resources,
+      running: true,
+      metadata
+    };
+    this.vms.set(spec.vmId, { handle, process: proc, pid: proc.pid, apiSocketPath, tapName, subnet, guestIp });
+    src_default.info({ vmId: spec.vmId, guestIp, tapName }, "firecracker vm ready");
+    return handle;
+  }
+  async pause(vmId) {
+    await this.patchVmState(vmId, "Paused");
+    return this.setRunning(vmId, false);
+  }
+  async resume(vmId) {
+    await this.patchVmState(vmId, "Resumed");
+    return this.setRunning(vmId, true);
+  }
+  async stop(vmId) {
+    await this.patchVmState(vmId, "Paused");
+    return this.setRunning(vmId, false);
+  }
+  async restore(vmId) {
+    await this.patchVmState(vmId, "Resumed");
+    return this.setRunning(vmId, true);
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    if (vm.process) {
+      const proc = vm.process;
+      proc.kill("SIGKILL");
+      await new Promise((resolve) => {
+        if (proc.exitCode !== null) return resolve();
+        proc.once("exit", resolve);
+        setTimeout(() => {
+          proc.kill("SIGKILL");
+          resolve();
+        }, 3e3);
+      });
+    } else if (vm.pid) {
+      try {
+        process.kill(vm.pid, "SIGKILL");
+      } catch {
+      }
+    }
+    this.usedSubnets.delete(vm.subnet);
+    this.vms.delete(vmId);
+    await execAsync(`ip link del ${vm.tapName}`).catch(() => {
+    });
+    await import_promises4.default.rm(import_path5.default.join(this.vmDataPath, vmId), { recursive: true, force: true });
+    src_default.info({ vmId }, "firecracker vm destroyed");
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  getSerialSource(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm?.process) return void 0;
+    return { type: "pipe", process: vm.process };
+  }
+  list() {
+    return [...this.vms.values()].map((v) => v.handle);
+  }
+  /**
+   * Recover a Firecracker VM after a worker restart: the process may well have survived, so
+   * probe its API socket — if it answers, lifecycle control and HTTP proxying resume
+   * normally. There's no live ChildProcess to reattach to, so destroy() falls back to
+   * killing the stored pid, and the serial console is unavailable (see getSerialSource).
+   */
+  async reattach(record) {
+    const meta = record.runtimeMetadata;
+    if (!meta?.apiSocketPath || !meta.tapName || meta.subnet === void 0 || !meta.guestIp) {
+      return void 0;
+    }
+    try {
+      await withTimeout(fcRequest(meta.apiSocketPath, "GET", "/", {}), 5e3);
+    } catch {
+      return void 0;
+    }
+    const handle = {
+      vmId: record.vmId,
+      sessionId: record.sessionId,
+      stack: record.stack,
+      resources: record.resources,
+      running: record.state === "running",
+      metadata: meta
+    };
+    this.usedSubnets.add(meta.subnet);
+    const tapNumber = Number(meta.tapName.replace(/^fctap/, ""));
+    if (Number.isFinite(tapNumber)) this.tapCounter = Math.max(this.tapCounter, tapNumber);
+    this.vms.set(record.vmId, {
+      handle,
+      pid: meta.pid,
+      apiSocketPath: meta.apiSocketPath,
+      tapName: meta.tapName,
+      subnet: meta.subnet,
+      guestIp: meta.guestIp
+    });
+    src_default.info({ vmId: record.vmId, guestIp: meta.guestIp, tapName: meta.tapName }, "firecracker vm reattached");
+    return handle;
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.vms.get(vmId);
+    if (!vm?.handle.running) throw new Error(`vm ${vmId} is not running`);
+    return new Promise((resolve, reject) => {
+      const req = import_http2.default.request(
+        {
+          host: vm.guestIp,
+          port: 8080,
+          method: request.method,
+          path: request.path,
+          headers: request.headers
+        },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on(
+            "end",
+            () => resolve({
+              statusCode: res.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            })
+          );
+        }
+      );
+      req.on("error", reject);
+      if (request.body) req.write(request.body);
+      req.end();
+    });
+  }
+  async patchVmState(vmId, state) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    await fcRequest(vm.apiSocketPath, "PATCH", "/vm", { state });
+  }
+  setRunning(vmId, running) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    vm.handle = { ...vm.handle, running };
+    return vm.handle;
+  }
+};
+function fcRequest(socketPath, method, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = import_http2.default.request(
+      {
+        socketPath,
+        method,
+        path: urlPath,
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+          Accept: "application/json"
+        }
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString();
+          if (res.statusCode && res.statusCode >= 400) {
+            reject(new Error(`Firecracker ${method} ${urlPath} \u2192 ${res.statusCode}: ${text}`));
+          } else {
+            try {
+              resolve(JSON.parse(text));
+            } catch {
+              resolve({});
+            }
+          }
+        });
+      }
+    );
+    req.on("error", reject);
+    req.write(payload);
+    req.end();
+  });
+}
+function waitForSocket(socketPath, timeoutMs = 1e4) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const attempt = () => {
+      if (Date.now() > deadline) return reject(new Error(`timed out waiting for Firecracker socket ${socketPath}`));
+      const sock = import_net2.default.createConnection(socketPath);
+      sock.once("connect", () => {
+        sock.destroy();
+        resolve();
+      });
+      sock.once("error", () => setTimeout(attempt, 100));
+    };
+    attempt();
+  });
+}
+function waitForHttp(host, port, timeoutMs = 6e4) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const attempt = () => {
+      if (Date.now() > deadline) return reject(new Error(`timed out waiting for HTTP at ${host}:${port}`));
+      const req = import_http2.default.get(`http://${host}:${port}/health`, (res) => {
+        if (res.statusCode && res.statusCode < 500) return resolve();
+        res.resume();
+        setTimeout(attempt, 1e3);
+      });
+      req.on("error", () => setTimeout(attempt, 1e3));
+      req.setTimeout(2e3, () => {
+        req.destroy();
+        setTimeout(attempt, 1e3);
+      });
+    };
+    attempt();
+  });
+}
+
+// src/executor/docker-executor.ts
+var import_child_process5 = require("child_process");
+var import_util2 = require("util");
+var import_http3 = __toESM(require("http"));
+var DEFAULT_EXEC_TIMEOUT_MS2 = 6e4;
+var MAX_EXEC_TIMEOUT_MS2 = 3e5;
+var MAX_OUTPUT_BYTES2 = 1024 * 1024;
+var MAX_FILE_BYTES2 = 5 * 1024 * 1024;
+var WORKSPACE_DIR = "/workspace";
+var execFileAsync = (0, import_util2.promisify)(import_child_process5.execFile);
+function assertSafeWorkspacePath(relativePath) {
+  const normalized = relativePath.replace(/^([/\\])+/, "");
+  if (normalized.split(/[/\\]/).includes("..")) {
+    throw new Error(`Path escapes the VM workspace: ${relativePath}`);
+  }
+  return normalized;
+}
+var DockerExecutor = class {
+  constructor(config) {
+    this.config = config;
+    this.vms = /* @__PURE__ */ new Map();
+    this.usedPorts = /* @__PURE__ */ new Set();
+    this.bin = config.bin;
+  }
+  allocatePort() {
+    for (let p = this.config.portRangeStart; p <= this.config.portRangeEnd; p++) {
+      if (!this.usedPorts.has(p)) {
+        this.usedPorts.add(p);
+        return p;
+      }
+    }
+    throw new Error("no free ports in docker port range");
+  }
+  async resolveImage(stack) {
+    const explicit = this.config.stackImages[stack];
+    if (explicit) return explicit;
+    const { imagePrefix, imageTag } = this.config;
+    const stackImage = `${imagePrefix}-${stack}:${imageTag}`;
+    if (await this.imageExists(stackImage)) return stackImage;
+    const genericImage = `${imagePrefix}-generic:${imageTag}`;
+    if (await this.imageExists(genericImage)) return genericImage;
+    throw new Error(`no local docker image for stack "${stack}" (${stackImage}) \u2014 run scripts/setup-docker-images.sh`);
+  }
+  async imageExists(image) {
+    try {
+      await execFileAsync(this.bin, ["image", "inspect", image]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async create(spec) {
+    const image = await this.resolveImage(spec.stack);
+    const hostPort = this.allocatePort();
+    const containerName = `multiplayer-vm-${spec.vmId}`;
+    const args = [
+      "run",
+      "-d",
+      "--name",
+      containerName,
+      "-p",
+      `127.0.0.1:${hostPort}:${this.config.guestPort}`,
+      "--memory",
+      `${spec.resources.memMib}m`,
+      "--cpus",
+      String(spec.resources.vcpuCount),
+      "-e",
+      `VM_ID=${spec.vmId}`,
+      "-e",
+      `STACK=${spec.stack}`,
+      ...spec.sessionId ? ["-e", `SESSION_ID=${spec.sessionId}`] : [],
+      ...spec.appUrl ? ["-e", `APP_URL=${spec.appUrl}`] : [],
+      ...this.config.network ? ["--network", this.config.network] : [],
+      image
+    ];
+    src_default.info({ vmId: spec.vmId, bin: this.bin, args }, "starting docker container");
+    let containerId;
+    try {
+      const { stdout } = await execFileAsync(this.bin, args);
+      containerId = stdout.trim();
+    } catch (error) {
+      this.usedPorts.delete(hostPort);
+      throw error;
+    }
+    const handle = {
+      vmId: spec.vmId,
+      sessionId: spec.sessionId,
+      stack: spec.stack,
+      resources: spec.resources,
+      running: true,
+      metadata: { containerId, containerName, hostPort }
+    };
+    this.vms.set(spec.vmId, { handle, containerId, containerName, hostPort });
+    this.watchExit(spec.vmId, containerId);
+    await this.waitForAgent(hostPort);
+    src_default.info({ vmId: spec.vmId, containerId, hostPort }, "docker vm ready");
+    return handle;
+  }
+  /** Frees the allocated port once the container exits on its own (crash, OOM kill, `docker stop` from outside us). */
+  watchExit(vmId, containerId) {
+    execFileAsync(this.bin, ["wait", containerId]).catch(() => {
+    }).then(() => {
+      const vm = this.vms.get(vmId);
+      if (vm?.containerId === containerId) {
+        vm.handle = { ...vm.handle, running: false };
+      }
+    });
+  }
+  async pause(vmId) {
+    const vm = this.mustGet(vmId);
+    await execFileAsync(this.bin, ["pause", vm.containerId]);
+    return this.setRunning(vmId, false);
+  }
+  async resume(vmId) {
+    const vm = this.mustGet(vmId);
+    await execFileAsync(this.bin, ["unpause", vm.containerId]);
+    return this.setRunning(vmId, true);
+  }
+  async stop(vmId) {
+    const vm = this.mustGet(vmId);
+    await execFileAsync(this.bin, ["stop", vm.containerId]);
+    return this.setRunning(vmId, false);
+  }
+  async restore(vmId) {
+    const vm = this.mustGet(vmId);
+    await execFileAsync(this.bin, ["start", vm.containerId]);
+    return this.setRunning(vmId, true);
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    await execFileAsync(this.bin, ["rm", "-f", vm.containerId]).catch(
+      (error) => src_default.warn({ vmId, err: error }, "docker rm on destroy failed")
+    );
+    this.usedPorts.delete(vm.hostPort);
+    this.vms.delete(vmId);
+    src_default.info({ vmId }, "docker vm destroyed");
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  list() {
+    return [...this.vms.values()].map((v) => v.handle);
+  }
+  /**
+   * Recover a container after a worker restart: it's an independent process the
+   * Docker daemon owns, so just re-inspect it by ID and rebuild the local handle.
+   */
+  async reattach(record) {
+    const meta = record.runtimeMetadata;
+    if (!meta?.containerId || meta.hostPort === void 0) return void 0;
+    let running;
+    try {
+      const { stdout } = await execFileAsync(this.bin, ["inspect", "-f", "{{.State.Running}}", meta.containerId]);
+      running = stdout.trim() === "true";
+    } catch {
+      return void 0;
+    }
+    const handle = {
+      vmId: record.vmId,
+      sessionId: record.sessionId,
+      stack: record.stack,
+      resources: record.resources,
+      running,
+      metadata: meta
+    };
+    this.usedPorts.add(meta.hostPort);
+    this.vms.set(record.vmId, {
+      handle,
+      containerId: meta.containerId,
+      containerName: meta.containerName ?? `multiplayer-vm-${record.vmId}`,
+      hostPort: meta.hostPort
+    });
+    if (running) this.watchExit(record.vmId, meta.containerId);
+    src_default.info({ vmId: record.vmId, containerId: meta.containerId }, "docker vm reattached");
+    return handle;
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.mustGet(vmId);
+    if (!vm.handle.running) throw new Error(`vm ${vmId} is not running`);
+    return new Promise((resolve, reject) => {
+      const req = import_http3.default.request(
+        { host: "127.0.0.1", port: vm.hostPort, method: request.method, path: request.path, headers: request.headers },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on(
+            "end",
+            () => resolve({
+              statusCode: res.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            })
+          );
+        }
+      );
+      req.on("error", reject);
+      if (request.body) req.write(request.body);
+      req.end();
+    });
+  }
+  async exec(vmId, request) {
+    const vm = this.mustGet(vmId);
+    const cwd = request.cwd ? `${WORKSPACE_DIR}/${assertSafeWorkspacePath(request.cwd)}` : WORKSPACE_DIR;
+    const timeoutMs = Math.min(request.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS2, MAX_EXEC_TIMEOUT_MS2);
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+      (0, import_child_process5.execFile)(
+        this.bin,
+        ["exec", "-w", cwd, vm.containerId, "/bin/sh", "-c", request.command],
+        { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES2 },
+        (error, stdout, stderr) => {
+          const failed = error;
+          const timedOut = Boolean(failed?.killed);
+          const truncated = failed?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+          resolve({
+            exitCode: typeof failed?.code === "number" ? failed.code : failed ? 1 : 0,
+            stdout: stdout.slice(0, MAX_OUTPUT_BYTES2),
+            stderr: stderr.slice(0, MAX_OUTPUT_BYTES2),
+            durationMs: Date.now() - startedAt,
+            truncated: Boolean(truncated),
+            timedOut
+          });
+        }
+      );
+    });
+  }
+  async writeFiles(vmId, files) {
+    const vm = this.mustGet(vmId);
+    const written = [];
+    for (const file of files) {
+      const relativePath = assertSafeWorkspacePath(file.path);
+      const buffer = Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8");
+      if (buffer.byteLength > MAX_FILE_BYTES2) {
+        throw new Error(`File too large (${buffer.byteLength} bytes, max ${MAX_FILE_BYTES2}): ${file.path}`);
+      }
+      const dir = relativePath.includes("/") ? relativePath.slice(0, relativePath.lastIndexOf("/")) : "";
+      if (dir) {
+        await execFileAsync(this.bin, ["exec", vm.containerId, "mkdir", "-p", `${WORKSPACE_DIR}/${dir}`]);
+      }
+      await this.copyIntoContainer(vm.containerId, `${WORKSPACE_DIR}/${relativePath}`, buffer);
+      written.push({ path: relativePath, bytes: buffer.byteLength });
+    }
+    src_default.info({ vmId, files: written.length }, "docker vm files written");
+    return { written };
+  }
+  /** `docker cp` needs a tar stream on stdin; build the smallest valid ustar archive for one file. */
+  copyIntoContainer(containerId, destPath, content) {
+    const entryName = destPath.replace(/^\//, "");
+    const tarStream = buildSingleFileTar(entryName, content);
+    return new Promise((resolve, reject) => {
+      const proc = (0, import_child_process5.spawn)(this.bin, ["cp", "-", `${containerId}:/`], { stdio: ["pipe", "ignore", "pipe"] });
+      let stderr = "";
+      proc.stderr?.on("data", (d) => {
+        stderr += d.toString();
+      });
+      proc.on("error", reject);
+      proc.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`docker cp exited ${code}: ${stderr}`)));
+      proc.stdin.end(tarStream);
+    });
+  }
+  mustGet(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    return vm;
+  }
+  setRunning(vmId, running) {
+    const vm = this.mustGet(vmId);
+    vm.handle = { ...vm.handle, running };
+    return vm.handle;
+  }
+  async waitForAgent(port, timeoutMs = 3e4) {
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const ok = await new Promise((resolve) => {
+        const req = import_http3.default.get({ host: "127.0.0.1", port, path: "/", timeout: 2e3 }, (res) => {
+          res.resume();
+          resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+          req.destroy();
+          resolve(false);
+        });
+      });
+      if (ok) return;
+      if (Date.now() > deadline) throw new Error(`timed out waiting for docker vm agent on port ${port}`);
+      await new Promise((resolve) => setTimeout(resolve, 500));
     }
+  }
+};
+function buildSingleFileTar(name, content) {
+  const header = Buffer.alloc(512);
+  header.write(name, 0, "utf8");
+  header.write("0000644\0", 100, "utf8");
+  header.write("0000000\0", 108, "utf8");
+  header.write("0000000\0", 116, "utf8");
+  header.write(content.byteLength.toString(8).padStart(11, "0") + "\0", 124, "utf8");
+  header.write(Math.floor(Date.now() / 1e3).toString(8).padStart(11, "0") + "\0", 136, "utf8");
+  header.write("        ", 148, "utf8");
+  header.write("0", 156, "utf8");
+  header.write("ustar\0", 257, "utf8");
+  header.write("00", 263, "utf8");
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  header.write(checksum.toString(8).padStart(6, "0") + "\0 ", 148, "utf8");
+  const paddedContentLength = Math.ceil(content.byteLength / 512) * 512;
+  const paddedContent = Buffer.alloc(paddedContentLength);
+  content.copy(paddedContent);
+  return Buffer.concat([header, paddedContent, Buffer.alloc(1024)]);
+}
+
+// src/executor/docker-sandbox-executor.ts
+var import_child_process6 = require("child_process");
+var import_util3 = require("util");
+var import_promises5 = __toESM(require("fs/promises"));
+var import_os8 = __toESM(require("os"));
+var import_path6 = __toESM(require("path"));
+var import_http4 = __toESM(require("http"));
+var DEFAULT_EXEC_TIMEOUT_MS3 = 6e4;
+var MAX_EXEC_TIMEOUT_MS3 = 3e5;
+var MAX_OUTPUT_BYTES3 = 1024 * 1024;
+var MAX_FILE_BYTES3 = 5 * 1024 * 1024;
+var WORKSPACE_DIR2 = "/workspace";
+var AGENT_DIR = "/app";
+var execFileAsync2 = (0, import_util3.promisify)(import_child_process6.execFile);
+function assertSafeWorkspacePath2(relativePath) {
+  const normalized = relativePath.replace(/^([/\\])+/, "");
+  if (normalized.split(/[/\\]/).includes("..")) {
+    throw new Error(`Path escapes the VM workspace: ${relativePath}`);
+  }
+  return normalized;
+}
+function sandboxNameFor(vmId) {
+  return `mp-${vmId.replace(/[^a-zA-Z0-9.-]/g, "-")}`;
+}
+var DockerSandboxExecutor = class {
+  constructor(config) {
+    this.config = config;
+    this.vms = /* @__PURE__ */ new Map();
+    this.usedPorts = /* @__PURE__ */ new Set();
+    this.loadedTemplates = /* @__PURE__ */ new Set();
+    this.bin = config.bin;
+  }
+  allocatePort() {
+    for (let p = this.config.portRangeStart; p <= this.config.portRangeEnd; p++) {
+      if (!this.usedPorts.has(p)) {
+        this.usedPorts.add(p);
+        return p;
+      }
+    }
+    throw new Error("no free ports in docker-sandbox port range");
+  }
+  resolveAgentCommand(stack) {
+    return this.config.stackAgentCommands[stack] ?? this.config.stackAgentCommands.generic ?? "node app.js";
+  }
+  /** Local `docker` image tag for a stack, same resolution order as DockerExecutor.resolveImage. */
+  localImageFor(stack) {
+    const { imagePrefix, imageTag } = this.config;
+    return `${imagePrefix}-${stack}:${imageTag}`;
+  }
+  /** Bridges the local docker image into sbx's own image store once per process; returns its ref. */
+  async ensureTemplateLoaded(stack) {
+    const explicit = this.config.stackTemplates[stack];
+    if (explicit) return explicit;
+    const localImage = this.localImageFor(stack);
+    const templateRef = `docker.io/library/${localImage}`;
+    if (this.loadedTemplates.has(templateRef)) return templateRef;
+    const tmpFile = import_path6.default.join(import_os8.default.tmpdir(), `sbx-template-${stack}-${Date.now()}.tar`);
+    try {
+      await execFileAsync2("docker", ["save", localImage, "-o", tmpFile]);
+      await execFileAsync2(this.bin, ["template", "load", tmpFile]);
+    } catch (error) {
+      throw new Error(`failed to bridge local image "${localImage}" into sbx \u2014 run scripts/setup-docker-images.sh: ${error}`);
+    } finally {
+      await import_promises5.default.rm(tmpFile, { force: true });
+    }
+    this.loadedTemplates.add(templateRef);
+    return templateRef;
+  }
+  async create(spec) {
+    const templateRef = await this.ensureTemplateLoaded(spec.stack);
+    const agentCommand = this.resolveAgentCommand(spec.stack);
+    const sandboxName = sandboxNameFor(spec.vmId);
+    const hostPort = this.allocatePort();
+    const vmDir = import_path6.default.join(this.config.workspaceRoot, spec.vmId);
+    await import_promises5.default.mkdir(vmDir, { recursive: true });
+    const memMib = Math.max(spec.resources.memMib, this.config.minMemoryMib);
+    const createArgs = [
+      "create",
+      "shell",
+      vmDir,
+      "--template",
+      templateRef,
+      "--name",
+      sandboxName,
+      "-p",
+      `127.0.0.1:${hostPort}:${this.config.guestPort}`,
+      "-m",
+      `${memMib}m`,
+      "--cpus",
+      String(spec.resources.vcpuCount),
+      "-e",
+      `VM_ID=${spec.vmId}`,
+      "-e",
+      `STACK=${spec.stack}`,
+      ...spec.sessionId ? ["-e", `SESSION_ID=${spec.sessionId}`] : [],
+      ...spec.appUrl ? ["-e", `APP_URL=${spec.appUrl}`] : []
+    ];
+    src_default.info({ vmId: spec.vmId, bin: this.bin, args: createArgs }, "creating docker sandbox");
+    try {
+      await execFileAsync2(this.bin, createArgs);
+      this.launchAgent(sandboxName, agentCommand);
+    } catch (error) {
+      this.usedPorts.delete(hostPort);
+      await import_promises5.default.rm(vmDir, { recursive: true, force: true }).catch(() => {
+      });
+      throw error;
+    }
+    const handle = {
+      vmId: spec.vmId,
+      sessionId: spec.sessionId,
+      stack: spec.stack,
+      resources: { ...spec.resources, memMib },
+      running: true,
+      metadata: { sandboxName, hostPort, vmDir, agentCommand }
+    };
+    this.vms.set(spec.vmId, { handle, sandboxName, vmDir, hostPort, agentCommand });
+    await this.waitForAgent(hostPort);
+    src_default.info({ vmId: spec.vmId, sandboxName, hostPort }, "docker sandbox ready");
+    return handle;
+  }
+  /**
+   * `sbx create shell` doesn't run the image's own CMD — launch the guest agent explicitly.
+   *
+   * Fire-and-forget: `sbx exec -d` (detach) launches the background command correctly but its
+   * own CLI process then hangs indefinitely instead of returning — confirmed live (the agent
+   * was already answering on its port while the CLI call itself sat stuck for 14+ minutes,
+   * needing a kill -9). `waitForAgent`'s port poll is the real readiness signal here, not this
+   * process exiting, so it's spawned detached and never awaited.
+   */
+  launchAgent(sandboxName, agentCommand) {
+    const proc = (0, import_child_process6.spawn)(this.bin, ["exec", "-d", "-w", AGENT_DIR, sandboxName, "/bin/sh", "-c", agentCommand], {
+      stdio: "ignore"
+    });
+    proc.on("error", (error) => src_default.warn({ sandboxName, err: error }, "sbx exec -d failed to spawn"));
+    proc.unref();
+  }
+  async pause(vmId) {
+    return this.stop(vmId);
+  }
+  async resume(vmId) {
+    return this.restore(vmId);
+  }
+  async stop(vmId) {
+    const vm = this.mustGet(vmId);
+    await execFileAsync2(this.bin, ["stop", vm.sandboxName]);
+    return this.setRunning(vmId, false);
+  }
+  async restore(vmId) {
+    const vm = this.mustGet(vmId);
+    await execFileAsync2(this.bin, ["run", "--name", vm.sandboxName, "--detached"]);
+    const alreadyUp = await this.probeAgent(vm.hostPort);
+    if (!alreadyUp) this.launchAgent(vm.sandboxName, vm.agentCommand);
+    await this.waitForAgent(vm.hostPort);
+    return this.setRunning(vmId, true);
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    await execFileAsync2(this.bin, ["rm", "-f", vm.sandboxName]).catch(
+      (error) => src_default.warn({ vmId, err: error }, "sbx rm on destroy failed")
+    );
+    await import_promises5.default.rm(vm.vmDir, { recursive: true, force: true }).catch(() => {
+    });
+    this.usedPorts.delete(vm.hostPort);
+    this.vms.delete(vmId);
+    src_default.info({ vmId }, "docker sandbox destroyed");
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  list() {
+    return [...this.vms.values()].map((v) => v.handle);
+  }
+  /**
+   * Recover a sandbox after a worker restart: it's owned by the independent `sandboxd`
+   * daemon, so a liveness probe against its name is enough to confirm it's still there.
+   */
+  async reattach(record) {
+    const meta = record.runtimeMetadata;
+    if (!meta?.sandboxName || meta.hostPort === void 0 || !meta.vmDir || !meta.agentCommand) return void 0;
+    let running;
+    try {
+      await execFileAsync2(this.bin, ["exec", meta.sandboxName, "true"]);
+      running = true;
+    } catch {
+      try {
+        await execFileAsync2(this.bin, ["ls", "--json"]);
+        running = false;
+      } catch {
+        return void 0;
+      }
+    }
+    const handle = {
+      vmId: record.vmId,
+      sessionId: record.sessionId,
+      stack: record.stack,
+      resources: record.resources,
+      running,
+      metadata: meta
+    };
+    this.usedPorts.add(meta.hostPort);
+    this.vms.set(record.vmId, {
+      handle,
+      sandboxName: meta.sandboxName,
+      vmDir: meta.vmDir,
+      hostPort: meta.hostPort,
+      agentCommand: meta.agentCommand
+    });
+    src_default.info({ vmId: record.vmId, sandboxName: meta.sandboxName }, "docker sandbox reattached");
+    return handle;
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.mustGet(vmId);
+    if (!vm.handle.running) throw new Error(`vm ${vmId} is not running`);
+    return new Promise((resolve, reject) => {
+      const req = import_http4.default.request(
+        { host: "127.0.0.1", port: vm.hostPort, method: request.method, path: request.path, headers: request.headers },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on(
+            "end",
+            () => resolve({
+              statusCode: res.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            })
+          );
+        }
+      );
+      req.on("error", reject);
+      if (request.body) req.write(request.body);
+      req.end();
+    });
+  }
+  async exec(vmId, request) {
+    const vm = this.mustGet(vmId);
+    const cwd = request.cwd ? `${WORKSPACE_DIR2}/${assertSafeWorkspacePath2(request.cwd)}` : WORKSPACE_DIR2;
+    const timeoutMs = Math.min(request.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS3, MAX_EXEC_TIMEOUT_MS3);
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+      (0, import_child_process6.execFile)(
+        this.bin,
+        ["exec", "-w", cwd, vm.sandboxName, "/bin/sh", "-c", request.command],
+        { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES3 },
+        (error, stdout, stderr) => {
+          const failed = error;
+          const timedOut = Boolean(failed?.killed);
+          const truncated = failed?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+          resolve({
+            exitCode: typeof failed?.code === "number" ? failed.code : failed ? 1 : 0,
+            stdout: stdout.slice(0, MAX_OUTPUT_BYTES3),
+            stderr: stderr.slice(0, MAX_OUTPUT_BYTES3),
+            durationMs: Date.now() - startedAt,
+            truncated: Boolean(truncated),
+            timedOut
+          });
+        }
+      );
+    });
+  }
+  async writeFiles(vmId, files) {
+    const vm = this.mustGet(vmId);
+    const written = [];
+    for (const file of files) {
+      const relativePath = assertSafeWorkspacePath2(file.path);
+      const buffer = Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8");
+      if (buffer.byteLength > MAX_FILE_BYTES3) {
+        throw new Error(`File too large (${buffer.byteLength} bytes, max ${MAX_FILE_BYTES3}): ${file.path}`);
+      }
+      const dir = relativePath.includes("/") ? relativePath.slice(0, relativePath.lastIndexOf("/")) : "";
+      if (dir) {
+        await execFileAsync2(this.bin, ["exec", vm.sandboxName, "mkdir", "-p", `${WORKSPACE_DIR2}/${dir}`]);
+      }
+      const tmpFile = import_path6.default.join(import_os8.default.tmpdir(), `sbx-write-${vmId}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      await import_promises5.default.writeFile(tmpFile, buffer);
+      try {
+        await execFileAsync2(this.bin, ["cp", tmpFile, `${vm.sandboxName}:${WORKSPACE_DIR2}/${relativePath}`]);
+      } finally {
+        await import_promises5.default.rm(tmpFile, { force: true });
+      }
+      written.push({ path: relativePath, bytes: buffer.byteLength });
+    }
+    src_default.info({ vmId, files: written.length }, "docker sandbox files written");
+    return { written };
+  }
+  mustGet(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    return vm;
+  }
+  setRunning(vmId, running) {
+    const vm = this.mustGet(vmId);
+    vm.handle = { ...vm.handle, running };
+    return vm.handle;
+  }
+  async probeAgent(port) {
+    return new Promise((resolve) => {
+      const req = import_http4.default.get({ host: "127.0.0.1", port, path: "/", timeout: 2e3 }, (res) => {
+        res.resume();
+        resolve(true);
+      });
+      req.on("error", () => resolve(false));
+      req.on("timeout", () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+  }
+  async waitForAgent(port, timeoutMs = 3e4) {
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      if (await this.probeAgent(port)) return;
+      if (Date.now() > deadline) throw new Error(`timed out waiting for docker sandbox agent on port ${port}`);
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+};
+
+// src/executor/remote-executor.ts
+var import_http5 = __toESM(require("http"));
+var import_https = __toESM(require("https"));
+var RemoteExecutor = class {
+  constructor(config) {
+    // The remote agent is the actual source of truth, but MultiEngineExecutor.route() (used by
+    // pause/resume/stop/restore/destroy/proxyHttp/exec/writeFiles) needs get() to find the
+    // right executor for a vmId — cache the handle each call returns so it does.
+    this.vms = /* @__PURE__ */ new Map();
+    this.base = config.agentUrl.replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      ...config.authToken ? { Authorization: `Bearer ${config.authToken}` } : {}
+    };
+  }
+  async create(spec) {
+    const handle = await this.request("POST", "/vms", spec);
+    this.vms.set(spec.vmId, handle);
+    return handle;
+  }
+  async pause(vmId) {
+    return this.updateCached(vmId, await this.request("POST", `/vms/${vmId}/pause`));
+  }
+  async resume(vmId) {
+    return this.updateCached(vmId, await this.request("POST", `/vms/${vmId}/resume`));
+  }
+  async stop(vmId) {
+    return this.updateCached(vmId, await this.request("POST", `/vms/${vmId}/stop`));
+  }
+  async restore(vmId) {
+    return this.updateCached(vmId, await this.request("POST", `/vms/${vmId}/restore`));
+  }
+  async destroy(vmId) {
+    await this.request("DELETE", `/vms/${vmId}`);
+    this.vms.delete(vmId);
+  }
+  get(vmId) {
+    return this.vms.get(vmId);
+  }
+  list() {
+    return [...this.vms.values()];
+  }
+  /**
+   * Recover a remote-agent VM after a worker restart. The agent owns the actual VM state
+   * independently of this process, so reattaching is just confirming it still knows about
+   * this vmId and re-populating the local get()/list() cache above.
+   */
+  async reattach(record) {
+    try {
+      const handle = await withTimeout(this.request("GET", `/vms/${record.vmId}`), 5e3);
+      this.vms.set(record.vmId, handle);
+      return handle;
+    } catch {
+      return void 0;
+    }
+  }
+  updateCached(vmId, handle) {
+    this.vms.set(vmId, handle);
+    return handle;
+  }
+  async proxyHttp(vmId, request) {
+    const result = await this.request("POST", `/vms/${vmId}/proxy`, {
+      method: request.method,
+      path: request.path,
+      headers: request.headers,
+      body: request.body?.toString("base64")
+    });
+    return {
+      statusCode: result.statusCode,
+      headers: result.headers,
+      body: result.body ? Buffer.from(result.body, "base64") : Buffer.alloc(0)
+    };
+  }
+  request(method, path7, body) {
+    const url = new URL(this.base + path7);
+    const lib = url.protocol === "https:" ? import_https.default : import_http5.default;
+    const payload = body !== void 0 ? JSON.stringify(body) : void 0;
+    return new Promise((resolve, reject) => {
+      const req = lib.request(
+        {
+          hostname: url.hostname,
+          port: url.port || (url.protocol === "https:" ? 443 : 80),
+          path: url.pathname,
+          method,
+          headers: {
+            ...this.headers,
+            ...payload ? { "Content-Length": Buffer.byteLength(payload) } : {}
+          }
+        },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on("end", () => {
+            const text = Buffer.concat(chunks).toString();
+            if (res.statusCode && res.statusCode >= 400) {
+              reject(new Error(`vm-agent ${method} ${path7} \u2192 ${res.statusCode}: ${text}`));
+              return;
+            }
+            if (res.statusCode === 204 || !text) {
+              resolve(void 0);
+              return;
+            }
+            try {
+              resolve(JSON.parse(text));
+            } catch {
+              resolve(text);
+            }
+          });
+        }
+      );
+      req.on("error", reject);
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+};
+
+// src/executor/lambda-microvm-executor.ts
+var import_https2 = __toESM(require("https"));
+var import_client_lambda_microvms = require("@aws-sdk/client-lambda-microvms");
+var AUTH_TOKEN_TTL_MINUTES = 60;
+var AUTH_TOKEN_REFRESH_MARGIN_MS = 2 * 6e4;
+var LambdaMicrovmExecutor = class {
+  constructor(config) {
+    this.config = config;
+    this.vms = /* @__PURE__ */ new Map();
+    this.client = new import_client_lambda_microvms.LambdaMicrovmsClient(config.region ? { region: config.region } : {});
+  }
+  async create(spec) {
+    const imageIdentifier = this.config.stackImageArns?.[spec.stack] ?? this.config.imageArn;
+    const maxIdle = this.config.maxIdleSeconds ?? 900;
+    const run = await this.client.send(
+      new import_client_lambda_microvms.RunMicrovmCommand({
+        imageIdentifier,
+        ingressNetworkConnectors: this.config.ingressConnectorArns,
+        egressNetworkConnectors: this.config.egressConnectorArns,
+        executionRoleArn: this.config.executionRoleArn,
+        maximumDurationInSeconds: this.config.maximumDurationInSeconds ?? 28800,
+        ...maxIdle > 0 ? {
+          idlePolicy: {
+            autoResumeEnabled: true,
+            maxIdleDurationSeconds: maxIdle,
+            suspendedDurationSeconds: this.config.suspendedDurationSeconds ?? 28800
+          }
+        } : {},
+        // The guest's /run lifecycle hook receives this payload — lets the image
+        // identify which builder session/VM it serves.
+        runHookPayload: JSON.stringify({ vmId: spec.vmId, sessionId: spec.sessionId, stack: spec.stack, appUrl: spec.appUrl })
+      })
+    );
+    if (!run.microvmId || !run.endpoint) {
+      throw new Error("run-microvm returned no microvmId/endpoint");
+    }
+    src_default.info(
+      { vmId: spec.vmId, microvmId: run.microvmId, endpoint: run.endpoint, state: run.state },
+      "[LambdaMicrovm] run-microvm accepted"
+    );
+    const handle = {
+      vmId: spec.vmId,
+      sessionId: spec.sessionId,
+      stack: spec.stack,
+      // Resources are fixed at MicroVM image build time; echo the request back for bookkeeping.
+      resources: spec.resources,
+      running: true,
+      metadata: { microvmId: run.microvmId, endpoint: run.endpoint }
+    };
+    const vm = { handle, microvmId: run.microvmId, endpoint: run.endpoint };
+    this.vms.set(spec.vmId, vm);
+    try {
+      await this.waitForState(run.microvmId, "RUNNING", this.config.createTimeoutMs ?? 25e3);
+    } catch (error) {
+      this.vms.delete(spec.vmId);
+      await this.client.send(new import_client_lambda_microvms.TerminateMicrovmCommand({ microvmIdentifier: run.microvmId })).catch(() => {
+      });
+      throw error;
+    }
+    src_default.info({ vmId: spec.vmId, microvmId: run.microvmId }, "[LambdaMicrovm] vm running");
+    return handle;
+  }
+  async pause(vmId) {
+    const vm = this.mustGet(vmId);
+    await this.client.send(new import_client_lambda_microvms.SuspendMicrovmCommand({ microvmIdentifier: vm.microvmId }));
+    return this.setRunning(vmId, false);
+  }
+  async resume(vmId) {
+    const vm = this.mustGet(vmId);
+    await this.client.send(new import_client_lambda_microvms.ResumeMicrovmCommand({ microvmIdentifier: vm.microvmId }));
+    return this.setRunning(vmId, true);
+  }
+  // Suspend preserves memory + disk, so stop/restore are the same checkpoint
+  // operations as pause/resume — there is no separate "powered off" state.
+  stop(vmId) {
+    return this.pause(vmId);
+  }
+  restore(vmId) {
+    return this.resume(vmId);
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    await this.client.send(new import_client_lambda_microvms.TerminateMicrovmCommand({ microvmIdentifier: vm.microvmId }));
+    this.vms.delete(vmId);
+    src_default.info({ vmId, microvmId: vm.microvmId }, "[LambdaMicrovm] vm terminated");
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  list() {
+    return [...this.vms.values()].map((v) => v.handle);
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.mustGet(vmId);
+    const auth = await this.getAuthHeaders(vm);
+    return new Promise((resolve, reject) => {
+      const req = import_https2.default.request(
+        {
+          host: vm.endpoint,
+          method: request.method,
+          path: request.path,
+          headers: {
+            ...request.headers,
+            ...auth,
+            // Lambda routes to port 8080 by default; make the guest port explicit.
+            "X-aws-proxy-port": "8080",
+            host: vm.endpoint
+          }
+        },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on(
+            "end",
+            () => resolve({
+              statusCode: res.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            })
+          );
+        }
+      );
+      req.on("error", reject);
+      if (request.body) req.write(request.body);
+      req.end();
+    });
+  }
+  /**
+   * Recover a Lambda MicroVM after a worker restart. It's an independent AWS-managed
+   * resource that outlives this process — just re-describe it by ID and, unless it's been
+   * terminated, rebuild the local handle (the auth token refetches lazily as usual).
+   */
+  async reattach(record) {
+    const meta = record.runtimeMetadata;
+    if (!meta?.microvmId || !meta.endpoint) return void 0;
+    const described = await this.client.send(new import_client_lambda_microvms.GetMicrovmCommand({ microvmIdentifier: meta.microvmId })).catch(() => void 0);
+    if (!described || described.state === "TERMINATED" || described.state === "TERMINATING") {
+      return void 0;
+    }
+    const handle = {
+      vmId: record.vmId,
+      sessionId: record.sessionId,
+      stack: record.stack,
+      resources: record.resources,
+      running: described.state === "RUNNING",
+      metadata: meta
+    };
+    this.vms.set(record.vmId, { handle, microvmId: meta.microvmId, endpoint: meta.endpoint });
+    src_default.info({ vmId: record.vmId, microvmId: meta.microvmId, state: described.state }, "[LambdaMicrovm] vm reattached");
+    return handle;
+  }
+  mustGet(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    return vm;
+  }
+  setRunning(vmId, running) {
+    const vm = this.mustGet(vmId);
+    vm.handle = { ...vm.handle, running };
+    return vm.handle;
+  }
+  async getAuthHeaders(vm) {
+    if (vm.authToken && vm.authToken.expiresAt - Date.now() > AUTH_TOKEN_REFRESH_MARGIN_MS) {
+      return vm.authToken.headers;
+    }
+    const resp = await this.client.send(
+      new import_client_lambda_microvms.CreateMicrovmAuthTokenCommand({
+        microvmIdentifier: vm.microvmId,
+        expirationInMinutes: AUTH_TOKEN_TTL_MINUTES,
+        allowedPorts: [{ allPorts: {} }]
+      })
+    );
+    if (!resp.authToken) throw new Error("create-microvm-auth-token returned no token");
+    vm.authToken = {
+      headers: resp.authToken,
+      expiresAt: Date.now() + AUTH_TOKEN_TTL_MINUTES * 6e4
+    };
+    return vm.authToken.headers;
+  }
+  async waitForState(microvmId, target, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const resp = await this.client.send(new import_client_lambda_microvms.GetMicrovmCommand({ microvmIdentifier: microvmId }));
+      if (resp.state === target) return;
+      if (resp.state === "TERMINATED" || resp.state === "TERMINATING") {
+        throw new Error(`microvm ${microvmId} entered ${resp.state} while waiting for ${target}`);
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`timed out waiting for microvm ${microvmId} to reach ${target} (still ${resp.state})`);
+      }
+      await new Promise((r) => setTimeout(r, 1e3));
+    }
+  }
+};
+
+// src/executor/fargate-executor.ts
+var import_http6 = __toESM(require("http"));
+var import_client_ecs = require("@aws-sdk/client-ecs");
+var FARGATE_MEM_RANGES = {
+  256: [512, 2048],
+  512: [1024, 4096],
+  1024: [2048, 8192],
+  2048: [4096, 16384],
+  4096: [8192, 30720]
+};
+function fargateResources(vcpuCount, memMib) {
+  const cpu = Math.min(4096, Math.max(256, vcpuCount * 1024));
+  const [min, max] = FARGATE_MEM_RANGES[cpu];
+  let memory = Math.min(max, Math.max(min, memMib));
+  if (memory > 512) memory = Math.ceil(memory / 1024) * 1024;
+  return { cpu: String(cpu), memory: String(Math.min(max, memory)) };
+}
+var FargateExecutor = class {
+  constructor(config) {
+    this.config = config;
+    this.vms = /* @__PURE__ */ new Map();
+    this.containerNames = /* @__PURE__ */ new Map();
+    this.client = new import_client_ecs.ECSClient(config.region ? { region: config.region } : {});
+  }
+  /** First container of the task definition — the target for env overrides. Cached per definition. */
+  async resolveContainerName(taskDefinition) {
+    const cached = this.containerNames.get(taskDefinition);
+    if (cached) return cached;
+    const described = await this.client.send(new import_client_ecs.DescribeTaskDefinitionCommand({ taskDefinition }));
+    const name = described.taskDefinition?.containerDefinitions?.[0]?.name;
+    if (!name) throw new Error(`task definition ${taskDefinition} has no containers`);
+    this.containerNames.set(taskDefinition, name);
+    return name;
+  }
+  async waitForRunning(taskArn) {
+    const timeoutMs = this.config.startTimeoutMs ?? 18e4;
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const described = await this.client.send(
+        new import_client_ecs.DescribeTasksCommand({ cluster: this.config.cluster, tasks: [taskArn] })
+      );
+      const task = described.tasks?.[0];
+      if (!task) throw new Error(`task ${taskArn} not found`);
+      if (task.lastStatus === "STOPPED") {
+        throw new Error(`fargate task stopped: ${task.stoppedReason ?? "unknown reason"}`);
+      }
+      if (task.lastStatus === "RUNNING") {
+        const ip = this.config.assignPublicIp ? await this.resolvePublicIp(task.attachments) : task.containers?.[0]?.networkInterfaces?.[0]?.privateIpv4Address;
+        if (!ip) throw new Error(`fargate task ${taskArn} is RUNNING but has no ${this.config.assignPublicIp ? "public" : "private"} IP`);
+        return ip;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`fargate task did not reach RUNNING within ${timeoutMs}ms (last status: ${task.lastStatus})`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 3e3));
+    }
+  }
+  async resolvePublicIp(attachments) {
+    const eniId = attachments?.find((a) => a.type === "ElasticNetworkInterface")?.details?.find((d) => d.name === "networkInterfaceId")?.value;
+    if (!eniId) return void 0;
+    const { EC2Client, DescribeNetworkInterfacesCommand } = await import("@aws-sdk/client-ec2");
+    const ec2 = new EC2Client(this.config.region ? { region: this.config.region } : {});
+    const described = await ec2.send(new DescribeNetworkInterfacesCommand({ NetworkInterfaceIds: [eniId] }));
+    return described.NetworkInterfaces?.[0]?.Association?.PublicIp;
+  }
+  async create(spec) {
+    const taskDefinition = this.config.stackTaskDefinitions?.[spec.stack] ?? this.config.taskDefinition;
+    if (!taskDefinition) {
+      throw new Error(`no Fargate task definition configured for stack "${spec.stack}"`);
+    }
+    const containerName = await this.resolveContainerName(taskDefinition);
+    const { cpu, memory } = fargateResources(spec.resources.vcpuCount, spec.resources.memMib);
+    const run = await this.client.send(
+      new import_client_ecs.RunTaskCommand({
+        cluster: this.config.cluster,
+        taskDefinition,
+        launchType: "FARGATE",
+        count: 1,
+        networkConfiguration: {
+          awsvpcConfiguration: {
+            subnets: this.config.subnets,
+            securityGroups: this.config.securityGroups,
+            assignPublicIp: this.config.assignPublicIp ? "ENABLED" : "DISABLED"
+          }
+        },
+        overrides: {
+          cpu,
+          memory,
+          containerOverrides: [
+            {
+              name: containerName,
+              environment: [
+                { name: "VM_ID", value: spec.vmId },
+                ...spec.sessionId ? [{ name: "SESSION_ID", value: spec.sessionId }] : [],
+                { name: "STACK", value: spec.stack },
+                // Release artifact: the container agent pulls, unzips, and starts it
+                ...spec.appUrl ? [{ name: "APP_URL", value: spec.appUrl }] : []
+              ]
+            }
+          ]
+        },
+        tags: [
+          { key: "vmId", value: spec.vmId },
+          ...spec.sessionId ? [{ key: "sessionId", value: spec.sessionId }] : []
+        ]
+      })
+    );
+    const taskArn = run.tasks?.[0]?.taskArn;
+    if (!taskArn) {
+      throw new Error(`RunTask failed: ${run.failures?.[0]?.reason ?? "no task returned"}`);
+    }
+    src_default.info({ vmId: spec.vmId, taskArn, taskDefinition, cpu, memory }, "fargate task started");
+    try {
+      const ip = await this.waitForRunning(taskArn);
+      const handle = {
+        vmId: spec.vmId,
+        sessionId: spec.sessionId,
+        stack: spec.stack,
+        resources: spec.resources,
+        running: true,
+        metadata: { taskArn, ip }
+      };
+      this.vms.set(spec.vmId, { handle, taskArn, ip });
+      src_default.info({ vmId: spec.vmId, ip }, "fargate task running");
+      return handle;
+    } catch (error) {
+      await this.client.send(new import_client_ecs.StopTaskCommand({ cluster: this.config.cluster, task: taskArn, reason: "startup failed" })).catch(() => {
+      });
+      throw error;
+    }
+  }
+  async pause(vmId) {
+    throw new Error(`fargate tasks cannot be paused (vm ${vmId})`);
+  }
+  async resume(vmId) {
+    throw new Error(`fargate tasks cannot be resumed (vm ${vmId})`);
+  }
+  async restore(vmId) {
+    throw new Error(`fargate tasks cannot be restored (vm ${vmId})`);
+  }
+  async stop(vmId) {
+    const vm = this.mustGet(vmId);
+    await this.client.send(
+      new import_client_ecs.StopTaskCommand({ cluster: this.config.cluster, task: vm.taskArn, reason: "stopped via API" })
+    );
+    vm.handle.running = false;
+    return vm.handle;
+  }
+  async destroy(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    await this.client.send(new import_client_ecs.StopTaskCommand({ cluster: this.config.cluster, task: vm.taskArn, reason: "destroyed via API" })).catch((error) => src_default.warn({ vmId, err: error }, "fargate stop on destroy failed"));
+    this.vms.delete(vmId);
+  }
+  get(vmId) {
+    return this.vms.get(vmId)?.handle;
+  }
+  list() {
+    return [...this.vms.values()].map((vm) => vm.handle);
+  }
+  async proxyHttp(vmId, request) {
+    const vm = this.mustGet(vmId);
+    if (!vm.handle.running) throw new Error(`vm ${vmId} is not running`);
+    return new Promise((resolve, reject) => {
+      const req = import_http6.default.request(
+        {
+          host: vm.ip,
+          port: this.config.guestPort ?? 8080,
+          method: request.method,
+          path: request.path,
+          headers: request.headers
+        },
+        (res) => {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on(
+            "end",
+            () => resolve({
+              statusCode: res.statusCode ?? 502,
+              headers: Object.fromEntries(
+                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+              ),
+              body: Buffer.concat(chunks)
+            })
+          );
+        }
+      );
+      req.on("error", reject);
+      if (request.body) req.write(request.body);
+      req.end();
+    });
+  }
+  /**
+   * Recover a Fargate task after a worker restart. The task is an independent AWS resource
+   * that outlives this process — just re-describe it by ARN and, if it's still RUNNING,
+   * rebuild the local handle.
+   */
+  async reattach(record) {
+    const meta = record.runtimeMetadata;
+    if (!meta?.taskArn) return void 0;
+    const described = await this.client.send(new import_client_ecs.DescribeTasksCommand({ cluster: this.config.cluster, tasks: [meta.taskArn] })).catch(() => void 0);
+    const task = described?.tasks?.[0];
+    if (!task || task.lastStatus !== "RUNNING") return void 0;
+    const ip = this.config.assignPublicIp ? await this.resolvePublicIp(task.attachments) : task.containers?.[0]?.networkInterfaces?.[0]?.privateIpv4Address;
+    if (!ip) return void 0;
+    const handle = {
+      vmId: record.vmId,
+      sessionId: record.sessionId,
+      stack: record.stack,
+      resources: record.resources,
+      running: true,
+      metadata: { taskArn: meta.taskArn, ip }
+    };
+    this.vms.set(record.vmId, { handle, taskArn: meta.taskArn, ip });
+    src_default.info({ vmId: record.vmId, taskArn: meta.taskArn, ip }, "fargate task reattached");
+    return handle;
+  }
+  mustGet(vmId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) throw new Error(`vm ${vmId} not found`);
+    return vm;
+  }
+};
+
+// src/executor/detect.ts
+var import_fs2 = __toESM(require("fs"));
+var import_child_process7 = require("child_process");
+var ENGINE_PRIORITY = ["firecracker", "qemu", "docker-sandbox", "docker", "lambda-microvm", "fargate", "remote", "mock"];
+function binaryOnPath(bin) {
+  if (bin.includes("/")) {
+    try {
+      import_fs2.default.accessSync(bin, import_fs2.default.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  try {
+    (0, import_child_process7.execFileSync)("which", [bin], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function kvmUsable() {
+  try {
+    import_fs2.default.accessSync("/dev/kvm", import_fs2.default.constants.R_OK | import_fs2.default.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasBaseImages(cfg) {
+  if (cfg.kernelPath && cfg.initrdPath) return import_fs2.default.existsSync(cfg.kernelPath) && import_fs2.default.existsSync(cfg.initrdPath);
+  return availableStacks(cfg.imagesDir).length > 0;
+}
+function probeQemu(config) {
+  const { bin, accel } = config.qemu;
+  if (!hasBaseImages(config.qemu)) {
+    return { engine: "qemu", available: false, reason: `no base images under ${config.qemu.imagesDir} \u2014 run "worker-cli images pull" or scripts/setup-vm-images.sh` };
+  }
+  if (!binaryOnPath(bin)) {
+    return { engine: "qemu", available: false, reason: `${bin} not found on PATH` };
+  }
+  if (accel === "hvf" && process.platform !== "darwin") {
+    return { engine: "qemu", available: false, reason: "QEMU_ACCEL=hvf requires macOS (use kvm or tcg)" };
+  }
+  if (accel === "kvm" && !kvmUsable()) {
+    return { engine: "qemu", available: false, reason: "QEMU_ACCEL=kvm but /dev/kvm is not accessible" };
+  }
+  return { engine: "qemu", available: true };
+}
+function probeFirecracker(config) {
+  const { bin } = config.firecracker;
+  if (process.platform !== "linux") {
+    return { engine: "firecracker", available: false, reason: "requires a Linux host" };
+  }
+  if (!kvmUsable()) {
+    return { engine: "firecracker", available: false, reason: "/dev/kvm is not accessible" };
+  }
+  if (!hasBaseImages(config.firecracker)) {
+    return { engine: "firecracker", available: false, reason: `no base images under ${config.firecracker.imagesDir} \u2014 run "worker-cli images pull" or scripts/setup-vm-images.sh` };
+  }
+  if (!binaryOnPath(bin)) {
+    return { engine: "firecracker", available: false, reason: `${bin} not found on PATH` };
+  }
+  return { engine: "firecracker", available: true };
+}
+function hasLocalDockerImage(imagePrefix, imageTag) {
+  return VM_STACKS.some((stack) => {
+    try {
+      (0, import_child_process7.execFileSync)("docker", ["image", "inspect", `${imagePrefix}-${stack}:${imageTag}`], { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+function probeDocker(config) {
+  const { bin, imagePrefix, imageTag } = config.docker;
+  if (!binaryOnPath(bin)) {
+    return { engine: "docker", available: false, reason: `${bin} not found on PATH` };
+  }
+  try {
+    (0, import_child_process7.execFileSync)(bin, ["info"], { stdio: "ignore" });
+  } catch {
+    return { engine: "docker", available: false, reason: "docker daemon not reachable" };
+  }
+  if (!hasLocalDockerImage(imagePrefix, imageTag)) {
+    return { engine: "docker", available: false, reason: "no local docker images \u2014 run scripts/setup-docker-images.sh" };
+  }
+  return { engine: "docker", available: true };
+}
+function probeDockerSandbox(config) {
+  const { bin, imagePrefix, imageTag } = config.dockerSandbox;
+  if (!binaryOnPath(bin)) {
+    return { engine: "docker-sandbox", available: false, reason: `${bin} not found on PATH` };
+  }
+  try {
+    (0, import_child_process7.execFileSync)(bin, ["ls"], { stdio: "ignore" });
+  } catch {
+    return { engine: "docker-sandbox", available: false, reason: 'sbx daemon not reachable \u2014 run "sbx daemon start" and "sbx login"' };
+  }
+  if (!hasLocalDockerImage(imagePrefix, imageTag)) {
+    return { engine: "docker-sandbox", available: false, reason: "no local docker images \u2014 run scripts/setup-docker-images.sh" };
+  }
+  return { engine: "docker-sandbox", available: true };
+}
+function probeRemote(config) {
+  return config.remote.agentUrl ? { engine: "remote", available: true } : { engine: "remote", available: false, reason: "AGENT_URL not set" };
+}
+function probeLambdaMicrovm(config) {
+  const { imageArn, stackImageArns } = config.lambdaMicrovm;
+  return imageArn || Object.keys(stackImageArns).length ? { engine: "lambda-microvm", available: true } : { engine: "lambda-microvm", available: false, reason: "MICROVM_IMAGE_ARN / MICROVM_STACK_IMAGE_ARNS not set" };
+}
+function probeFargate(config) {
+  const { cluster, taskDefinition, stackTaskDefinitions, subnets } = config.fargate;
+  if (!cluster) {
+    return { engine: "fargate", available: false, reason: "FARGATE_CLUSTER not set" };
+  }
+  if (!taskDefinition && !Object.keys(stackTaskDefinitions).length) {
+    return { engine: "fargate", available: false, reason: "FARGATE_TASK_DEFINITION / FARGATE_STACK_TASK_DEFS not set" };
+  }
+  if (!subnets.length) {
+    return { engine: "fargate", available: false, reason: "FARGATE_SUBNETS not set" };
+  }
+  return { engine: "fargate", available: true };
+}
+function probeEngines(config) {
+  return [
+    { engine: "mock", available: true },
+    probeQemu(config),
+    probeFirecracker(config),
+    probeDocker(config),
+    probeDockerSandbox(config),
+    probeRemote(config),
+    probeLambdaMicrovm(config),
+    probeFargate(config)
+  ];
+}
+function detectEngines(config) {
+  const probes = probeEngines(config);
+  for (const probe of probes) {
+    if (probe.available) {
+      src_default.info({ engine: probe.engine }, "micro-VM engine available");
+    } else {
+      src_default.debug({ engine: probe.engine, reason: probe.reason }, "micro-VM engine unavailable");
+    }
+  }
+  const engines = probes.filter((p) => p.available).map((p) => p.engine);
+  const defaultEngine = ENGINE_PRIORITY.find((engine) => engines.includes(engine)) ?? "mock";
+  return { engines, defaultEngine };
+}
+
+// src/executor/index.ts
+function findNotAttachedVms(executor, records) {
+  return records.filter((record) => !executor.get(record.vmId));
+}
+function createEngineExecutor(engine, config) {
+  switch (engine) {
+    case "mock":
+      return new MockExecutor();
+    case "qemu":
+      return new QemuExecutor(config.qemu);
+    case "firecracker":
+      return new FirecrackerExecutor(config.firecracker);
+    case "docker":
+      return new DockerExecutor(config.docker);
+    case "docker-sandbox":
+      return new DockerSandboxExecutor(config.dockerSandbox);
+    case "remote":
+      return new RemoteExecutor(config.remote);
+    case "lambda-microvm":
+      return new LambdaMicrovmExecutor(config.lambdaMicrovm);
+    case "fargate":
+      return new FargateExecutor(config.fargate);
+    default:
+      throw new Error(`unknown engine "${engine}"`);
+  }
+}
+var MultiEngineExecutor = class {
+  constructor(executors, defaultEngine) {
+    this.executors = executors;
+    this.defaultEngine = defaultEngine;
+  }
+  get engines() {
+    return [...this.executors.keys()];
+  }
+  async create(spec) {
+    const engine = spec.engine ?? this.defaultEngine;
+    const executor = this.executors.get(engine);
+    if (!executor) {
+      throw new Error(`engine "${engine}" is not available on this worker (available: ${this.engines.join(", ")})`);
+    }
+    const handle = await executor.create(spec);
+    return { ...handle, engine };
+  }
+  pause(vmId) {
+    return this.route(vmId).pause(vmId);
+  }
+  resume(vmId) {
+    return this.route(vmId).resume(vmId);
+  }
+  stop(vmId) {
+    return this.route(vmId).stop(vmId);
+  }
+  restore(vmId) {
+    return this.route(vmId).restore(vmId);
+  }
+  destroy(vmId) {
+    return this.route(vmId).destroy(vmId);
+  }
+  proxyHttp(vmId, request) {
+    return this.route(vmId).proxyHttp(vmId, request);
+  }
+  get(vmId) {
+    for (const executor of this.executors.values()) {
+      const handle = executor.get(vmId);
+      if (handle) return handle;
+    }
+    return void 0;
+  }
+  list() {
+    return [...this.executors.values()].flatMap((executor) => executor.list());
+  }
+  getSerialSource(vmId) {
+    for (const executor of this.executors.values()) {
+      if (executor.get(vmId)) return executor.getSerialSource?.(vmId);
+    }
+    return void 0;
+  }
+  exec(vmId, request) {
+    const executor = this.route(vmId);
+    if (!executor.exec) return Promise.reject(new Error("executor does not support guest exec"));
+    return executor.exec(vmId, request);
+  }
+  writeFiles(vmId, files) {
+    const executor = this.route(vmId);
+    if (!executor.writeFiles) return Promise.reject(new Error("executor does not support guest file writes"));
+    return executor.writeFiles(vmId, files);
+  }
+  /**
+   * Recover VMs sandbox says this workerId owns but that aren't currently tracked (a worker
+   * restart, most likely). Runs in parallel — probing many VMs serially would needlessly
+   * delay the first heartbeat, which reports capacity from `list()` and must reflect
+   * reattached VMs to avoid sandbox overbooking this worker. Best-effort: failures are logged,
+   * never thrown — a VM that can't be reattached just stays unavailable until something
+   * touches it again (create/proxy/lifecycle), which already errors gracefully today.
+   */
+  async reattachAll(records) {
+    const pending = findNotAttachedVms(this, records);
+    if (!pending.length) return;
+    const results = await Promise.allSettled(
+      pending.map(async (record) => {
+        const executor = record.engine ? this.executors.get(record.engine) : void 0;
+        if (!executor) throw new Error(`engine "${record.engine ?? "unknown"}" not available on this worker`);
+        if (!executor.reattach) throw new Error(`engine "${record.engine}" does not support reattach`);
+        const handle = await executor.reattach(record);
+        if (!handle) throw new Error("resource no longer exists");
+      })
+    );
+    results.forEach((result, i) => {
+      const vmId = pending[i].vmId;
+      if (result.status === "fulfilled") src_default.info({ vmId }, "vm reattached");
+      else src_default.warn({ vmId, err: result.reason }, "vm reattach failed \u2014 staying unavailable until next touch");
+    });
+  }
+  route(vmId) {
+    for (const executor of this.executors.values()) {
+      if (executor.get(vmId)) return executor;
+    }
+    throw new Error(`vm ${vmId} not found on this worker`);
+  }
+};
+function createExecutor(config) {
+  const { engines, defaultEngine } = detectEngines(config);
+  const executors = /* @__PURE__ */ new Map();
+  for (const engine of engines) {
+    executors.set(engine, createEngineExecutor(engine, config));
+  }
+  src_default.info({ engines, defaultEngine }, "micro-VM engines initialized");
+  return new MultiEngineExecutor(executors, defaultEngine);
+}
+
+// src/socket-client.ts
+var import_os9 = __toESM(require("os"));
+var import_socket = require("socket.io-client");
+var HEARTBEAT_INTERVAL_MS = 1e4;
+var REATTACH_FALLBACK_MS = 5e3;
+function primaryIp() {
+  for (const ifaces of Object.values(import_os9.default.networkInterfaces())) {
+    for (const iface of ifaces ?? []) {
+      if (!iface.internal && iface.family === "IPv4") return iface.address;
+    }
+  }
+  return void 0;
+}
+function buildHeartbeat(config, executor) {
+  return {
+    hostname: import_os9.default.hostname(),
+    ip: primaryIp(),
+    region: config.region,
+    version,
+    engines: executor.engines,
+    defaultEngine: executor.defaultEngine,
+    capacity: {
+      maxVms: config.maxVms,
+      usedVms: executor.list().length,
+      cpuCores: import_os9.default.cpus().length,
+      memMib: Math.round(import_os9.default.totalmem() / (1024 * 1024))
+    }
+  };
+}
+function wrap(handler) {
+  return (payload, callback) => {
+    handler(payload).then((result) => callback({ ok: true, result })).catch((error) => {
+      src_default.error({ err: error }, "command failed");
+      callback({ ok: false, error: error.message });
+    });
+  };
+}
+function registerCommandHandlers(socket, executor) {
+  socket.on(WorkerEvent.VM_CREATE, wrap((spec) => executor.create(spec)));
+  socket.on(WorkerEvent.VM_PAUSE, wrap(({ vmId }) => executor.pause(vmId)));
+  socket.on(WorkerEvent.VM_RESUME, wrap(({ vmId }) => executor.resume(vmId)));
+  socket.on(WorkerEvent.VM_STOP, wrap(({ vmId }) => executor.stop(vmId)));
+  socket.on(WorkerEvent.VM_RESTORE, wrap(({ vmId }) => executor.restore(vmId)));
+  socket.on(WorkerEvent.VM_DESTROY, wrap(({ vmId }) => executor.destroy(vmId)));
+  socket.on(
+    WorkerEvent.PROXY_HTTP,
+    wrap(
+      ({ vmId, ...request }) => executor.proxyHttp(vmId, request)
+    )
+  );
+  socket.on(
+    WorkerEvent.VM_EXEC,
+    wrap(({ vmId, ...request }) => {
+      if (!executor.exec) {
+        return Promise.reject(new Error("executor does not support guest exec"));
+      }
+      return executor.exec(vmId, request);
+    })
+  );
+  socket.on(
+    WorkerEvent.VM_WRITE_FILES,
+    wrap(({ vmId, files }) => {
+      if (!executor.writeFiles) {
+        return Promise.reject(new Error("executor does not support guest file writes"));
+      }
+      return executor.writeFiles(vmId, files);
+    })
+  );
+}
+function connectToSandbox(config, executor) {
+  const socket = (0, import_socket.io)(config.sandboxUrl, {
+    path: config.workerSocketPath,
+    auth: { workerId: config.workerId, token: config.token },
+    transports: ["websocket"],
+    reconnection: true
+  });
+  let heartbeatTimer;
+  let reattachFallbackTimer;
+  const sendHeartbeat = () => socket.emit(WorkerEvent.HEARTBEAT, buildHeartbeat(config, executor));
+  function startHeartbeat() {
+    if (heartbeatTimer) return;
+    sendHeartbeat();
+    heartbeatTimer = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
+  }
+  socket.on("connect", () => {
+    src_default.info({ workerId: config.workerId, url: config.sandboxUrl }, "connected to sandbox");
+    socket.off(WorkerEvent.REATTACH);
+    reattachFallbackTimer = setTimeout(() => {
+      src_default.warn({ workerId: config.workerId }, "no reattach handshake from sandbox \u2014 starting heartbeat anyway");
+      startHeartbeat();
+    }, REATTACH_FALLBACK_MS);
+    socket.once(WorkerEvent.REATTACH, (records) => {
+      clearTimeout(reattachFallbackTimer);
+      executor.reattachAll(records).catch((error) => src_default.error({ err: error }, "reattach batch failed")).finally(startHeartbeat);
+    });
+  });
+  socket.on("disconnect", (reason) => {
+    src_default.warn({ workerId: config.workerId, reason }, "disconnected from sandbox");
+    clearInterval(heartbeatTimer);
+    clearTimeout(reattachFallbackTimer);
+    heartbeatTimer = void 0;
+    socket.off(WorkerEvent.REATTACH);
+  });
+  socket.on("connect_error", (error) => {
+    src_default.error({ err: error }, "sandbox connection error");
+  });
+  registerCommandHandlers(socket, executor);
+  return socket;
+}
+
+// src/services/vnc-relay.ts
+var import_rfb2 = __toESM(require("rfb2"));
+function bgraToRgba(src) {
+  const dst = Buffer.allocUnsafe(src.length);
+  for (let i = 0; i < src.length; i += 4) {
+    dst[i] = src[i + 2];
+    dst[i + 1] = src[i + 1];
+    dst[i + 2] = src[i];
+    dst[i + 3] = 255;
+  }
+  return dst;
+}
+var VncRelay = class {
+  constructor(vmId, host, port, socket) {
+    this.vmId = vmId;
+    this.host = host;
+    this.port = port;
+    this.socket = socket;
+    this.rfbc = null;
+    this.interval = null;
+    this.mouseHandler = null;
+    this.keyHandler = null;
+  }
+  start() {
+    this.rfbc = import_rfb2.default.createConnection({ host: this.host, port: this.port, password: "" });
+    const rfbc = this.rfbc;
+    rfbc.on("connect", () => {
+      rfbc.autoUpdate = true;
+      this.socket.emit(WorkerEvent.VNC_INIT, { vmId: this.vmId, width: rfbc.width, height: rfbc.height });
+      this.interval = setInterval(() => {
+        rfbc.requestUpdate(false, 0, 0, rfbc.width, rfbc.height);
+      }, 300);
+    });
+    rfbc.on("rect", (rect) => {
+      switch (rect.encoding) {
+        case import_rfb2.default.encodings.raw: {
+          const frame = {
+            vmId: this.vmId,
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height,
+            encoding: "raw",
+            data: bgraToRgba(rect.data)
+          };
+          this.socket.emit(WorkerEvent.VNC_FRAME, frame);
+          break;
+        }
+        case import_rfb2.default.encodings.copyRect: {
+          const frame = {
+            vmId: this.vmId,
+            x: rect.x,
+            y: rect.y,
+            src: rect.src,
+            width: rect.width,
+            height: rect.height
+          };
+          this.socket.emit(WorkerEvent.VNC_COPY_FRAME, frame);
+          break;
+        }
+      }
+    });
+    rfbc.on("resize", (rect) => {
+      src_default.info({ vmId: this.vmId, width: rect.width, height: rect.height }, "[VNC] desktop resized");
+      this.socket.emit(WorkerEvent.VNC_INIT, { vmId: this.vmId, width: rect.width, height: rect.height });
+      rfbc.requestUpdate(false, 0, 0, rect.width, rect.height);
+    });
+    rfbc.on("error", (err) => src_default.error({ vmId: this.vmId, err }, "[VNC] RFB error"));
+    this.mouseHandler = (e) => {
+      if (e.vmId === this.vmId) rfbc.pointerEvent(e.x, e.y, e.button);
+    };
+    this.keyHandler = (e) => {
+      if (e.vmId === this.vmId) rfbc.keyEvent(e.keyCode, e.isDown);
+    };
+    this.socket.on(WorkerEvent.VNC_MOUSE, this.mouseHandler);
+    this.socket.on(WorkerEvent.VNC_KEYBOARD, this.keyHandler);
+    src_default.info({ vmId: this.vmId, port: this.port }, "[VNC] relay started");
+  }
+  destroy() {
+    if (this.interval) clearInterval(this.interval);
+    if (this.mouseHandler) this.socket.off(WorkerEvent.VNC_MOUSE, this.mouseHandler);
+    if (this.keyHandler) this.socket.off(WorkerEvent.VNC_KEYBOARD, this.keyHandler);
+    try {
+      this.rfbc?.end();
+    } catch {
+    }
+    this.rfbc = null;
+    src_default.info({ vmId: this.vmId }, "[VNC] relay destroyed");
+  }
+};
+
+// src/services/serial-relay.ts
+var import_net3 = __toESM(require("net"));
+var SerialRelay = class {
+  constructor(vmId, source, socket) {
+    this.vmId = vmId;
+    this.source = source;
+    this.socket = socket;
+    this.conn = null;
+    this.inputHandler = null;
+  }
+  connect() {
+    if (this.source.type === "tcp") {
+      this.connectTcp();
+    } else {
+      this.connectPipe();
+    }
+    this.inputHandler = (e) => {
+      if (e.vmId !== this.vmId) return;
+      if (this.source.type === "tcp" && this.conn) {
+        this.conn.write(e.data);
+      } else if (this.source.type === "pipe") {
+        const proc = this.source.process;
+        proc.stdin?.write(e.data);
+      }
+    };
+    this.socket.on(WorkerEvent.TERMINAL_INPUT, this.inputHandler);
+  }
+  connectTcp() {
+    const { host, port } = this.source;
+    const attempt = () => {
+      const sock = import_net3.default.createConnection(port, host);
+      sock.once("connect", () => {
+        this.conn = sock;
+        src_default.info({ vmId: this.vmId, port }, "[Serial] TCP connected");
+        sock.on("data", (d) => this.socket.emit(WorkerEvent.TERMINAL_DATA, { vmId: this.vmId, data: d }));
+        sock.on("end", () => src_default.info({ vmId: this.vmId }, "[Serial] TCP ended"));
+        sock.on("error", (err) => src_default.error({ vmId: this.vmId, err }, "[Serial] TCP error"));
+      });
+      sock.once("error", () => setTimeout(attempt, 1e3));
+    };
+    attempt();
+  }
+  connectPipe() {
+    const { process: proc } = this.source;
+    proc.stdout?.on("data", (d) => this.socket.emit(WorkerEvent.TERMINAL_DATA, { vmId: this.vmId, data: d }));
+    proc.stderr?.on("data", (d) => this.socket.emit(WorkerEvent.TERMINAL_DATA, { vmId: this.vmId, data: d }));
+  }
+  destroy() {
+    if (this.inputHandler) this.socket.off(WorkerEvent.TERMINAL_INPUT, this.inputHandler);
+    try {
+      this.conn?.destroy();
+    } catch {
+    }
+    this.conn = null;
+    src_default.info({ vmId: this.vmId }, "[Serial] relay destroyed");
+  }
+};
+
+// src/console-relays.ts
+function attachConsoleRelays(executor, sandboxSocket) {
+  const relays = /* @__PURE__ */ new Map();
+  const originalCreate = executor.create.bind(executor);
+  executor.create = async (spec) => {
+    const handle = await originalCreate(spec);
+    const entry = {};
+    if (handle.vncPort) {
+      const vnc = new VncRelay(handle.vmId, "127.0.0.1", handle.vncPort, sandboxSocket);
+      vnc.start();
+      entry.vnc = vnc;
+    }
+    const serialSource = handle.serialPort ? { type: "tcp", host: "127.0.0.1", port: handle.serialPort } : executor.getSerialSource?.(handle.vmId);
+    if (serialSource) {
+      const serial = new SerialRelay(handle.vmId, serialSource, sandboxSocket);
+      serial.connect();
+      entry.serial = serial;
+    }
+    if (entry.vnc || entry.serial) relays.set(handle.vmId, entry);
+    return handle;
+  };
+  const originalDestroy = executor.destroy.bind(executor);
+  executor.destroy = async (vmId) => {
+    const entry = relays.get(vmId);
+    entry?.vnc?.destroy();
+    entry?.serial?.destroy();
+    relays.delete(vmId);
+    return originalDestroy(vmId);
+  };
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("sandbox").description("Run and manage a Multiplayer sandbox worker").version(version);
+program.command("start").description("start a worker and connect it to the sandbox control plane").option("--token <token>", "worker authentication token (env: WORKER_TOKEN)").option("--worker-id <id>", "stable worker ID (env: WORKER_ID; default: hostname)").option("--sandbox-url <url>", "control-plane URL (env: SANDBOX_URL; default: https://api.sandbox.filingramp.com)").option("--max-vms <count>", "maximum concurrent VMs (env: MAX_VMS)").action(async (opts) => {
+  const config = loadWorkerConfigFromEnv({
+    ...process.env,
+    ...opts.token ? { WORKER_TOKEN: opts.token } : {},
+    ...opts.workerId ? { WORKER_ID: opts.workerId } : {},
+    ...opts.sandboxUrl ? { SANDBOX_URL: opts.sandboxUrl } : {},
+    ...opts.maxVms ? { MAX_VMS: opts.maxVms } : {}
+  });
+  const executor = createExecutor(config);
+  const socket = connectToSandbox(config, executor);
+  attachConsoleRelays(executor, socket);
+  let stopping = false;
+  const stop = async (signal) => {
+    if (stopping) return;
+    stopping = true;
+    console.log(`
+${signal} received; shutting down sandbox worker...`);
+    socket.disconnect();
+    const results = await Promise.allSettled(executor.list().map((vm) => executor.destroy(vm.vmId)));
+    const failed = results.filter((result) => result.status === "rejected");
+    if (failed.length) console.error(`Failed to destroy ${failed.length} VM(s) during shutdown`);
+    process.exit(failed.length ? 1 : 0);
+  };
+  process.once("SIGINT", () => {
+    void stop("SIGINT");
+  });
+  process.once("SIGTERM", () => {
+    void stop("SIGTERM");
+  });
+  console.log(`Starting sandbox worker ${config.workerId} \u2192 ${config.sandboxUrl}`);
+});
+program.command("detect").description("probe this host and report which micro-VM engines it can run").action(() => {
+  const probes = probeEngines(loadWorkerConfigFromEnv({ ...process.env, WORKER_ID: "-", WORKER_TOKEN: "-" }));
+  for (const probe of probes) {
+    const status = probe.available ? "available" : `unavailable \u2014 ${probe.reason}`;
+    console.log(`${probe.engine.padEnd(15)} ${status}`);
+  }
 });
-const images = program
-    .command('images')
-    .description('manage engine base images (kernel + initramfs for QEMU/Firecracker)');
-images
-    .command('pull')
-    .description('download per-stack base images from S3 or an HTTPS mirror into the standard location')
-    .requiredOption('--from <location>', 's3://bucket[/prefix] or https:// base URL (env: VM_IMAGES_URL)', process.env.VM_IMAGES_URL)
-    .option('--arch <arch>', 'image architecture', (0, images_1.hostArch)())
-    .option('--stack <stack...>', 'stacks to pull (default: all)')
-    .option('--dest <dir>', 'destination directory (default: ~/.multiplayer/vm-images/<arch>)')
-    .option('--endpoint <url>', 'custom S3 endpoint, e.g. a MinIO URL (env: VM_IMAGES_ENDPOINT)', process.env.VM_IMAGES_ENDPOINT)
-    .action(async (opts) => {
-    var _a;
-    const dest = (_a = opts.dest) !== null && _a !== void 0 ? _a : (0, images_1.defaultImagesDir)(opts.arch);
-    const files = await (0, images_1.pullImages)({ location: opts.from, arch: opts.arch, stacks: opts.stack, endpoint: opts.endpoint }, dest);
-    for (const file of files)
-        console.log(`pulled ${file}`);
-    console.log('\nbase images ready — "sandbox detect" shows which engines they enable');
+var images = program.command("images").description("manage engine base images (kernel + initramfs for QEMU/Firecracker)");
+images.command("pull").description("download per-stack base images from S3 or an HTTPS mirror into the standard location").requiredOption("--from <location>", "s3://bucket[/prefix] or https:// base URL (env: VM_IMAGES_URL)", process.env.VM_IMAGES_URL).option("--arch <arch>", "image architecture", hostArch()).option("--stack <stack...>", "stacks to pull (default: all)").option("--dest <dir>", "destination directory (default: ~/.multiplayer/vm-images/<arch>)").option("--endpoint <url>", "custom S3 endpoint, e.g. a MinIO URL (env: VM_IMAGES_ENDPOINT)", process.env.VM_IMAGES_ENDPOINT).action(async (opts) => {
+  const dest = opts.dest ?? defaultImagesDir(opts.arch);
+  const files = await pullImages({ location: opts.from, arch: opts.arch, stacks: opts.stack, endpoint: opts.endpoint }, dest);
+  for (const file of files) console.log(`pulled ${file}`);
+  console.log('\nbase images ready \u2014 "sandbox detect" shows which engines they enable');
 });
-images
-    .command('push')
-    .description('upload locally built per-stack base images (scripts/setup-vm-images.sh) to S3')
-    .requiredOption('--to <location>', 's3://bucket[/prefix] (env: VM_IMAGES_URL)', process.env.VM_IMAGES_URL)
-    .option('--arch <arch>', 'image architecture', (0, images_1.hostArch)())
-    .option('--stack <stack...>', 'stacks to push (default: all found locally)')
-    .option('--src <dir>', 'source directory (default: ~/.multiplayer/vm-images/<arch>)')
-    .option('--endpoint <url>', 'custom S3 endpoint, e.g. a MinIO URL (env: VM_IMAGES_ENDPOINT)', process.env.VM_IMAGES_ENDPOINT)
-    .action(async (opts) => {
-    var _a;
-    const src = (_a = opts.src) !== null && _a !== void 0 ? _a : (0, images_1.defaultImagesDir)(opts.arch);
-    const uploaded = await (0, images_1.pushImages)({ location: opts.to, arch: opts.arch, stacks: opts.stack, endpoint: opts.endpoint }, src);
-    for (const uri of uploaded)
-        console.log(`pushed ${uri}`);
+images.command("push").description("upload locally built per-stack base images (scripts/setup-vm-images.sh) to S3").requiredOption("--to <location>", "s3://bucket[/prefix] (env: VM_IMAGES_URL)", process.env.VM_IMAGES_URL).option("--arch <arch>", "image architecture", hostArch()).option("--stack <stack...>", "stacks to push (default: all found locally)").option("--src <dir>", "source directory (default: ~/.multiplayer/vm-images/<arch>)").option("--endpoint <url>", "custom S3 endpoint, e.g. a MinIO URL (env: VM_IMAGES_ENDPOINT)", process.env.VM_IMAGES_ENDPOINT).action(async (opts) => {
+  const src = opts.src ?? defaultImagesDir(opts.arch);
+  const uploaded = await pushImages({ location: opts.to, arch: opts.arch, stacks: opts.stack, endpoint: opts.endpoint }, src);
+  for (const uri of uploaded) console.log(`pushed ${uri}`);
 });
 program.parseAsync().catch((error) => {
-    console.error(`Error: ${error.message}`);
-    process.exit(1);
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
 });
-//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map