@multiplayer-app/sandbox 6.0.0-sandbox-docker-image.0 → 7.0.0

package/dist/cli.js

@@ -28,7 +28,7 @@ var import_config5 = require("dotenv/config");
 var import_commander = require("commander");
 
 // package.json
-var version = "6.0.0-sandbox-docker-image.0";
+var version = "7.0.0";
 
 // src/config.ts
 var import_os2 = __toESM(require("os"));
@@ -48,6 +48,12 @@ var VM_STACKS = ["generic", "node", "python", "static"];
 var WorkerEvent = {
   // worker → sandbox
   HEARTBEAT: "worker:heartbeat",
+  // worker → sandbox, fire-and-forget like HEARTBEAT — sent once when a 'job' VM's
+  // entrypoint exits on its own (the worker has already torn the resource down by then).
+  VM_RUN_EXITED: "vm:run-exited",
+  // sandbox → worker, generated by the control plane and reused by this worker process
+  // on Socket.IO reconnects. This keeps duplicate configured WORKER_ID values isolated.
+  ASSIGNED_ID: "worker:assigned-id",
   // 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.
@@ -83,6 +89,7 @@ var VM_ACTION_EVENTS = {
 
 // src/images.ts
 var IMAGE_FILES = ["vmlinuz", "initramfs.img"];
+var PUBLISHED_IMAGE_STACKS = VM_STACKS.filter((stack) => stack !== "generic");
 function hostArch() {
   switch (process.arch) {
     case "arm64":
@@ -141,7 +148,7 @@ async function downloadFromHttp(opts, stack, file, dest) {
 async function pullImages(opts, destDir) {
   const isS3 = opts.location.startsWith("s3://");
   const downloaded = [];
-  for (const stack of opts.stacks ?? VM_STACKS) {
+  for (const stack of opts.stacks ?? PUBLISHED_IMAGE_STACKS) {
     const stackDir = import_path.default.join(destDir, stack);
     import_fs.default.mkdirSync(stackDir, { recursive: true });
     for (const file of IMAGE_FILES) {
@@ -200,18 +207,32 @@ function parseArnList(raw) {
   const arns = raw.split(",").map((s) => s.trim()).filter(Boolean);
   return arns.length ? arns : void 0;
 }
+function resolveSandboxEndpoint(rawUrl, explicitSocketPath) {
+  const url = new URL(rawUrl);
+  const basePath = url.pathname.replace(/\/+$/, "") || "/v0";
+  return {
+    // Socket.IO treats a URL pathname as a namespace, so connect to the origin
+    // and pass the derived HTTP transport path separately.
+    sandboxUrl: url.origin,
+    workerSocketPath: explicitSocketPath ?? `${basePath}/sapi/workers/ws`
+  };
+}
 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");
-  }
+  const token = env.WORKER_TOKEN?.trim() || void 0;
+  const sandboxEndpoint = resolveSandboxEndpoint(
+    env.SANDBOX_URL ?? "https://api.sandbox.filingramp.com/v0",
+    env.WORKER_SOCKET_PATH
+  );
   return {
     workerId,
     token,
-    sandboxUrl: env.SANDBOX_URL ?? "https://api.sandbox.filingramp.com",
-    workerSocketPath: env.WORKER_SOCKET_PATH ?? "/v0/sapi/workers/ws",
+    sandboxUrl: sandboxEndpoint.sandboxUrl,
+    workerSocketPath: sandboxEndpoint.workerSocketPath,
     maxVms: Number(env.MAX_VMS) || 10,
+    healthHost: env.SANDBOX_HEALTH_HOST ?? "0.0.0.0",
+    healthPort: Number(env.SANDBOX_HEALTH_PORT) || 3e3,
+    healthPathPrefix: (env.API_PREFIX ?? "/v0/api").replace(/\/+$/, ""),
     region: env.WORKER_REGION,
     remote: {
       // No default: an unset AGENT_URL means the remote engine is not configured on this worker
@@ -269,8 +290,8 @@ function loadWorkerConfigFromEnv(env = process.env) {
       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",
+      imagePrefix: env.SBX_IMAGE_PREFIX ?? env.DOCKER_IMAGE_PREFIX ?? "multiplayer-builder-vm",
+      imageTag: env.SBX_IMAGE_TAG ?? env.DOCKER_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.
@@ -316,7 +337,7 @@ 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 APP_NAME = process.env.APP_NAME || process.env.npm_package_name?.split("/").pop() || "unknown-app";
 var LOG_LEVEL = process.env.LOG_LEVEL || (isProduction ? "info" : "debug");
 
 // ../logger/src/logger.ts
@@ -358,6 +379,7 @@ var CONTENT_TYPES = {
   ".txt": "text/plain; charset=utf-8",
   ".md": "text/plain; charset=utf-8"
 };
+var MOCK_JOB_DURATION_MS = 250;
 function resolveWorkspacePath(workspaceDir, relativePath) {
   const normalized = import_path3.default.normalize(relativePath).replace(/^([/\\])+/, "");
   const resolved = import_path3.default.resolve(workspaceDir, normalized);
@@ -374,12 +396,16 @@ function startStandInServer(spec, workspaceDir) {
       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.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}
-`);
+        res.end(
+          `mock vm ${spec.vmId} (${spec.stack}) \u2014 session ${spec.sessionId} \u2014 ${req.method} ${req.url}
+`
+        );
       }
     })();
   });
@@ -393,6 +419,7 @@ function startStandInServer(spec, workspaceDir) {
 var MockExecutor = class {
   constructor() {
     this.vms = /* @__PURE__ */ new Map();
+    this.exitHandlers = /* @__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}-`));
@@ -402,12 +429,38 @@ var MockExecutor = class {
       sessionId: spec.sessionId,
       stack: spec.stack,
       resources: spec.resources,
-      running: true
+      running: true,
+      // No real process to configure — just echoed back for introspection/tests.
+      ...spec.env ? { metadata: { env: spec.env } } : {}
     };
-    this.vms.set(spec.vmId, { handle, server, port, workspaceDir });
-    src_default.info({ vmId: spec.vmId, port, workspaceDir }, "mock vm created");
+    const runMode = spec.runMode ?? "service";
+    this.vms.set(spec.vmId, { handle, server, port, workspaceDir, runMode, startedAt: Date.now() });
+    src_default.info({ vmId: spec.vmId, port, workspaceDir, runMode }, "mock vm created");
     return handle;
   }
+  /** No real process to watch — just synthesize a successful run shortly after create(). */
+  onExit(vmId, handler) {
+    const startedAt = this.vms.get(vmId)?.startedAt ?? Date.now();
+    this.exitHandlers.set(vmId, handler);
+    setTimeout(() => {
+      void (async () => {
+        const registered = this.exitHandlers.get(vmId);
+        this.exitHandlers.delete(vmId);
+        if (!registered) return;
+        const result = {
+          exitCode: 0,
+          stdout: `mock job ${vmId} completed
+`,
+          stderr: "",
+          truncated: false,
+          durationMs: Date.now() - startedAt,
+          finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.destroy(vmId);
+        registered(result);
+      })();
+    }, MOCK_JOB_DURATION_MS);
+  }
   async pause(vmId) {
     return this.setRunning(vmId, false);
   }
@@ -452,7 +505,10 @@ var MockExecutor = class {
             resolve({
               statusCode: proxyRes.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(proxyRes.headers).map(([key, value]) => [key, Array.isArray(value) ? value.join(", ") : value ?? ""])
+                Object.entries(proxyRes.headers).map(([key, value]) => [
+                  key,
+                  Array.isArray(value) ? value.join(", ") : value ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             });
@@ -470,7 +526,9 @@ var MockExecutor = class {
     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}`);
+        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 });
@@ -541,11 +599,22 @@ function withTimeout(promise, ms) {
   ]);
 }
 
+// src/executor/env-encoding.ts
+function encodeEnvB64(env) {
+  if (!env || Object.keys(env).length === 0) return void 0;
+  const lines = Object.entries(env).map(([key, value]) => `${key}=${value}`).join("\n");
+  return Buffer.from(lines).toString("base64");
+}
+
 // src/executor/qemu-executor.ts
+var MAX_OUTPUT_BYTES2 = 1024 * 1024;
+var JOB_EXIT_SENTINEL = "__JOB_EXIT_CODE__:";
 var QemuExecutor = class {
   constructor(config) {
     this.config = config;
     this.vms = /* @__PURE__ */ new Map();
+    this.pendingResults = /* @__PURE__ */ new Map();
+    this.exitHandlers = /* @__PURE__ */ new Map();
     this.usedHttpPorts = /* @__PURE__ */ new Set();
     this.usedDisplays = /* @__PURE__ */ new Set();
     // VNC display indices
@@ -594,12 +663,15 @@ var QemuExecutor = class {
     }
     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"`);
+      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 envB64 = encodeEnvB64(spec.env);
     const hostPort = this.allocateHttpPort();
     const vncDisplay = this.allocateVncDisplay();
     const serialPort = this.allocateSerialPort();
@@ -629,7 +701,9 @@ var QemuExecutor = class {
       [
         `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")}` : ""
+        spec.appUrl ? `APP_URL_B64=${Buffer.from(spec.appUrl).toString("base64")}` : "",
+        spec.runMode === "job" ? "RUN_MODE=job" : "",
+        envB64 ? `ENV_B64=${envB64}` : ""
       ].filter(Boolean).join(" "),
       // Networking
       "-netdev",
@@ -654,15 +728,24 @@ var QemuExecutor = class {
     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.stderr?.on(
+      "data",
+      (d) => src_default.error({ vmId: spec.vmId }, d.toString().trimEnd())
+    );
+    const runMode = spec.runMode ?? "service";
+    const startedAt = Date.now();
     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);
+      if (!vm2) return;
+      this.usedHttpPorts.delete(vm2.hostPort);
+      this.usedDisplays.delete(vm2.vncDisplay);
+      this.usedSerialPorts.delete(vm2.serialPort);
+      if (vm2.runMode === "job") {
+        vm2.handle = { ...vm2.handle, running: false };
+        this.reportJobResult(spec.vmId, vm2);
+      } else {
         this.vms.delete(spec.vmId);
       }
     });
@@ -677,12 +760,61 @@ var QemuExecutor = class {
       serialPort,
       metadata
     };
-    const vm = { handle, process: proc, pid: proc.pid, hostPort, qmpSocketPath, vncDisplay, serialPort };
+    const vm = {
+      handle,
+      process: proc,
+      pid: proc.pid,
+      hostPort,
+      qmpSocketPath,
+      vncDisplay,
+      serialPort,
+      runMode,
+      startedAt
+    };
     this.vms.set(spec.vmId, vm);
+    if (runMode === "job") vm.serialBuffer = connectSerialBuffer(serialPort);
     await waitForQmp(qmpSocketPath);
-    src_default.info({ vmId: spec.vmId, hostPort, vncPort, serialPort }, "qemu vm ready");
+    src_default.info({ vmId: spec.vmId, hostPort, vncPort, serialPort, runMode }, "qemu vm ready");
     return handle;
   }
+  /** Scrapes JOB_EXIT_SENTINEL out of the buffered serial console and reports the result. */
+  reportJobResult(vmId, vm) {
+    vm.serialBuffer?.socket.destroy();
+    const output = Buffer.concat(vm.serialBuffer?.chunks ?? []).toString("utf8");
+    const sentinelIndex = output.lastIndexOf(JOB_EXIT_SENTINEL);
+    const exitCode = sentinelIndex === -1 ? 1 : Number.parseInt(output.slice(sentinelIndex + JOB_EXIT_SENTINEL.length), 10) || 0;
+    const stdout = sentinelIndex === -1 ? output : output.slice(0, sentinelIndex);
+    const result = {
+      exitCode,
+      stdout: stdout.slice(0, MAX_OUTPUT_BYTES2),
+      stderr: "",
+      truncated: (vm.serialBuffer?.bytes ?? 0) > MAX_OUTPUT_BYTES2,
+      durationMs: Date.now() - vm.startedAt,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    src_default.info({ vmId, exitCode }, "qemu job vm exited");
+    this.deliverJobResult(vmId, result);
+  }
+  deliverJobResult(vmId, result) {
+    const handler = this.exitHandlers.get(vmId);
+    if (handler) {
+      this.exitHandlers.delete(vmId);
+      this.vms.delete(vmId);
+      handler(result);
+    } else {
+      this.pendingResults.set(vmId, result);
+    }
+  }
+  onExit(vmId, handler) {
+    const pending = this.pendingResults.get(vmId);
+    if (pending) {
+      this.pendingResults.delete(vmId);
+      this.vms.delete(vmId);
+      handler(pending);
+      return;
+    }
+    this.exitHandlers.set(vmId, handler);
+  }
   async pause(vmId) {
     await this.qmp(vmId, "stop");
     return this.setRunning(vmId, false);
@@ -769,7 +901,9 @@ var QemuExecutor = class {
       hostPort: meta.hostPort,
       qmpSocketPath: meta.qmpSocketPath,
       vncDisplay: meta.vncDisplay,
-      serialPort: meta.serialPort
+      serialPort: meta.serialPort,
+      runMode: record.runMode,
+      startedAt: Date.parse(record.createdAt) || Date.now()
     });
     src_default.info({ vmId: record.vmId }, "qemu vm reattached");
     return handle;
@@ -789,10 +923,16 @@ var QemuExecutor = class {
   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");
+    const { default: http8 } = 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 },
+      const req = http8.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));
@@ -801,7 +941,10 @@ var QemuExecutor = class {
             () => resolve({
               statusCode: res.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+                Object.entries(res.headers).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? v.join(", ") : v ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             })
@@ -825,11 +968,27 @@ var QemuExecutor = class {
     await sendQmpCommand(vm.qmpSocketPath, execute);
   }
 };
+function connectSerialBuffer(port) {
+  const buffer = {
+    chunks: [],
+    bytes: 0,
+    socket: import_net.default.connect({ host: "127.0.0.1", port })
+  };
+  buffer.socket.on("data", (chunk) => {
+    if (buffer.bytes >= MAX_OUTPUT_BYTES2) return;
+    buffer.chunks.push(chunk);
+    buffer.bytes += chunk.byteLength;
+  });
+  buffer.socket.on("error", () => {
+  });
+  return buffer;
+}
 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}`));
+      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();
@@ -891,11 +1050,15 @@ 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 MAX_OUTPUT_BYTES3 = 1024 * 1024;
+var JOB_EXIT_SENTINEL2 = "__JOB_EXIT_CODE__:";
 var FirecrackerExecutor = class {
   constructor(config) {
     this.config = config;
     this.vms = /* @__PURE__ */ new Map();
     this.usedSubnets = /* @__PURE__ */ new Set();
+    this.pendingResults = /* @__PURE__ */ new Map();
+    this.exitHandlers = /* @__PURE__ */ new Map();
     this.tapCounter = 0;
     this.networkReady = false;
     this.bin = config.bin ?? "firecracker";
@@ -918,7 +1081,9 @@ var FirecrackerExecutor = class {
       "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");
+      await execAsync(
+        "iptables -t nat -A POSTROUTING -s 172.16.0.0/12 ! -d 172.16.0.0/12 -j MASQUERADE"
+      );
     }
     this.networkReady = true;
   }
@@ -929,7 +1094,9 @@ var FirecrackerExecutor = class {
     }
     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"`);
+      throw new Error(
+        `no base image for stack "${stack}" under ${this.config.imagesDir} \u2014 run "worker-cli images pull"`
+      );
     }
     return resolved;
   }
@@ -947,17 +1114,35 @@ var FirecrackerExecutor = class {
     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 runMode = spec.runMode ?? "service";
+    const envB64 = encodeEnvB64(spec.env);
+    const startedAt = Date.now();
+    const serialBuffer = runMode === "job" ? { chunks: [], bytes: 0 } : void 0;
     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.stdout?.on("data", (d) => {
+      src_default.debug({ vmId: spec.vmId }, d.toString().trimEnd());
+      if (serialBuffer && serialBuffer.bytes < MAX_OUTPUT_BYTES3) {
+        serialBuffer.chunks.push(d);
+        serialBuffer.bytes += d.byteLength;
+      }
+    });
+    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);
+        if (vm.runMode === "job") {
+          vm.handle = { ...vm.handle, running: false };
+          this.reportJobResult(spec.vmId, vm);
+        } else {
+          this.vms.delete(spec.vmId);
+        }
       }
       execAsync(`ip link del ${tapName}`).catch(() => {
       });
@@ -984,7 +1169,9 @@ var FirecrackerExecutor = class {
         // 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}`
+        `HOST_IP=${hostIp}`,
+        ...runMode === "job" ? ["RUN_MODE=job"] : [],
+        ...envB64 ? [`ENV_B64=${envB64}`] : []
       ].join(" ")
     });
     await fcRequest(apiSocketPath, "PUT", "/network-interfaces/eth0", {
@@ -994,7 +1181,7 @@ var FirecrackerExecutor = class {
       host_dev_name: tapName
     });
     await fcRequest(apiSocketPath, "PUT", "/actions", { action_type: "InstanceStart" });
-    await waitForHttp(guestIp, 8080);
+    if (runMode !== "job") await waitForHttp(guestIp, 8080);
     const metadata = { apiSocketPath, tapName, subnet, guestIp, pid: proc.pid };
     const handle = {
       vmId: spec.vmId,
@@ -1004,10 +1191,58 @@ var FirecrackerExecutor = class {
       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");
+    this.vms.set(spec.vmId, {
+      handle,
+      process: proc,
+      pid: proc.pid,
+      apiSocketPath,
+      tapName,
+      subnet,
+      guestIp,
+      runMode,
+      startedAt,
+      serialBuffer
+    });
+    src_default.info({ vmId: spec.vmId, guestIp, tapName, runMode }, "firecracker vm ready");
     return handle;
   }
+  /** Scrapes JOB_EXIT_SENTINEL out of the buffered serial stdout and reports the result. */
+  reportJobResult(vmId, vm) {
+    const output = Buffer.concat(vm.serialBuffer?.chunks ?? []).toString("utf8");
+    const sentinelIndex = output.lastIndexOf(JOB_EXIT_SENTINEL2);
+    const exitCode = sentinelIndex === -1 ? 1 : Number.parseInt(output.slice(sentinelIndex + JOB_EXIT_SENTINEL2.length), 10) || 0;
+    const stdout = sentinelIndex === -1 ? output : output.slice(0, sentinelIndex);
+    const result = {
+      exitCode,
+      stdout: stdout.slice(0, MAX_OUTPUT_BYTES3),
+      stderr: "",
+      truncated: (vm.serialBuffer?.bytes ?? 0) > MAX_OUTPUT_BYTES3,
+      durationMs: Date.now() - vm.startedAt,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    src_default.info({ vmId, exitCode }, "firecracker job vm exited");
+    this.deliverJobResult(vmId, result);
+  }
+  deliverJobResult(vmId, result) {
+    const handler = this.exitHandlers.get(vmId);
+    if (handler) {
+      this.exitHandlers.delete(vmId);
+      this.vms.delete(vmId);
+      handler(result);
+    } else {
+      this.pendingResults.set(vmId, result);
+    }
+  }
+  onExit(vmId, handler) {
+    const pending = this.pendingResults.get(vmId);
+    if (pending) {
+      this.pendingResults.delete(vmId);
+      this.vms.delete(vmId);
+      handler(pending);
+      return;
+    }
+    this.exitHandlers.set(vmId, handler);
+  }
   async pause(vmId) {
     await this.patchVmState(vmId, "Paused");
     return this.setRunning(vmId, false);
@@ -1095,9 +1330,14 @@ var FirecrackerExecutor = class {
       apiSocketPath: meta.apiSocketPath,
       tapName: meta.tapName,
       subnet: meta.subnet,
-      guestIp: meta.guestIp
+      guestIp: meta.guestIp,
+      runMode: record.runMode,
+      startedAt: Date.parse(record.createdAt) || Date.now()
     });
-    src_default.info({ vmId: record.vmId, guestIp: meta.guestIp, tapName: meta.tapName }, "firecracker vm reattached");
+    src_default.info(
+      { vmId: record.vmId, guestIp: meta.guestIp, tapName: meta.tapName },
+      "firecracker vm reattached"
+    );
     return handle;
   }
   async proxyHttp(vmId, request) {
@@ -1120,7 +1360,10 @@ var FirecrackerExecutor = class {
             () => resolve({
               statusCode: res.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+                Object.entries(res.headers).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? v.join(", ") : v ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             })
@@ -1184,7 +1427,8 @@ 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}`));
+      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();
@@ -1199,7 +1443,8 @@ 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}`));
+      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();
@@ -1221,7 +1466,7 @@ 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_OUTPUT_BYTES4 = 1024 * 1024;
 var MAX_FILE_BYTES2 = 5 * 1024 * 1024;
 var WORKSPACE_DIR = "/workspace";
 var execFileAsync = (0, import_util2.promisify)(import_child_process5.execFile);
@@ -1237,6 +1482,9 @@ var DockerExecutor = class {
     this.config = config;
     this.vms = /* @__PURE__ */ new Map();
     this.usedPorts = /* @__PURE__ */ new Set();
+    /** Job VMs that exited before onExit() was called to claim the result (create() → onExit() isn't atomic). */
+    this.pendingResults = /* @__PURE__ */ new Map();
+    this.exitHandlers = /* @__PURE__ */ new Map();
     this.bin = config.bin;
   }
   allocatePort() {
@@ -1256,7 +1504,9 @@ var DockerExecutor = class {
     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`);
+    throw new Error(
+      `no local docker image for stack "${stack}" (${stackImage}) \u2014 run scripts/setup-docker-images.sh`
+    );
   }
   async imageExists(image) {
     try {
@@ -1287,6 +1537,7 @@ var DockerExecutor = class {
       `STACK=${spec.stack}`,
       ...spec.sessionId ? ["-e", `SESSION_ID=${spec.sessionId}`] : [],
       ...spec.appUrl ? ["-e", `APP_URL=${spec.appUrl}`] : [],
+      ...Object.entries(spec.env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`]),
       ...this.config.network ? ["--network", this.config.network] : [],
       image
     ];
@@ -1307,22 +1558,91 @@ var DockerExecutor = class {
       running: true,
       metadata: { containerId, containerName, hostPort }
     };
-    this.vms.set(spec.vmId, { handle, containerId, containerName, hostPort });
+    const runMode = spec.runMode ?? "service";
+    this.vms.set(spec.vmId, {
+      handle,
+      containerId,
+      containerName,
+      hostPort,
+      runMode,
+      startedAt: Date.now()
+    });
     this.watchExit(spec.vmId, containerId);
-    await this.waitForAgent(hostPort);
-    src_default.info({ vmId: spec.vmId, containerId, hostPort }, "docker vm ready");
+    if (runMode !== "job") await this.waitForAgent(hostPort);
+    src_default.info({ vmId: spec.vmId, containerId, hostPort, runMode }, "docker vm ready");
     return handle;
   }
-  /** Frees the allocated port once the container exits on its own (crash, OOM kill, `docker stop` from outside us). */
+  /**
+   * For 'service' VMs: frees the allocated port once the container exits on its own (crash,
+   * OOM kill, `docker stop` from outside us) — same as before.
+   * For 'job' VMs: captures the exit code + logs, tears the container down, and reports the
+   * result to whoever calls onExit() (immediately if they already have, otherwise once they do).
+   */
   watchExit(vmId, containerId) {
-    execFileAsync(this.bin, ["wait", containerId]).catch(() => {
-    }).then(() => {
+    execFileAsync(this.bin, ["wait", containerId]).catch(() => ({ stdout: "" })).then(async ({ stdout }) => {
       const vm = this.vms.get(vmId);
-      if (vm?.containerId === containerId) {
+      if (!vm || vm.containerId !== containerId) return;
+      if (vm.runMode !== "job") {
         vm.handle = { ...vm.handle, running: false };
+        return;
       }
+      const exitCode = Number.parseInt(stdout.trim(), 10) || 0;
+      const logs = await this.captureLogs(containerId);
+      await execFileAsync(this.bin, ["rm", "-f", containerId]).catch(
+        (error) => src_default.warn({ vmId, err: error }, "docker rm after job exit failed")
+      );
+      this.usedPorts.delete(vm.hostPort);
+      vm.handle = { ...vm.handle, running: false };
+      const result = {
+        exitCode,
+        ...logs,
+        durationMs: Date.now() - vm.startedAt,
+        finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      src_default.info({ vmId, exitCode }, "docker job vm exited");
+      this.deliverJobResult(vmId, result);
     });
   }
+  deliverJobResult(vmId, result) {
+    const handler = this.exitHandlers.get(vmId);
+    if (handler) {
+      this.exitHandlers.delete(vmId);
+      this.vms.delete(vmId);
+      handler(result);
+    } else {
+      this.pendingResults.set(vmId, result);
+    }
+  }
+  /** `docker logs` mirrors the container's stdout/stderr onto its own, so the CLI's streams stay separate. */
+  async captureLogs(containerId) {
+    try {
+      const { stdout, stderr } = await execFileAsync(this.bin, ["logs", containerId], {
+        maxBuffer: MAX_OUTPUT_BYTES4
+      });
+      return {
+        stdout: stdout.slice(0, MAX_OUTPUT_BYTES4),
+        stderr: stderr.slice(0, MAX_OUTPUT_BYTES4),
+        truncated: stdout.length > MAX_OUTPUT_BYTES4 || stderr.length > MAX_OUTPUT_BYTES4
+      };
+    } catch (error) {
+      const failed = error;
+      return {
+        stdout: (failed.stdout ?? "").slice(0, MAX_OUTPUT_BYTES4),
+        stderr: (failed.stderr ?? "").slice(0, MAX_OUTPUT_BYTES4),
+        truncated: true
+      };
+    }
+  }
+  onExit(vmId, handler) {
+    const pending = this.pendingResults.get(vmId);
+    if (pending) {
+      this.pendingResults.delete(vmId);
+      this.vms.delete(vmId);
+      handler(pending);
+      return;
+    }
+    this.exitHandlers.set(vmId, handler);
+  }
   async pause(vmId) {
     const vm = this.mustGet(vmId);
     await execFileAsync(this.bin, ["pause", vm.containerId]);
@@ -1368,7 +1688,12 @@ var DockerExecutor = class {
     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]);
+      const { stdout } = await execFileAsync(this.bin, [
+        "inspect",
+        "-f",
+        "{{.State.Running}}",
+        meta.containerId
+      ]);
       running = stdout.trim() === "true";
     } catch {
       return void 0;
@@ -1386,18 +1711,58 @@ var DockerExecutor = class {
       handle,
       containerId: meta.containerId,
       containerName: meta.containerName ?? `multiplayer-vm-${record.vmId}`,
-      hostPort: meta.hostPort
+      hostPort: meta.hostPort,
+      runMode: record.runMode,
+      startedAt: Date.parse(record.createdAt) || Date.now()
     });
-    if (running) this.watchExit(record.vmId, meta.containerId);
+    if (running) {
+      this.watchExit(record.vmId, meta.containerId);
+    } else if (record.runMode === "job") {
+      void this.finishExitedJob(record.vmId, meta.containerId);
+    }
     src_default.info({ vmId: record.vmId, containerId: meta.containerId }, "docker vm reattached");
     return handle;
   }
+  /** Same capture-and-report sequence as watchExit's job branch, for a container found already stopped. */
+  async finishExitedJob(vmId, containerId) {
+    const vm = this.vms.get(vmId);
+    if (!vm) return;
+    let exitCode = 0;
+    try {
+      const { stdout } = await execFileAsync(this.bin, [
+        "inspect",
+        "-f",
+        "{{.State.ExitCode}}",
+        containerId
+      ]);
+      exitCode = Number.parseInt(stdout.trim(), 10) || 0;
+    } catch {
+    }
+    const logs = await this.captureLogs(containerId);
+    await execFileAsync(this.bin, ["rm", "-f", containerId]).catch(() => {
+    });
+    this.usedPorts.delete(vm.hostPort);
+    vm.handle = { ...vm.handle, running: false };
+    const result = {
+      exitCode,
+      ...logs,
+      durationMs: Date.now() - vm.startedAt,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.deliverJobResult(vmId, result);
+  }
   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 },
+        {
+          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));
@@ -1406,7 +1771,10 @@ var DockerExecutor = class {
             () => resolve({
               statusCode: res.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+                Object.entries(res.headers).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? v.join(", ") : v ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             })
@@ -1427,15 +1795,15 @@ var DockerExecutor = class {
       (0, import_child_process5.execFile)(
         this.bin,
         ["exec", "-w", cwd, vm.containerId, "/bin/sh", "-c", request.command],
-        { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES2 },
+        { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES4 },
         (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),
+            stdout: stdout.slice(0, MAX_OUTPUT_BYTES4),
+            stderr: stderr.slice(0, MAX_OUTPUT_BYTES4),
             durationMs: Date.now() - startedAt,
             truncated: Boolean(truncated),
             timedOut
@@ -1451,11 +1819,19 @@ var DockerExecutor = class {
       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}`);
+        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 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 });
@@ -1468,13 +1844,18 @@ var DockerExecutor = class {
     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"] });
+      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.on(
+        "exit",
+        (code) => code === 0 ? resolve() : reject(new Error(`docker cp exited ${code}: ${stderr}`))
+      );
       proc.stdin.end(tarStream);
     });
   }
@@ -1503,7 +1884,8 @@ var DockerExecutor = class {
         });
       });
       if (ok) return;
-      if (Date.now() > deadline) throw new Error(`timed out waiting for docker vm agent on port ${port}`);
+      if (Date.now() > deadline)
+        throw new Error(`timed out waiting for docker vm agent on port ${port}`);
       await new Promise((resolve) => setTimeout(resolve, 500));
     }
   }
@@ -1515,7 +1897,11 @@ function buildSingleFileTar(name, content) {
   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(
+    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");
@@ -1538,7 +1924,7 @@ 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_OUTPUT_BYTES5 = 1024 * 1024;
 var MAX_FILE_BYTES3 = 5 * 1024 * 1024;
 var WORKSPACE_DIR2 = "/workspace";
 var AGENT_DIR = "/app";
@@ -1559,6 +1945,8 @@ var DockerSandboxExecutor = class {
     this.vms = /* @__PURE__ */ new Map();
     this.usedPorts = /* @__PURE__ */ new Set();
     this.loadedTemplates = /* @__PURE__ */ new Set();
+    this.pendingResults = /* @__PURE__ */ new Map();
+    this.exitHandlers = /* @__PURE__ */ new Map();
     this.bin = config.bin;
   }
   allocatePort() {
@@ -1590,7 +1978,9 @@ var DockerSandboxExecutor = class {
       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}`);
+      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 });
     }
@@ -1624,12 +2014,14 @@ var DockerSandboxExecutor = class {
       "-e",
       `STACK=${spec.stack}`,
       ...spec.sessionId ? ["-e", `SESSION_ID=${spec.sessionId}`] : [],
-      ...spec.appUrl ? ["-e", `APP_URL=${spec.appUrl}`] : []
+      ...spec.appUrl ? ["-e", `APP_URL=${spec.appUrl}`] : [],
+      ...Object.entries(spec.env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`])
     ];
+    const runMode = spec.runMode ?? "service";
     src_default.info({ vmId: spec.vmId, bin: this.bin, args: createArgs }, "creating docker sandbox");
     try {
       await execFileAsync2(this.bin, createArgs);
-      this.launchAgent(sandboxName, agentCommand);
+      if (runMode !== "job") this.launchAgent(sandboxName, agentCommand);
     } catch (error) {
       this.usedPorts.delete(hostPort);
       await import_promises5.default.rm(vmDir, { recursive: true, force: true }).catch(() => {
@@ -1644,11 +2036,84 @@ var DockerSandboxExecutor = class {
       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");
+    this.vms.set(spec.vmId, {
+      handle,
+      sandboxName,
+      vmDir,
+      hostPort,
+      agentCommand,
+      runMode,
+      startedAt: Date.now()
+    });
+    if (runMode === "job") {
+      this.runJob(spec.vmId, sandboxName, agentCommand);
+    } else {
+      await this.waitForAgent(hostPort);
+    }
+    src_default.info({ vmId: spec.vmId, sandboxName, hostPort, runMode }, "docker sandbox ready");
     return handle;
   }
+  /**
+   * Job mode: unlike `launchAgent` (fire-and-forget `sbx exec -d`, used for persistent
+   * services), run the entrypoint in the *foreground* — the CLI call itself blocks until the
+   * command exits and hands back its exit code + captured stdout/stderr directly, so there's
+   * no separate wait/logs step needed the way DockerExecutor needs for a backgrounded container.
+   */
+  runJob(vmId, sandboxName, agentCommand) {
+    const startedAt = this.vms.get(vmId)?.startedAt ?? Date.now();
+    (0, import_child_process6.execFile)(
+      this.bin,
+      ["exec", "-w", AGENT_DIR, sandboxName, "/bin/sh", "-c", agentCommand],
+      { maxBuffer: MAX_OUTPUT_BYTES5 },
+      (error, stdout, stderr) => {
+        const failed = error;
+        const truncated = failed?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        const result = {
+          exitCode: typeof failed?.code === "number" ? failed.code : failed ? 1 : 0,
+          stdout: stdout.slice(0, MAX_OUTPUT_BYTES5),
+          stderr: stderr.slice(0, MAX_OUTPUT_BYTES5),
+          truncated: Boolean(truncated),
+          durationMs: Date.now() - startedAt,
+          finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        void this.finishJob(vmId, sandboxName, result);
+      }
+    );
+  }
+  async finishJob(vmId, sandboxName, result) {
+    src_default.info({ vmId, exitCode: result.exitCode }, "docker sandbox job exited");
+    await execFileAsync2(this.bin, ["rm", "-f", sandboxName]).catch(
+      (error) => src_default.warn({ vmId, err: error }, "sbx rm after job exit failed")
+    );
+    const vm = this.vms.get(vmId);
+    if (vm) {
+      await import_promises5.default.rm(vm.vmDir, { recursive: true, force: true }).catch(() => {
+      });
+      this.usedPorts.delete(vm.hostPort);
+      vm.handle = { ...vm.handle, running: false };
+    }
+    this.deliverJobResult(vmId, result);
+  }
+  deliverJobResult(vmId, result) {
+    const handler = this.exitHandlers.get(vmId);
+    if (handler) {
+      this.exitHandlers.delete(vmId);
+      this.vms.delete(vmId);
+      handler(result);
+    } else {
+      this.pendingResults.set(vmId, result);
+    }
+  }
+  onExit(vmId, handler) {
+    const pending = this.pendingResults.get(vmId);
+    if (pending) {
+      this.pendingResults.delete(vmId);
+      this.vms.delete(vmId);
+      handler(pending);
+      return;
+    }
+    this.exitHandlers.set(vmId, handler);
+  }
   /**
    * `sbx create shell` doesn't run the image's own CMD — launch the guest agent explicitly.
    *
@@ -1659,10 +2124,17 @@ var DockerSandboxExecutor = class {
    * 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"));
+    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) {
@@ -1708,7 +2180,8 @@ var DockerSandboxExecutor = class {
    */
   async reattach(record) {
     const meta = record.runtimeMetadata;
-    if (!meta?.sandboxName || meta.hostPort === void 0 || !meta.vmDir || !meta.agentCommand) return void 0;
+    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"]);
@@ -1735,8 +2208,20 @@ var DockerSandboxExecutor = class {
       sandboxName: meta.sandboxName,
       vmDir: meta.vmDir,
       hostPort: meta.hostPort,
-      agentCommand: meta.agentCommand
+      agentCommand: meta.agentCommand,
+      runMode: record.runMode,
+      startedAt: Date.parse(record.createdAt) || Date.now()
     });
+    if (record.runMode === "job") {
+      void this.finishJob(record.vmId, meta.sandboxName, {
+        exitCode: -1,
+        stdout: "",
+        stderr: "worker restarted while this job was still running",
+        truncated: false,
+        durationMs: Date.now() - (Date.parse(record.createdAt) || Date.now()),
+        finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
     src_default.info({ vmId: record.vmId, sandboxName: meta.sandboxName }, "docker sandbox reattached");
     return handle;
   }
@@ -1745,7 +2230,13 @@ var DockerSandboxExecutor = class {
     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 },
+        {
+          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));
@@ -1754,7 +2245,10 @@ var DockerSandboxExecutor = class {
             () => resolve({
               statusCode: res.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+                Object.entries(res.headers).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? v.join(", ") : v ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             })
@@ -1775,15 +2269,15 @@ var DockerSandboxExecutor = class {
       (0, import_child_process6.execFile)(
         this.bin,
         ["exec", "-w", cwd, vm.sandboxName, "/bin/sh", "-c", request.command],
-        { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES3 },
+        { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES5 },
         (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),
+            stdout: stdout.slice(0, MAX_OUTPUT_BYTES5),
+            stderr: stderr.slice(0, MAX_OUTPUT_BYTES5),
             durationMs: Date.now() - startedAt,
             truncated: Boolean(truncated),
             timedOut
@@ -1799,16 +2293,31 @@ var DockerSandboxExecutor = class {
       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}`);
+        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}`]);
+        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)}`);
+      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}`]);
+        await execFileAsync2(this.bin, [
+          "cp",
+          tmpFile,
+          `${vm.sandboxName}:${WORKSPACE_DIR2}/${relativePath}`
+        ]);
       } finally {
         await import_promises5.default.rm(tmpFile, { force: true });
       }
@@ -1844,7 +2353,8 @@ var DockerSandboxExecutor = class {
     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}`);
