@madarco/agentbox 0.4.1 → 0.6.0

package/runtime/docker/packages/ctl/dist/bin.cjs

@@ -10371,8 +10371,27 @@ var {
 } = import_index.default;
 
 // src/client.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
 var import_node_net = require("net");
-async function connect(opts) {
+async function tryReviveDaemon(socketPath) {
+  if (process.env.AGENTBOX !== "1") return false;
+  try {
+    const child = (0, import_node_child_process.spawn)("agentbox-ctl", ["daemon"], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+  } catch {
+    return false;
+  }
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 100));
+    if ((0, import_node_fs.existsSync)(socketPath)) return true;
+  }
+  return false;
+}
+async function connectOnce(opts) {
   const sock = (0, import_node_net.createConnection)(opts.socketPath);
   await new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
@@ -10390,6 +10409,17 @@ async function connect(opts) {
   });
   return sock;
 }
+async function connect(opts) {
+  try {
+    return await connectOnce(opts);
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ECONNREFUSED" && code !== "ENOENT") throw err;
+    const revived = await tryReviveDaemon(opts.socketPath);
+    if (!revived) throw err;
+    return await connectOnce(opts);
+  }
+}
 async function sendOneShot(opts, req) {
   const sock = await connect(opts);
   sock.write(`${JSON.stringify(req)}
@@ -10545,6 +10575,108 @@ var claudeStateCommand = new Command("claude-state").description("Report Claude
   process.exit(0);
 });
 
+// src/relay-rpc.ts
+var import_node_http = require("http");
+var import_node_https = require("https");
+function postRpc(method, params, opts = {}) {
+  const prefix = opts.errorPrefix ?? "agentbox-ctl rpc";
+  const urlStr = process.env.AGENTBOX_RELAY_URL;
+  const token = process.env.AGENTBOX_RELAY_TOKEN;
+  if (!urlStr || !token) {
+    process.stderr.write(
+      `${prefix}: AGENTBOX_RELAY_URL / AGENTBOX_RELAY_TOKEN not set; no relay configured for this box.
+`
+    );
+    return Promise.resolve({ status: 0, parsed: null, raw: "", internalExitCode: 65 });
+  }
+  let url;
+  try {
+    url = new URL(urlStr);
+  } catch {
+    process.stderr.write(`${prefix}: invalid AGENTBOX_RELAY_URL: ${urlStr}
+`);
+    return Promise.resolve({ status: 0, parsed: null, raw: "", internalExitCode: 65 });
+  }
+  const body = JSON.stringify({ method, params });
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? import_node_https.request : import_node_http.request;
+  const port = url.port.length > 0 ? Number.parseInt(url.port, 10) : isHttps ? 443 : 80;
+  return new Promise((resolve) => {
+    const req = transport(
+      {
+        host: url.hostname,
+        port,
+        method: "POST",
+        path: `${url.pathname.replace(/\/$/, "")}/rpc`,
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body).toString(),
+          Authorization: `Bearer ${token}`
+        }
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          const status2 = res.statusCode ?? 0;
+          const text = Buffer.concat(chunks).toString("utf8");
+          let parsed = null;
+          try {
+            const v = JSON.parse(text);
+            if (v && typeof v === "object" && typeof v.exitCode === "number") {
+              parsed = v;
+            }
+          } catch {
+            parsed = null;
+          }
+          resolve({ status: status2, parsed, raw: text, internalExitCode: null });
+        });
+      }
+    );
+    req.on("error", (err) => {
+      process.stderr.write(`${prefix}: ${String(err.message ?? err)}
+`);
+      resolve({ status: 0, parsed: null, raw: "", internalExitCode: 126 });
+    });
+    req.write(body);
+    req.end();
+  });
+}
+async function postRpcAndExit(method, params, opts = {}) {
+  const prefix = opts.errorPrefix ?? "agentbox-ctl rpc";
+  const out = await postRpc(method, params, opts);
+  if (out.internalExitCode !== null) return out.internalExitCode;
+  if (out.parsed) {
+    if (out.parsed.stdout) process.stdout.write(out.parsed.stdout);
+    if (out.parsed.stderr) process.stderr.write(out.parsed.stderr);
+    return out.parsed.exitCode;
+  }
+  process.stderr.write(`${prefix}: relay returned ${String(out.status)}: ${out.raw}
+`);
+  return out.status >= 200 && out.status < 300 ? 0 : 1;
+}
+
+// src/commands/cp.ts
+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, {
+      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, {
+      errorPrefix: "agentbox-ctl cp"
+    });
+    process.exit(code);
+  })
+);
+
 // src/config.ts
 var import_promises = require("fs/promises");
 var import_yaml = __toESM(require_dist(), 1);
@@ -10975,9 +11107,9 @@ function describeCommand(cmd) {
 }
 
 // src/supervisor.ts
-var import_node_child_process = require("child_process");
+var import_node_child_process2 = require("child_process");
 var import_node_events = require("events");
-var import_node_fs = require("fs");
+var import_node_fs2 = require("fs");
 var import_promises3 = require("fs/promises");
 var import_node_path = require("path");
 
@@ -11088,8 +11220,8 @@ function startProbe(probe, ctx) {
 }
 
 // src/relay-client.ts
-var import_node_http = require("http");
-var import_node_https = require("https");
+var import_node_http2 = require("http");
+var import_node_https2 = require("https");
 var RelayClient = class {
   url;
   token;
@@ -11115,7 +11247,7 @@ var RelayClient = class {
     const url = this.url;
     const body = JSON.stringify({ type, ts: (/* @__PURE__ */ new Date()).toISOString(), payload });
     const isHttps = url.protocol === "https:";
-    const transport = isHttps ? import_node_https.request : import_node_http.request;
+    const transport = isHttps ? import_node_https2.request : import_node_http2.request;
     const port = url.port.length > 0 ? Number.parseInt(url.port, 10) : isHttps ? 443 : 80;
     const req = transport(
       {
@@ -11237,12 +11369,26 @@ function spawnArgs(cmd) {
   if (typeof cmd === "string") return { bin: "bash", args: ["-c", cmd] };
   return { bin: cmd[0], args: cmd.slice(1) };
 }
+var cachedLoginPath;
+function loginShellPath() {
+  if (cachedLoginPath !== void 0) return cachedLoginPath;
+  try {
+    const out = (0, import_node_child_process2.execFileSync)("bash", ["-lc", 'printf %s "$PATH"'], {
+      encoding: "utf8",
+      timeout: 5e3
+    }).trim();
+    cachedLoginPath = out || (process.env.PATH ?? "");
+  } catch {
+    cachedLoginPath = process.env.PATH ?? "";
+  }
+  return cachedLoginPath;
+}
 var ServiceRunner = class extends import_node_events.EventEmitter {
   constructor(spec, opts) {
     super();
     this.spec = spec;
     this.opts = opts;
-    this.spawnFn = opts.spawn ?? import_node_child_process.spawn;
+    this.spawnFn = opts.spawn ?? import_node_child_process2.spawn;
     this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
     this.clearTimer = opts.clearTimer ?? ((h) => {
       clearTimeout(h);
@@ -11339,7 +11485,7 @@ var ServiceRunner = class extends import_node_events.EventEmitter {
     const spec = this.spec;
     const cwd = resolveCwd(spec.cwd, this.opts.cwd);
     if (!this.logStream) {
-      this.logStream = (0, import_node_fs.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
+      this.logStream = (0, import_node_fs2.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
         flags: "a"
       });
       this.logStream.on("error", (err) => {
@@ -11351,7 +11497,7 @@ var ServiceRunner = class extends import_node_events.EventEmitter {
     try {
       child = this.spawnFn(bin, args, {
         cwd,
-        env: { ...process.env, ...spec.env ?? {} },
+        env: { ...process.env, PATH: loginShellPath(), ...spec.env ?? {} },
         stdio: ["ignore", "pipe", "pipe"]
       });
     } catch (err) {
@@ -11473,7 +11619,7 @@ var TaskRunner = class extends import_node_events.EventEmitter {
     super();
     this.spec = spec;
     this.opts = opts;
-    this.spawnFn = opts.spawn ?? import_node_child_process.spawn;
+    this.spawnFn = opts.spawn ?? import_node_child_process2.spawn;
   }
   spec;
   opts;
@@ -11537,7 +11683,7 @@ var TaskRunner = class extends import_node_events.EventEmitter {
     const spec = this.spec;
     const cwd = resolveCwd(spec.cwd, this.opts.cwd);
     if (!this.logStream) {
-      this.logStream = (0, import_node_fs.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
+      this.logStream = (0, import_node_fs2.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
         flags: "a"
       });
       this.logStream.on("error", (err) => {
@@ -11549,7 +11695,7 @@ var TaskRunner = class extends import_node_events.EventEmitter {
     try {
       child = this.spawnFn(bin, args, {
         cwd,
-        env: { ...process.env, ...spec.env ?? {} },
+        env: { ...process.env, PATH: loginShellPath(), ...spec.env ?? {} },
         stdio: ["ignore", "pipe", "pipe"]
       });
     } catch (err) {
@@ -11853,6 +11999,14 @@ var Supervisor = class extends import_node_events.EventEmitter {
         changed.push(spec.name);
       }
     }
+    for (const [name, unit] of this.units) {
+      if (unit.kind !== "task") continue;
+      const task = unit;
+      if (task.getState() === "skipped") {
+        this.failed.delete(name);
+        task.resetForRerun();
+      }
+    }
     this.applyWebProxy();
     this.schedule();
     return { added, removed, changed };
@@ -12013,10 +12167,10 @@ var import_promises4 = require("fs/promises");
 var import_node_path2 = require("path");
 
 // src/status-reporter.ts
-var import_node_child_process3 = require("child_process");
+var import_node_child_process4 = require("child_process");
 
 // src/tmux.ts
-var import_node_child_process2 = require("child_process");
+var import_node_child_process3 = require("child_process");
 var import_node_os = require("os");
 var MAX_TITLE_LEN = 120;
 function sanitizePaneTitle(raw, ctx) {
@@ -12030,7 +12184,7 @@ function sanitizePaneTitle(raw, ctx) {
 }
 function runTool(cmd, args) {
   return new Promise((resolve) => {
-    const child = (0, import_node_child_process2.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (b) => stdout += b.toString("utf8"));
@@ -12174,7 +12328,7 @@ async function collectPorts(supervisor) {
 }
 function run(cmd, args) {
   return new Promise((resolve) => {
-    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+    const child = (0, import_node_child_process4.spawn)(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
     let stdout = "";
     child.stdout.on("data", (b) => stdout += b.toString("utf8"));
     child.on("error", () => resolve({ exitCode: 127, stdout }));
@@ -12221,7 +12375,8 @@ async function startServer(opts) {
       resolve();
     });
   });
-  await (0, import_promises4.chmod)(opts.socketPath, 432);
+  await (0, import_promises4.chmod)(opts.socketPath, 432).catch(() => {
+  });
   return server;
 }
 async function handleConnection(sock, opts) {
@@ -12427,174 +12582,127 @@ var daemonCommand = new Command("daemon").description("Run the agentbox-ctl supe
   process.on("SIGINT", () => void shutdown("SIGINT"));
 });
 
-// src/commands/checkpoint.ts
-var import_node_http2 = require("http");
-var import_node_https2 = require("https");
-async function rpc(params) {
-  const urlStr = process.env.AGENTBOX_RELAY_URL;
-  const token = process.env.AGENTBOX_RELAY_TOKEN;
-  if (!urlStr || !token) {
+// src/commands/download.ts
+var KINDS = ["workspace", "env", "config", "claude"];
+function isKind(v) {
+  return KINDS.includes(v);
+}
+var downloadCommand = new Command("download").description(
+  "Download box contents to the host (gated by user prompt). Kinds: workspace (default), env, config, claude"
+).argument("[kind]", `one of: ${KINDS.join(", ")}`, "workspace").action(async (kindArg) => {
+  if (!isKind(kindArg)) {
     process.stderr.write(
-      "agentbox-ctl checkpoint: AGENTBOX_RELAY_URL / AGENTBOX_RELAY_TOKEN not set; no relay configured for this box.\n"
-    );
-    return 65;
-  }
-  let url;
-  try {
-    url = new URL(urlStr);
-  } catch {
-    process.stderr.write(`agentbox-ctl checkpoint: invalid AGENTBOX_RELAY_URL: ${urlStr}
-`);
-    return 65;
-  }
-  const body = JSON.stringify({ method: "checkpoint.create", params });
-  const isHttps = url.protocol === "https:";
-  const transport = isHttps ? import_node_https2.request : import_node_http2.request;
-  const port = url.port.length > 0 ? Number.parseInt(url.port, 10) : isHttps ? 443 : 80;
-  return new Promise((resolve) => {
-    const req = transport(
-      {
-        host: url.hostname,
-        port,
-        method: "POST",
-        path: `${url.pathname.replace(/\/$/, "")}/rpc`,
-        headers: {
-          "Content-Type": "application/json",
-          "Content-Length": Buffer.byteLength(body).toString(),
-          Authorization: `Bearer ${token}`
-        }
-      },
-      (res) => {
-        const chunks = [];
-        res.on("data", (c) => chunks.push(c));
-        res.on("end", () => {
-          const status2 = res.statusCode ?? 0;
-          const text = Buffer.concat(chunks).toString("utf8");
-          let parsed = null;
-          try {
-            parsed = JSON.parse(text);
-          } catch {
-            parsed = null;
-          }
-          if (parsed && typeof parsed.exitCode === "number") {
-            if (parsed.stdout) process.stdout.write(parsed.stdout);
-            if (parsed.stderr) process.stderr.write(parsed.stderr);
-            resolve(parsed.exitCode);
-            return;
-          }
-          process.stderr.write(
-            `agentbox-ctl checkpoint: relay returned ${String(status2)}: ${text}
+      `agentbox-ctl download: unknown kind "${kindArg}"; expected one of: ${KINDS.join(", ")}
 `
-          );
-          resolve(status2 >= 200 && status2 < 300 ? 0 : 1);
-        });
-      }
     );
