@madarco/agentbox 0.7.0 → 0.9.0

package/runtime/relay/bin.cjs

@@ -3514,7 +3514,7 @@ var require_cross_spawn = __commonJS({
     var cp = require("child_process");
     var parse = require_parse();
     var enoent = require_enoent();
-    function spawn4(command, args, options) {
+    function spawn6(command, args, options) {
       const parsed = parse(command, args, options);
       const spawned = cp.spawn(parsed.command, parsed.args, parsed.options);
       enoent.hookChildProcess(spawned, parsed);
@@ -3526,8 +3526,8 @@ var require_cross_spawn = __commonJS({
       result.error = result.error || enoent.verifyENOENTSync(result.status, parsed);
       return result;
     }
-    module2.exports = spawn4;
-    module2.exports.spawn = spawn4;
+    module2.exports = spawn6;
+    module2.exports.spawn = spawn6;
     module2.exports.sync = spawnSync2;
     module2.exports._parse = parse;
     module2.exports._enoent = enoent;
@@ -3540,7 +3540,13 @@ __export(cloud_poller_exports, {
   CloudBoxPoller: () => CloudBoxPoller,
   CloudBoxPollers: () => CloudBoxPollers
 });
-var import_node_http, import_node_https, import_promises15, BACKOFF_BASE_MS, BACKOFF_MAX_MS, REQUEST_TIMEOUT_MS, FAST_REQUEST_TIMEOUT_MS, FAST_MODE_DECAY_POLLS, STOPPED_TICK_MS, CloudBoxPoller, CloudBoxPollers;
+function isConnectionLevelError(err) {
+  const code = err?.code;
+  if (code && CONNECTION_LEVEL_CODES.has(code)) return true;
+  const msg = err instanceof Error ? err.message : String(err);
+  return /\b(ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ECONNRESET|EPIPE)\b/.test(msg);
+}
+var import_node_http, import_node_https, import_promises15, BACKOFF_BASE_MS, BACKOFF_MAX_MS, REQUEST_TIMEOUT_MS, FAST_REQUEST_TIMEOUT_MS, FAST_MODE_DECAY_POLLS, STOPPED_TICK_MS, CONNECTION_LEVEL_CODES, CloudBoxPoller, CloudBoxPollers;
 var init_cloud_poller = __esm({
   "src/cloud-poller.ts"() {
     "use strict";
@@ -3553,9 +3559,17 @@ var init_cloud_poller = __esm({
     FAST_REQUEST_TIMEOUT_MS = 8e3;
     FAST_MODE_DECAY_POLLS = 5;
     STOPPED_TICK_MS = 250;
+    CONNECTION_LEVEL_CODES = /* @__PURE__ */ new Set([
+      "ECONNREFUSED",
+      "ENOTFOUND",
+      "EHOSTUNREACH",
+      "ECONNRESET",
+      "EPIPE"
+    ]);
     CloudBoxPoller = class {
       constructor(deps) {
         this.deps = deps;
+        this.currentPreviewUrl = deps.previewUrl;
       }
       deps;
       stopped = false;
@@ -3569,6 +3583,15 @@ var init_cloud_poller = __esm({
        * within ~5 successful round-trips.
        */
       fastModePolls = 0;
+      /**
+       * Mutable copy of `deps.previewUrl`. We don't read `deps.previewUrl`
+       * directly after construction because `recoverPreviewUrl` may hand us a
+       * new URL (e.g. Hetzner reopens its SSH ControlMaster and the `-L`
+       * forward gets a new ephemeral local port).
+       */
+      currentPreviewUrl;
+      /** Guards against recovery storms — at most one recovery attempt in flight. */
+      recovering = null;
       start() {
         if (this.loopPromise) return;
         this.loopPromise = this.run().catch((err) => {
@@ -3585,7 +3608,7 @@ var init_cloud_poller = __esm({
        * and the in-box agent finally sees the answer.
        */
       async respond(actionId, result) {
-        const base = this.deps.previewUrl.replace(/\/+$/, "");
+        const base = this.currentPreviewUrl.replace(/\/+$/, "");
         const url = new URL(`${base}/bridge/action-result`);
         const isHttps = url.protocol === "https:";
         const transport = isHttps ? import_node_https.request : import_node_http.request;
@@ -3675,6 +3698,9 @@ var init_cloud_poller = __esm({
               this.fastModePolls = FAST_MODE_DECAY_POLLS;
             }
             this.log(`poll error: ${msg}`);
+            if (this.deps.recoverPreviewUrl && isConnectionLevelError(err)) {
+              await this.tryRecoverPreviewUrl();
+            }
             await this.backoff();
           }
           if (this.currentBackoffMs === 0 && this.fastModePolls > 0) {
@@ -3687,8 +3713,33 @@ var init_cloud_poller = __esm({
         this.currentBackoffMs = this.currentBackoffMs === 0 ? BACKOFF_BASE_MS : Math.min(this.currentBackoffMs * 2, BACKOFF_MAX_MS);
         await (0, import_promises15.setTimeout)(this.currentBackoffMs);
       }
+      async tryRecoverPreviewUrl() {
+        if (!this.deps.recoverPreviewUrl) return;
+        if (this.recovering) {
+          await this.recovering;
+          return;
+        }
+        this.recovering = (async () => {
+          try {
+            const next = await this.deps.recoverPreviewUrl();
+            if (typeof next === "string" && next.length > 0 && next !== this.currentPreviewUrl) {
+              this.log(`preview URL recovered: ${this.currentPreviewUrl} \u2192 ${next}`);
+              this.currentPreviewUrl = next;
+              this.currentBackoffMs = 0;
+            } else if (typeof next === "string" && next === this.currentPreviewUrl) {
+              this.log("preview URL recovered (unchanged)");
+              this.currentBackoffMs = 0;
+            }
+          } catch (err) {
+            this.log(`preview URL recover failed: ${err instanceof Error ? err.message : String(err)}`);
+          } finally {
+            this.recovering = null;
+          }
+        })();
+        await this.recovering;
+      }
       async pollOnce() {
-        const base = this.deps.previewUrl.replace(/\/+$/, "");
+        const base = this.currentPreviewUrl.replace(/\/+$/, "");
         const url = new URL(`${base}/bridge/poll?since=${String(this.cursor)}`);
         const isHttps = url.protocol === "https:";
         const transport = isHttps ? import_node_https.request : import_node_http.request;
@@ -11124,10 +11175,11 @@ var import_node_http3 = require("http");
 
 // src/types.ts
 var DEFAULT_RELAY_PORT = 8787;
+var DEFAULT_BOX_RELAY_PORT = 8788;
 var RELAY_EVENT_RING_SIZE = 1e3;
 
 // src/server.ts
-var import_node_child_process6 = require("child_process");
+var import_node_child_process7 = require("child_process");
 var import_node_http2 = require("http");
 
 // ../../node_modules/.pnpm/is-plain-obj@4.1.0/node_modules/is-plain-obj/index.js
@@ -17953,6 +18005,8 @@ function projectDockerFields(box) {
     webHostPort: box.webHostPort,
     portlessAlias: box.portlessAlias,
     portlessUrl: box.portlessUrl,
+    portlessVncAlias: box.portlessVncAlias,
+    portlessVncUrl: box.portlessVncUrl,
     dockerVolume: box.dockerVolume,
     dockerCacheShared: box.dockerCacheShared,
     checkpointImage: box.checkpointImage
@@ -17973,8 +18027,262 @@ function findBox(idOrName, state) {
   return { kind: "none" };
 }
 
-// src/prompts.ts
+// src/gh.ts
+var import_node_child_process6 = require("child_process");
+var GH_PR_OPS = [
+  "create",
+  "view",
+  "list",
+  "comment",
+  "review",
+  "merge",
+  "checkout",
+  "close",
+  "reopen"
+];
+function isGhPrOp(value) {
+  return GH_PR_OPS.includes(value);
+}
+var GH_PR_READ_ONLY_OPS = /* @__PURE__ */ new Set(["view", "list"]);
+function injectPrCreateHead(op, branch, args) {
+  if (op !== "create") return args;
+  if (!branch || branch === "HEAD") return args;
+  if (hasHeadArg(args)) return args;
+  return ["--head", branch, ...args];
+}
+function hasHeadArg(args) {
+  return args.some((a2) => a2 === "--head" || a2.startsWith("--head=") || a2.startsWith("-H"));
+}
+function prCreateNeedsHead(op, args) {
+  return op === "create" && !hasHeadArg(args);
+}
+var PR_CREATE_NO_HEAD_REFUSAL = {
+  exitCode: 65,
+  stdout: "",
+  stderr: "gh pr create: refusing to run without --head \u2014 could not resolve this box's branch, and falling back to the host repo's checked-out branch would open a PR for the wrong branch. Ensure the box branch is pushed, or pass --head <branch> explicitly.\n"
+};
+var GH_RPC_TIMEOUT_MS = 12e4;
+var GH_READY_CACHE_TTL_MS = 6e4;
+var ghReadyCache;
+async function assertGhReady() {
+  const now = Date.now();
+  if (ghReadyCache && ghReadyCache.expiresAt > now) {
+    return ghReadyCache.result;
+  }
+  const result = await probeGh();
+  ghReadyCache = { result, expiresAt: now + GH_READY_CACHE_TTL_MS };
+  return result;
+}
+async function probeGh() {
+  const version = await runHostGh(["--version"], process.cwd(), 1e4);
+  if (version.exitCode === 127 || /ENOENT/.test(version.stderr)) {
+    return {
+      exitCode: 127,
+      stdout: "",
+      stderr: "gh not installed on host (https://cli.github.com)\n"
+    };
+  }
+  if (version.exitCode !== 0) {
+    return {
+      exitCode: version.exitCode,
+      stdout: "",
+      stderr: `gh --version failed: ${version.stderr || version.stdout}`.trimEnd() + "\n"
+    };
+  }
+  const auth = await runHostGh(["auth", "status"], process.cwd(), 15e3);
+  if (auth.exitCode !== 0) {
+    return {
+      exitCode: 4,
+      stdout: "",
+      stderr: "gh not authenticated on host (run `gh auth login`)\n"
+    };
+  }
+  return null;
+}
+function runHostGh(args, cwd, timeoutMs = GH_RPC_TIMEOUT_MS) {
+  return new Promise((resolve2) => {
+    const child = (0, import_node_child_process6.spawn)("gh", args, {
+      cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (exitCode) => {
+      if (settled) return;
+      settled = true;
+      resolve2({ exitCode, stdout, stderr });
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      stderr += `
+relay: gh command timed out after ${String(timeoutMs)}ms
+`;
+      finish(124);
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      const code = err.code;
+      stderr += String(err.message ?? err);
+      finish(code === "ENOENT" ? 127 : 1);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      finish(code ?? -1);
+    });
+  });
+}
+async function checkoutGuards(hostMainRepo, registeredBranches) {
+  const status = await runGitProbe(["-C", hostMainRepo, "status", "--porcelain"]);
+  if (status.exitCode !== 0) {
+    return {
+      exitCode: status.exitCode,
+      stdout: "",
+      stderr: `gh pr checkout: failed to inspect host repo: ${status.stderr || status.stdout}`.trimEnd() + "\n"
+    };
+  }
+  if (status.stdout.trim().length > 0) {
+    return {
+      exitCode: 12,
+      stdout: "",
+      stderr: `gh pr checkout: ${hostMainRepo} has uncommitted changes; refusing to switch branches
+`
+    };
+  }
+  const head = await runGitProbe(["-C", hostMainRepo, "rev-parse", "--abbrev-ref", "HEAD"]);
+  if (head.exitCode !== 0) {
+    return {
+      exitCode: head.exitCode,
+      stdout: "",
+      stderr: `gh pr checkout: failed to resolve HEAD: ${head.stderr || head.stdout}`.trimEnd() + "\n"
+    };
+  }
+  const currentBranch = head.stdout.trim();
+  if (registeredBranches.includes(currentBranch)) {
+    return {
+      exitCode: 12,
+      stdout: "",
+      stderr: `gh pr checkout: ${hostMainRepo} is on registered box branch ${currentBranch}; refusing (would corrupt the bind-mounted box HEAD)
+`
+    };
+  }
+  return null;
+}
+function runGitProbe(args) {
+  return new Promise((resolve2) => {
+    const child = (0, import_node_child_process6.spawn)("git", args, { env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (c3) => {
+      stdout += c3.toString("utf8");
+    });
+    child.stderr?.on("data", (c3) => {
+      stderr += c3.toString("utf8");
+    });
+    child.on("error", (err) => {
+      resolve2({ exitCode: 127, stdout, stderr: stderr + String(err.message ?? err) });
+    });
+    child.on("close", (code) => {
+      resolve2({ exitCode: code ?? -1, stdout, stderr });
+    });
+  });
+}
+function refuseMergeBypass(op) {
+  if (op !== "merge") return null;
+  if (process.env["AGENTBOX_PROMPT"] !== "off") return null;
+  if (process.env["AGENTBOX_GH_FORCE"] === "1") return null;
+  return {
+    exitCode: 10,
+    stdout: "",
+    stderr: "gh pr merge: AGENTBOX_PROMPT=off bypass requires AGENTBOX_GH_FORCE=1 (merge is irreversible)\n"
+  };
+}
+function refuseCheckoutByDefault(op) {
+  if (op !== "checkout") return null;
+  if (process.env["AGENTBOX_GH_PR_CHECKOUT"] === "allow") return null;
+  return {
+    exitCode: 13,
+    stdout: "",
+    stderr: "gh pr checkout: disabled by default; set AGENTBOX_GH_PR_CHECKOUT=allow to enable\n"
+  };
+}
+
+// src/host-initiated.ts
 var import_node_crypto = require("crypto");
+var DEFAULT_TTL_MS = 12e4;
+function hashRpcParams(params) {
+  return (0, import_node_crypto.createHash)("sha256").update(canonicalJson(params)).digest("hex");
+}
+function canonicalJson(v) {
+  if (v === null) return "null";
+  if (typeof v === "undefined") return "null";
+  if (typeof v === "number") return Number.isFinite(v) ? String(v) : "null";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(canonicalJson).join(",") + "]";
+  if (typeof v === "object") {
+    const entries = Object.entries(v).filter(([k]) => k !== "hostInitiated").filter(([, val]) => val !== void 0).sort(([a2], [b]) => a2 < b ? -1 : a2 > b ? 1 : 0);
+    return "{" + entries.map(([k, val]) => JSON.stringify(k) + ":" + canonicalJson(val)).join(",") + "}";
+  }
+  return "null";
+}
+var HostInitiatedTokens = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Mint a fresh one-time token scoped to (boxId, method, paramsHash).
+   * `paramsHash` MUST be supplied for any call surface where the box can
+   * influence the eventual RPC params. Pass `null` only when there are no
+   * params (no current call sites use this).
+   */
+  mint(boxId, method, paramsHash, ttlMs = DEFAULT_TTL_MS) {
+    const token = (0, import_node_crypto.randomBytes)(32).toString("hex");
+    this.store.set(token, { boxId, method, paramsHash, expiresAt: Date.now() + ttlMs });
+    return token;
+  }
+  /**
+   * Returns true exactly once if `token` is a valid, unexpired token for the
+   * given `(boxId, method)` AND the supplied `incomingParamsHash` matches
+   * the hash bound at mint time. The token is removed on a successful match
+   * (one-shot semantics). All failure modes return false — callers fall back
+   * to the normal prompt path.
+   */
+  consume(token, boxId, method, incomingParamsHash) {
+    if (!token || typeof token !== "string") return false;
+    const record = this.store.get(token);
+    if (!record) return false;
+    if (record.expiresAt < Date.now()) {
+      this.store.delete(token);
+      return false;
+    }
+    if (record.boxId !== boxId || record.method !== method) return false;
+    if (record.paramsHash !== null && record.paramsHash !== incomingParamsHash) {
+      return false;
+    }
+    this.store.delete(token);
+    return true;
+  }
+  /** Drop expired entries. Cheap; safe to call periodically. */
+  gc() {
+    const now = Date.now();
+    for (const [token, record] of this.store) {
+      if (record.expiresAt < now) this.store.delete(token);
+    }
+  }
+  /** Test-only: number of live tokens. */
+  size() {
+    return this.store.size;
+  }
+};
+
+// src/prompts.ts
+var import_node_crypto2 = require("crypto");
 var PendingPrompts = class {
   entries = /* @__PURE__ */ new Map();
   add(boxId, ev) {
@@ -18063,7 +18371,7 @@ async function askPrompt(prompts, subscribers, boxId, params, opts) {
   if (process.env.AGENTBOX_PROMPT === "off") {
     return { answer: "y" };
   }
-  const ev = { id: (0, import_node_crypto.randomUUID)(), ...params };
+  const ev = { id: (0, import_node_crypto2.randomUUID)(), ...params };
   const promise = prompts.add(boxId, ev);
   subscribers.broadcast(boxId, "prompt-ask", ev);
   if (opts?.ttlMs !== void 0 && opts.ttlMs > 0) {
@@ -18092,36 +18400,43 @@ function isPromptAnswerBody(v) {
 async function resolveCloudBackend(name) {
   if (name === "daytona") {
     const pkg = "@agentbox/sandbox-daytona";
-    try {
-      const mod = await import(pkg);
-      return mod.daytonaBackend;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (/cannot find module|MODULE_NOT_FOUND/i.test(msg)) {
-        throw new Error(
-          `relay: cannot load '${pkg}' at runtime \u2014 install it alongside @agentbox/relay (the @madarco/agentbox CLI normally provides this dependency). Original: ${msg}`
-        );
-      }
-      throw err;
-    }
+    return loadCloudBackend(pkg, async () => (await import(pkg)).daytonaBackend);
   }
   if (name === "hetzner") {
     const pkg = "@agentbox/sandbox-hetzner";
-    try {
-      const mod = await import(pkg);
-      return mod.hetznerBackend;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (/cannot find module|MODULE_NOT_FOUND/i.test(msg)) {
-        throw new Error(
-          `relay: cannot load '${pkg}' at runtime \u2014 install it alongside @agentbox/relay (the @madarco/agentbox CLI normally provides this dependency). Original: ${msg}`
-        );
-      }
-      throw err;
-    }
+    return loadCloudBackend(pkg, async () => (await import(pkg)).hetznerBackend);
+  }
+  if (name === "vercel") {
+    const pkg = "@agentbox/sandbox-vercel";
+    return loadCloudBackend(pkg, async () => (await import(pkg)).vercelBackend);
   }
   throw new Error(`no host executor for cloud backend '${name}'`);
 }
+async function loadCloudBackend(pkg, load2) {
+  try {
+    return await load2();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/cannot find module|MODULE_NOT_FOUND/i.test(msg)) {
+      throw new Error(
+        `relay: cannot load '${pkg}' at runtime \u2014 install it alongside @agentbox/relay (the @madarco/agentbox CLI normally provides this dependency). Original: ${msg}`
+      );
+    }
+    throw err;
+  }
+}
+async function refreshCloudPreviewUrl(backendName, boxId, port) {
+  try {
+    const backend = await resolveCloudBackend(backendName);
+    if (!backend.refreshPreviewUrl) return null;
+    const lookup = await lookupCloudBox(boxId);
+    const handle = { sandboxId: lookup.cloudSandboxId };
+    const url = await backend.refreshPreviewUrl(handle, port);
+    return url.url;
+  } catch {
+    return null;
+  }
+}
 async function executeCloudAction(action, deps) {
   const log = deps.log ?? (() => {
   });
@@ -18141,6 +18456,17 @@ async function executeCloudAction(action, deps) {
   if (action.method === "browser.open.mirror") {
     return runBrowserOpenMirror(action, deps);
   }
+  if (action.method.startsWith("gh.pr.")) {
+    return runGhPrRpc(action, deps);
+  }
+  if (action.method === "git.clone" || action.method === "gh.repo.clone") {
+    return {
+      exitCode: 64,
+      stdout: "",
+      stderr: `${action.method}: not yet implemented (deferred; see docs/plans/gh-and-git-shims-host-only.md). Run \`gh\` / \`git\` on the host directly for now.
+`
+    };
+  }
   return {
     exitCode: 1,
     stdout: "",
@@ -18148,6 +18474,99 @@ async function executeCloudAction(action, deps) {
 `
   };
 }
+async function runGhPrRpc(action, deps) {
+  const op = action.method.slice("gh.pr.".length);
+  if (!isGhPrOp(op)) {
+    return {
+      exitCode: 64,
+      stdout: "",
+      stderr: `unknown gh.pr.* op: ${op}
+`
+    };
+  }
+  const mergeBypass = refuseMergeBypass(op);
+  if (mergeBypass) return mergeBypass;
+  const checkoutOptIn = refuseCheckoutByDefault(op);
+  if (checkoutOptIn) return checkoutOptIn;
+  const params = action.params ?? {};
+  const args = Array.isArray(params.args) ? params.args.filter((a2) => typeof a2 === "string") : [];
+  const ghReady = await assertGhReady();
+  if (ghReady) return ghReady;
+  const lookup = await lookupCloudBox(deps.boxId);
+  if (op === "checkout") {
+    const guard = await checkoutGuards(lookup.workspacePath, []);
+    if (guard) return guard;
+  }
+  const tokenClaimedGhCloud = typeof params.hostInitiated === "string";
+  const incomingHashGhCloud = hashRpcParams(params);
+  const hostInitiatedGhOk = !GH_PR_READ_ONLY_OPS.has(op) && tokenClaimedGhCloud && (deps.hostInitiatedTokens?.consume(
+    params.hostInitiated,
+    deps.boxId,
+    `gh.pr.${op}`,
+    incomingHashGhCloud
+  ) ?? false);
+  if (!GH_PR_READ_ONLY_OPS.has(op) && tokenClaimedGhCloud && !hostInitiatedGhOk) {
+    return {
+      exitCode: 10,
+      stdout: "",
+      stderr: "host-initiated token rejected: invalid, expired, or bound to different params\n"
+    };
+  }
+  if (!GH_PR_READ_ONLY_OPS.has(op) && !hostInitiatedGhOk && deps.prompts && deps.subscribers) {
+    const detail = args.join(" ").slice(0, 200);
+    const ctx = {
+      kind: "confirm",
+      message: `Allow gh pr ${op} from cloud box ${deps.boxName ?? deps.boxId}?`,
+      detail,
+      defaultAnswer: "n",
+      context: {
+        command: `gh pr ${op}`,
+        cwd: params.path,
+        argv: args
+      }
+    };
+    const hasSubscriber = deps.subscribers.forBox(deps.boxId).length > 0;
+    if (!hasSubscriber && process.env["AGENTBOX_PROMPT"] !== "off") {
+      const noSubMode = (process.env["AGENTBOX_GH_NO_SUB"] ?? "deny").toLowerCase();
+      if (noSubMode === "deny") {
+        return {
+          exitCode: 10,
+          stdout: "",
+          stderr: "denied automatically \u2014 no attached wrapper to confirm. Attach `agentbox claude` (or similar) and retry, or set AGENTBOX_GH_NO_SUB=allow.\n"
+        };
+      }
+      if (noSubMode === "allow") {
+        deps.log?.(`gh.pr.${op} auto-approved (no subscribers, AGENTBOX_GH_NO_SUB=allow)`);
+      } else {
+        const verdict = await askPrompt(deps.prompts, deps.subscribers, deps.boxId, ctx, {
+          ttlMs: 5 * 60 * 1e3
+        });
+        if (verdict.answer !== "y") {
+          return { exitCode: 10, stdout: "", stderr: "denied by user\n" };
+        }
+      }
+    } else {
+      const verdict = await askPrompt(deps.prompts, deps.subscribers, deps.boxId, ctx);
+      if (verdict.answer !== "y") {
+        return { exitCode: 10, stdout: "", stderr: "denied by user\n" };
+      }
+    }
+  }
+  let finalArgs = args;
+  if (op === "create" && !args.some((a2) => a2 === "--head" || a2.startsWith("--head="))) {
+    const backend = await resolveCloudBackend(deps.backendName);
+    const handle = { sandboxId: lookup.cloudSandboxId };
+    const containerPath = params.path ?? "/workspace";
+    const branchProbe = await backend.exec(
+      handle,
+      `git -C ${shellQuote(containerPath)} rev-parse --abbrev-ref HEAD`
+    );
+    const branch = branchProbe.exitCode === 0 ? (branchProbe.stdout ?? "").trim() : "";
+    finalArgs = injectPrCreateHead(op, branch, args);
+  }
+  if (prCreateNeedsHead(op, finalArgs)) return PR_CREATE_NO_HEAD_REFUSAL;
+  return runHostGh(["pr", op, ...finalArgs], lookup.workspacePath);
+}
 async function runBrowserOpenMirror(action, deps) {
   const params = action.params ?? {};
   const url = typeof params.url === "string" ? params.url.trim() : "";
@@ -18174,8 +18593,8 @@ async function runBrowserOpenMirror(action, deps) {
       { ttlMs: TTL_MS }
     );
     if (verdict.answer === "y" && !verdict.cancelled) {
-      const { spawn: spawn4 } = await import("child_process");
-      const child = spawn4("open", [url], { stdio: "ignore", detached: true });
+      const { spawn: spawn6 } = await import("child_process");
+      const child = spawn6("open", [url], { stdio: "ignore", detached: true });
       child.unref();
     }
   } catch (err) {
@@ -18346,7 +18765,23 @@ async function runGitRpc(action, deps) {
       stderr: `failed to resolve branch in sandbox ${containerPath}: ${branchProbe.stderr || branch}`
     };
   }
-  if (action.method === "git.push" && deps.prompts && deps.subscribers) {
+  const isAgentboxBranch = branch.startsWith("agentbox/");
+  const tokenClaimedGit = typeof params.hostInitiated === "string";
+  const incomingHashGit = hashRpcParams(params);
+  const hostInitiatedOk = !isAgentboxBranch && tokenClaimedGit && (deps.hostInitiatedTokens?.consume(
+    params.hostInitiated,
+    deps.boxId,
+    "git.push",
+    incomingHashGit
+  ) ?? false);
+  if (action.method === "git.push" && !isAgentboxBranch && tokenClaimedGit && !hostInitiatedOk) {
+    return {
+      exitCode: 10,
+      stdout: "",
+      stderr: "host-initiated token rejected: invalid, expired, or bound to different params\n"
+    };
+  }
+  if (action.method === "git.push" && !isAgentboxBranch && !hostInitiatedOk && deps.prompts && deps.subscribers) {
     const hasSubscriber = deps.subscribers.forBox(deps.boxId).length > 0;
     if (!hasSubscriber && process.env["AGENTBOX_PROMPT"] !== "off") {
       const noSubMode = (process.env["AGENTBOX_GIT_PUSH_NO_SUB"] ?? "deny").toLowerCase();
@@ -18421,10 +18856,45 @@ async function runGitRpc(action, deps) {
         for (const a2 of params.args) if (typeof a2 === "string") argv.push(a2);
       }
       const push = await execa("git", argv, { reject: false });
+      let pushStderr = push.stderr ?? "";
+      if ((push.exitCode ?? 1) === 0 && !branch.startsWith("agentbox/")) {
+        try {
+          const sha = await execa(
+            "git",
+            ["-C", lookup.workspacePath, "rev-parse", branch],
+            { reject: false }
+          );
+          const shaText = (sha.stdout ?? "").trim();
+          if (sha.exitCode === 0 && shaText.length > 0) {
+            const updateRef = await backend.exec(
+              handle,
+              `git -C ${shellQuote(containerPath)} update-ref refs/remotes/${remote2}/${branch} ${shellQuote(shaText)}`
+            );
+            if (updateRef.exitCode !== 0) {
+              pushStderr += `
+relay: post-push in-box update-ref refs/remotes/${remote2}/${branch} failed: ${updateRef.stderr || updateRef.stdout}`;
+            }
+            const setUpstream = await backend.exec(
+              handle,
+              `git -C ${shellQuote(containerPath)} branch --set-upstream-to=${remote2}/${branch} ${shellQuote(branch)}`
+            );
+            if (setUpstream.exitCode !== 0) {
+              pushStderr += `
+relay: post-push in-box --set-upstream-to=${remote2}/${branch} failed: ${setUpstream.stderr || setUpstream.stdout}`;
+            }
+          } else {
+            pushStderr += `
+relay: post-push rev-parse ${branch} failed on host; skipping in-box origin/upstream sync`;
+          }
+        } catch (err) {
+          pushStderr += `
+relay: post-push in-box origin/upstream sync threw: ${err instanceof Error ? err.message : String(err)}`;
+        }
+      }
       return {
         exitCode: push.exitCode ?? 1,
         stdout: push.stdout ?? "",
-        stderr: push.stderr ?? ""
+        stderr: pushStderr
       };
     }
     const remote = params.remote ?? "origin";
@@ -18471,7 +18941,7 @@ function shellQuote(arg) {
 }
 
 // src/host-action-queue.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var DEFAULT_HOST_ACTION_MAX_AGE_MS = 15 * 60 * 1e3;
 var HostActionQueue = class {
   map = /* @__PURE__ */ new Map();
@@ -18489,7 +18959,7 @@ var HostActionQueue = class {
    * is open" semantics).
    */
   enqueue(boxId, method, params) {
-    const id = (0, import_node_crypto2.randomUUID)();
+    const id = (0, import_node_crypto3.randomUUID)();
     const action = {
       id,
       boxId,
@@ -18555,7 +19025,7 @@ var HostActionQueue = class {
 };
 
 // src/notices.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var DEFAULT_NOTICE_TTL_MS = 66e4;
 var BoxNotices = class {
   constructor(subscribers) {
@@ -18578,7 +19048,7 @@ var BoxNotices = class {
         this.entries.delete(id);
       }
     }
-    const ev = { id: (0, import_node_crypto3.randomUUID)(), kind, message };
+    const ev = { id: (0, import_node_crypto4.randomUUID)(), kind, message };
     const ttl = typeof ttlMs === "number" && ttlMs > 0 ? ttlMs : DEFAULT_NOTICE_TTL_MS;
     const timer = setTimeout(() => {
       if (this.entries.delete(ev.id)) {
@@ -18796,6 +19266,8 @@ function createRelayServer(opts) {
   const prompts = new PendingPrompts();
   const subscribers = new PromptSubscribers();
   const notices = new BoxNotices(subscribers);
+  const hostInitiatedTokens = new HostInitiatedTokens();
+  let queuePoke = null;
   const host = opts.host ?? "0.0.0.0";
   const mode = opts.mode ?? "host";
   const hostActions = mode === "box" ? new HostActionQueue() : null;
@@ -18823,7 +19295,13 @@ function createRelayServer(opts) {
     const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "relay"}`);
     const route = `${req.method ?? "GET"} ${url.pathname}`;
     if (route === "GET /healthz") {
-      send(res, 200, { ok: true, boxes: registry.size(), events: events.size() });
+      send(res, 200, {
+        ok: true,
+        boxes: registry.size(),
+        events: events.size(),
+        pid: process.pid,
+        cliEntry: Boolean(process.env.AGENTBOX_CLI_ENTRY)
+      });
       return;
     }
     if (url.pathname.startsWith("/bridge/")) {
@@ -18928,21 +19406,36 @@ function createRelayServer(opts) {
       if (body.method === "git.push" || body.method === "git.fetch") {
         if (body.method === "git.push") {
           const params = body.params;
-          const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
-            kind: "confirm",
-            message: `Allow git push from box ${reg.name}?`,
-            detail: `${params?.remote ?? "origin"} ${(params?.args ?? []).join(" ")}`.trim(),
-            defaultAnswer: "n",
-            context: {
-              command: "git push",
-              cwd: params?.path,
-              argv: params?.args
-            }
-          });
-          if (verdict.answer !== "y") {
-            send(res, 500, { exitCode: 10, stdout: "", stderr: "denied by user\n" });
+          const worktree = resolveWorktree(reg, params?.path ?? "/workspace");
+          const isAgentboxBranch = worktree?.branch.startsWith("agentbox/") ?? false;
+          const tokenClaimed = typeof params?.hostInitiated === "string";
+          const incomingHash = hashRpcParams(params);
+          const hostInitiatedOk = !isAgentboxBranch && tokenClaimed && hostInitiatedTokens.consume(params?.hostInitiated, reg.boxId, "git.push", incomingHash);
+          if (!isAgentboxBranch && tokenClaimed && !hostInitiatedOk) {
+            send(res, 500, {
+              exitCode: 10,
+              stdout: "",
+              stderr: "host-initiated token rejected: invalid, expired, or bound to different params\n"
+            });
             return;
           }
+          if (!isAgentboxBranch && !hostInitiatedOk) {
+            const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
+              kind: "confirm",
+              message: `Allow git push from box ${reg.name}?`,
+              detail: `${params?.remote ?? "origin"} ${(params?.args ?? []).join(" ")}`.trim(),
+              defaultAnswer: "n",
+              context: {
+                command: "git push",
+                cwd: params?.path,
+                argv: params?.args
+              }
+            });
+            if (verdict.answer !== "y") {
+              send(res, 500, { exitCode: 10, stdout: "", stderr: "denied by user\n" });
+              return;
+            }
+          }
         }
         const result = await handleGitRpc(reg, body.method, body.params);
         const status = result.exitCode === 0 ? 200 : 500;
@@ -18975,6 +19468,33 @@ function createRelayServer(opts) {
         send(res, status, result);
         return;
       }
+      if (body.method.startsWith("gh.pr.")) {
+        const op = body.method.slice("gh.pr.".length);
+        if (!isGhPrOp(op)) {
+          send(res, 400, { error: `unknown gh.pr.* op: ${op}` });
+          return;
+        }
+        const result = await handleGhPrRpc(
+          op,
+          reg,
+          body.params,
+          prompts,
+          subscribers,
+          hostInitiatedTokens
+        );
+        const status = result.exitCode === 0 ? 200 : 500;
+        send(res, status, result);
+        return;
+      }
+      if (body.method === "git.clone" || body.method === "gh.repo.clone") {
+        send(res, 501, {
+          exitCode: 64,
+          stdout: "",
+          stderr: `${body.method}: not yet implemented (deferred; see docs/plans/gh-and-git-shims-host-only.md). Run \`gh\` / \`git\` on the host directly for now.
+`
+        });
+        return;
+      }
       if (body.method === "download.workspace" || body.method === "download.env" || body.method === "download.config" || body.method === "download.claude") {
         const params = body.params;
         const kind = body.method.split(".")[1] ?? "workspace";
@@ -19111,6 +19631,7 @@ function createRelayServer(opts) {
                   boxName: reg.name,
                   prompts,
                   subscribers,
+                  hostInitiatedTokens,
                   log
                 });
                 await respond(result);
@@ -19123,6 +19644,11 @@ function createRelayServer(opts) {
                 });
               }
             } : void 0,
+            // Self-heal a dead preview transport (hetzner SSH `-L` after a
+            // ControlMaster death). The relay strips the `cloud:` prefix
+            // the cloud-provider tags onto BoxRecord.container — what the
+            // backend's `get(sandboxId)` expects is the bare sandbox id.
+            recoverPreviewUrl: reg.backend ? async () => refreshCloudPreviewUrl(reg.backend, reg.boxId, DEFAULT_BOX_RELAY_PORT) : void 0,
             logger: log
           });
         } catch (err) {
@@ -19237,6 +19763,27 @@ data: {"ts":"${(/* @__PURE__ */ new Date()).toISOString()}"}
       send(res, 204, null);
       return;
     }
+    if (route === "POST /admin/host-initiated/mint") {
+      const body = await readJsonBody(req);
+      if (!body || typeof body.boxId !== "string" || body.boxId.length === 0 || typeof body.method !== "string" || body.method.length === 0) {
+        send(res, 400, { error: "expected {boxId, method, paramsHash, ttlMs?}" });
+        return;
+      }
+      let paramsHash;
+      if (body.paramsHash === null || body.paramsHash === void 0) {
+        paramsHash = null;
+      } else if (typeof body.paramsHash === "string" && /^[0-9a-f]{64}$/.test(body.paramsHash)) {
+        paramsHash = body.paramsHash;
+      } else {
+        send(res, 400, { error: "paramsHash must be a 64-hex sha256 string or null" });
+        return;
+      }
+      const ttlMs = typeof body.ttlMs === "number" && Number.isFinite(body.ttlMs) && body.ttlMs > 0 ? body.ttlMs : void 0;
+      const token = hostInitiatedTokens.mint(body.boxId, body.method, paramsHash, ttlMs);
+      log(`host-initiated-mint box=${body.boxId} method=${body.method} paramsBound=${paramsHash !== null}`);
+      send(res, 200, { token });
+      return;
+    }
     if (route === "POST /admin/notices/set") {
       const body = await readJsonBody(req);
       if (!body || typeof body.boxId !== "string" || body.boxId.length === 0 || typeof body.kind !== "string" || body.kind.length === 0 || typeof body.message !== "string" || body.message.length === 0) {
@@ -19249,6 +19796,17 @@ data: {"ts":"${(/* @__PURE__ */ new Date()).toISOString()}"}
       send(res, 200, { id });
       return;
     }
+    if (route === "POST /admin/queue/enqueue") {
+      const body = await readJsonBody(req);
+      if (!body || typeof body.id !== "string" || body.id.length === 0) {
+        send(res, 400, { error: "expected {id}" });
+        return;
+      }
+      log(`queue-enqueue id=${body.id}`);
+      queuePoke?.();
+      send(res, 204, null);
+      return;
+    }
     if (route === "POST /admin/notices/clear") {
       const body = await readJsonBody(req);
       if (!body || typeof body.id !== "string" || body.id.length === 0) {
@@ -19285,6 +19843,9 @@ data: {"ts":"${(/* @__PURE__ */ new Date()).toISOString()}"}
     notices,
     hostActions: hostActions ?? void 0,
     url: `http://${host}:${String(opts.port)}`,
+    setQueuePoke: (fn) => {
+      queuePoke = fn;
+    },
     close: async () => {
       if (pollers) await pollers.stopAll();
       await new Promise((resolve2, reject) => {
@@ -19336,7 +19897,71 @@ async function handleGitRpc(reg, method, params) {
       if (typeof a2 === "string") argv.push(a2);
     }
   }
-  return runHostCommand(argv);
+  const result = await runHostCommand(argv);
+  if (method === "git.push" && result.exitCode === 0 && !worktree.branch.startsWith("agentbox/")) {
+    await runHostCommand([
+      "git",
+      "-C",
+      worktree.hostMainRepo,
+      "branch",
+      `--set-upstream-to=${remote}/${worktree.branch}`,
+      worktree.branch
+    ]);
+  }
+  return result;
+}
+async function handleGhPrRpc(op, reg, params, prompts, subscribers, hostInitiatedTokens) {
+  const mergeBypass = refuseMergeBypass(op);
+  if (mergeBypass) return mergeBypass;
+  const checkoutOptIn = refuseCheckoutByDefault(op);
+  if (checkoutOptIn) return checkoutOptIn;
+  const containerPath = params?.path ?? "/workspace";
+  const worktree = resolveWorktree(reg, containerPath);
+  if (!worktree) {
+    return {
+      exitCode: 64,
+      stdout: "",
+      stderr: `no worktree registered for box ${reg.boxId} matching ${containerPath}`
+    };
+  }
+  const ghReady = await assertGhReady();
+  if (ghReady) return ghReady;
+  const args = Array.isArray(params?.args) ? params.args.filter((a2) => typeof a2 === "string") : [];
+  if (op === "checkout") {
+    const branches = (reg.worktrees ?? []).map((w) => w.branch);
+    const guard = await checkoutGuards(worktree.hostMainRepo, branches);
+    if (guard) return guard;
+  }
+  const tokenClaimedGh = typeof params?.hostInitiated === "string";
+  const incomingHashGh = hashRpcParams(params);
+  const hostInitiatedOk = !GH_PR_READ_ONLY_OPS.has(op) && tokenClaimedGh && hostInitiatedTokens.consume(params?.hostInitiated, reg.boxId, `gh.pr.${op}`, incomingHashGh);
+  if (!GH_PR_READ_ONLY_OPS.has(op) && tokenClaimedGh && !hostInitiatedOk) {
+    return {
+      exitCode: 10,
+      stdout: "",
+      stderr: "host-initiated token rejected: invalid, expired, or bound to different params\n"
+    };
+  }
+  if (!GH_PR_READ_ONLY_OPS.has(op) && !hostInitiatedOk) {
+    const detail = args.join(" ").slice(0, 200);
+    const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
+      kind: "confirm",
+      message: `Allow gh pr ${op} from box ${reg.name}?`,
+      detail,
+      defaultAnswer: "n",
+      context: {
+        command: `gh pr ${op}`,
+        cwd: containerPath,
+        argv: args
+      }
+    });
+    if (verdict.answer !== "y") {
+      return { exitCode: 10, stdout: "", stderr: "denied by user\n" };
+    }
+  }
+  const finalArgs = injectPrCreateHead(op, worktree.branch, args);
+  if (prCreateNeedsHead(op, finalArgs)) return PR_CREATE_NO_HEAD_REFUSAL;
+  return runHostGh(["pr", op, ...finalArgs], worktree.hostMainRepo);
 }
 async function handleCpRpc(reg, method, params) {
   const entry = process.env.AGENTBOX_CLI_ENTRY;
@@ -19397,7 +20022,7 @@ function runHostCommand(argv, timeoutMs = GIT_RPC_TIMEOUT_MS) {
       resolve2({ exitCode: 64, stdout: "", stderr: "empty command" });
       return;
     }
-    const child = (0, import_node_child_process6.spawn)(cmd, rest, {
+    const child = (0, import_node_child_process7.spawn)(cmd, rest, {
       env: process.env,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -19446,7 +20071,7 @@ async function startRelayServer(opts) {
 }
 
 // src/autopause.ts
-var import_node_child_process7 = require("child_process");
+var import_node_child_process8 = require("child_process");
 var import_promises16 = require("fs/promises");
 
 // ../config/dist/index.js
@@ -19464,6 +20089,7 @@ var BUILT_IN_DEFAULTS = {
     defaultCheckpointDocker: "",
     defaultCheckpointDaytona: "",
     defaultCheckpointHetzner: "",
+    defaultCheckpointVercel: "",
     withPlaywright: false,
     withEnv: false,
     vnc: true,
@@ -19475,7 +20101,11 @@ var BUILT_IN_DEFAULTS = {
     memory: 0,
     cpus: 0,
     pidsLimit: 0,
-    disk: ""
+    disk: "",
+    bundleDepth: void 0,
+    vercelVcpus: 2,
+    vercelTimeoutMs: 27e5,
+    vercelNetworkPolicy: ""
   },
   checkpoint: {
     maxLayers: 3
@@ -19524,6 +20154,15 @@ var BUILT_IN_DEFAULTS = {
     maxRunningBoxes: 5,
     idleMinutes: 5
   },
+  queue: {
+    enabled: true,
+    maxConcurrent: 5,
+    maxWorking: 0,
+    idleGraceSeconds: 15
+  },
+  cloud: {
+    useCurrentBranch: false
+  },
   maintenance: {
     pruneProjectConfigs: true,
     pruneProjectConfigsEvery: 50
@@ -19533,8 +20172,8 @@ var KEY_REGISTRY = [
   {
     key: "box.provider",
     type: "enum",
-    enumValues: ["docker", "daytona", "hetzner"],
-    description: "Sandbox backend new boxes are created on: local Docker containers, Daytona Cloud sandboxes, or Hetzner Cloud VPSes."
+    enumValues: ["docker", "daytona", "hetzner", "vercel"],
+    description: "Sandbox backend new boxes are created on: local Docker containers, Daytona Cloud sandboxes, Hetzner Cloud VPSes, or Vercel Sandboxes."
   },
   {
     key: "box.hostSnapshot",
@@ -19564,6 +20203,12 @@ var KEY_REGISTRY = [
     description: "Per-provider override of `box.defaultCheckpoint` for hetzner. Wins over the global when set; set via `agentbox checkpoint set-default --provider hetzner`.",
     advanced: true
   },
+  {
+    key: "box.defaultCheckpointVercel",
+    type: "string",
+    description: "Per-provider override of `box.defaultCheckpoint` for vercel. Wins over the global when set; set via `agentbox checkpoint set-default --provider vercel`.",
+    advanced: true
+  },
   {
     key: "checkpoint.maxLayers",
     type: "int",
@@ -19632,6 +20277,26 @@ var KEY_REGISTRY = [
     description: "Best-effort writable-layer size for new boxes, e.g. '10G'. No-op on overlay2 / the macOS engines.",
     advanced: true
   },
+  {
+    key: "box.bundleDepth",
+    type: "int",
+    description: "Cap git bundle history shipped to cloud sandboxes (daytona, hetzner). 0 = full history. Unset = adaptive default (last 200 commits; re-bundle at 100 if the bundle exceeds 20 MB). Ignored for docker (which bind-mounts .git/)."
+  },
+  {
+    key: "box.vercelVcpus",
+    type: "int",
+    description: "vCPUs for new --provider vercel boxes (Vercel couples RAM at 2048 MB/vCPU). Default 2. Vercel only accepts specific counts (e.g. 1, 2, 4, 8) \u2014 an unsupported value fails create with a 400. Vercel-only; ignored by other providers."
+  },
+  {
+    key: "box.vercelTimeoutMs",
+    type: "int",
+    description: "Max session length (ms) for new --provider vercel boxes before the VM auto-snapshots; persistent mode auto-resumes on the next call. Default 2700000 (45 min, the Hobby ceiling). Vercel-only."
+  },
+  {
+    key: "box.vercelNetworkPolicy",
+    type: "string",
+    description: "Egress lock for new --provider vercel boxes: 'allow-all' (default, unset), 'deny-all', or a comma-separated domain allowlist (e.g. 'github.com,*.npmjs.org') that denies everything else. Vercel-only; ignored by other providers."
+  },
   {
     key: "claude.sessionName",
     type: "string",
@@ -19739,6 +20404,31 @@ var KEY_REGISTRY = [
     type: "int",
     description: "Minutes a box must be continuously idle (claude state) before it is eligible for auto-pause."
   },
+  {
+    key: "queue.enabled",
+    type: "bool",
+    description: "Run `agentbox claude|codex|opencode -i <prompt>` jobs through the host-wide background queue (FIFO, capped by queue.maxConcurrent)."
+  },
+  {
+    key: "queue.maxConcurrent",
+    type: "int",
+    description: "Max number of simultaneously-running boxes (across providers) before background `-i` jobs queue up instead of starting immediately. Per-invocation override: `--max-running <n>`."
+  },
+  {
+    key: "queue.maxWorking",
+    type: "int",
+    description: "Max agents actively working/thinking (quota-consuming) at once before background `-i` jobs queue. 0 = disabled (use the queue.maxConcurrent running-box gate). Counts all boxes, foreground + queued. Per-invocation override: `--max-working <n>`."
+  },
+  {
+    key: "queue.idleGraceSeconds",
+    type: "int",
+    description: "Seconds an agent must stay non-working before it frees its working slot (debounce against brief idle flaps between turns). Only used when queue.maxWorking > 0."
+  },
+  {
+    key: "cloud.useCurrentBranch",
+    type: "bool",
+    description: "On cloud providers (daytona/hetzner), start new boxes on the host's current branch instead of forking a new agentbox/<box-name> branch. Overridden by an explicit --use-branch / --from-branch."
+  },
   {
     key: "maintenance.pruneProjectConfigs",
     type: "bool",
@@ -19833,6 +20523,15 @@ function parseUserConfigObject(doc, where) {
   }
   const out = {};
   for (const [branchName, branchRaw] of Object.entries(doc)) {
+    if (branchName === "schema") {
+      if (branchRaw !== void 0 && branchRaw !== null) {
+        if (typeof branchRaw !== "number" || !Number.isInteger(branchRaw)) {
+          throw new UserConfigError(`${where}.schema: must be an integer (got ${String(branchRaw)})`);
+        }
+        out.schema = branchRaw;
+      }
+      continue;
+    }
     const branchSpec = BRANCHES.get(branchName);
     if (!branchSpec) {
       throw new UserConfigError(
@@ -20005,7 +20704,7 @@ var INSPECT_TIMEOUT_MS = 15e3;
 var PAUSE_TIMEOUT_MS = 3e4;
 function runDocker(args, timeoutMs) {
   return new Promise((resolve2) => {
-    const child = (0, import_node_child_process7.spawn)("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = (0, import_node_child_process8.spawn)("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     let settled = false;
@@ -20063,6 +20762,381 @@ async function pauseContainer(name) {
   }
 }
 
+// src/queue.ts
+var import_node_child_process9 = require("child_process");
+var import_promises17 = require("fs/promises");
+var import_node_fs6 = require("fs");
+var import_node_path8 = require("path");
+var import_promises18 = require("timers/promises");
+var QUEUE_DIR = (0, import_node_path8.join)(STATE_DIR, "queue");
+async function loadQueueConfig() {
+  const d = BUILT_IN_DEFAULTS.queue;
+  let global3 = {};
+  try {
+    global3 = parseUserConfig(await (0, import_promises17.readFile)(GLOBAL_CONFIG_FILE, "utf8"), GLOBAL_CONFIG_FILE);
+  } catch {
+  }
+  const q = global3.queue ?? {};
+  return {
+    enabled: q.enabled ?? d.enabled,
+    maxConcurrent: q.maxConcurrent ?? d.maxConcurrent,
+    maxWorking: q.maxWorking ?? d.maxWorking,
+    idleGraceMs: (q.idleGraceSeconds ?? d.idleGraceSeconds) * 1e3
+  };
+}
+async function writeJob(job) {
+  await (0, import_promises17.mkdir)(QUEUE_DIR, { recursive: true });
+  const final = (0, import_node_path8.join)(QUEUE_DIR, `${job.id}.json`);
+  const tmp = `${final}.tmp.${String(process.pid)}.${String(Date.now())}`;
+  await (0, import_promises17.writeFile)(tmp, JSON.stringify(job, null, 2) + "\n", "utf8");
+  await (0, import_promises17.rename)(tmp, final);
+}
+async function readJob(id) {
+  try {
+    const raw = await (0, import_promises17.readFile)((0, import_node_path8.join)(QUEUE_DIR, `${id}.json`), "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function loadQueue() {
+  let entries;
+  try {
+    entries = await (0, import_promises17.readdir)(QUEUE_DIR);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  const out = [];
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const raw = await (0, import_promises17.readFile)((0, import_node_path8.join)(QUEUE_DIR, name), "utf8");
+      out.push(JSON.parse(raw));
+    } catch {
+    }
+  }
+  out.sort((a2, b) => a2.createdAt < b.createdAt ? -1 : a2.createdAt > b.createdAt ? 1 : 0);
+  return out;
+}
+function selectNextRunnable(jobs, runningCount) {
+  for (const j of jobs) {
+    if (j.status !== "queued") continue;
+    if (runningCount < j.maxConcurrent) return j;
+  }
+  return null;
+}
+var WORKING_AGENT_STATES = [
+  "working",
+  "idle",
+  "waiting",
+  "end-plan",
+  "question",
+  "compacting",
+  "error",
+  "unknown"
+];
+function isWorkingAgentState(v) {
+  return typeof v === "string" && WORKING_AGENT_STATES.includes(v);
+}
+var STARTUP_GRACE_MS = 9e4;
+function occupiesWorkingSlot(e, idleGraceMs) {
+  if (e.agentState === "working" || e.agentState === "compacting") return true;
+  if ((e.agentState === null || e.agentState === "unknown") && e.sinceCreateMs !== null && e.sinceCreateMs < STARTUP_GRACE_MS) {
+    return true;
+  }
+  if ((e.agentState === "idle" || e.agentState === "waiting" || e.agentState === "end-plan" || e.agentState === "question") && e.sinceUpdateMs !== null && e.sinceUpdateMs < idleGraceMs) {
+    return true;
+  }
+  return false;
+}
+function countWorkingSlots(entries, idleGraceMs) {
+  return entries.reduce((n2, e) => occupiesWorkingSlot(e, idleGraceMs) ? n2 + 1 : n2, 0);
+}
+function selectNextRunnableByWorking(jobs, workingCount, globalMaxWorking) {
+  for (const j of jobs) {
+    if (j.status !== "queued") continue;
+    const ceil = typeof j.maxWorking === "number" && j.maxWorking > 0 ? j.maxWorking : globalMaxWorking;
+    if (workingCount < ceil) return j;
+  }
+  return null;
+}
+function readActiveAgent(snap) {
+  if (!snap || typeof snap !== "object") return { state: null, updatedAt: null };
+  const candidates = [];
+  for (const key of ["claude", "codex", "opencode"]) {
+    const sub = snap[key];
+    if (!sub || typeof sub !== "object") continue;
+    const o2 = sub;
+    if (!isWorkingAgentState(o2.state)) continue;
+    candidates.push({
+      state: o2.state,
+      updatedAt: typeof o2.updatedAt === "string" ? o2.updatedAt : null
+    });
+  }
+  if (candidates.length === 0) return { state: null, updatedAt: null };
+  const active = candidates.find((c3) => c3.state === "working" || c3.state === "compacting");
+  if (active) return active;
+  candidates.sort((a2, b) => parseTime(b.updatedAt) - parseTime(a2.updatedAt));
+  return candidates[0];
+}
+function parseTime(iso) {
+  if (!iso) return 0;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? 0 : t;
+}
+function msSince2(iso) {
+  if (!iso) return null;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? null : Date.now() - t;
+}
+var DEFAULT_INTERVAL_MS2 = 2e3;
+function startQueueLoop(deps) {
+  const loadConfig = deps.loadConfig ?? loadQueueConfig;
+  const countRunning = deps.countRunning ?? defaultCountRunningBoxes;
+  const spawnWorker = deps.spawnWorker ?? defaultSpawnWorker;
+  const intervalMs = deps.intervalMs ?? DEFAULT_INTERVAL_MS2;
+  const { log, onStatusChange } = deps;
+  const countWorking = deps.countWorking ?? (deps.registry && deps.statusStore ? (idleGraceMs) => defaultCountWorkingBoxes(deps.registry, deps.statusStore, idleGraceMs) : null);
+  let ticking = false;
+  let stopped = false;
+  let warnedNoWorkingDeps = false;
+  let inFlight = recoverOrphanedWorkers(log, onStatusChange).catch((err) => {
+    log(`queue: orphan recovery failed: ${err instanceof Error ? err.message : String(err)}`);
+  });
+  async function tick() {
+    if (ticking) return;
+    ticking = true;
+    try {
+      const cfg = await loadConfig();
+      if (!cfg.enabled) return;
+      const jobs = await loadQueue();
+      const hasQueued = jobs.some((j) => j.status === "queued");
+      if (!hasQueued) return;
+      let gateByWorking = cfg.maxWorking > 0;
+      if (gateByWorking && !countWorking) {
+        gateByWorking = false;
+        if (!warnedNoWorkingDeps) {
+          warnedNoWorkingDeps = true;
+          log("queue: maxWorking set but registry/statusStore not wired; using running-box gate");
+        }
+      }
+      while (!stopped) {
+        let occupancy;
+        let next;
+        if (gateByWorking && countWorking) {
+          occupancy = await countWorking(cfg.idleGraceMs);
+          const fresh = await loadQueue();
+          next = selectNextRunnableByWorking(fresh, occupancy, cfg.maxWorking);
+        } else {
+          occupancy = await countRunning();
+          const fresh = await loadQueue();
+          next = selectNextRunnable(fresh, occupancy);
+        }
+        if (!next) return;
+        const current = await readJob(next.id);
+        if (!current || current.status !== "queued") continue;
+        const updated = {
+          ...current,
+          status: "running",
+          startedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await writeJob(updated);
+        onStatusChange?.(updated);
+        try {
+          const pid = await spawnWorker(updated);
+          if (typeof pid === "number") {
+            const withPid = { ...updated, pid };
+            await writeJob(withPid);
+            onStatusChange?.(withPid);
+            const ceil = gateByWorking ? typeof updated.maxWorking === "number" && updated.maxWorking > 0 ? updated.maxWorking : cfg.maxWorking : updated.maxConcurrent;
+            log(
+              `queue: started job ${updated.id} (${updated.agent}) as pid ${String(pid)}; ${gateByWorking ? "working" : "running"} ${String(occupancy + 1)}/${String(ceil)}`
+            );
+          } else {
+            log(`queue: started job ${updated.id} (${updated.agent}); pid unknown`);
+          }
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          const failed = {
+            ...updated,
+            status: "failed",
+            finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            reason: `worker-spawn-failed: ${msg}`
+          };
+          await writeJob(failed);
+          onStatusChange?.(failed);
+          log(`queue: spawn for job ${updated.id} failed: ${msg}`);
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log(`queue: tick error: ${msg}`);
+    } finally {
+      ticking = false;
+    }
+  }
+  function poke() {
+    if (stopped) return;
+    inFlight = tick();
+  }
+  const handle = {
+    poke,
+    stop: async () => {
+      stopped = true;
+      clearInterval(timer);
+      await inFlight.catch(() => {
+      });
+    }
+  };
+  const timer = setInterval(() => {
+    if (stopped) return;
+    inFlight = tick();
+  }, intervalMs);
+  timer.unref();
+  return handle;
+}
+async function recoverOrphanedWorkers(log, onChange) {
+  const jobs = await loadQueue();
+  for (const j of jobs) {
+    if (j.status !== "running") continue;
+    if (typeof j.pid === "number" && processAlive(j.pid)) continue;
+    const failed = {
+      ...j,
+      status: "failed",
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      reason: "worker-died"
+    };
+    await writeJob(failed);
+    onChange?.(failed);
+    log(`queue: recovered orphan job ${j.id} (pid ${String(j.pid ?? "?")} not alive) -> failed`);
+  }
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function defaultCountWorkingBoxes(registry, statusStore, idleGraceMs) {
+  const boxes = registry.list();
+  const registeredIds = new Set(boxes.map((b) => b.boxId));
+  const entries = boxes.map((b) => {
+    const active = readActiveAgent(statusStore.get(b.boxId));
+    return {
+      key: b.boxId,
+      agentState: active.state,
+      sinceUpdateMs: msSince2(active.updatedAt),
+      sinceCreateMs: msSince2(b.createdAt)
+    };
+  });
+  let count2 = countWorkingSlots(entries, idleGraceMs);
+  let jobs;
+  try {
+    jobs = await loadQueue();
+  } catch {
+    return count2;
+  }
+  for (const j of jobs) {
+    if (j.status !== "running") continue;
+    if (j.boxId && registeredIds.has(j.boxId)) continue;
+    if (typeof j.pid === "number" && !processAlive(j.pid)) continue;
+    count2 += 1;
+  }
+  return count2;
+}
+var RUNNING_COUNT_CACHE_MS = 3e3;
+var runningCountCache = null;
+async function defaultCountRunningBoxes() {
+  const now = Date.now();
+  if (runningCountCache && runningCountCache.expiresAt > now) {
+    return runningCountCache.value;
+  }
+  const value = await uncachedCountRunningBoxes();
+  runningCountCache = { value, expiresAt: now + RUNNING_COUNT_CACHE_MS };
+  return value;
+}
+async function uncachedCountRunningBoxes() {
+  let boxes;
+  try {
+    boxes = (await readState(STATE_FILE)).boxes;
+  } catch {
+    return 0;
+  }
+  if (boxes.length === 0) return 0;
+  let count2 = 0;
+  const dockerBoxes = [];
+  for (const b of boxes) {
+    const provider = b.provider ?? "docker";
+    if (provider === "docker") {
+      dockerBoxes.push(b);
+    } else {
+      count2 += 1;
+    }
+  }
+  if (dockerBoxes.length > 0) {
+    const states = await Promise.all(dockerBoxes.map((b) => inspectDockerState(b.container)));
+    for (const s of states) {
+      if (s === "running") count2 += 1;
+    }
+  }
+  return count2;
+}
+function inspectDockerState(containerName) {
+  return new Promise((resolveP) => {
+    const child = (0, import_node_child_process9.spawn)("docker", ["inspect", "--format", "{{.State.Status}}", containerName], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let out = "";
+    let settled = false;
+    const finish = (state) => {
+      if (settled) return;
+      settled = true;
+      resolveP(state);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish("other");
+    }, 1e4);
+    child.stdout?.on("data", (c3) => {
+      out += c3.toString("utf8");
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      finish("other");
+    });
+    child.on("close", () => {
+      clearTimeout(timer);
+      finish(out.trim() === "running" ? "running" : "other");
+    });
+  });
+}
+async function defaultSpawnWorker(job) {
+  const entry = process.env.AGENTBOX_CLI_ENTRY;
+  if (!entry || !(0, import_node_fs6.existsSync)(entry)) {
+    throw new Error(
+      `AGENTBOX_CLI_ENTRY not set or missing (${String(entry)}); cannot spawn queue worker`
+    );
+  }
+  await (0, import_promises17.mkdir)((0, import_node_path8.join)(STATE_DIR, "logs"), { recursive: true });
+  const fd = (0, import_node_fs6.openSync)(job.logPath, "a");
+  const child = (0, import_node_child_process9.spawn)(process.execPath, [entry, "_run-queued-job", job.id], {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+    env: process.env
+  });
+  child.unref();
+  try {
+    (0, import_node_fs6.closeSync)(fd);
+  } catch {
+  }
+  return typeof child.pid === "number" ? child.pid : null;
+}
+var QUEUE_LOGS_DIR = (0, import_node_path8.join)(STATE_DIR, "logs");
+
 // src/bin.ts
 var program2 = new Command();
 program2.name("agentbox-relay").description("Host-side HTTP relay for box\u2192host events and RPCs").version("0.0.0");
@@ -20088,10 +21162,19 @@ program2.command("serve").description("Run the HTTP relay in the foreground").op
     log: (line) => process.stdout.write(`agentbox-relay: ${line}
 `)
   });
+  const queue = startQueueLoop({
+    log: (line) => process.stdout.write(`agentbox-relay: ${line}
+`),
+    registry: handle.registry,
+    statusStore: handle.statusStore
+  });
+  handle.setQueuePoke(() => {
+    queue.poke?.();
+  });
   const shutdown = (signal) => {
     process.stdout.write(`agentbox-relay: ${signal} \u2014 shutting down
 `);
-    autopause.stop().finally(() => handle.close()).finally(() => process.exit(0));
+    Promise.allSettled([autopause.stop(), queue.stop()]).finally(() => handle.close()).finally(() => process.exit(0));
   };
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("SIGINT", () => shutdown("SIGINT"));