+      if (Date.now() > deadline)
+        throw new Error(`timed out waiting for docker sandbox agent on port ${port}`);
       await new Promise((resolve) => setTimeout(resolve, 500));
     }
   }
@@ -1853,12 +2363,14 @@ var DockerSandboxExecutor = class {
 // src/executor/remote-executor.ts
 var import_http5 = __toESM(require("http"));
 var import_https = __toESM(require("https"));
+var JOB_POLL_INTERVAL_MS = 3e3;
 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.jobStartedAt = /* @__PURE__ */ new Map();
     this.base = config.agentUrl.replace(/\/$/, "");
     this.headers = {
       "Content-Type": "application/json",
@@ -1868,8 +2380,38 @@ var RemoteExecutor = class {
   async create(spec) {
     const handle = await this.request("POST", "/vms", spec);
     this.vms.set(spec.vmId, handle);
+    if (spec.runMode === "job") this.jobStartedAt.set(spec.vmId, Date.now());
     return handle;
   }
+  /**
+   * The remote agent's own wire protocol (VmHandle) has no exit-code/output field — extending
+   * it is out of this repo's control, so this only detects completion (poll GET /vms/:vmId
+   * until running flips false) without a real exit code or captured output. Good enough to
+   * unblock the record from being stuck in 'running' forever; a real RemoteExecutor deployment
+   * wanting full job support needs its agent protocol extended first.
+   */
+  onExit(vmId, handler) {
+    const startedAt = this.jobStartedAt.get(vmId) ?? Date.now();
+    const poll = async () => {
+      const handle = await this.request("GET", `/vms/${vmId}`).catch(() => void 0);
+      if (handle) this.vms.set(vmId, handle);
+      if (!handle || !handle.running) {
+        this.jobStartedAt.delete(vmId);
+        this.vms.delete(vmId);
+        handler({
+          exitCode: 0,
+          stdout: "",
+          stderr: "remote engine does not report job exit codes/output \u2014 completion detected via polling only",
+          truncated: false,
+          durationMs: Date.now() - startedAt,
+          finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        return;
+      }
+      setTimeout(() => void poll(), JOB_POLL_INTERVAL_MS);
+    };
+    void poll();
+  }
   async pause(vmId) {
     return this.updateCached(vmId, await this.request("POST", `/vms/${vmId}/pause`));
   }
@@ -1997,7 +2539,13 @@ var LambdaMicrovmExecutor = class {
         } : {},
         // 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 })
+        runHookPayload: JSON.stringify({
+          vmId: spec.vmId,
+          sessionId: spec.sessionId,
+          stack: spec.stack,
+          appUrl: spec.appUrl,
+          env: spec.env
+        })
       })
     );
     if (!run.microvmId || !run.endpoint) {
@@ -2085,7 +2633,10 @@ var LambdaMicrovmExecutor = class {
             () => resolve({
               statusCode: res.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+                Object.entries(res.headers).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? v.join(", ") : v ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             })
@@ -2118,7 +2669,10 @@ var LambdaMicrovmExecutor = class {
       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");
+    src_default.info(
+      { vmId: record.vmId, microvmId: meta.microvmId, state: described.state },
+      "[LambdaMicrovm] vm reattached"
+    );
     return handle;
   }
   mustGet(vmId) {
@@ -2158,7 +2712,9 @@ var LambdaMicrovmExecutor = class {
         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})`);
+        throw new Error(
+          `timed out waiting for microvm ${microvmId} to reach ${target} (still ${resp.state})`
+        );
       }
       await new Promise((r) => setTimeout(r, 1e3));
     }
@@ -2168,6 +2724,7 @@ var LambdaMicrovmExecutor = class {
 // src/executor/fargate-executor.ts
 var import_http6 = __toESM(require("http"));
 var import_client_ecs = require("@aws-sdk/client-ecs");
+var JOB_POLL_INTERVAL_MS2 = 5e3;
 var FARGATE_MEM_RANGES = {
   256: [512, 2048],
   512: [1024, 4096],
@@ -2187,6 +2744,8 @@ var FargateExecutor = class {
     this.config = config;
     this.vms = /* @__PURE__ */ new Map();
     this.containerNames = /* @__PURE__ */ new Map();
+    this.pendingResults = /* @__PURE__ */ new Map();
+    this.exitHandlers = /* @__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. */
@@ -2213,11 +2772,16 @@ var FargateExecutor = class {
       }
       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`);
+        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})`);
+        throw new Error(
+          `fargate task did not reach RUNNING within ${timeoutMs}ms (last status: ${task.lastStatus})`
+        );
       }
       await new Promise((resolve) => setTimeout(resolve, 3e3));
     }
@@ -2227,7 +2791,9 @@ var FargateExecutor = class {
     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] }));
+    const described = await ec2.send(
+      new DescribeNetworkInterfacesCommand({ NetworkInterfaceIds: [eniId] })
+    );
     return described.NetworkInterfaces?.[0]?.Association?.PublicIp;
   }
   async create(spec) {
@@ -2261,7 +2827,8 @@ var FargateExecutor = class {
                 ...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 }] : []
+                ...spec.appUrl ? [{ name: "APP_URL", value: spec.appUrl }] : [],
+                ...Object.entries(spec.env ?? {}).map(([name, value]) => ({ name, value }))
               ]
             }
           ]
@@ -2277,6 +2844,7 @@ var FargateExecutor = class {
       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");
+    const runMode = spec.runMode ?? "service";
     try {
       const ip = await this.waitForRunning(taskArn);
       const handle = {
@@ -2287,11 +2855,18 @@ var FargateExecutor = class {
         running: true,
         metadata: { taskArn, ip }
       };
-      this.vms.set(spec.vmId, { handle, taskArn, ip });
-      src_default.info({ vmId: spec.vmId, ip }, "fargate task running");
+      this.vms.set(spec.vmId, { handle, taskArn, ip, runMode, startedAt: Date.now() });
+      if (runMode === "job") void this.watchJob(spec.vmId, taskArn);
+      src_default.info({ vmId: spec.vmId, ip, runMode }, "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(() => {
+      await this.client.send(
+        new import_client_ecs.StopTaskCommand({
+          cluster: this.config.cluster,
+          task: taskArn,
+          reason: "startup failed"
+        })
+      ).catch(() => {
       });
       throw error;
     }
@@ -2308,7 +2883,11 @@ var FargateExecutor = class {
   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" })
+      new import_client_ecs.StopTaskCommand({
+        cluster: this.config.cluster,
+        task: vm.taskArn,
+        reason: "stopped via API"
+      })
     );
     vm.handle.running = false;
     return vm.handle;
@@ -2316,7 +2895,13 @@ var FargateExecutor = class {
   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"));
+    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) {
@@ -2345,7 +2930,10 @@ var FargateExecutor = class {
             () => resolve({
               statusCode: res.statusCode ?? 502,
               headers: Object.fromEntries(
-                Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v ?? ""])
+                Object.entries(res.headers).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? v.join(", ") : v ?? ""
+                ])
               ),
               body: Buffer.concat(chunks)
             })
@@ -2378,10 +2966,82 @@ var FargateExecutor = class {
       running: true,
       metadata: { taskArn: meta.taskArn, ip }
     };
-    this.vms.set(record.vmId, { handle, taskArn: meta.taskArn, ip });
+    this.vms.set(record.vmId, {
+      handle,
+      taskArn: meta.taskArn,
+      ip,
+      runMode: record.runMode,
+      startedAt: Date.parse(record.createdAt) || Date.now()
+    });
+    if (record.runMode === "job") void this.watchJob(record.vmId, meta.taskArn);
     src_default.info({ vmId: record.vmId, taskArn: meta.taskArn, ip }, "fargate task reattached");
     return handle;
   }
+  /**
+   * No push notification exists for "task stopped" without EventBridge wiring (v1 doesn't set
+   * that up), so poll DescribeTasks. Exit code comes straight from the container's own
+   * `exitCode` field — no CloudWatch Logs integration yet, so stdout/stderr capture isn't
+   * implemented for this engine (the caller can still find full output in CloudWatch directly,
+   * via the task's own log configuration).
+   */
+  async watchJob(vmId, taskArn) {
+    const startedAt = this.vms.get(vmId)?.startedAt ?? Date.now();
+    for (; ; ) {
+      await new Promise((resolve) => setTimeout(resolve, JOB_POLL_INTERVAL_MS2));
+      if (!this.vms.has(vmId)) return;
+      const described = await this.client.send(new import_client_ecs.DescribeTasksCommand({ cluster: this.config.cluster, tasks: [taskArn] })).catch(() => void 0);
+      const task = described?.tasks?.[0];
+      if (!task) {
+        this.finishJob(vmId, {
+          exitCode: -1,
+          stdout: "",
+          stderr: "fargate task not found while polling for completion",
+          truncated: false,
+          durationMs: Date.now() - startedAt,
+          finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        return;
+      }
+      if (task.lastStatus === "STOPPED") {
+        const exitCode = task.containers?.[0]?.exitCode;
+        this.finishJob(vmId, {
+          exitCode: exitCode ?? 1,
+          stdout: "",
+          stderr: [
+            task.stoppedReason ? `stoppedReason: ${task.stoppedReason}` : void 0,
+            "output capture not implemented for the fargate engine \u2014 see CloudWatch Logs for this task"
+          ].filter(Boolean).join("; "),
+          truncated: false,
+          durationMs: Date.now() - startedAt,
+          finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        return;
+      }
+    }
+  }
+  finishJob(vmId, result) {
+    src_default.info({ vmId, exitCode: result.exitCode }, "fargate job task exited");
+    const vm = this.vms.get(vmId);
+    if (vm) vm.handle = { ...vm.handle, running: false };
+    const handler = this.exitHandlers.get(vmId);
+    if (handler) {
+      this.exitHandlers.delete(vmId);
+      this.vms.delete(vmId);
+      handler(result);
+    } else {
+      this.pendingResults.set(vmId, result);
+    }
+  }
+  onExit(vmId, handler) {
+    const pending = this.pendingResults.get(vmId);
+    if (pending) {
+      this.pendingResults.delete(vmId);
+      this.vms.delete(vmId);
+      handler(pending);
+      return;
+    }
+    this.exitHandlers.set(vmId, handler);
+  }
   mustGet(vmId) {
     const vm = this.vms.get(vmId);
     if (!vm) throw new Error(`vm ${vmId} not found`);
@@ -2392,7 +3052,16 @@ var FargateExecutor = class {
 // 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"];
+var ENGINE_PRIORITY = [
+  "firecracker",
+  "qemu",
+  "docker-sandbox",
+  "docker",
+  "lambda-microvm",
+  "fargate",
+  "remote",
+  "mock"
+];
 function binaryOnPath(bin) {
   if (bin.includes("/")) {
     try {
@@ -2418,22 +3087,35 @@ function kvmUsable() {
   }
 }
 function hasBaseImages(cfg) {
-  if (cfg.kernelPath && cfg.initrdPath) return import_fs2.default.existsSync(cfg.kernelPath) && import_fs2.default.existsSync(cfg.initrdPath);
+  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` };
+    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)" };
+    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: false,
+      reason: "QEMU_ACCEL=kvm but /dev/kvm is not accessible"
+    };
   }
   return { engine: "qemu", available: true };
 }