-    req.on("error", (err) => {
-      process.stderr.write(`agentbox-ctl checkpoint: ${String(err.message ?? err)}
-`);
-      resolve(126);
-    });
-    req.write(body);
-    req.end();
+    process.exit(64);
+  }
+  const params = { kind: kindArg };
+  const code = await postRpcAndExit(`download.${kindArg}`, params, {
+    errorPrefix: "agentbox-ctl download"
   });
-}
-var checkpointCommand = new Command("checkpoint").description("Capture this box as a project checkpoint (host-side, via the agentbox relay)").option("--name <name>", "checkpoint name (default: <box-name>-<next>)").option("--merged", "flatten lower+upper into one tree instead of a layered delta").option("--set-default", "mark this checkpoint as the project default for new boxes").action(async (opts) => {
-  const params = {};
-  if (opts.name) params.name = opts.name;
-  if (opts.merged === true) params.merged = true;
-  if (opts.setDefault === true) params.setDefault = true;
-  const code = await rpc(params);
   process.exit(code);
 });
 
-// src/commands/git.ts
-var import_node_http3 = require("http");
-var import_node_https3 = require("https");
-async function rpc2(method, opts, extra) {
-  const urlStr = process.env.AGENTBOX_RELAY_URL;
-  const token = process.env.AGENTBOX_RELAY_TOKEN;
-  if (!urlStr || !token) {
-    process.stderr.write(
-      "agentbox-ctl git: AGENTBOX_RELAY_URL / AGENTBOX_RELAY_TOKEN not set; no relay configured for this box.\n"
-    );
-    return 65;
-  }
-  let url;
-  try {
-    url = new URL(urlStr);
-  } catch {
-    process.stderr.write(`agentbox-ctl git: invalid AGENTBOX_RELAY_URL: ${urlStr}
-`);
-    return 65;
+// src/commands/checkpoint.ts
+var checkpointCommand = new Command("checkpoint").description("Capture this box as a project checkpoint (host-side, via the agentbox relay)").option("--name <name>", "checkpoint name (default: <box-name>-<next>)").option("--merged", "flatten lower+upper into one tree instead of a layered delta").option("--set-default", "mark this checkpoint as the project default for new boxes").option(
+  "--replace",
+  "if a checkpoint with the same name exists, rm it first (idempotent recapture; safe to retry when the previous run's stdout was lost)"
+).action(
+  async (opts) => {
+    const params = {};
+    if (opts.name) params.name = opts.name;
+    if (opts.merged === true) params.merged = true;
+    if (opts.setDefault === true) params.setDefault = true;
+    if (opts.replace === true) params.replace = true;
+    const code = await postRpcAndExit("checkpoint.create", params, {
+      errorPrefix: "agentbox-ctl checkpoint"
+    });
+    process.exit(code);
   }
-  const params = {
-    path: opts.cwd ?? process.cwd()
-  };
+);
+
+// src/commands/git.ts
+var import_node_child_process5 = require("child_process");
+function buildParams(opts, extra) {
+  const params = { path: opts.cwd ?? process.cwd() };
   if (opts.remote) params.remote = opts.remote;
   if (extra.length > 0) params.args = extra;
-  const body = JSON.stringify({ method, params });
-  const isHttps = url.protocol === "https:";
-  const transport = isHttps ? import_node_https3.request : import_node_http3.request;
-  const port = url.port.length > 0 ? Number.parseInt(url.port, 10) : isHttps ? 443 : 80;
+  return params;
+}
+function runLocalGit(args, cwd) {
   return new Promise((resolve) => {
-    const req = transport(
-      {
-        host: url.hostname,
-        port,
-        method: "POST",
-        path: `${url.pathname.replace(/\/$/, "")}/rpc`,
-        headers: {
-          "Content-Type": "application/json",
-          "Content-Length": Buffer.byteLength(body).toString(),
-          Authorization: `Bearer ${token}`
-        }
-      },
-      (res) => {
-        const chunks = [];
-        res.on("data", (c) => chunks.push(c));
-        res.on("end", () => {
-          const status2 = res.statusCode ?? 0;
-          const text = Buffer.concat(chunks).toString("utf8");
-          let parsed = null;
-          try {
-            parsed = JSON.parse(text);
-          } catch {
-            parsed = null;
-          }
-          if (parsed && typeof parsed.exitCode === "number") {
-            if (parsed.stdout) process.stdout.write(parsed.stdout);
-            if (parsed.stderr) process.stderr.write(parsed.stderr);
-            resolve(parsed.exitCode);
-            return;
-          }
-          process.stderr.write(`agentbox-ctl git: relay returned ${String(status2)}: ${text}
-`);
-          resolve(status2 >= 200 && status2 < 300 ? 0 : 1);
-        });
-      }
-    );
-    req.on("error", (err) => {
+    const child = (0, import_node_child_process5.spawn)("git", args, { cwd, stdio: "inherit" });
+    child.on("close", (code) => resolve(code ?? 1));
+    child.on("error", (err) => {
       process.stderr.write(`agentbox-ctl git: ${String(err.message ?? err)}
 `);
       resolve(126);
     });
-    req.write(body);
-    req.end();
   });
 }
 var gitCommand = new Command("git").description("Git operations that need host credentials (routed through the agentbox relay)").addCommand(
-  new Command("pull").description("Run `git pull` on the host worktree for this box").option("--remote <name>", "remote name (default: origin)").option("--cwd <path>", "path inside the container identifying which worktree to use").allowExcessArguments(true).allowUnknownOption(true).argument("[args...]", "additional args forwarded to git pull").action(async (args, opts) => {
-    const code = await rpc2("git.pull", opts, args);
+  new Command("push").description("Run `git push` on the host main repo against this box's branch (user is prompted on the host wrapper to confirm)").option("--remote <name>", "remote name (default: origin)").option("--cwd <path>", "container path identifying which registered worktree to use").allowExcessArguments(true).allowUnknownOption(true).argument("[args...]", "additional args forwarded to git push").action(async (args, opts) => {
+    const code = await postRpcAndExit("git.push", buildParams(opts, args), {
+      errorPrefix: "agentbox-ctl git"
+    });
     process.exit(code);
   })
 ).addCommand(
-  new Command("push").description("Run `git push` on the host worktree for this box").option("--remote <name>", "remote name (default: origin)").option("--cwd <path>", "path inside the container identifying which worktree to use").allowExcessArguments(true).allowUnknownOption(true).argument("[args...]", "additional args forwarded to git push").action(async (args, opts) => {
-    const code = await rpc2("git.push", opts, args);
+  new Command("fetch").description("Run `git fetch` on the host main repo (refs land in the shared .git)").option("--remote <name>", "remote name (default: origin)").option("--cwd <path>", "container path identifying which registered worktree to use").allowExcessArguments(true).allowUnknownOption(true).argument("[args...]", "additional args forwarded to git fetch").action(async (args, opts) => {
+    const code = await postRpcAndExit("git.fetch", buildParams(opts, args), {
+      errorPrefix: "agentbox-ctl git"
+    });
     process.exit(code);
   })
+).addCommand(
+  new Command("pull").description(
+    "Fetch via the relay (host creds), then merge into the in-container working tree locally"
+  ).option("--remote <name>", "remote name (default: origin)").option("--cwd <path>", "container path identifying which registered worktree to use").option("--ff-only", "pass --ff-only to the local merge").allowExcessArguments(true).allowUnknownOption(true).argument("[args...]", "additional args forwarded to git fetch").action(
+    async (args, opts) => {
+      const fetchCode = await postRpcAndExit("git.fetch", buildParams(opts, args), {
+        errorPrefix: "agentbox-ctl git"
+      });
+      if (fetchCode !== 0) process.exit(fetchCode);
+      const remote = opts.remote ?? "origin";
+      const cwd = opts.cwd ?? process.cwd();
+      const mergeArgs = ["merge"];
+      if (opts.ffOnly) mergeArgs.push("--ff-only");
+      mergeArgs.push(`${remote}/HEAD`);
+      const mergeCode = await runLocalGit(mergeArgs, cwd);
+      process.exit(mergeCode);
+    }
+  )
+);
+
+// src/commands/notify.ts
+async function reportState(opts, state) {
+  try {
+    await claudeState({ socketPath: opts.socket, timeoutMs: 1500 }, state);
+  } catch {
+  }
+}
+var notifyCommand = new Command("notify").description(
+  "Signal that the in-box agent is waiting for user input (highlights the box in the dashboard)"
+).option("--socket <path>", "unix socket path", DEFAULT_SOCKET_PATH).option("--message <text>", "reserved for future use; accepted but ignored in v1").action(async (opts) => {
+  await reportState(opts, "waiting");
+  process.exit(0);
+}).addCommand(
+  new Command("clear").description("Clear the waiting state (alias for `claude-state idle`)").option("--socket <path>", "unix socket path", DEFAULT_SOCKET_PATH).action(async (opts) => {
+    await reportState(opts, "idle");
+    process.exit(0);
+  })
 );
 
+// src/commands/open.ts
+var openCommand = new Command("open").description("Open a URL in the host's default browser (via the agentbox relay)").argument("<url>", "http(s) URL to open on the host").action(async (url) => {
+  const params = { url };
+  const code = await postRpcAndExit("browser.open", params, {
+    errorPrefix: "agentbox-ctl open"
+  });
+  process.exit(code);
+});
+
 // src/render.ts
 function renderStatusTable(rows) {
   if (rows.length === 0) return "(no services configured)";
@@ -12783,6 +12891,10 @@ program2.addCommand(waitReadyCommand);
 program2.addCommand(runTaskCommand);
 program2.addCommand(gitCommand);
 program2.addCommand(checkpointCommand);
+program2.addCommand(cpCommand);
+program2.addCommand(downloadCommand);
+program2.addCommand(notifyCommand);
+program2.addCommand(openCommand);
 program2.parseAsync(process.argv).catch((err) => {
   const msg = err instanceof Error ? err.message : String(err);
   process.stderr.write(`agentbox-ctl: ${msg}

package/runtime/docker/packages/sandbox-docker/scripts/agentbox-checkpoint-cleanup

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Pre-`docker commit` cleanup: strip ephemeral / disposable state so the
+# captured checkpoint image is closer to "warm project state, nothing else".
+#
+# Invoked by the host via `docker exec --user root <container>
+# /usr/local/bin/agentbox-checkpoint-cleanup` right before
+# `docker commit`. Best-effort: every step is allowed to fail (a checkpoint
+# capture should never block on cleanup hiccups).
+#
+# What we DELIBERATELY keep:
+#   - /workspace                  the actual point of the checkpoint
+#   - /home/vscode/.npm           warm npm cache (next install is fast)
+#   - /home/vscode/.cache         pnpm/yarn/Cargo/etc. caches
+#   - /var/lib/docker             in-box dockerd's data root
+#   - /home/vscode/.claude        the named volume is bind-mounted; image
+#                                 layer never sees it anyway
+set +e
+
+# apt: drop downloaded .deb cache and the package index. The index is ~50MB
+# and gets refreshed on the next `apt-get update`; the .deb cache is reusable
+# only if we don't change versions, which we usually do.
+apt-get clean 2>/dev/null
+rm -rf /var/lib/apt/lists/* 2>/dev/null
+
+# Throwaway scratch dirs. Preserve /tmp/claude-* — that is the live in-box
+# Claude Code session's working tree (its per-task stdout/stderr files). The
+# agent that triggered this checkpoint *is* that session; deleting its task
+# output mid-run makes its harness see ENOENT, treat the command as failed,
+# and retry the checkpoint (observed: 5 duplicate auto-named checkpoints).
+# Stale claude-* dirs baked into the image are tiny and Claude Code prunes
+# them itself on the next session start.
+find /tmp /var/tmp -mindepth 1 -maxdepth 1 ! -name 'claude-*' -exec rm -rf {} + 2>/dev/null
+
+# Logs: truncate (don't delete) so the original file modes / ownerships stay
+# intact for the next run. Targets common rotated archives too.
+find /var/log -type f \( -name '*.log' -o -name '*.gz' -o -name '*.1' \) \
+  -exec truncate -s0 {} + 2>/dev/null
+find /var/log/agentbox -type f -exec truncate -s0 {} + 2>/dev/null
+
+# Bash history (root + vscode). Re-assert vscode ownership: `: >` run as root
+# (re)creates the file root-owned 0644 when it didn't exist, which the uid-1000
+# vscode user cannot append to, silently dropping all shell history.
+: > /root/.bash_history 2>/dev/null
+: > /home/vscode/.bash_history 2>/dev/null
+chown vscode:vscode /home/vscode/.bash_history 2>/dev/null
+chmod 600 /home/vscode/.bash_history 2>/dev/null
+
+# Anthropic's installer writes a transient marker; redundant once the binary
+# is in place. Safe to wipe.
+rm -rf /home/vscode/.claude-installer 2>/dev/null
+
+exit 0