@madarco/agentbox 0.14.0 → 0.15.0

package/runtime/e2b/ctl.cjs

@@ -3801,7 +3801,7 @@ var require_cross_spawn = __commonJS({
     var cp = require("child_process");
     var parse = require_parse();
     var enoent = require_enoent();
-    function spawn10(command, args, options) {
+    function spawn11(command, args, options) {
       const parsed = parse(command, args, options);
       const spawned = cp.spawn(parsed.command, parsed.args, parsed.options);
       enoent.hookChildProcess(spawned, parsed);
@@ -3813,8 +3813,8 @@ var require_cross_spawn = __commonJS({
       result.error = result.error || enoent.verifyENOENTSync(result.status, parsed);
       return result;
     }
-    module2.exports = spawn10;
-    module2.exports.spawn = spawn10;
+    module2.exports = spawn11;
+    module2.exports.spawn = spawn11;
     module2.exports.sync = spawnSync2;
     module2.exports._parse = parse;
     module2.exports._enoent = enoent;
@@ -11566,20 +11566,28 @@ async function postRpcAndExit(method, params, opts = {}) {
 }
 
 // src/commands/cp.ts
+function collectExclude(val, acc) {
+  acc.push(val);
+  return acc;
+}
+function buildCpParams(boxPath, hostPath, opts) {
+  const params = { boxPath, hostPath };
+  if (opts.recursive === false) params.recursive = false;
+  if (opts.exclude.length > 0) params.exclude = opts.exclude;
+  if (opts.defaultExcludes === false) params.defaultExcludes = false;
+  if (opts.yes) params.yes = true;
+  return params;
+}
 var cpCommand = new Command("cp").description("Copy a file/dir between this box and the host (gated by user prompt on the host wrapper)").addCommand(
-  new Command("toHost").description("Copy box:<boxPath> -> host:<hostPath>").argument("<boxPath>", "source path inside the container").argument("<hostPath>", "destination path on the host").option("--no-recursive", "reserved; current implementation is always recursive (docker cp -a)").action(async (boxPath, hostPath, opts) => {
-    const params = { boxPath, hostPath };
-    if (opts.recursive === false) params.recursive = false;
-    const code = await postRpcAndExit("cp.toHost", params, {
+  new Command("toHost").description("Copy box:<boxPath> -> host:<hostPath>").argument("<boxPath>", "source path inside the container").argument("<hostPath>", "destination path on the host").option("--no-recursive", "reserved; current implementation is always recursive (docker cp -a)").option("--exclude <pattern>", "exclude paths matching <pattern> (repeatable)", collectExclude, []).option("--no-default-excludes", "keep heavy dirs the host drops by default (.git, node_modules, ...)").option("-y, --yes", "copy even if the source is over the host size limit").action(async (boxPath, hostPath, opts) => {
+    const code = await postRpcAndExit("cp.toHost", buildCpParams(boxPath, hostPath, opts), {
       errorPrefix: "agentbox-ctl cp"
     });
     process.exit(code);
   })
 ).addCommand(
-  new Command("fromHost").description("Copy host:<hostPath> -> box:<boxPath>").argument("<hostPath>", "source path on the host").argument("<boxPath>", "destination path inside the container").option("--no-recursive", "reserved; current implementation is always recursive (docker cp -a)").action(async (hostPath, boxPath, opts) => {
-    const params = { boxPath, hostPath };
-    if (opts.recursive === false) params.recursive = false;
-    const code = await postRpcAndExit("cp.fromHost", params, {
+  new Command("fromHost").description("Copy host:<hostPath> -> box:<boxPath>").argument("<hostPath>", "source path on the host").argument("<boxPath>", "destination path inside the container").option("--no-recursive", "reserved; current implementation is always recursive (docker cp -a)").option("--exclude <pattern>", "exclude paths matching <pattern> (repeatable)", collectExclude, []).option("--no-default-excludes", "keep heavy dirs the host drops by default (.git, node_modules, ...)").option("-y, --yes", "copy even if the source is over the host size limit").action(async (hostPath, boxPath, opts) => {
+    const code = await postRpcAndExit("cp.fromHost", buildCpParams(boxPath, hostPath, opts), {
       errorPrefix: "agentbox-ctl cp"
     });
     process.exit(code);
@@ -18468,6 +18476,115 @@ var import_path2 = require("path");
 var import_yaml2 = __toESM(require_dist(), 1);
 var import_path3 = require("path");
 var import_yaml3 = __toESM(require_dist(), 1);
+var BUILT_IN_DEFAULTS = {
+  box: {
+    provider: "docker",
+    hostSnapshot: void 0,
+    defaultCheckpoint: "",
+    defaultCheckpointDocker: "",
+    defaultCheckpointDaytona: "",
+    defaultCheckpointHetzner: "",
+    defaultCheckpointVercel: "",
+    defaultCheckpointE2b: "",
+    size: "",
+    sizeDocker: "",
+    sizeDaytona: "",
+    sizeHetzner: "",
+    sizeVercel: "",
+    sizeE2b: "",
+    withPlaywright: false,
+    withEnv: false,
+    resyncOnStart: true,
+    vnc: true,
+    autoApproveHostActions: false,
+    isolateClaudeConfig: false,
+    isolateCodexConfig: false,
+    isolateOpencodeConfig: false,
+    image: "agentbox/box:dev",
+    imageDocker: "",
+    imageDaytona: "",
+    imageHetzner: "",
+    imageVercel: "",
+    imageE2b: "",
+    // Mirrors BOX_IMAGE_REGISTRY in @agentbox/sandbox-docker. Empty disables the
+    // registry pull (always build the docker base image locally).
+    imageRegistry: "ghcr.io/madarco/agentbox/box",
+    dockerCacheShared: false,
+    memory: 0,
+    cpus: 0,
+    pidsLimit: 0,
+    disk: "",
+    bundleDepth: void 0,
+    vercelVcpus: 2,
+    vercelTimeoutMs: 27e5,
+    vercelNetworkPolicy: "",
+    cpMaxBytes: 100 * 1024 * 1024
+  },
+  checkpoint: {
+    maxLayers: 3
+  },
+  claude: {
+    sessionName: "claude",
+    dangerouslySkipPermissions: true
+  },
+  codex: {
+    sessionName: "codex",
+    dangerouslySkipPermissions: true
+  },
+  opencode: {
+    sessionName: "opencode"
+  },
+  attach: {
+    openIn: "split",
+    cmuxStatus: true
+  },
+  code: {
+    ide: "auto",
+    wait: true,
+    timeoutMs: 12e4,
+    autoTerminals: true
+  },
+  shell: {
+    user: "vscode",
+    login: true,
+    tmux: true
+  },
+  engine: {
+    kind: "auto"
+  },
+  browser: {
+    default: "agent-browser"
+  },
+  relay: {
+    port: 8787
+  },
+  vnc: {
+    containerPort: 6080
+  },
+  portless: {
+    enabled: void 0,
+    stateDir: ""
+  },
+  autopause: {
+    enabled: true,
+    maxRunningBoxes: 5,
+    idleMinutes: 5
+  },
+  queue: {
+    enabled: true,
+    maxConcurrent: 5,
+    maxWorking: 0,
+    idleGraceSeconds: 15,
+    openIn: "none"
+  },
+  cloud: {
+    useCurrentBranch: false
+  },
+  maintenance: {
+    pruneProjectConfigs: true,
+    pruneProjectConfigsEvery: 50
+  }
+};
 var KEY_REGISTRY = [
   {
     key: "box.provider",
@@ -18576,6 +18693,11 @@ var KEY_REGISTRY = [
     type: "bool",
     description: "Run the per-box Xvnc + noVNC stack."
   },
+  {
+    key: "box.autoApproveHostActions",
+    type: "bool",
+    description: "Auto-approve host-action confirmations (git push, cp host<->box, gh PR writes, checkpoint) for this box without an interactive prompt. Off by default; intended for unattended orchestration of trusted boxes. Each auto-approval is recorded as a relay event (visible in `agentbox agent` / the dashboard)."
+  },
   {
     key: "box.isolateClaudeConfig",
     type: "bool",
@@ -18674,6 +18796,12 @@ var KEY_REGISTRY = [
     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.cpMaxBytes",
+    type: "int",
+    description: "Max bytes a single host\u2192box copy may transfer after excludes, shared by `agentbox cp` (blocked with a size breakdown unless --yes) and each `carry:` entry (rejected at resolve time). Default 104857600 (100 MiB).",
+    advanced: true
+  },
   {
     key: "box.vercelNetworkPolicy",
     type: "string",
@@ -18821,6 +18949,12 @@ var KEY_REGISTRY = [
     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: "queue.openIn",
+    type: "enum",
+    enumValues: ["none", "split", "window", "tab"],
+    description: "When a background `-i` job finishes creating its box, where the host relay opens an attached terminal onto it: `none` (default \u2014 open nothing, just queue), `split`, `window`, or `tab`. Honored only when the submitting shell runs inside tmux, cmux, or iTerm2 (the targeting is captured at submit time). Under cmux, `split` splits the pane you submitted from (falling back to the parent workspace, then a new workspace), `tab` adds a tab in the parent workspace, and `window` opens a separate workspace; iTerm2 opens relative to the frontmost window. Unlike `attach.openIn` there is no `same` mode \u2014 the box is created asynchronously, so it is always a fresh terminal."
+  },
   {
     key: "cloud.useCurrentBranch",
     type: "bool",
@@ -19008,6 +19142,21 @@ var EventBuffer = class {
 };
 var PendingPrompts = class {
   entries = /* @__PURE__ */ new Map();
+  autoApprove = null;
+  /** Install the per-box auto-approve policy (relay server, once at startup). */
+  setAutoApprovePolicy(policy) {
+    this.autoApprove = policy;
+  }
+  /**
+   * True when this box opted into `box.autoApproveHostActions`. Records the
+   * bypass to the audit sink as a side effect so the caller short-circuits
+   * with a trail. Returns false when no policy is installed.
+   */
+  consumeAutoApprove(boxId, params) {
+    if (!this.autoApprove || !this.autoApprove.shouldAutoApprove(boxId)) return false;
+    this.autoApprove.audit(boxId, params);
+    return true;
+  }
   add(boxId, ev) {
     return new Promise((resolve2) => {
       this.entries.set(ev.id, {
@@ -19094,6 +19243,9 @@ async function askPrompt(prompts, subscribers, boxId, params, opts) {
   if (process.env.AGENTBOX_PROMPT === "off") {
     return { answer: "y" };
   }
+  if (prompts.consumeAutoApprove(boxId, params)) {
+    return { answer: "y" };
+  }
   const ev = { id: (0, import_crypto2.randomUUID)(), ...params };
   const promise = prompts.add(boxId, ev);
   subscribers.broadcast(boxId, "prompt-ask", ev);
@@ -20240,6 +20392,21 @@ function createRelayServer(opts) {
   const prompts = new PendingPrompts();
   const subscribers = new PromptSubscribers();
   const notices = new BoxNotices(subscribers);
+  prompts.setAutoApprovePolicy({
+    shouldAutoApprove: (boxId) => registry.get(boxId)?.autoApproveHostActions === true,
+    audit: (boxId, params) => {
+      events.append({
+        boxId,
+        type: "host-action-auto-approved",
+        payload: {
+          command: params.context?.command,
+          argv: params.context?.argv,
+          message: params.message
+        }
+      });
+      log(`auto-approved host action for ${boxId}: ${params.context?.command ?? params.message}`);
+    }
+  });
   const hostInitiatedTokens = new HostInitiatedTokens();
   let queuePoke = null;
   const host = opts.host ?? "0.0.0.0";
@@ -20427,11 +20594,22 @@ function createRelayServer(opts) {
           send(res, 400, { error: "cp.* requires {boxPath, hostPath} strings" });
           return;
         }
+        if (params.exclude !== void 0 && (!Array.isArray(params.exclude) || params.exclude.some((p) => typeof p !== "string"))) {
+          send(res, 400, { error: "cp.* exclude must be an array of strings" });
+          return;
+        }
         const direction = body.method === "cp.toHost" ? "box -> host" : "host -> box";
+        const pathDetail = body.method === "cp.toHost" ? `${params.boxPath} -> ${params.hostPath}` : `${params.hostPath} -> ${params.boxPath}`;
+        const detailParts = [pathDetail];
+        if (params.exclude && params.exclude.length > 0) {
+          detailParts.push(`exclude: ${params.exclude.join(", ")}`);
+        }
+        if (params.defaultExcludes === false) detailParts.push("(default excludes off)");
+        if (params.yes) detailParts.push("(over size limit \u2014 confirmed)");
         const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
           kind: "confirm",
           message: `Allow cp (${direction}) on ${reg.name}?`,
-          detail: body.method === "cp.toHost" ? `${params.boxPath} -> ${params.hostPath}` : `${params.hostPath} -> ${params.boxPath}`,
+          detail: detailParts.join("\n"),
           defaultAnswer: "n",
           context: {
             command: body.method,
@@ -20597,7 +20775,8 @@ function createRelayServer(opts) {
         worktrees,
         previewUrl: typeof body.previewUrl === "string" && body.previewUrl.length > 0 ? body.previewUrl : void 0,
         previewToken: typeof body.previewToken === "string" && body.previewToken.length > 0 ? body.previewToken : void 0,
-        bridgeToken: typeof body.bridgeToken === "string" && body.bridgeToken.length > 0 ? body.bridgeToken : void 0
+        bridgeToken: typeof body.bridgeToken === "string" && body.bridgeToken.length > 0 ? body.bridgeToken : void 0,
+        autoApproveHostActions: body.autoApproveHostActions === true
       };
       registry.register(reg);
       log(
@@ -20705,6 +20884,15 @@ function createRelayServer(opts) {
       send(res, 200, { boxes: redacted });
       return;
     }
+    if (route === "GET /admin/prompts") {
+      const boxId = url.searchParams.get("boxId") ?? "";
+      if (boxId.length === 0) {
+        send(res, 400, { error: "missing boxId query param" });
+        return;
+      }
+      send(res, 200, { prompts: prompts.forBox(boxId) });
+      return;
+    }
     if (route === "GET /admin/prompts/stream") {
       const boxId = url.searchParams.get("boxId") ?? "";
       if (boxId.length === 0) {
@@ -21022,7 +21210,11 @@ async function handleCpRpc(reg, method, params) {
     };
   }
   const boxRef = `${reg.name}:${params.boxPath}`;
-  const argv = method === "cp.toHost" ? [process.execPath, entry, "cp", boxRef, params.hostPath] : [process.execPath, entry, "cp", params.hostPath, boxRef];
+  const flags = [];
+  for (const pat of params.exclude ?? []) flags.push("--exclude", pat);
+  if (params.defaultExcludes === false) flags.push("--no-default-excludes");
+  if (params.yes) flags.push("--yes");
+  const argv = method === "cp.toHost" ? [process.execPath, entry, "cp", boxRef, params.hostPath, ...flags] : [process.execPath, entry, "cp", params.hostPath, boxRef, ...flags];
   return runHostCommand(argv, CP_RPC_TIMEOUT_MS);
 }
 async function handleDownloadRpc(reg, kind) {
@@ -21639,8 +21831,68 @@ function defaultCapturePane(sessionName) {
   });
 }
 
-// src/supervisor.ts
+// src/claude-scraper.ts
 var import_node_child_process8 = require("child_process");
+var DEFAULT_INTERVAL_MS2 = 1500;
+var DEFAULT_SESSION2 = "claude";
+var BOTTOM_LINES = 25;
+var WORKING_GUARD = /\besc to interrupt\b|ctrl-?c to (stop|interrupt)/i;
+var WAITING_PATTERNS = [
+  /❯\s*\d+\.\s/,
+  // the selector arrow on a numbered option — the Claude select menu
+  /Do you want to proceed\?/i,
+  /Would you like to proceed\?/i,
+  /\b\d+\.\s+Yes\b/,
+  // a "N. Yes" option line
+  /\b(wants to (use|run|access)|Allow .* to (use|run|access))/i
+  // MCP / tool trust dialog
+];
+function startClaudeScraper(opts) {
+  const sessionName = opts.sessionName ?? DEFAULT_SESSION2;
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS2;
+  const capture = opts.capturePane ?? defaultCapturePane2;
+  let stopped = false;
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const pane = await capture(sessionName);
+      if (pane === null) return;
+      if (matchWaiting(pane)) opts.reporter.markScreenWaiting();
+    } catch {
+    }
+  };
+  const timer = setInterval(() => void tick(), intervalMs);
+  timer.unref();
+  void tick();
+  return {
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+    }
+  };
+}
+function matchWaiting(pane) {
+  const region = pane.split("\n").slice(-BOTTOM_LINES).join("\n");
+  if (WORKING_GUARD.test(region)) return false;
+  return WAITING_PATTERNS.some((re) => re.test(region));
+}
+function defaultCapturePane2(sessionName) {
+  return new Promise((resolve2) => {
+    const child = (0, import_node_child_process8.spawn)("tmux", ["capture-pane", "-p", "-t", sessionName], {
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    let stdout = "";
+    child.stdout.on("data", (b) => stdout += b.toString("utf8"));
+    child.on("error", () => resolve2(null));
+    child.on("close", (code) => {
+      if (code === 0) resolve2(stdout);
+      else resolve2(null);
+    });
+  });
+}
+
+// src/supervisor.ts
+var import_node_child_process9 = require("child_process");
 var import_node_events15 = require("events");
 var import_node_fs7 = require("fs");
 var import_promises18 = require("fs/promises");
@@ -21906,7 +22158,7 @@ var cachedLoginPath;
 function loginShellPath() {
   if (cachedLoginPath !== void 0) return cachedLoginPath;
   try {
-    const out = (0, import_node_child_process8.execFileSync)("bash", ["-lc", 'printf %s "$PATH"'], {
+    const out = (0, import_node_child_process9.execFileSync)("bash", ["-lc", 'printf %s "$PATH"'], {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
@@ -21921,7 +22173,7 @@ var ServiceRunner = class extends import_node_events15.EventEmitter {
     super();
     this.spec = spec;
     this.opts = opts;
-    this.spawnFn = opts.spawn ?? import_node_child_process8.spawn;
+    this.spawnFn = opts.spawn ?? import_node_child_process9.spawn;
     this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
     this.clearTimer = opts.clearTimer ?? ((h2) => {
       clearTimeout(h2);
@@ -22152,7 +22404,7 @@ var TaskRunner = class extends import_node_events15.EventEmitter {
     super();
     this.spec = spec;
     this.opts = opts;
-    this.spawnFn = opts.spawn ?? import_node_child_process8.spawn;
+    this.spawnFn = opts.spawn ?? import_node_child_process9.spawn;
   }
   spec;
   opts;
@@ -22325,6 +22577,20 @@ var Supervisor = class extends import_node_events15.EventEmitter {
     }
     return out;
   }
+  /**
+   * Set of service names that declare a `ready_when` probe of any kind (port or
+   * log_match). A probed service is only "up" once it reaches `ready`; an
+   * unprobed one is up at `running`. The status reporter surfaces this so the
+   * host can tell a warming-up `running` service from a settled one.
+   */
+  probedServices() {
+    const out = /* @__PURE__ */ new Set();
+    for (const u2 of this.units.values()) {
+      if (u2.kind !== "service") continue;
+      if (u2.spec.readyWhen) out.add(u2.name);
+    }
+    return out;
+  }
   /**
    * Map of service name -> `expose:` mapping, for the (at most one) service
    * that declares it. The status reporter surfaces this so the host knows the
@@ -22701,10 +22967,10 @@ var import_promises19 = require("fs/promises");
 var import_node_path7 = require("path");
 
 // src/status-reporter.ts
-var import_node_child_process10 = require("child_process");
+var import_node_child_process11 = require("child_process");
 
 // src/tmux.ts
-var import_node_child_process9 = require("child_process");
+var import_node_child_process10 = require("child_process");
 var import_node_os4 = require("os");
 var MAX_TITLE_LEN = 120;
 function sanitizePaneTitle(raw, ctx) {
@@ -22718,7 +22984,7 @@ function sanitizePaneTitle(raw, ctx) {
 }
 function runTool(cmd, args) {
   return new Promise((resolve2) => {
-    const child = (0, import_node_child_process9.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = (0, import_node_child_process10.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (b) => stdout += b.toString("utf8"));
@@ -22815,6 +23081,23 @@ var StatusReporter = class {
     }
     this.schedulePush();
   }
+  /**
+   * Screen-scraper safety net: promote a *stuck* `working` to `waiting` when the
+   * Claude tmux pane shows a prompt the hooks missed (MCP tool dialogs have no
+   * hook; the `Notification:permission_prompt` hook can fire late or drop).
+   * Deliberately promote-ONLY — it acts solely when the current state is
+   * `working`, so it never clobbers the richer hook-driven `end-plan`/`question`
+   * (sticky) or `idle`/`compacting`/`error`. The next real hook
+   * (`UserPromptSubmit`/`PreToolUse`) overwrites `waiting`→`working` when the
+   * agent resumes, so no demote path is needed. Returns true if it promoted.
+   */
+  markScreenWaiting() {
+    if (this.claudeState !== "working") return false;
+    this.claudeState = "waiting";
+    this.claudeUpdatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.schedulePush();
+    return true;
+  }
   setCodexState(state) {
     this.codexState = state;
     this.codexUpdatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -22851,11 +23134,13 @@ var StatusReporter = class {
   }
   async snapshot() {
     const probePorts = this.supervisor.serviceProbePorts();
+    const probed = this.supervisor.probedServices();
     const exposes = this.supervisor.serviceExposes();
     const services = this.supervisor.list().map((s) => ({
       name: s.name,
       state: s.state,
       port: probePorts.get(s.name) ?? null,
+      ...probed.has(s.name) ? { probed: true } : {},
       ...exposes.has(s.name) ? { expose: exposes.get(s.name) } : {}
     }));
     const tasks = this.supervisor.listTasks().map((t) => ({ name: t.name, state: t.state }));
@@ -22911,7 +23196,7 @@ async function collectPorts(supervisor) {
 }
 function run(cmd, args) {
   return new Promise((resolve2) => {
-    const child = (0, import_node_child_process10.spawn)(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+    const child = (0, import_node_child_process11.spawn)(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
     let stdout = "";
     child.stdout.on("data", (b) => stdout += b.toString("utf8"));
     child.on("error", () => resolve2({ exitCode: 127, stdout }));
@@ -23248,6 +23533,14 @@ var daemonCommand = new Command("daemon").description("Run the agentbox-ctl supe
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`agentbox-ctl: codex scraper failed to start: ${msg}
+`);
+  }
+  let claudeScraper = null;
+  try {
+    claudeScraper = startClaudeScraper({ reporter });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`agentbox-ctl: claude scraper failed to start: ${msg}
 `);
   }
   const server = await startServer({
@@ -23325,6 +23618,7 @@ var daemonCommand = new Command("daemon").description("Run the agentbox-ctl supe
     process.stdout.write(`agentbox-ctl: ${signal} \u2014 shutting down
 `);
     if (codexScraper) codexScraper.stop();
+    if (claudeScraper) claudeScraper.stop();
     reporter.stop();
     reporter.flush();
     server.close();
@@ -23486,7 +23780,7 @@ var apiCommand = new Command("api").description(
 var ghCommand = new Command("gh").description("GitHub CLI operations routed through the relay (host `gh` runs with host creds; box never sees a token)").addCommand(buildPrCommand("agentbox-ctl gh pr")).addCommand(buildRunCommand("agentbox-ctl gh run")).addCommand(apiCommand).addCommand(repoCommand);
 
 // src/commands/git.ts
-var import_node_child_process11 = require("child_process");
+var import_node_child_process12 = require("child_process");
 function hostInitiatedOption() {
   return new Option(
     "--host-initiated-token <token>",
@@ -23502,7 +23796,7 @@ function buildParams(opts, extra) {
 }
 function runLocalGit(args, cwd) {
   return new Promise((resolve2) => {
-    const child = (0, import_node_child_process11.spawn)("git", args, { cwd, stdio: "inherit" });
+    const child = (0, import_node_child_process12.spawn)("git", args, { cwd, stdio: "inherit" });
     child.on("close", (code) => resolve2(code ?? 1));
     child.on("error", (err) => {
       process.stderr.write(`agentbox-ctl git: ${String(err.message ?? err)}
@@ -23513,7 +23807,7 @@ function runLocalGit(args, cwd) {
 }
 function hasGitIdentity(cwd) {
   return new Promise((resolve2) => {
-    const child = (0, import_node_child_process11.spawn)("git", ["config", "user.email"], {
+    const child = (0, import_node_child_process12.spawn)("git", ["config", "user.email"], {
       cwd,
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -23615,7 +23909,7 @@ var notifyCommand = new Command("notify").description(
 );
 
 // src/commands/open.ts
-var import_node_child_process12 = require("child_process");
+var import_node_child_process13 = require("child_process");
 var OPEN_TIMEOUT_MS = 3e4;
 function isHttpUrl(value) {
   try {
@@ -23627,7 +23921,7 @@ function isHttpUrl(value) {
 }
 function openInBoxBrowser(url) {
   return new Promise((resolve2) => {
-    const child = (0, import_node_child_process12.spawn)("agent-browser", ["open", "--headed", url], { stdio: "inherit" });
+    const child = (0, import_node_child_process13.spawn)("agent-browser", ["open", "--headed", url], { stdio: "inherit" });
     const timer = setTimeout(() => {
       child.kill("SIGTERM");
       process.stderr.write(

package/runtime/hetzner/agentbox-setup-skill.md

@@ -192,6 +192,36 @@ services:
       factor: 2
 ```
 
+## 6b. Bringing extra host files/folders into the box
+
+Two ways to copy host files in (both COPY — never a live mount, so the box can't
+write back to the host):
+
+- **`carry:` block** (declarative, in `agentbox.yaml`) — for files/dirs every box
+  should get at create time. Each entry is `{ src, dest }` with optional `mode`,
+  `user`, `optional`, and `exclude:` (a list of tar globs / bare dir names to drop
+  when copying a directory). Heavy regenerable dirs (`.git`, `node_modules`, `bin`,
+  `obj`, `packages`, `dist`, `.next`, `target`) are dropped by default; `exclude:`
+  is additive. Each carry entry is capped at `box.cpMaxBytes` (default 100 MiB
+  after excludes) — the same limit `agentbox cp` enforces.
+- **`agentbox-ctl cp fromHost <hostPath> <boxPath>`** (ad-hoc, from inside the box)
+  — for a one-off copy. Prompts the user on the host to approve.
+
+**The per-copy size limit (important for large/legacy folders).** A single copy is
+blocked above `box.cpMaxBytes` (default **100 MB**) *after* default excludes, so it
+fails loud instead of silently hanging. When blocked you get a `du`-style tree of
+the biggest remaining folders/subfolders. To get under the limit, EITHER:
+
+- **drop what the box can regenerate** (the default excludes already remove
+  `node_modules`/`.git`/build output; add more with `--exclude=<glob-or-name>`), OR
+- **copy the heavy folders one at a time** so each copy is under the limit, OR
+- pass `--yes` to copy the whole thing anyway (only when you really need it all).
+
+Example: a 2.4 GB legacy folder is mostly `packages/` (NuGet) + `.git`; those are
+excluded by default, and what's left can be split:
+`agentbox-ctl cp fromHost ../legacy/src /workspace/legacy/src` then
+`... cp fromHost ../legacy/Database /workspace/legacy/Database`.
+
 ## 7. Validate before handing off
 
 - check with `agentbox-ctl reload` and then `agentbox-ctl status` that everything is running as expected.