@@ -2446,17 +3128,22 @@ function probeFirecracker(config) {
     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` };
+    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) {
+function hasLocalDockerImage(bin, imagePrefix, imageTag, stackImages = {}) {
   return VM_STACKS.some((stack) => {
     try {
-      (0, import_child_process7.execFileSync)("docker", ["image", "inspect", `${imagePrefix}-${stack}:${imageTag}`], { stdio: "ignore" });
+      const image = stackImages[stack] ?? `${imagePrefix}-${stack}:${imageTag}`;
+      (0, import_child_process7.execFileSync)(bin, ["image", "inspect", image], { stdio: "ignore" });
       return true;
     } catch {
       return false;
@@ -2464,7 +3151,7 @@ function hasLocalDockerImage(imagePrefix, imageTag) {
   });
 }
 function probeDocker(config) {
-  const { bin, imagePrefix, imageTag } = config.docker;
+  const { bin, imagePrefix, imageTag, stackImages } = config.docker;
   if (!binaryOnPath(bin)) {
     return { engine: "docker", available: false, reason: `${bin} not found on PATH` };
   }
@@ -2473,8 +3160,12 @@ function probeDocker(config) {
   } 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" };
+  if (!hasLocalDockerImage(bin, imagePrefix, imageTag, stackImages)) {
+    return {
+      engine: "docker",
+      available: false,
+      reason: "no local docker images \u2014 run scripts/setup-docker-images.sh"
+    };
   }
   return { engine: "docker", available: true };
 }
@@ -2486,10 +3177,18 @@ function probeDockerSandbox(config) {
   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"' };
+    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" };
+  if (!hasLocalDockerImage(config.docker.bin, 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 };
 }
@@ -2498,7 +3197,11 @@ function probeRemote(config) {
 }
 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" };
+  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;
@@ -2506,7 +3209,11 @@ function probeFargate(config) {
     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" };
+    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" };
@@ -2577,7 +3284,9 @@ var MultiEngineExecutor = class {
     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(", ")})`);
+      throw new Error(
+        `engine "${engine}" is not available on this worker (available: ${this.engines.join(", ")})`
+      );
     }
     const handle = await executor.create(spec);
     return { ...handle, engine };
@@ -2623,9 +3332,15 @@ var MultiEngineExecutor = class {
   }
   writeFiles(vmId, files) {
     const executor = this.route(vmId);
-    if (!executor.writeFiles) return Promise.reject(new Error("executor does not support guest file writes"));
+    if (!executor.writeFiles)
+      return Promise.reject(new Error("executor does not support guest file writes"));
     return executor.writeFiles(vmId, files);
   }
+  onExit(vmId, handler) {
+    const executor = this.route(vmId);
+    if (!executor.onExit) throw new Error("executor does not support job run mode");
+    executor.onExit(vmId, handler);
+  }
   /**
    * 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
@@ -2640,8 +3355,10 @@ var MultiEngineExecutor = class {
     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`);
+        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");
       })
@@ -2649,7 +3366,11 @@ var MultiEngineExecutor = class {
     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");
+      else
+        src_default.warn(
+          { vmId, err: result.reason },
+          "vm reattach failed \u2014 staying unavailable until next touch"
+        );
     });
   }
   route(vmId) {
@@ -2707,16 +3428,52 @@ function wrap(handler) {
   };
 }
 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.VM_CREATE,
+    wrap(async (spec) => {
+      const handle = await executor.create(spec);
+      if (spec.runMode === "job") {
+        try {
+          executor.onExit(
+            spec.vmId,
+            (result) => socket.emit(WorkerEvent.VM_RUN_EXITED, { vmId: spec.vmId, ...result })
+          );
+        } catch (error) {
+          await executor.destroy(spec.vmId).catch(() => {
+          });
+          throw error;
+        }
+      }
+      return handle;
+    })
+  );
+  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)
+      ({
+        vmId,
+        ...request
+      }) => executor.proxyHttp(vmId, request)
     )
   );
   socket.on(
@@ -2739,14 +3496,23 @@ function registerCommandHandlers(socket, executor) {
   );
 }
 function connectToSandbox(config, executor) {
+  let assignedWorkerId;
   const socket = (0, import_socket.io)(config.sandboxUrl, {
     path: config.workerSocketPath,
-    auth: { workerId: config.workerId, token: config.token },
+    auth: (callback) => callback({
+      workerId: config.workerId,
+      ...assignedWorkerId ? { assignedWorkerId } : {},
+      ...config.token ? { token: config.token } : {}
+    }),
     transports: ["websocket"],
     reconnection: true
   });
   let heartbeatTimer;
   let reattachFallbackTimer;
+  socket.on(WorkerEvent.ASSIGNED_ID, ({ workerId }) => {
+    assignedWorkerId = workerId;
+    src_default.info({ workerId: config.workerId, assignedWorkerId }, "worker runtime ID assigned");
+  });
   const sendHeartbeat = () => socket.emit(WorkerEvent.HEARTBEAT, buildHeartbeat(config, executor));
   function startHeartbeat() {
     if (heartbeatTimer) return;
@@ -2754,15 +3520,37 @@ function connectToSandbox(config, executor) {
     heartbeatTimer = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
   }
   socket.on("connect", () => {
-    src_default.info({ workerId: config.workerId, url: config.sandboxUrl }, "connected to sandbox");
+    src_default.info(
+      { workerId: config.workerId, assignedWorkerId, 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");
+      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);
+      executor.reattachAll(records).catch((error) => src_default.error({ err: error }, "reattach batch failed")).finally(() => {
+        for (const record of records) {
+          if (record.runMode !== "job" || !executor.get(record.vmId)) continue;
+          try {
+            executor.onExit(
+              record.vmId,
+              (result) => socket.emit(WorkerEvent.VM_RUN_EXITED, { vmId: record.vmId, ...result })
+            );
+          } catch (error) {
+            src_default.warn(
+              { vmId: record.vmId, err: error },
+              "reattached job vm has no onExit support"
+            );
+          }
+        }
+        startHeartbeat();
+      });
     });
   });
   socket.on("disconnect", (reason) => {
@@ -2773,7 +3561,10 @@ function connectToSandbox(config, executor) {
     socket.off(WorkerEvent.REATTACH);
   });
   socket.on("connect_error", (error) => {
-    src_default.error({ err: error }, "sandbox connection error");
+    src_default.error({
+      err: error,
+      sandboxUrl: config.sandboxUrl
+    }, "sandbox connection error");
   });
   registerCommandHandlers(socket, executor);
   return socket;
@@ -2807,7 +3598,11 @@ var VncRelay = class {
     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.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);
@@ -2842,8 +3637,15 @@ var VncRelay = class {
       }
     });
     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 });
+      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"));
@@ -2904,7 +3706,10 @@ var SerialRelay = class {
       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(
+          "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"));
       });
@@ -2914,8 +3719,14 @@ var SerialRelay = class {
   }
   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 }));
+    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);
@@ -2959,10 +3770,93 @@ function attachConsoleRelays(executor, sandboxSocket) {
   };
 }
 
+// src/prepare-images.ts
+var import_child_process8 = require("child_process");
+var import_util4 = require("util");
+var execFileAsync3 = (0, import_util4.promisify)(import_child_process8.execFile);
+function artifactImageLocation(env = process.env) {
+  const bucket = env.S3_BUCKET_ARTIFACTS?.trim();
+  if (!bucket) return void 0;
+  if (bucket.includes("/") || bucket.includes("://")) {
+    throw new Error("S3_BUCKET_ARTIFACTS must contain only the bucket name (no scheme or path)");
+  }
+  const version2 = env.NODE_ENV === "development" || env.BUILDER_ENV === "local" ? "local" : version;
+  return `s3://${bucket}/${version2}/qemu`;
+}
+function allStacksAvailable(imagesDir) {
+  const available = new Set(availableStacks(imagesDir));
+  return PUBLISHED_IMAGE_STACKS.every((stack) => available.has(stack));
+}
+async function dockerAvailable(bin) {
+  try {
+    await execFileAsync3(bin, ["info"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function dockerImageExists(bin, image) {
+  try {
+    await execFileAsync3(bin, ["image", "inspect", image]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function prepareWorkerImages(config, env = process.env) {
+  const vmImagesUrl = artifactImageLocation(env);
+  const refreshVmImages = env.VM_IMAGES_REFRESH === "true";
+  if (vmImagesUrl) {
+    const destinations = /* @__PURE__ */ new Set([config.qemu.imagesDir, config.firecracker.imagesDir]);
+    for (const imagesDir of destinations) {
+      if (!refreshVmImages && allStacksAvailable(imagesDir)) continue;
+      await pullImages({
+        location: vmImagesUrl,
+        arch: hostArch(),
+        endpoint: env.S3_ARTIFACTS_ENDPOINT
+      }, imagesDir);
+    }
+  }
+  const shouldPullDocker = env.DOCKER_PULL_IMAGES === "true" || env.DOCKER_PULL_IMAGES !== "false" && config.docker.imagePrefix.includes("/");
+  if (!shouldPullDocker || !await dockerAvailable(config.docker.bin)) return;
+  for (const stack of PUBLISHED_IMAGE_STACKS) {
+    const image = config.docker.stackImages[stack] ?? `${config.docker.imagePrefix}-${stack}:${config.docker.imageTag}`;
+    if (!await dockerImageExists(config.docker.bin, image)) {
+      await execFileAsync3(config.docker.bin, ["pull", image]);
+    }
+  }
+}
+
+// src/health-server.ts
+var import_http7 = __toESM(require("http"));
+async function startSandboxHealthServer(options) {
+  const server = import_http7.default.createServer((req, res) => {
+    const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (pathname === `${options.pathPrefix}/healthz`) {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: true, status: "alive" }));
+      return;
+    }
+    if (pathname === `${options.pathPrefix}/health`) {
+      const ready = options.isReady();
+      res.writeHead(ready ? 200 : 503, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: ready, status: ready ? "ready" : "not-ready" }));
+      return;
+    }
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: false, error: "not found" }));
+  });
+  await new Promise((resolve, reject) => {
+    server.listen(options.port, options.host, resolve);
+    server.once("error", reject);
+  });
+  return server;
+}
+
 // 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) => {
+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>", "worker pool/authentication ID (env: WORKER_ID; default: hostname)").option("--sandbox-url <url>", "control-plane base URL (env: SANDBOX_URL; default: https://api.sandbox.filingramp.com/v0)").option("--max-vms <count>", "maximum concurrent VMs (env: MAX_VMS)").action(async (opts) => {
   const config = loadWorkerConfigFromEnv({
     ...process.env,
     ...opts.token ? { WORKER_TOKEN: opts.token } : {},
@@ -2970,8 +3864,17 @@ program.command("start").description("start a worker and connect it to the sandb
     ...opts.sandboxUrl ? { SANDBOX_URL: opts.sandboxUrl } : {},
     ...opts.maxVms ? { MAX_VMS: opts.maxVms } : {}
   });
+  const socketRef = {};
+  const healthServer = await startSandboxHealthServer({
+    host: config.healthHost,
+    port: config.healthPort,
+    pathPrefix: config.healthPathPrefix,
+    isReady: () => socketRef.current?.connected === true
+  });
+  await prepareWorkerImages(config);
   const executor = createExecutor(config);
   const socket = connectToSandbox(config, executor);
+  socketRef.current = socket;
   attachConsoleRelays(executor, socket);
   let stopping = false;
   const stop = async (signal) => {
@@ -2980,6 +3883,7 @@ program.command("start").description("start a worker and connect it to the sandb
     console.log(`
 ${signal} received; shutting down sandbox worker...`);
     socket.disconnect();
+    healthServer.close();
     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`);
@@ -2991,7 +3895,7 @@ ${signal} received; shutting down sandbox worker...`);
   process.once("SIGTERM", () => {
     void stop("SIGTERM");
   });
-  console.log(`Starting sandbox worker ${config.workerId} \u2192 ${config.sandboxUrl}`);
+  src_default.info(`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: "-" }));
@@ -3001,13 +3905,13 @@ program.command("detect").description("probe this host and report which micro-VM
   }
 });
 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) => {
+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 (default derived from S3_BUCKET_ARTIFACTS)", artifactImageLocation()).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: S3_ARTIFACTS_ENDPOINT)", process.env.S3_ARTIFACTS_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", 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) => {
+images.command("push").description("upload locally built per-stack base images (scripts/setup-vm-images.sh) to S3").requiredOption("--to <location>", "s3://bucket[/prefix] (default derived from S3_BUCKET_ARTIFACTS)", artifactImageLocation()).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: S3_ARTIFACTS_ENDPOINT)", process.env.S3_ARTIFACTS_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}`);