@madarco/agentbox 0.1.0

package/dist/index.js

@@ -0,0 +1,4067 @@
+#!/usr/bin/env node
+import {
+  createBox
+} from "./chunk-OOOKFFR5.js";
+import {
+  AmbiguousBoxError,
+  BoxNotFoundError,
+  destroyBox,
+  getBoxHostPaths,
+  inspectBox,
+  listBoxes,
+  openBoxInFinder,
+  pauseBox,
+  pruneBoxes,
+  startBox,
+  stopBox,
+  unpauseBox
+} from "./chunk-RWJE6AER.js";
+import {
+  ClaudeSessionError,
+  SHARED_CLAUDE_VOLUME,
+  attachClaudeSession,
+  buildClaudeDashboardAttachArgv,
+  buildShellArgv,
+  buildVncUrls,
+  claudeSessionInfo,
+  containerHex,
+  ensureAgentboxTasksFile,
+  ensureClaudeVolume,
+  ensureRelay,
+  ideProfile,
+  pullClaudeExtras,
+  rebuildPluginNativeDeps,
+  renderPortsTable,
+  renderStatusTable,
+  renderTaskTable,
+  resolveClaudeVolume,
+  startClaudeSession,
+  stopRelay
+} from "./chunk-O5HS3QHW.js";
+import {
+  STATE_DIR,
+  readState,
+  resolveBoxRef
+} from "./chunk-IDR4HVIC.js";
+import {
+  agentboxHomeBytes,
+  allCheckpointVolumesBytes,
+  boxResourceStats,
+  projectCheckpointVolumeBytes
+} from "./chunk-J35IH7W5.js";
+import {
+  DEFAULT_BOX_IMAGE,
+  DEFAULT_ENV_PATTERNS,
+  KEY_REGISTRY,
+  UserConfigError,
+  bumpProjectGcCounter,
+  configPathFor,
+  createCheckpoint,
+  detectEngine,
+  execInBox,
+  findProjectRoot,
+  listCheckpoints,
+  listProjectsConfigured,
+  loadEffectiveConfig,
+  lookupKey,
+  pruneOrphanProjectConfigs,
+  pullToHost,
+  refreshExport,
+  removeCheckpoint,
+  removeImage,
+  setConfigValue,
+  setEngineOverride,
+  unsetConfigValue
+} from "./chunk-SOMIKEN2.js";
+
+// src/index.ts
+import { Command as Command27 } from "commander";
+
+// ../../packages/sandbox-docker/dist/index.js
+function browserSessionActive(stdout, exitCode) {
+  return exitCode === 0 && !/no active sessions/i.test(stdout);
+}
+async function ensureBoxBrowser(container, timeoutMs = 8e3) {
+  const list = await execInBox(container, ["agent-browser", "session", "list"], {
+    user: "vscode",
+    timeoutMs
+  });
+  if (browserSessionActive(list.stdout, list.exitCode)) {
+    return { up: true, alreadyRunning: true };
+  }
+  const open = await execInBox(container, ["agent-browser", "open", "--headed", "about:blank"], {
+    user: "vscode",
+    timeoutMs
+  });
+  if (open.exitCode === 0) return { up: true };
+  return {
+    up: false,
+    reason: `agent-browser open failed: ${open.stderr || open.stdout || `exit ${String(open.exitCode)}`}`
+  };
+}
+
+// src/engine-override.ts
+async function applyEngineOverrideAtStartup() {
+  try {
+    const loaded = await loadEffectiveConfig(process.cwd());
+    const kind = loaded.effective.engine.kind;
+    if (kind === "auto") return;
+    setEngineOverride(kind);
+  } catch {
+  }
+}
+
+// src/help.ts
+var HELP_GROUPS = [
+  { title: "Create & run", commands: ["create", "claude"] },
+  {
+    title: "Access",
+    commands: ["dashboard", "browser", "screen", "code", "shell", "open", "logs"]
+  },
+  { title: "Inspect", commands: ["list", "status", "top"] },
+  { title: "Lifecycle", commands: ["start", "stop", "destroy", "pause", "unpause"] },
+  { title: "Sync & state", commands: ["pull", "checkpoint"] },
+  {
+    title: "Advanced",
+    commands: ["wait", "prune", "self-update", "config"]
+  }
+];
+function term(cmd) {
+  const aliases = cmd.aliases();
+  return aliases.length ? `${cmd.name()}|${aliases.join("|")}` : cmd.name();
+}
+function buildGroupedHelp(program2) {
+  const byName = new Map(program2.commands.map((c) => [c.name(), c]));
+  const grouped = new Set(HELP_GROUPS.flatMap((g) => g.commands));
+  const orphans = program2.commands.map((c) => c.name()).filter((n) => !grouped.has(n));
+  const groups = [...HELP_GROUPS];
+  if (orphans.length) groups.push({ title: "Other", commands: orphans });
+  const terms = [];
+  for (const g of groups) {
+    for (const name of g.commands) {
+      const cmd = byName.get(name);
+      if (cmd) terms.push(term(cmd));
+    }
+  }
+  const pad = Math.max(0, ...terms.map((t) => t.length)) + 2;
+  const lines = ["Commands:"];
+  for (const g of groups) {
+    const title = g.hint ? `${g.title}  (${g.hint})` : g.title;
+    lines.push("", `  ${title}`);
+    for (const name of g.commands) {
+      const cmd = byName.get(name);
+      if (!cmd) continue;
+      lines.push(`    ${term(cmd).padEnd(pad)}${cmd.description()}`);
+    }
+  }
+  lines.push("", "Run `agentbox <command> --help` for command-specific options.");
+  return lines.join("\n");
+}
+
+// src/commands/browser.ts
+import { spawnSync } from "child_process";
+import { log as log3 } from "@clack/prompts";
+import { Command } from "commander";
+
+// src/box-ref.ts
+import { log } from "@clack/prompts";
+async function resolveBoxOrShift(ref, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const project = await findProjectRoot(cwd);
+  const state = await readState();
+  const firstTry = resolveBoxRef(ref, state, project.root);
+  if (firstTry.kind === "ok") return { box: firstTry.box, shifted: false };
+  if (ref !== void 0) {
+    const pick = resolveBoxRef(void 0, state, project.root);
+    if (pick.kind === "ok") return { box: pick.box, shifted: true };
+    if (pick.kind === "ambiguous") {
+      log.error(`multiple boxes in this project \u2014 pick one:`);
+      for (const b of pick.matches) {
+        const idx = typeof b.projectIndex === "number" ? `${String(b.projectIndex)})` : " -)";
+        process.stderr.write(`  ${idx} ${b.name}   (id ${b.id})
+`);
+      }
+      log.info("try: agentbox <cmd> <n> -- <args>   (or use the box name / id prefix)");
+      process.exit(2);
+    }
+  }
+  const box = await resolveBoxOrExit(ref, opts);
+  return { box, shifted: false };
+}
+async function resolveBoxOrExit(ref, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const project = await findProjectRoot(cwd);
+  const state = await readState();
+  const result = resolveBoxRef(ref, state, project.root);
+  if (result.kind === "ok") return result.box;
+  if (result.kind === "ambiguous") {
+    if (ref === void 0) {
+      log.error(`multiple boxes in this project \u2014 pick one:`);
+      for (const b of result.matches) {
+        const idx = typeof b.projectIndex === "number" ? `${String(b.projectIndex)})` : " -)";
+        process.stderr.write(`  ${idx} ${b.name}   (id ${b.id})
+`);
+      }
+      log.info("try: agentbox <cmd> <n>   (or use the box name / id prefix)");
+      process.exit(2);
+    }
+    throw new AmbiguousBoxError(ref, result.matches);
+  }
+  if (ref === void 0) {
+    log.error(`no boxes in this project (${project.root})`);
+    log.info("run `agentbox create` to make one, or pass a box ref explicitly");
+    process.exit(2);
+  }
+  if (/^[1-9][0-9]*$/.test(ref.trim())) {
+    log.error(`no box with index ${ref.trim()} in this project (${project.root})`);
+    log.info("run `agentbox list` to see available indices");
+    process.exit(2);
+  }
+  throw new BoxNotFoundError(ref);
+}
+
+// src/commands/_errors.ts
+import { log as log2 } from "@clack/prompts";
+function handleLifecycleError(err) {
+  if (err instanceof BoxNotFoundError) {
+    log2.error(err.message);
+    log2.info("Run `agentbox list` to see available boxes.");
+    process.exit(2);
+  }
+  if (err instanceof AmbiguousBoxError) {
+    log2.error(err.message);
+    log2.info("Specify more characters of the id, or use the full name.");
+    process.exit(2);
+  }
+  if (err instanceof ClaudeSessionError) {
+    log2.error(err.message);
+    process.exit(2);
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  log2.error(msg);
+  process.exit(1);
+}
+
+// src/commands/browser.ts
+var browserCommand = new Command("browser").description(
+  "Open a box's web app URL in the browser, even when no service declares `expose:` (auto-unpause/start)"
+).argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--print", "print the URL to stdout instead of launching the browser").option("--loopback", "use the 127.0.0.1 URL instead of the OrbStack .orb.local URL").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log3.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log3.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    const { record } = await getBoxHostPaths(box.id);
+    if (record.webContainerPort === void 0) {
+      throw new Error(
+        `box ${box.name} predates the reserved web port; recreate it to use \`agentbox browser\``
+      );
+    }
+    const engine = await detectEngine();
+    let url;
+    if (engine === "orbstack" && !opts.loopback) {
+      url = `http://${record.container}.orb.local`;
+    } else {
+      if (record.webHostPort === void 0) {
+        throw new Error(
+          `web port not resolved for box ${box.name}; is the container running? try \`agentbox inspect ${box.name}\``
+        );
+      }
+      url = `http://127.0.0.1:${String(record.webHostPort)}`;
+    }
+    if (opts.print) {
+      process.stdout.write(`${url}
+`);
+      return;
+    }
+    const opened = spawnSync("open", [url], { stdio: "inherit" });
+    if (opened.status !== 0) {
+      throw new Error(`open ${url} failed (exit ${String(opened.status ?? "n/a")})`);
+    }
+    process.stdout.write(`opened ${url}
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/claude.ts
+import { confirm as confirm2, intro, isCancel as isCancel2, log as log5, outro, password, spinner } from "@clack/prompts";
+import { Command as Command2 } from "commander";
+
+// src/auth.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var AUTH_FILE = join(STATE_DIR, "auth.json");
+async function resolveClaudeAuth(processEnv, opts = {}) {
+  const env = {};
+  const envApiKey = processEnv["ANTHROPIC_API_KEY"];
+  const envOauth = processEnv["CLAUDE_CODE_OAUTH_TOKEN"];
+  if (typeof envApiKey === "string" && envApiKey.length > 0) env["ANTHROPIC_API_KEY"] = envApiKey;
+  if (typeof envOauth === "string" && envOauth.length > 0) env["CLAUDE_CODE_OAUTH_TOKEN"] = envOauth;
+  if (Object.keys(env).length > 0) return { env, source: "host-env" };
+  const file = await readAuthFile(opts.authFilePath);
+  if (file.claudeCodeOauthToken && file.claudeCodeOauthToken.length > 0) {
+    return {
+      env: { CLAUDE_CODE_OAUTH_TOKEN: file.claudeCodeOauthToken },
+      source: "auth-file"
+    };
+  }
+  return { env: {}, source: "none" };
+}
+async function readAuthFile(path = AUTH_FILE) {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const t = parsed.claudeCodeOauthToken;
+      return typeof t === "string" && t.length > 0 ? { claudeCodeOauthToken: t } : {};
+    }
+    return {};
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    return {};
+  }
+}
+async function writeAuthFile(next, path = AUTH_FILE) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(next, null, 2) + "\n", { mode: 384, flag: "w" });
+}
+function hostClaudeAvailable() {
+  const r = spawnSync2("which", ["claude"], { stdio: ["ignore", "pipe", "ignore"] });
+  return r.status === 0 && (r.stdout?.toString().trim().length ?? 0) > 0;
+}
+function runHostSetupToken() {
+  const child = spawnSync2("claude", ["setup-token"], { stdio: "inherit" });
+  return { exitCode: child.status ?? -1 };
+}
+function isPlausibleOauthToken(s) {
+  const t = s.trim();
+  return t.startsWith("sk-ant-oat") && t.length >= 40;
+}
+
+// ../../packages/core/dist/index.js
+var claudeCodeLauncher = {
+  kind: "claude-code",
+  // claude treats its first positional argument as the seed user turn in
+  // interactive mode (`claude "<message>"`), so we slot the initial message
+  // ahead of any user-passed flags.
+  buildArgs(initialMessage, userArgs) {
+    if (!initialMessage) return [...userArgs];
+    return [initialMessage, ...userArgs];
+  }
+};
+var codexLauncher = {
+  kind: "codex",
+  buildArgs() {
+    throw new Error(
+      "codex agent is not yet supported by agentbox; install + wire the codex launcher first"
+    );
+  }
+};
+function resolveAgentLauncher(kind) {
+  if (kind === "claude-code") return claudeCodeLauncher;
+  if (kind === "codex") return codexLauncher;
+  throw new Error(`unknown agent kind: ${String(kind)}`);
+}
+
+// src/spinner-line.ts
+var SPINNER_CHROME = 6;
+function clampSpinnerLine(line) {
+  const cols = process.stdout.columns;
+  if (!process.stdout.isTTY || !cols) return line;
+  const trimmed = line.replace(/\s+$/, "");
+  const max = cols - SPINNER_CHROME;
+  if (max <= 1 || trimmed.length <= max) return trimmed;
+  return `${trimmed.slice(0, max - 1)}\u2026`;
+}
+
+// src/limits.ts
+function parseMemoryToBytes(raw) {
+  const m = /^\s*([\d.]+)\s*([bkmg]?)b?\s*$/i.exec(raw);
+  if (!m) throw new Error(`invalid --memory value "${raw}" (try e.g. 512m, 2g)`);
+  const n = Number(m[1]);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new Error(`invalid --memory value "${raw}"`);
+  }
+  const unit = (m[2] ?? "").toLowerCase();
+  const factor = unit === "k" ? 1024 : unit === "m" ? 1024 ** 2 : unit === "g" ? 1024 ** 3 : 1;
+  return Math.floor(n * factor);
+}
+var MIB = 1024 * 1024;
+function resolveLimits(box, flags) {
+  let memoryBytes = box.memory > 0 ? box.memory * MIB : null;
+  if (flags.memory !== void 0 && flags.memory !== "") {
+    memoryBytes = parseMemoryToBytes(flags.memory);
+  }
+  let cpus = box.cpus > 0 ? box.cpus : null;
+  if (flags.cpus !== void 0 && flags.cpus !== "") {
+    const n = Number(flags.cpus);
+    if (!Number.isFinite(n) || n < 0) {
+      throw new Error(`invalid --cpus value "${flags.cpus}"`);
+    }
+    cpus = n > 0 ? n : null;
+  }
+  let pidsLimit = box.pidsLimit > 0 ? box.pidsLimit : null;
+  if (flags.pidsLimit !== void 0 && flags.pidsLimit !== "") {
+    const n = Number(flags.pidsLimit);
+    if (!Number.isInteger(n) || n < 0) {
+      throw new Error(`invalid --pids-limit value "${flags.pidsLimit}"`);
+    }
+    pidsLimit = n > 0 ? n : null;
+  }
+  let disk = box.disk ? box.disk : null;
+  if (flags.disk !== void 0 && flags.disk !== "") disk = flags.disk;
+  return { memoryBytes, cpus, pidsLimit, disk };
+}
+
+// src/wizard.ts
+import { confirm, isCancel, log as log4 } from "@clack/prompts";
+import { copyFile, mkdir as mkdir2, stat } from "fs/promises";
+import { homedir } from "os";
+import { basename, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var IN_BOX_SETUP_GUIDE_PATH = "/usr/local/share/agentbox/setup-guide.md";
+var HOST_SKILLS_DIR = join2(homedir(), ".claude", "skills", "agentbox-setup");
+var HOST_SKILL_FILE = join2(HOST_SKILLS_DIR, "SKILL.md");
+function bundledSkillPath() {
+  return fileURLToPath(new URL("../share/agentbox-setup/SKILL.md", import.meta.url));
+}
+async function fileExists(p) {
+  try {
+    const st = await stat(p);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+async function installAgentboxSetupSkill(opts = {}) {
+  const targetFile = opts.targetFile ?? HOST_SKILL_FILE;
+  const targetDir = join2(targetFile, "..");
+  if (await fileExists(targetFile)) return { installed: false, targetFile };
+  const src = opts.sourceFile ?? bundledSkillPath();
+  if (!await fileExists(src)) {
+    return { installed: false, targetFile };
+  }
+  await mkdir2(targetDir, { recursive: true, mode: 448 });
+  await copyFile(src, targetFile);
+  return { installed: true, targetFile };
+}
+function buildSetupInitialPrompt(workspace) {
+  const name = basename(workspace);
+  return `The user just opened a new agentbox sandbox for "${name}" but the workspace has no agentbox.yaml yet. Please run the /agentbox-setup skill (or read ${IN_BOX_SETUP_GUIDE_PATH} if the skill is not loaded), then explore /workspace and propose an agentbox.yaml. Save the file to /workspace/agentbox.yaml. Then run \`agentbox-ctl reload\` from inside the box so the already-running supervisor applies the new config and immediately runs the declared tasks and autostarts the services (no box restart needed). When done, summarise what services and tasks you declared, and remind the user how to land the file on the host (commit through the bind-mounted .git, or "agentbox pull env" on the host).`;
+}
+var WIZARD_AUTOLAUNCH_ENV = "AGENTBOX_WIZARD_AUTOLAUNCH";
+async function maybeRunSetupWizard(args) {
+  if (process.env[WIZARD_AUTOLAUNCH_ENV] === "1") {
+    if (args.command !== "claude") return { action: "proceed" };
+    if (args.checkpointRef) return { action: "proceed" };
+    const proj2 = await findProjectRoot(args.workspace);
+    if (proj2.hasAgentboxYaml) return { action: "proceed" };
+    return {
+      action: "launch-with-prompt",
+      initialPrompt: buildSetupInitialPrompt(proj2.root)
+    };
+  }
+  if (args.yes) return { action: "proceed" };
+  if (!process.stdin.isTTY) return { action: "proceed" };
+  const proj = await findProjectRoot(args.workspace);
+  if (proj.hasAgentboxYaml) return { action: "proceed" };
+  if (args.checkpointRef) {
+    log4.info(`starting from checkpoint "${args.checkpointRef}"; skipping agentbox.yaml setup`);
+    return { action: "proceed" };
+  }
+  const go = await confirm({
+    message: "Set up a new Agentbox environment?",
+    initialValue: true
+  });
+  if (isCancel(go) || !go) return { action: "proceed" };
+  try {
+    const r = await installAgentboxSetupSkill();
+    if (r.installed) {
+      log4.success(`installed /agentbox-setup skill at ${r.targetFile}`);
+    }
+  } catch (err) {
+    log4.warn(`could not install /agentbox-setup skill: ${err.message}`);
+  }
+  if (args.command === "create") return { action: "switch-to-claude" };
+  return {
+    action: "launch-with-prompt",
+    initialPrompt: buildSetupInitialPrompt(proj.root)
+  };
+}
+function passthroughFlags(opts) {
+  const out = [];
+  if (opts.workspace) out.push("--workspace", opts.workspace);
+  if (opts.name) out.push("--name", opts.name);
+  if (opts.hostSnapshot === true) out.push("--host-snapshot");
+  if (opts.hostSnapshot === false) out.push("--no-host-snapshot");
+  if (opts.snapshot) out.push("--snapshot", opts.snapshot);
+  if (opts.image) out.push("--image", opts.image);
+  if (opts.withPlaywright === true) out.push("--with-playwright");
+  if (opts.vnc === false) out.push("--no-vnc");
+  if (opts.sharedDockerCache === true) out.push("--shared-docker-cache");
+  return out;
+}
+
+// src/commands/claude.ts
+function reattachRef(r) {
+  return typeof r.projectIndex === "number" ? String(r.projectIndex) : r.name;
+}
+function buildClaudeCliOverrides(opts) {
+  const box = {};
+  if (opts.hostSnapshot !== void 0) box.hostSnapshot = opts.hostSnapshot;
+  if (opts.image !== void 0) box.image = opts.image;
+  if (opts.withPlaywright === true) box.withPlaywright = true;
+  if (opts.withEnv === true) box.withEnv = true;
+  if (opts.vnc === false) box.vnc = false;
+  if (opts.isolateClaudeConfig === true) box.isolateClaudeConfig = true;
+  if (opts.sharedDockerCache === true) box.dockerCacheShared = true;
+  const claude = {};
+  if (opts.sessionName !== void 0) claude.sessionName = opts.sessionName;
+  const out = {};
+  if (Object.keys(box).length > 0) out.box = box;
+  if (Object.keys(claude).length > 0) out.claude = claude;
+  return out;
+}
+async function offerSetupToken() {
+  log5.info("first time setup: setup token for Claude Code");
+  const canRun = hostClaudeAvailable();
+  if (canRun) {
+    const yes = await confirm2({
+      message: "Run `claude setup-token` now to save a token?",
+      initialValue: true
+    });
+    if (isCancel2(yes) || !yes) {
+      log5.info("ok, continuing without a saved token; /login inside the box once and it persists in the shared volume.");
+      return null;
+    }
+    const { exitCode } = runHostSetupToken();
+    if (exitCode !== 0) {
+      log5.warn(`\`claude setup-token\` exited with code ${String(exitCode)}; you can still paste a token below if you have one.`);
+    }
+  } else {
+    log5.warn(
+      "Claude Code is not installed on the host, so I cannot run `claude setup-token` for you. Run it on a machine that has Claude Code installed, then paste the token below \u2014 or skip and /login inside the box."
+    );
+  }
+  const pasted = await password({ message: "Paste OAuth token (or empty to skip):" });
+  if (isCancel2(pasted) || !pasted) {
+    log5.info("ok, continuing without a saved token; /login inside the box once and it persists in the shared volume.");
+    return null;
+  }
+  const token = pasted.trim();
+  if (!isPlausibleOauthToken(token)) {
+    log5.warn("That doesn't look like an OAuth token (expected `sk-ant-oat\u2026`); saving anyway \u2014 verify inside the box.");
+  }
+  await writeAuthFile({ claudeCodeOauthToken: token });
+  log5.success(`saved to ${AUTH_FILE} (mode 0600)`);
+  return { env: { CLAUDE_CODE_OAUTH_TOKEN: token }, source: "auth-file" };
+}
+var claudeCommand = new Command2("claude").description("Create a sandboxed box and launch Claude Code in a detachable tmux session").option("-w, --workspace <path>", "host workspace to mount", process.cwd()).option("-n, --name <name>", "friendly box name (default: <workspace-basename>-<id>)").option("--host-snapshot", "use a frozen APFS clone of the host workspace as the overlay lower").option("--no-host-snapshot", "bind the live workspace directly (host edits leak into reads)").option(
+  "--snapshot <ref>",
+  "start from a project checkpoint (see `agentbox checkpoint`); overrides box.defaultCheckpoint"
+).option("--image <ref>", "override the box image").option("-y, --yes", "skip prompts, accept defaults (host-snapshot=on)").option(
+  "--isolate-claude-config",
+  "use a per-box ~/.claude volume instead of the shared agentbox-claude-config"
+).option("--with-playwright", "also install @playwright/cli@latest globally inside the box").option(
+  "--with-env",
+  "copy host env/config files (.env*, secrets.toml, agentbox.yaml, ...) into /workspace at create time (gitignore-bypassing)"
+).option("--no-vnc", "disable the per-box Xvnc + noVNC web client (on by default)").option(
+  "--shared-docker-cache",
+  "use the shared 'agentbox-docker-cache' volume for in-box docker images (preserved on destroy; only one box can run at a time when set)"
+).option("--session-name <name>", "tmux session name (default from config; built-in: claude)").option("--memory <size>", "memory ceiling (e.g. 512m, 2g); unset = unlimited").option("--cpus <n>", "CPU count cap (fractional ok, e.g. 1.5); unset = unlimited").option("--pids-limit <n>", "max process count (PIDs cgroup); unset = unlimited").option("--disk <size>", "best-effort writable-layer size (e.g. 10g); no-op on overlay2/macOS").argument(
+  "[claude-args...]",
+  "extra args passed to claude inside the box; place after `--`, e.g. `agentbox claude -- --model sonnet`"
+).action(async (claudeArgs, opts) => {
+  intro("agentbox claude");
+  const cfg = await loadEffectiveConfig(opts.workspace, {
+    cliOverrides: buildClaudeCliOverrides(opts)
+  });
+  const projectRoot = (await findProjectRoot(opts.workspace)).root;
+  const checkpointRef = opts.snapshot && opts.snapshot.length > 0 ? opts.snapshot : cfg.effective.box.defaultCheckpoint.length > 0 ? cfg.effective.box.defaultCheckpoint : void 0;
+  const wiz = await maybeRunSetupWizard({
+    workspace: opts.workspace,
+    yes: !!opts.yes,
+    command: "claude",
+    checkpointRef
+  });
+  let effectiveClaudeArgs = claudeArgs;
+  if (wiz.action === "launch-with-prompt" && wiz.initialPrompt) {
+    effectiveClaudeArgs = resolveAgentLauncher("claude-code").buildArgs(
+      wiz.initialPrompt,
+      claudeArgs
+    );
+  }
+  const useSnapshot = opts.hostSnapshot === false ? false : opts.hostSnapshot === true ? true : cfg.effective.box.hostSnapshot ?? true;
+  const sessionName = cfg.effective.claude.sessionName;
+  let resolved = await resolveClaudeAuth(process.env);
+  if (resolved.source === "none" && process.stdin.isTTY && !opts.yes) {
+    const next = await offerSetupToken();
+    if (next) resolved = next;
+  }
+  const s = spinner();
+  s.start("creating box");
+  let containerName = "";
+  try {
+    const withPlaywright = cfg.effective.box.withPlaywright || cfg.effective.browser.default !== "agent-browser";
+    const result = await createBox({
+      workspacePath: opts.workspace,
+      name: opts.name,
+      useSnapshot,
+      checkpointRef,
+      image: cfg.effective.box.image,
+      claudeConfig: { isolate: cfg.effective.box.isolateClaudeConfig },
+      claudeEnv: resolved.env,
+      withPlaywright,
+      withEnv: cfg.effective.box.withEnv,
+      vnc: { enabled: cfg.effective.box.vnc },
+      docker: { sharedCache: cfg.effective.box.dockerCacheShared },
+      limits: resolveLimits(cfg.effective.box, opts),
+      projectRoot,
+      onLog: (line) => s.message(clampSpinnerLine(line))
+    });
+    containerName = result.record.container;
+    s.message("checking plugin native deps");
+    const rebuild = await rebuildPluginNativeDeps(result.record.container, {
+      volume: result.record.claudeConfigVolume ?? SHARED_CLAUDE_VOLUME,
+      onProgress: (line) => s.message(clampSpinnerLine(line))
+    });
+    s.message("starting claude session");
+    await startClaudeSession({
+      container: result.record.container,
+      claudeArgs: effectiveClaudeArgs,
+      sessionName,
+      boxName: result.record.name
+    });
+    const nSuffix = typeof result.record.projectIndex === "number" ? `  \xB7  n ${String(result.record.projectIndex)}` : "";
+    s.stop(`box ${result.record.container} ready${nSuffix}`);
+    for (const f of rebuild.failed) {
+      log5.warn(`plugin install failed for ${f.dir}; claude may still load it. stderr:
+${f.stderr.trim()}`);
+    }
+    outro("attaching \u2014 Ctrl-b d to detach, leaves claude running");
+    attachClaudeSession(result.record.container, sessionName, reattachRef(result.record));
+  } catch (err) {
+    s.stop("failed");
+    if (err instanceof ClaudeSessionError) {
+      log5.error(err.message);
+      if (containerName) {
+        log5.info(`The box ${containerName} is still running. Destroy it with:`);
+        log5.info(`  agentbox destroy ${containerName} -y`);
+      }
+      process.exit(1);
+    }
+    handleLifecycleError(err);
+  }
+});
+async function startOrAttachClaude(box, claudeArgs, opts) {
+  const cfg = await loadEffectiveConfig(box.workspacePath, {
+    cliOverrides: opts.sessionName ? { claude: { sessionName: opts.sessionName } } : {}
+  });
+  const sessionName = cfg.effective.claude.sessionName;
+  const insp = await inspectBox(box.id);
+  if (insp.state === "missing") {
+    throw new Error(`box ${box.name} has no container; was it destroyed?`);
+  }
+  const existing = await claudeSessionInfo(box.container, sessionName);
+  if (existing.running) {
+    outro(`session "${sessionName}" already running \u2014 attaching (Ctrl-b d to detach)`);
+    attachClaudeSession(box.container, sessionName, reattachRef(box));
+    return;
+  }
+  const s = spinner();
+  s.start("preparing box");
+  if (insp.state === "paused") {
+    s.message("unpausing box");
+    await unpauseBox(box.id);
+  } else if (insp.state === "stopped") {
+    s.message("starting box (remounting overlay)");
+    await startBox(box.id);
+  }
+  const syncConfig = opts.syncConfig !== false;
+  if (syncConfig) {
+    s.message("syncing ~/.claude into box volume");
+    const volume = box.claudeConfigVolume ?? SHARED_CLAUDE_VOLUME;
+    await ensureClaudeVolume(
+      { volume },
+      {
+        syncFromHost: true,
+        image: box.image,
+        hostWorkspace: box.workspacePath
+      }
+    );
+  }
+  s.message("checking plugin native deps");
+  const rebuild = await rebuildPluginNativeDeps(box.container, {
+    volume: box.claudeConfigVolume ?? SHARED_CLAUDE_VOLUME,
+    onProgress: (line) => s.message(clampSpinnerLine(line))
+  });
+  s.message("starting claude session");
+  await startClaudeSession({
+    container: box.container,
+    claudeArgs,
+    sessionName,
+    boxName: box.name
+  });
+  s.stop(`box ${box.container} ready`);
+  for (const f of rebuild.failed) {
+    log5.warn(`plugin install failed for ${f.dir}; claude may still load it. stderr:
+${f.stderr.trim()}`);
+  }
+  outro("attaching \u2014 Ctrl-b d to detach, leaves claude running");
+  attachClaudeSession(box.container, sessionName, reattachRef(box));
+}
+var claudeAttachCommand = new Command2("attach").description(
+  "Attach to a Claude Code tmux session in a box, starting one if none is running (auto-unpause/start)"
+).argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--session-name <name>", "tmux session name (default from config; built-in: claude)").option(
+  "--no-sync-config",
+  "when starting a fresh session, skip rsyncing the host's ~/.claude into the box's volume (faster)"
+).action(async function(idOrName) {
+  const opts = this.optsWithGlobals();
+  intro("agentbox claude attach");
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    await startOrAttachClaude(box, [], opts);
+  } catch (err) {
+    if (err instanceof ClaudeSessionError) {
+      log5.error(err.message);
+      process.exit(1);
+    }
+    handleLifecycleError(err);
+  }
+});
+var claudeStartCommand = new Command2("start").description(
+  "Start a Claude Code tmux session in an already-existing box (auto-unpause/start). If a session is already running, just attach."
+).argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--session-name <name>", "tmux session name (default from config; built-in: claude)").option(
+  "--no-sync-config",
+  "skip rsyncing the host's ~/.claude into the box's volume before starting (faster; use existing in-box state)"
+).argument(
+  "[claude-args...]",
+  "extra args passed to claude when starting a new session; ignored if a session is already running. Place after `--`, e.g. `agentbox claude start 1 -- --model sonnet`"
+).action(async function(idOrName, claudeArgs) {
+  const opts = this.optsWithGlobals();
+  intro("agentbox claude start");
+  try {
+    const { box, shifted } = await resolveBoxOrShift(idOrName);
+    const effectiveClaudeArgs = shifted && idOrName ? [idOrName, ...claudeArgs] : claudeArgs;
+    await startOrAttachClaude(box, effectiveClaudeArgs, opts);
+  } catch (err) {
+    if (err instanceof ClaudeSessionError) {
+      log5.error(err.message);
+      process.exit(1);
+    }
+    handleLifecycleError(err);
+  }
+});
+claudeCommand.addCommand(claudeAttachCommand);
+claudeCommand.addCommand(claudeStartCommand);
+
+// src/commands/checkpoint.ts
+import { confirm as confirm3, isCancel as isCancel3, log as log6 } from "@clack/prompts";
+import { Command as Command3 } from "commander";
+async function projectRootFor(cwd, recordRoot) {
+  return recordRoot ?? (await findProjectRoot(cwd)).root;
+}
+var createSub = new Command3("create").description("Capture a box state as a project checkpoint (<box-name>-<n>)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).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 (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log6.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log6.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    const projectRoot = await projectRootFor(box.workspacePath, box.projectRoot);
+    const cfg = await loadEffectiveConfig(projectRoot);
+    const info = await createCheckpoint({
+      box,
+      projectRoot,
+      name: opts.name,
+      merged: opts.merged === true,
+      setDefault: opts.setDefault === true,
+      maxLayers: cfg.effective.checkpoint.maxLayers,
+      onLog: (line) => log6.info(line)
+    });
+    log6.success(
+      `checkpoint ${info.name} (${info.manifest.type}) -> ${info.dir}` + (opts.setDefault ? "  [project default]" : "")
+    );
+    if (!opts.setDefault) {
+      log6.info(`make it the default for new boxes: agentbox checkpoint set-default ${info.name}`);
+    }
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+var lsSub = new Command3("ls").description("List this project's checkpoints").action(async () => {
+  try {
+    const projectRoot = (await findProjectRoot(process.cwd())).root;
+    const cfg = await loadEffectiveConfig(projectRoot);
+    const def = cfg.effective.box.defaultCheckpoint;
+    const list = await listCheckpoints(projectRoot);
+    if (list.length === 0) {
+      process.stdout.write(`no checkpoints for ${projectRoot}
+`);
+      return;
+    }
+    for (const c of list) {
+      const flag = c.name === def ? " *default" : "";
+      process.stdout.write(
+        `${c.name}  ${c.manifest.type}  from ${c.manifest.sourceBoxName}  ${c.manifest.createdAt}${flag}
+`
+      );
+    }
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+var setDefaultSub = new Command3("set-default").description("Pin a checkpoint as the project default (box.defaultCheckpoint)").argument("[ref]", "checkpoint name (omit with --clear)").option("--clear", "unset the project default instead of setting one").action(async (ref, opts) => {
+  try {
+    const projectRoot = (await findProjectRoot(process.cwd())).root;
+    if (opts.clear) {
+      if (ref !== void 0) {
+        throw new Error("pass either a <ref> or --clear, not both");
+      }
+      const r2 = await unsetConfigValue("project", "box.defaultCheckpoint", projectRoot);
+      process.stdout.write(
+        r2.existed ? `cleared project default checkpoint   (wrote ${r2.path})
+` : `no project default checkpoint was set   (${r2.path})
+`
+      );
+      return;
+    }
+    if (ref === void 0) {
+      throw new Error("missing <ref> (or pass --clear to unset the default)");
+    }
+    const list = await listCheckpoints(projectRoot);
+    if (!list.some((c) => c.name === ref)) {
+      throw new Error(`checkpoint not found: ${ref} (see \`agentbox checkpoint ls\`)`);
+    }
+    const r = await setConfigValue("project", "box.defaultCheckpoint", ref, projectRoot);
+    process.stdout.write(`project default checkpoint = ${ref}   (wrote ${r.path})
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+var rmSub = new Command3("rm").description("Delete a checkpoint").argument("<ref>", "checkpoint name").option("-y, --yes", "skip the confirmation prompt").action(async (ref, opts) => {
+  try {
+    const projectRoot = (await findProjectRoot(process.cwd())).root;
+    if (!opts.yes) {
+      const ok = await confirm3({ message: `Delete checkpoint ${ref}?`, initialValue: false });
+      if (isCancel3(ok) || !ok) {
+        log6.info("cancelled");
+        return;
+      }
+    }
+    const removed = await removeCheckpoint(projectRoot, ref);
+    if (!removed) throw new Error(`checkpoint not found: ${ref}`);
+    process.stdout.write(`removed checkpoint ${ref}
+`);
+    const cfg = await loadEffectiveConfig(projectRoot);
+    if (cfg.layers.project.values.box?.defaultCheckpoint === ref) {
+      await unsetConfigValue("project", "box.defaultCheckpoint", projectRoot);
+      log6.info(`cleared project default checkpoint (was ${ref})`);
+    } else if (cfg.effective.box.defaultCheckpoint === ref) {
+      log6.warn(
+        `default checkpoint ${ref} is set outside the per-project config (global or agentbox.yaml defaults) \u2014 clear it manually`
+      );
+    }
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+var checkpointCommand = new Command3("checkpoint").description("Capture and manage project checkpoints (warm box state new boxes can start from)").addCommand(createSub, { isDefault: true }).addCommand(lsSub).addCommand(setDefaultSub).addCommand(rmSub);
+
+// src/commands/code.ts
+import { spawn } from "child_process";
+import { log as log7 } from "@clack/prompts";
+import { Command as Command4, InvalidArgumentError } from "commander";
+function buildCodeCliOverrides(opts) {
+  const code = {};
+  if (opts.ide !== void 0) code.ide = opts.ide;
+  if (opts.noWait === true) code.wait = false;
+  if (opts.noAutoTerminals === true) code.autoTerminals = false;
+  if (opts.timeout !== void 0) {
+    const n = Number(opts.timeout);
+    if (Number.isFinite(n) && Number.isInteger(n)) code.timeoutMs = n;
+  }
+  return Object.keys(code).length > 0 ? { code } : {};
+}
+function parseIdeFlavor(value) {
+  if (value === "vscode" || value === "cursor") return value;
+  throw new InvalidArgumentError(`expected one of: vscode, cursor (got "${value}")`);
+}
+var codeCommand = new Command4("code").description("Open a box in VS Code or Cursor via the Dev Containers extension").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--no-wait", "don't block on agentbox-ctl wait-ready before opening").option("--timeout <ms>", "wait-ready timeout in milliseconds (default from config; built-in: 120000)").option("--no-auto-terminals", "don't generate /workspace/.vscode/tasks.json").option("--regen-tasks", "overwrite a user-owned tasks.json (skips sentinel check)", false).option(
+  "--ide <flavor>",
+  "force a specific IDE: vscode | cursor (default from config; built-in: auto)",
+  parseIdeFlavor
+).option(
+  "--print",
+  "print the folder URI instead of launching the IDE (still refreshes/waits)"
+).action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const cfg = await loadEffectiveConfig(box.workspacePath, {
+      cliOverrides: buildCodeCliOverrides(opts)
+    });
+    const wait = cfg.effective.code.wait;
+    const autoTerminals = cfg.effective.code.autoTerminals;
+    const timeoutMs = String(cfg.effective.code.timeoutMs);
+    const ide = cfg.effective.code.ide;
+    const forcedIde = ide === "auto" ? void 0 : ide;
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log7.info(`box is paused; unpausing`);
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log7.info(`box is stopped; starting (remounting overlay)`);
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    if (wait) {
+      const reply = await runWaitReady(box.container, timeoutMs);
+      if (!reply.ready) {
+        const lines = [];
+        if (reply.timedOut.length > 0) lines.push(`timed out: ${reply.timedOut.join(", ")}`);
+        if (reply.failed.length > 0) lines.push(`failed: ${reply.failed.join(", ")}`);
+        log7.warn(`box not fully ready (${lines.join("; ")}). Opening anyway.`);
+      } else {
+        log7.success("all units ready");
+      }
+    }
+    if (autoTerminals) {
+      try {
+        const services = await fetchServiceNames(box.container);
+        const r = await ensureAgentboxTasksFile(box.container, services, {
+          regen: opts.regenTasks
+        });
+        if (r.status === "wrote") {
+          log7.info(`wrote /workspace/.vscode/tasks.json (${String(services.length)} service(s))`);
+        } else if (r.status === "skipped-user-owned") {
+          log7.warn(
+            "user-owned .vscode/tasks.json detected; skipping auto-terminals (pass --regen-tasks to overwrite)"
+          );
+        }
+      } catch (err) {
+        log7.warn(
+          `auto-terminals failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    const folderUri = `vscode-remote://attached-container+${containerHex(box.container)}/workspace`;
+    if (opts.print) {
+      process.stdout.write(folderUri + "\n");
+      return;
+    }
+    const exit = await launchIde(folderUri, forcedIde);
+    if (exit.code !== 0) {
+      log7.error(`failed to launch ${exit.flavor ? ideProfile(exit.flavor).displayName : "IDE"} via ${exit.via} (exit ${String(exit.code)})`);
+      process.stdout.write(folderUri + "\n");
+      process.exit(1);
+    }
+    log7.success(
+      `opening ${box.container} in ${ideProfile(exit.flavor).displayName} (${exit.via})`
+    );
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+async function runWaitReady(container, timeoutMs) {
+  const proc = await execInBox(
+    container,
+    ["agentbox-ctl", "wait-ready", "--json", "--timeout", timeoutMs],
+    { user: "vscode" }
+  );
+  try {
+    return JSON.parse(proc.stdout);
+  } catch {
+    throw new Error(
+      `agentbox-ctl wait-ready returned unparseable output: ${proc.stderr || proc.stdout}`
+    );
+  }
+}
+async function launchIde(folderUri, forced) {
+  if (forced) {
+    return launchOne(forced, folderUri);
+  }
+  const code = await tryCli("vscode", folderUri);
+  if (code !== null) return code;
+  const cursor = await tryCli("cursor", folderUri);
+  if (cursor !== null) return cursor;
+  log7.warn("neither `code` nor `cursor` found in PATH; falling back to `open vscode://...`");
+  return launchOne("vscode", folderUri);
+}
+async function tryCli(flavor, folderUri) {
+  const profile = ideProfile(flavor);
+  const code = await spawnCommand(profile.cli, ["--folder-uri", folderUri]);
+  if (code === 127) return null;
+  return { code, flavor, via: "cli" };
+}
+async function launchOne(flavor, folderUri) {
+  const profile = ideProfile(flavor);
+  const cliCode = await spawnCommand(profile.cli, ["--folder-uri", folderUri]);
+  if (cliCode !== 127) return { code: cliCode, flavor, via: "cli" };
+  log7.warn(
+    `\`${profile.cli}\` not found in PATH; falling back to \`open ${profile.protocolScheme}://...\` (the %2B URL-encoding bug may break attach)`
+  );
+  const url = `${profile.protocolScheme}://${folderUri.replace(/^vscode-remote:\/\//, "vscode-remote/")}`;
+  const fallback = await spawnCommand("open", [url]);
+  return { code: fallback, flavor, via: "open" };
+}
+function spawnCommand(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "ignore" });
+    child.once("error", () => resolve(127));
+    child.once("exit", (code) => resolve(code ?? -1));
+  });
+}
+async function fetchServiceNames(container) {
+  const proc = await execInBox(container, ["agentbox-ctl", "status", "--json"], {
+    user: "vscode"
+  });
+  if (proc.exitCode !== 0) return [];
+  try {
+    const reply = JSON.parse(proc.stdout);
+    return reply.services.map((s) => ({ name: s.name }));
+  } catch {
+    return [];
+  }
+}
+
+// src/commands/config.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { Command as Command5, InvalidArgumentError as InvalidArgumentError2 } from "commander";
+function resolveWriteScope(opts) {
+  if (opts.global && opts.project) {
+    fail("pass at most one of --global / --project");
+  }
+  if (opts.global) return "global";
+  return "project";
+}
+function resolveEditScope(opts) {
+  const flags = [opts.global, opts.project, opts.workspace].filter(Boolean).length;
+  if (flags > 1) fail("pass at most one of --global / --project / --workspace");
+  if (opts.workspace) return "workspace";
+  if (opts.global) return "global";
+  return "project";
+}
+function fail(message) {
+  process.stderr.write(`error: ${message}
+`);
+  process.exit(1);
+}
+function leafValue(loaded, key) {
+  const idx = key.indexOf(".");
+  const branch = key.slice(0, idx);
+  const leaf = key.slice(idx + 1);
+  return loaded.effective[branch]?.[leaf];
+}
+function rawLeafFromValues(values, key) {
+  if (!values) return void 0;
+  const idx = key.indexOf(".");
+  const b = values[key.slice(0, idx)];
+  if (!b || typeof b !== "object") return void 0;
+  return b[key.slice(idx + 1)];
+}
+function describeSource(source, loaded) {
+  switch (source) {
+    case "cli":
+      return "cli flag";
+    case "workspace":
+      return loaded.layers.workspace.path ? `workspace ${loaded.layers.workspace.path}` : "workspace";
+    case "project":
+      return `project ${loaded.layers.project.path}`;
+    case "global":
+      return `global ${loaded.layers.global.path}`;
+    case "default":
+      return "built-in default";
+  }
+}
+function fmtValue(v) {
+  if (v === void 0) return "<unset>";
+  if (typeof v === "string") return v;
+  return String(v);
+}
+var getCommand = new Command5("get").description("Print the effective value of a config key (with --all, show every layer)").argument("<key>", "dot-path key (e.g. box.hostSnapshot)").option("--all", "print every layer with its source").option("--json", "machine-readable output").action(async (key, opts) => {
+  const desc = lookupKey(key);
+  if (!desc) fail(`unknown key "${key}"`);
+  try {
+    const loaded = await loadEffectiveConfig(process.cwd());
+    const value = leafValue(loaded, key);
+    const source = loaded.sources[key] ?? "default";
+    if (opts.json) {
+      const layerView = (values, path) => ({
+        value: rawLeafFromValues(values, key) ?? null,
+        path
+      });
+      process.stdout.write(
+        JSON.stringify(
+          {
+            key,
+            value: value ?? null,
+            source,
+            layers: opts.all ? {
+              cli: layerView(loaded.layers.cli.values, null),
+              workspace: layerView(
+                loaded.layers.workspace.values,
+                loaded.layers.workspace.path
+              ),
+              project: layerView(
+                loaded.layers.project.values,
+                loaded.layers.project.path
+              ),
+              global: layerView(
+                loaded.layers.global.values,
+                loaded.layers.global.path
+              ),
+              default: { value: leafValue({ ...loaded, effective: loaded.layers.defaults }, key) ?? null, path: null }
+            } : void 0
+          },
+          null,
+          2
+        ) + "\n"
+      );
+      return;
+    }
+    if (opts.all) {
+      const lines = [
+        `${key}:`,
+        `  effective: ${fmtValue(value)}   (${describeSource(source, loaded)})`,
+        `  cli:       ${fmtValue(rawLeafFromValues(loaded.layers.cli.values, key))}`,
+        `  workspace: ${fmtValue(rawLeafFromValues(loaded.layers.workspace.values, key))}` + (loaded.layers.workspace.path ? `   ${loaded.layers.workspace.path}` : ""),
+        `  project:   ${fmtValue(rawLeafFromValues(loaded.layers.project.values, key))}   ${loaded.layers.project.path}`,
+        `  global:    ${fmtValue(rawLeafFromValues(loaded.layers.global.values, key))}   ${loaded.layers.global.path}`,
+        `  default:   ${fmtValue(leafValue({ ...loaded, effective: loaded.layers.defaults }, key))}`
+      ];
+      process.stdout.write(lines.join("\n") + "\n");
+      return;
+    }
+    process.stdout.write(`${key} = ${fmtValue(value)}   (from: ${describeSource(source, loaded)})
+`);
+  } catch (err) {
+    handleError(err);
+  }
+});
+var setCommand = new Command5("set").description("Set a config key in the global or per-project file (default: --project)").argument("<key>", "dot-path key (e.g. box.hostSnapshot)").argument("<value>", "value to set; coerced to the key's declared type").option("--global", "write to ~/.agentbox/config.yaml").option("--project", "write to ~/.agentbox/projects/<hash>/config.yaml (default)").action(async (key, value, opts) => {
+  const scope = resolveWriteScope(opts);
+  try {
+    const r = await setConfigValue(scope, key, value, process.cwd(), { raw: true });
+    if (opts.json) {
+      process.stdout.write(
+        JSON.stringify({ key, scope, value: r.coerced, path: r.path }, null, 2) + "\n"
+      );
+    } else {
+      process.stdout.write(`${key} = ${fmtValue(r.coerced)}   (wrote ${r.path})
+`);
+    }
+  } catch (err) {
+    handleError(err);
+  }
+});
+var unsetCommand = new Command5("unset").description("Remove a config key from the global or per-project file (default: --project)").argument("<key>", "dot-path key (e.g. box.hostSnapshot)").option("--global", "edit ~/.agentbox/config.yaml").option("--project", "edit ~/.agentbox/projects/<hash>/config.yaml (default)").action(async (key, opts) => {
+  const scope = resolveWriteScope(opts);
+  try {
+    const r = await unsetConfigValue(scope, key, process.cwd());
+    if (r.existed) {
+      process.stdout.write(`removed ${key} from ${r.path}
+`);
+    } else {
+      process.stdout.write(`${key} was not set in ${r.path}
+`);
+    }
+  } catch (err) {
+    handleError(err);
+  }
+});
+function parseListScope(value) {
+  if (value === "global" || value === "project" || value === "workspace" || value === "effective") {
+    return value;
+  }
+  throw new InvalidArgumentError2(`expected one of: global, project, workspace, effective`);
+}
+var listCommand = new Command5("list").description("List config values, either for a single layer or the merged effective view").option(
+  "--scope <s>",
+  "one of: global, project, workspace, effective (default: effective)",
+  parseListScope,
+  "effective"
+).option("--include-advanced", "include advanced keys (image, ports)").option("--json", "machine-readable output").action(async (opts) => {
+  try {
+    const loaded = await loadEffectiveConfig(process.cwd());
+    const scope = opts.scope ?? "effective";
+    const showAdvanced = !!opts.includeAdvanced;
+    const visibleKeys = KEY_REGISTRY.filter((d) => showAdvanced || !d.advanced);
+    if (opts.json) {
+      const obj = {};
+      for (const desc of visibleKeys) {
+        const value = pickFromScope(loaded, scope, desc.key);
+        obj[desc.key] = scope === "effective" ? { value: value ?? null, source: loaded.sources[desc.key] ?? "default" } : { value: value ?? null };
+      }
+      process.stdout.write(JSON.stringify({ scope, keys: obj }, null, 2) + "\n");
+      return;
+    }
+    if (scope === "effective") {
+      const lines = [];
+      for (const desc of visibleKeys) {
+        const value = leafValue(loaded, desc.key);
+        const source = loaded.sources[desc.key] ?? "default";
+        lines.push(`${desc.key.padEnd(28)} ${fmtValue(value).padEnd(20)} (${source})`);
+      }
+      process.stdout.write(lines.join("\n") + "\n");
+      return;
+    }
+    const layerPath = scope === "global" ? loaded.layers.global.path : scope === "project" ? loaded.layers.project.path : loaded.layers.workspace.path;
+    process.stdout.write(`# ${scope} ${layerPath ?? "(no agentbox.yaml in ancestors)"}
+`);
+    let any = false;
+    for (const desc of visibleKeys) {
+      const v = pickFromScope(loaded, scope, desc.key);
+      if (v === void 0) continue;
+      any = true;
+      process.stdout.write(`${desc.key.padEnd(28)} ${fmtValue(v)}
+`);
+    }
+    if (!any) process.stdout.write("(no values set in this scope)\n");
+  } catch (err) {
+    handleError(err);
+  }
+});
+function pickFromScope(loaded, scope, key) {
+  switch (scope) {
+    case "global":
+      return rawLeafFromValues(loaded.layers.global.values, key);
+    case "project":
+      return rawLeafFromValues(loaded.layers.project.values, key);
+    case "workspace":
+      return rawLeafFromValues(loaded.layers.workspace.values, key);
+    case "effective":
+    default:
+      return leafValue(loaded, key);
+  }
+}
+var pathCommand = new Command5("path").description("Print the file path for a config scope (default: --project)").option("--global", "~/.agentbox/config.yaml").option("--project", "~/.agentbox/projects/<hash>/config.yaml (default)").option("--workspace", "./agentbox.yaml (resolved by walking up to the nearest one)").option("--json", "machine-readable output").action(async (opts) => {
+  try {
+    const scope = resolveEditScope(opts);
+    const path = await configPathFor(scope, process.cwd());
+    if (opts.json) process.stdout.write(JSON.stringify({ scope, path }, null, 2) + "\n");
+    else process.stdout.write(`${path}
+`);
+  } catch (err) {
+    handleError(err);
+  }
+});
+var editCommand = new Command5("edit").description("Open a config file in $EDITOR (default: --project)").option("--global", "edit ~/.agentbox/config.yaml").option("--project", "edit ~/.agentbox/projects/<hash>/config.yaml (default)").option("--workspace", "edit ./agentbox.yaml (the resolved one \u2014 and remember to fill in the `defaults:` block)").action(async (opts) => {
+  try {
+    const scope = resolveEditScope(opts);
+    const path = await configPathFor(scope, process.cwd());
+    const editor = process.env["EDITOR"] || process.env["VISUAL"] || "vi";
+    const child = spawnSync3(editor, [path], { stdio: "inherit" });
+    process.exit(child.status ?? 0);
+  } catch (err) {
+    handleError(err);
+  }
+});
+var listProjectsCommand = new Command5("list-projects").description("List directories that have per-user-per-project config recorded under ~/.agentbox/projects/").option("--json", "machine-readable output").action(async (opts) => {
+  try {
+    const projects = await listProjectsConfigured();
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(projects, null, 2) + "\n");
+      return;
+    }
+    if (projects.length === 0) {
+      process.stdout.write("(no per-project config recorded)\n");
+      return;
+    }
+    for (const p of projects) {
+      process.stdout.write(
+        `${p.hash}  ${p.originalPath}${p.hasConfigFile ? "" : "  (meta only \u2014 no config.yaml)"}
+`
+      );
+    }
+  } catch (err) {
+    handleError(err);
+  }
+});
+function handleError(err) {
+  if (err instanceof UserConfigError) {
+    process.stderr.write(`error: ${err.message}
+`);
+    process.exit(2);
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`error: ${msg}
+`);
+  process.exit(1);
+}
+var configCommand = new Command5("config").description("Read / write layered config (global, per-project, workspace `defaults:` block)").addCommand(getCommand).addCommand(setCommand).addCommand(unsetCommand).addCommand(listCommand).addCommand(pathCommand).addCommand(editCommand).addCommand(listProjectsCommand);
+
+// src/commands/create.ts
+import { intro as intro2, log as log8, outro as outro2, spinner as spinner2 } from "@clack/prompts";
+import { Command as Command6 } from "commander";
+import { execSync, spawnSync as spawnSync4 } from "child_process";
+function buildCliOverrides(opts) {
+  const box = {};
+  if (opts.hostSnapshot !== void 0) box.hostSnapshot = opts.hostSnapshot;
+  if (opts.image !== void 0) box.image = opts.image;
+  if (opts.withPlaywright === true) box.withPlaywright = true;
+  if (opts.withEnv === true) box.withEnv = true;
+  if (opts.vnc === false) box.vnc = false;
+  if (opts.sharedDockerCache === true) box.dockerCacheShared = true;
+  return Object.keys(box).length > 0 ? { box } : {};
+}
+function resolveUseSnapshot(opts, configDefault) {
+  if (opts.hostSnapshot === false) return false;
+  if (opts.hostSnapshot === true) return true;
+  return configDefault ?? true;
+}
+function resolveCheckpointRef(opts, configDefault) {
+  if (opts.snapshot && opts.snapshot.length > 0) return opts.snapshot;
+  return configDefault.length > 0 ? configDefault : void 0;
+}
+function attachShell(container) {
+  const child = spawnSync4("docker", ["exec", "-it", container, "bash"], {
+    stdio: "inherit"
+  });
+  process.exit(child.status ?? 0);
+}
+var createCommand = new Command6("create").description("Create and start a new agent box (Docker container with FUSE overlay)").option("-w, --workspace <path>", "host workspace to mount", process.cwd()).option("-n, --name <name>", "friendly box name (default: <workspace-basename>-<id>)").option("--host-snapshot", "use a frozen APFS clone of the host workspace as the overlay lower").option("--no-host-snapshot", "bind the live workspace directly (host edits leak into reads)").option(
+  "--snapshot <ref>",
+  "start from a project checkpoint (see `agentbox checkpoint`); overrides box.defaultCheckpoint"
+).option("--image <ref>", "override the box image", void 0).option("--attach", "drop into a shell inside the box after it is ready").option("--with-playwright", "also install @playwright/cli@latest globally inside the box").option(
+  "--with-env",
+  "copy host env/config files (.env*, secrets.toml, agentbox.yaml, ...) into /workspace at create time (gitignore-bypassing)"
+).option("--no-vnc", "disable the per-box Xvnc + noVNC web client (on by default)").option(
+  "--shared-docker-cache",
+  "use the shared 'agentbox-docker-cache' volume for in-box docker images (preserved on destroy; only one box can run at a time when set)"
+).option("--memory <size>", "memory ceiling (e.g. 512m, 2g); unset = unlimited").option("--cpus <n>", "CPU count cap (fractional ok, e.g. 1.5); unset = unlimited").option("--pids-limit <n>", "max process count (PIDs cgroup); unset = unlimited").option("--disk <size>", "best-effort writable-layer size (e.g. 10g); no-op on overlay2/macOS").option("-y, --yes", "skip prompts, accept defaults (host-snapshot=on)").action(async (opts) => {
+  intro2("agentbox create");
+  const cfg = await loadEffectiveConfig(opts.workspace, {
+    cliOverrides: buildCliOverrides(opts)
+  });
+  const projectRoot = (await findProjectRoot(opts.workspace)).root;
+  const checkpointRef = resolveCheckpointRef(opts, cfg.effective.box.defaultCheckpoint);
+  const wiz = await maybeRunSetupWizard({
+    workspace: opts.workspace,
+    yes: !!opts.yes,
+    command: "create",
+    checkpointRef
+  });
+  if (wiz.action === "switch-to-claude") {
+    process.env[WIZARD_AUTOLAUNCH_ENV] = "1";
+    try {
+      await claudeCommand.parseAsync(passthroughFlags(opts), { from: "user" });
+    } finally {
+      delete process.env[WIZARD_AUTOLAUNCH_ENV];
+    }
+    return;
+  }
+  const useSnapshot = resolveUseSnapshot(opts, cfg.effective.box.hostSnapshot);
+  const s = spinner2();
+  s.start("creating box");
+  try {
+    const withPlaywright = cfg.effective.box.withPlaywright || cfg.effective.browser.default !== "agent-browser";
+    const result = await createBox({
+      workspacePath: opts.workspace,
+      name: opts.name,
+      useSnapshot,
+      checkpointRef,
+      image: cfg.effective.box.image,
+      withPlaywright,
+      withEnv: cfg.effective.box.withEnv,
+      vnc: { enabled: cfg.effective.box.vnc },
+      docker: { sharedCache: cfg.effective.box.dockerCacheShared },
+      limits: resolveLimits(cfg.effective.box, opts),
+      projectRoot,
+      onLog: (line) => s.message(clampSpinnerLine(line))
+    });
+    s.stop(`box ${result.record.container} ready`);
+    log8.info(`id:        ${result.record.id}`);
+    if (typeof result.record.projectIndex === "number") {
+      log8.info(`n:         ${String(result.record.projectIndex)}   (in ${projectRoot})`);
+    }
+    log8.info(`container: ${result.record.container}`);
+    log8.info(`image:     ${result.record.image}${result.imageBuilt ? " (built just now)" : ""}`);
+    log8.info(`lower:     ${result.record.lowerPath}`);
+    log8.info(`upper:     ${result.record.upperVolume}`);
+    if (result.record.snapshotDir) {
+      log8.info(`snapshot:  ${result.record.snapshotDir}`);
+    }
+    if (result.record.checkpointSource) {
+      log8.info(
+        `checkpoint: ${result.record.checkpointSource.ref} (${result.record.checkpointSource.type})`
+      );
+    }
+    for (const check of result.overlayChecks) {
+      log8.success(`${check.name} \u2014 ${check.detail}`);
+    }
+    log8.message(
+      [
+        "",
+        "Try it:",
+        `  docker exec -it ${result.record.container} bash`,
+        `  docker exec ${result.record.container} ls /workspace`,
+        "",
+        "Destroy:",
+        `  docker rm -f ${result.record.container}`,
+        `  docker volume rm ${result.record.upperVolume}`
+      ].join("\n")
+    );
+    const m = cfg.effective.maintenance;
+    if (m.pruneProjectConfigs) {
+      try {
+        const n = await bumpProjectGcCounter();
+        if (n % m.pruneProjectConfigsEvery === 0) {
+          const boxes = await listBoxes();
+          const protectedPaths = boxes.map((b) => b.projectRoot).filter((p) => typeof p === "string");
+          const res = await pruneOrphanProjectConfigs({ protectedPaths });
+          if (res.removed.length > 0) {
+            log8.info(
+              `cleaned ${String(res.removed.length)} orphan project config dir(s): ` + res.removed.map((r) => r.originalPath).join(", ")
+            );
+          }
+        }
+      } catch {
+      }
+    }
+    outro2("done");
+    if (opts.attach) {
+      attachShell(result.record.container);
+    }
+  } catch (err) {
+    s.stop("failed");
+    const msg = err instanceof Error ? err.message : String(err);
+    log8.error(msg);
+    try {
+      const running = execSync('docker ps --format "{{.Names}}"', {
+        stdio: ["ignore", "pipe", "ignore"]
+      }).toString().split("\n").filter((n) => n.startsWith("agentbox-"));
+      if (running.length > 0) {
+        log8.warn(`leftover containers: ${running.join(", ")}`);
+        log8.warn(`remove with: docker rm -f ${running.join(" ")}`);
+      }
+    } catch {
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/dashboard.ts
+import { spawn as spawn2 } from "child_process";
+import { log as log9 } from "@clack/prompts";
+import { Command as Command7 } from "commander";
+
+// src/dashboard/layout.ts
+var SIDEBAR_WIDTH = 32;
+var MIN_RIGHT_W = 20;
+var MIN_RIGHT_H = 4;
+function computeLayout(cols, rows) {
+  const sidebarW = Math.min(SIDEBAR_WIDTH, Math.max(0, cols - MIN_RIGHT_W - 1));
+  const sepX = sidebarW;
+  const rightX = sidebarW + 1;
+  const rightW = Math.max(0, cols - rightX);
+  const statusY = rows - 1;
+  const paneH = Math.max(0, statusY);
+  return {
+    cols,
+    rows,
+    sidebar: { x: 0, y: 0, w: sidebarW, h: paneH },
+    sepX,
+    right: { x: rightX, y: 0, w: rightW, h: paneH },
+    statusY,
+    tooSmall: rightW < MIN_RIGHT_W || paneH < MIN_RIGHT_H
+  };
+}
+
+// src/dashboard/renderer.ts
+var RESET = "\x1B[0m";
+function fgParams(c) {
+  if (c.kind === "default") return "39";
+  if (c.kind === "palette") {
+    const n = c.n;
+    if (n < 8) return String(30 + n);
+    if (n < 16) return String(90 + (n - 8));
+    return `38;5;${String(n)}`;
+  }
+  return `38;2;${String(c.rgb >> 16 & 255)};${String(c.rgb >> 8 & 255)};${String(c.rgb & 255)}`;
+}
+function bgParams(c) {
+  if (c.kind === "default") return "49";
+  if (c.kind === "palette") {
+    const n = c.n;
+    if (n < 8) return String(40 + n);
+    if (n < 16) return String(100 + (n - 8));
+    return `48;5;${String(n)}`;
+  }
+  return `48;2;${String(c.rgb >> 16 & 255)};${String(c.rgb >> 8 & 255)};${String(c.rgb & 255)}`;
+}
+function sgrFor(cell) {
+  const parts = ["0", fgParams(cell.fg), bgParams(cell.bg)];
+  if (cell.bold) parts.push("1");
+  if (cell.dim) parts.push("2");
+  if (cell.italic) parts.push("3");
+  if (cell.underline) parts.push("4");
+  if (cell.inverse) parts.push("7");
+  if (cell.invisible) parts.push("8");
+  if (cell.strike) parts.push("9");
+  return `\x1B[${parts.join(";")}m`;
+}
+function composeRow(snap, y) {
+  let out = "";
+  let lastSgr = "";
+  for (let x = 0; x < snap.cols; x++) {
+    const cell = snap.cell(x, y);
+    if (cell.width === 0) continue;
+    const sgr = sgrFor(cell);
+    if (sgr !== lastSgr) {
+      out += sgr;
+      lastSgr = sgr;
+    }
+    out += cell.chars === "" ? " " : cell.chars;
+  }
+  return out + RESET;
+}
+function cursorTo(row0, col0) {
+  return `\x1B[${String(row0 + 1)};${String(col0 + 1)}H`;
+}
+function diffFrame(prev, snap, rect) {
+  const h = Math.min(rect.h, snap.rows);
+  const rows = new Array(h);
+  let out = "\x1B[?25l";
+  for (let i = 0; i < h; i++) {
+    const payload = composeRow(snap, i);
+    rows[i] = payload;
+    if (prev && prev[i] === payload) continue;
+    out += cursorTo(rect.y + i, rect.x) + RESET + payload + RESET;
+  }
+  if (snap.cursor.visible) {
+    const cy = Math.min(Math.max(snap.cursor.y, 0), h - 1);
+    const cx = Math.min(Math.max(snap.cursor.x, 0), rect.w - 1);
+    out += cursorTo(rect.y + cy, rect.x + cx) + "\x1B[?25h";
+  }
+  return { out, rows };
+}
+
+// src/dashboard/input.ts
+var LEADER = 1;
+var ESC = 27;
+var InputParser = class {
+  state = "normal";
+  esc = [];
+  fwd = [];
+  timer = null;
+  timerId = 0;
+  leaderMs;
+  escMs;
+  setTimer;
+  clearTimer;
+  onEvent;
+  mouseTransform;
+  constructor(opts) {
+    this.onEvent = opts.onEvent;
+    this.mouseTransform = opts.mouseTransform;
+    this.leaderMs = opts.leaderMs ?? 700;
+    this.escMs = opts.escMs ?? 50;
+    this.setTimer = opts.setTimer ?? ((ms, fn) => setTimeout(fn, ms));
+    this.clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+  }
+  feed(buf) {
+    let i = 0;
+    while (i < buf.length) {
+      const b = buf[i];
+      if (this.state === "normal") {
+        if (b === LEADER) {
+          this.flush();
+          this.state = "leader";
+          this.arm(this.leaderMs, "leader");
+        } else if (b === ESC) {
+          this.flush();
+          this.state = "esc";
+          this.esc = [ESC];
+          this.arm(this.escMs, "esc");
+        } else {
+          this.fwd.push(b);
+        }
+        i++;
+        continue;
+      }
+      if (this.state === "leader") {
+        this.disarm();
+        if (b === LEADER) {
+          this.fwd.push(LEADER);
+          this.flush();
+        } else {
+          const c = String.fromCharCode(b);
+          if (c === "v") this.onEvent({ type: "action", name: "vnc" });
+          else if (c === "w") this.onEvent({ type: "action", name: "web" });
+          else if (c === "c") this.onEvent({ type: "action", name: "code" });
+          else if (c === "q" || c === "d") this.onEvent({ type: "quit" });
+          else if (c === "k" || c === "p" || c === "P") this.onEvent({ type: "switch", dir: "prev" });
+          else if (c === "j" || c === "n" || c === "N") this.onEvent({ type: "switch", dir: "next" });
+          else {
+            this.fwd.push(b);
+            this.flush();
+          }
+        }
+        this.state = "normal";
+        i++;
+        continue;
+      }
+      if (this.state === "mouseX10") {
+        this.esc.push(b);
+        if (this.esc.length === 6) {
+          this.disarm();
+          this.emitMouseX10();
+          this.reset();
+        } else {
+          this.arm(this.escMs, "esc");
+        }
+        i++;
+        continue;
+      }
+      if (this.esc.length === 1) {
+        if (b === 91 || b === 79) {
+          this.esc.push(b);
+          this.arm(this.escMs, "esc");
+          i++;
+          continue;
+        }
+        this.disarm();
+        this.forwardVerbatim([ESC]);
+        this.reset();
+        continue;
+      }
+      if (this.esc[1] === 91 && this.esc.length === 2 && b === 77) {
+        this.esc.push(b);
+        this.state = "mouseX10";
+        this.arm(this.escMs, "esc");
+        i++;
+        continue;
+      }
+      this.esc.push(b);
+      const isFinal = this.esc[1] === 79 ? this.esc.length === 3 : b >= 64 && b <= 126;
+      const isParam = b >= 32 && b <= 63;
+      if (isFinal) {
+        this.disarm();
+        this.classifyCsi();
+        this.reset();
+      } else if (isParam || this.esc[1] === 79) {
+        this.arm(this.escMs, "esc");
+      } else {
+        this.disarm();
+        this.forwardVerbatim(this.esc);
+        this.reset();
+      }
+      i++;
+    }
+    if (this.state === "normal") this.flush();
+  }
+  dispose() {
+    this.disarm();
+  }
+  classifyCsi() {
+    const s = String.fromCharCode(...this.esc);
+    if (s === "\x1B[1;7A") return void this.onEvent({ type: "switch", dir: "prev" });
+    if (s === "\x1B[1;7B") return void this.onEvent({ type: "switch", dir: "next" });
+    const m = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(s);
+    if (m) return this.emitMouseSgr(m);
+    this.forwardVerbatim(this.esc);
+  }
+  emitMouseSgr(m) {
+    if (!this.mouseTransform) {
+      this.forwardVerbatim(this.esc);
+      return;
+    }
+    const t = this.mouseTransform(Number(m[2]), Number(m[3]));
+    if (!t) return;
+    this.forwardVerbatim([
+      ...Buffer.from(`\x1B[<${m[1]};${String(t.x)};${String(t.y)}${m[4]}`, "latin1")
+    ]);
+  }
+  emitMouseX10() {
+    const e = this.esc;
+    if (e.length !== 6 || !this.mouseTransform) {
+      this.forwardVerbatim(e);
+      return;
+    }
+    const t = this.mouseTransform(e[4] - 32, e[5] - 32);
+    if (!t) return;
+    this.forwardVerbatim([27, 91, 77, e[3], t.x + 32, t.y + 32]);
+  }
+  reset() {
+    this.state = "normal";
+    this.esc = [];
+  }
+  flush() {
+    if (this.fwd.length === 0) return;
+    this.onEvent({ type: "forward", bytes: Buffer.from(this.fwd) });
+    this.fwd = [];
+  }
+  forwardVerbatim(bytes) {
+    for (const x of bytes) this.fwd.push(x);
+    this.flush();
+  }
+  arm(ms, kind) {
+    this.disarm();
+    const id = ++this.timerId;
+    this.timer = this.setTimer(ms, () => {
+      if (id !== this.timerId) return;
+      this.timer = null;
+      if (kind === "leader" && this.state === "leader") {
+        this.fwd.push(LEADER);
+        this.flush();
+        this.state = "normal";
+      } else if (kind === "esc" && (this.state === "esc" || this.state === "mouseX10")) {
+        this.forwardVerbatim(this.esc);
+        this.reset();
+      }
+    });
+  }
+  disarm() {
+    this.timerId++;
+    if (this.timer != null) {
+      this.clearTimer(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/dashboard/pty-session.ts
+function fgSpec(c) {
+  if (c.isFgDefault()) return { kind: "default" };
+  if (c.isFgPalette()) return { kind: "palette", n: c.getFgColor() };
+  if (c.isFgRGB()) return { kind: "rgb", rgb: c.getFgColor() };
+  return { kind: "default" };
+}
+function bgSpec(c) {
+  if (c.isBgDefault()) return { kind: "default" };
+  if (c.isBgPalette()) return { kind: "palette", n: c.getBgColor() };
+  if (c.isBgRGB()) return { kind: "rgb", rgb: c.getBgColor() };
+  return { kind: "default" };
+}
+var MOUSE_ENABLE_SEQ = "\x1B[?1000h\x1B[?1002h\x1B[?1006h";
+var MOUSE_MODES = [1e3, 1002, 1003, 1005, 1006, 1015];
+var MOUSE_DISABLE_SEQ = MOUSE_MODES.map((n) => `\x1B[?${String(n)}l`).join("");
+var BLANK = {
+  width: 1,
+  chars: " ",
+  fg: { kind: "default" },
+  bg: { kind: "default" },
+  bold: false,
+  dim: false,
+  italic: false,
+  underline: false,
+  inverse: false,
+  invisible: false,
+  strike: false
+};
+var PtySession = class {
+  term;
+  pty;
+  disposed = false;
+  // Reused per cell read — valid only until the next cell() call (the renderer
+  // consumes it synchronously within composeRow).
+  out = { ...BLANK };
+  constructor(spawn5, TerminalClass, dockerArgv, cols, rows, onRenderable, onExit) {
+    this.term = new TerminalClass({
+      cols,
+      rows,
+      allowProposedApi: true,
+      scrollback: 0,
+      convertEol: false
+    });
+    this.pty = spawn5("docker", dockerArgv, {
+      name: "xterm-256color",
+      cols,
+      rows,
+      env: process.env
+    });
+    this.pty.onData((d) => {
+      this.term.write(d, () => onRenderable());
+    });
+    this.term.onData((d) => {
+      if (!this.disposed) this.pty.write(d);
+    });
+    this.pty.onExit(() => {
+      if (!this.disposed) onExit();
+    });
+  }
+  write(bytes) {
+    if (!this.disposed) this.pty.write(bytes.toString("utf8"));
+  }
+  resize(cols, rows) {
+    if (this.disposed) return;
+    this.term.resize(cols, rows);
+    this.pty.resize(cols, rows);
+  }
+  snapshot() {
+    const buf = this.term.buffer.active;
+    const base = buf.baseY;
+    const cell = buf.getNullCell();
+    const o = this.out;
+    return {
+      cols: this.term.cols,
+      rows: this.term.rows,
+      cursor: { x: buf.cursorX, y: buf.cursorY, visible: true },
+      cell: (x, y) => {
+        const line = buf.getLine(base + y);
+        if (!line) return BLANK;
+        line.getCell(x, cell);
+        o.width = cell.getWidth();
+        o.chars = cell.getChars();
+        o.fg = fgSpec(cell);
+        o.bg = bgSpec(cell);
+        o.bold = Boolean(cell.isBold());
+        o.dim = Boolean(cell.isDim());
+        o.italic = Boolean(cell.isItalic());
+        o.underline = Boolean(cell.isUnderline());
+        o.inverse = Boolean(cell.isInverse());
+        o.invisible = Boolean(cell.isInvisible());
+        o.strike = Boolean(cell.isStrikethrough());
+        return o;
+      }
+    };
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    try {
+      this.pty.kill();
+    } catch {
+    }
+    this.term.dispose();
+  }
+};
+
+// src/dashboard/sidebar.ts
+function activityCell(b) {
+  if (b.state !== "running") return `[${b.state}]`;
+  switch (b.claudeActivity) {
+    case "working":
+      return "\u25CF working";
+    case "idle":
+      return "\u25CB idle";
+    case "waiting":
+      return "\u25D0 waiting";
+    default:
+      return "? unknown";
+  }
+}
+var NEW_BOX_ID = "__agentbox_new__";
+var NEW_BOX_LABEL = "+ New box";
+var SIDEBAR_HEADER = "\u2550 AgentBox \u2550";
+var SIDEBAR_HEADER_LINES = 2;
+function fit(s, w) {
+  if (s.length === w) return s;
+  if (s.length > w) return s.slice(0, w);
+  return s + " ".repeat(w - s.length);
+}
+function center(s, w) {
+  if (s.length >= w) return s.slice(0, w);
+  const pad = w - s.length;
+  const leftPad = Math.floor(pad / 2);
+  return " ".repeat(leftPad) + s + " ".repeat(pad - leftPad);
+}
+function sidebarLines(boxes, selectedId, w, h) {
+  const lines = [center(SIDEBAR_HEADER, w), fit("", w)];
+  const nameW = Math.min(16, Math.max(6, ...boxes.map((b) => b.name.length), 6));
+  for (const b of boxes) {
+    const marker = b.id === selectedId ? "\u25B8 " : "  ";
+    const row2 = b.id === NEW_BOX_ID ? `${marker}${NEW_BOX_LABEL}` : `${marker}${fit(b.name, nameW)}  ${activityCell(b)}`;
+    lines.push(fit(row2, w));
+  }
+  if (boxes.length === 0) lines.push(fit(" (no boxes)", w));
+  while (lines.length < h) lines.push(fit("", w));
+  return lines.slice(0, h);
+}
+function menuLines(boxName, w, h) {
+  const body = [
+    "",
+    `  No Claude session in ${boxName}.`,
+    "",
+    "   [c]  Start Claude here",
+    "   [s]  Open a shell",
+    "",
+    "  Ctrl+Option+\u2191/\u2193 switch \xB7 Ctrl-a then v/c/w/q (vnc/code/web/quit)"
+  ];
+  const top = Math.max(0, Math.floor((h - body.length) / 2));
+  const out = [];
+  for (let i = 0; i < h; i++) out.push(fit(body[i - top] ?? "", w));
+  return out;
+}
+function createMenuLines(where, w, h) {
+  const body = [
+    "",
+    "  Create a new box",
+    "",
+    "   [c]  Create + launch Claude",
+    "   [n]  Create only",
+    "",
+    `  in ${where}`,
+    "",
+    "  Ctrl+Option+\u2191/\u2193 switch \xB7 Ctrl-a then q quit"
+  ];
+  const top = Math.max(0, Math.floor((h - body.length) / 2));
+  const out = [];
+  for (let i = 0; i < h; i++) out.push(fit(body[i - top] ?? "", w));
+  return out;
+}
+var BAR_BG = "\x1B[48;2;48;48;48m";
+var BAR_BASE = BAR_BG + "\x1B[38;5;250m";
+var BAR_BRAND = "\x1B[48;5;39m\x1B[38;5;16m";
+var BRAND_BOLD = "\x1B[1m";
+var BRAND_NOBOLD = "\x1B[22m";
+var HINT_KEY = "\x1B[38;5;255m";
+var HINT_TXT = "\x1B[38;5;245m";
+var BAR_RESET = "\x1B[0m";
+var HINT_GROUPS = [
+  ["Control+Option+Up/Down", "switch"],
+  ["Control+a c", "code"],
+  ["Control+a v", "vnc"],
+  ["Control+a w", "web"],
+  ["Control+a q", "quit"]
+];
+function statusLine(box, w, stateLabel) {
+  const state = stateLabel ?? (box ? box.state === "running" ? box.claudeActivity ?? "unknown" : box.state : "");
+  const brandPrefix = box ? " agentbox \u25B8 " : " agentbox ";
+  const brandMain = box ? `${box.name} (${state}) ` : "";
+  const left = brandPrefix + brandMain;
+  const leftStyled = BAR_BRAND + brandPrefix + BRAND_BOLD + brandMain + BRAND_NOBOLD;
+  const SEP = "   \u2502   ";
+  const rightPlain = HINT_GROUPS.map(([k, l]) => `${k}: ${l}`).join(SEP) + " ";
+  const rightStyled = HINT_GROUPS.map(([k, l]) => `${HINT_KEY}${k}${HINT_TXT}: ${l}`).join(
+    `${HINT_TXT}${SEP}`
+  ) + " ";
+  if (left.length + rightPlain.length + 1 > w) {
+    return BAR_BASE + BAR_BRAND + fit(left, w) + BAR_RESET;
+  }
+  const gap = w - left.length - rightPlain.length;
+  return BAR_BASE + leftStyled + BAR_BASE + " ".repeat(gap) + rightStyled + BAR_RESET;
+}
+
+// src/dashboard/compositor.ts
+var SB_BODY = BAR_BG + "\x1B[38;5;250m";
+var SB_HEADER = BAR_BG + "\x1B[38;5;39m\x1B[1m";
+var SB_SELECTED = BAR_BG + "\x1B[38;5;255m\x1B[1m";
+var SGR_RESET = "\x1B[0m";
+var POLL_MS = 1e3;
+var FRAME_MS = 16;
+var RESIZE_DEBOUNCE_MS = 120;
+var SYNC_BEGIN = "\x1B[?2026h";
+var SYNC_END = "\x1B[?2026l";
+function cursorTo2(x, y) {
+  return `\x1B[${String(y + 1)};${String(x + 1)}H`;
+}
+var Compositor = class {
+  constructor(deps, initialId) {
+    this.deps = deps;
+    this.selectedId = initialId;
+    this.layout = computeLayout(this.out.columns ?? 100, this.out.rows ?? 30);
+    this.parser = new InputParser({
+      onEvent: (e) => {
+        if (e.type === "quit") this.onSig();
+        else if (e.type === "switch") this.switchBox(e.dir);
+        else if (e.type === "action") void this.doAction(e.name);
+        else if (this.createMenu) this.handleCreateMenuKey(e.bytes);
+        else if (this.menu) this.handleMenuKey(e.bytes);
+        else this.session?.write(e.bytes);
+      },
+      // Absolute 1-based host coords → right-pane-local 1-based; null = the
+      // pointer is over the sidebar/status, so Claude shouldn't see it.
+      mouseTransform: (x, y) => {
+        const r = this.layout.right;
+        if (!this.session || this.layout.tooSmall) return null;
+        const lx = x - r.x;
+        const ly = y - r.y;
+        if (lx < 1 || ly < 1 || lx > r.w || ly > r.h) return null;
+        return { x: lx, y: ly };
+      }
+    });
+  }
+  deps;
+  out = process.stdout;
+  inp = process.stdin;
+  boxes = [];
+  selectedId;
+  session = null;
+  placeholder = null;
+  menu = null;
+  createMenu = null;
+  activeMode = "claude";
+  flashMsg = null;
+  flashTimer = null;
+  /** True while a start-Claude / open-shell action is in flight (suppresses
+   * the poll respawn so it can't interrupt the transition). */
+  busy = false;
+  layout;
+  prevRows = null;
+  renderTimer = null;
+  pollTimer = null;
+  resizeTimer = null;
+  parser;
+  tornDown = false;
+  resolveDone = null;
+  onData = (d) => this.parser.feed(d);
+  onResize = () => this.scheduleResize();
+  onSig = () => {
+    this.teardown();
+    process.exit(0);
+  };
+  onFatal = (err) => {
+    this.teardown();
+    process.stderr.write(`dashboard: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+    process.exit(1);
+  };
+  async run() {
+    this.out.write("\x1B[?1049h\x1B[?25l\x1B[2J" + MOUSE_ENABLE_SEQ);
+    if (this.inp.isTTY) this.inp.setRawMode(true);
+    this.inp.resume();
+    this.inp.on("data", this.onData);
+    this.out.on("resize", this.onResize);
+    process.once("SIGINT", this.onSig);
+    process.once("SIGTERM", this.onSig);
+    process.once("uncaughtException", this.onFatal);
+    process.once("unhandledRejection", this.onFatal);
+    process.once("exit", () => this.teardown());
+    await this.refreshBoxes();
+    if (!this.boxes.some((b) => b.id === this.selectedId) && this.boxes[0]) {
+      this.selectedId = this.boxes[0].id;
+    }
+    await this.spawnActive();
+    this.drawChrome();
+    this.scheduleRender();
+    this.pollTimer = setInterval(() => void this.poll(), POLL_MS);
+    await new Promise((resolve) => {
+      this.resolveDone = resolve;
+    });
+  }
+  async refreshBoxes() {
+    try {
+      this.boxes = await this.deps.listCandidates();
+    } catch {
+    }
+  }
+  selectedBox() {
+    return this.boxes.find((b) => b.id === this.selectedId);
+  }
+  async poll() {
+    const before = JSON.stringify(this.boxes.map((b) => [b.id, b.state, b.claudeActivity]));
+    await this.refreshBoxes();
+    if (this.busy) {
+    } else if (!this.boxes.some((b) => b.id === this.selectedId) && this.boxes[0]) {
+      this.selectedId = this.boxes[0].id;
+      await this.spawnActive();
+    } else {
+      const box = this.selectedBox();
+      const running = box?.state === "running";
+      const reresolve = this.session && !running || this.placeholder && running || this.menu && !running;
+      if (reresolve) await this.spawnActive();
+    }
+    if (JSON.stringify(this.boxes.map((b) => [b.id, b.state, b.claudeActivity])) !== before) {
+      this.drawChrome();
+    }
+  }
+  disposeSession() {
+    if (!this.session) return;
+    this.session.dispose();
+    this.session = null;
+  }
+  async spawnActive() {
+    this.disposeSession();
+    this.placeholder = null;
+    this.menu = null;
+    this.createMenu = null;
+    this.clearRightPane();
+    const id = this.selectedId;
+    const target = await this.deps.resolveTarget(id);
+    if (this.selectedId !== id || this.tornDown) return;
+    this.applyTarget(target);
+  }
+  /** Turn a resolved/started target into the right-pane state. */
+  applyTarget(target) {
+    this.disposeSession();
+    this.placeholder = null;
+    this.menu = null;
+    this.createMenu = null;
+    if (target.kind === "attach") {
+      this.activeMode = target.mode ?? "claude";
+      this.session = new PtySession(
+        this.deps.ptySpawn,
+        this.deps.termCtor,
+        target.argv,
+        Math.max(1, this.layout.right.w),
+        Math.max(1, this.layout.right.h),
+        () => this.scheduleRender(),
+        () => this.onSessionExit()
+      );
+    } else if (target.kind === "menu") {
+      this.menu = { boxName: this.selectedBox()?.name ?? this.selectedId };
+    } else if (target.kind === "create-menu") {
+      this.createMenu = { where: target.where };
+    } else {
+      this.placeholder = target.lines;
+    }
+    this.prevRows = null;
+    this.drawChrome();
+    this.scheduleRender();
+  }
+  handleMenuKey(bytes) {
+    for (const b of bytes) {
+      if (b === 99 || b === 13 || b === 10) {
+        void this.chooseAction("claude");
+        return;
+      }
+      if (b === 115) {
+        void this.chooseAction("shell");
+        return;
+      }
+    }
+  }
+  async chooseAction(which) {
+    if (this.busy) return;
+    const id = this.selectedId;
+    const name = this.selectedBox()?.name ?? id;
+    this.busy = true;
+    this.menu = null;
+    this.createMenu = null;
+    this.placeholder = ["", which === "claude" ? "  Starting Claude\u2026" : "  Opening shell\u2026"];
+    this.prevRows = null;
+    this.drawChrome();
+    this.scheduleRender();
+    try {
+      const target = which === "claude" ? await this.deps.startClaude(id) : await this.deps.openShell(id);
+      if (this.selectedId !== id || this.tornDown) return;
+      this.applyTarget(target);
+    } catch (err) {
+      if (this.selectedId !== id || this.tornDown) return;
+      const msg = err instanceof Error ? err.message : String(err);
+      this.placeholder = [
+        "",
+        `  Failed to ${which === "claude" ? "start Claude" : "open a shell"} in ${name}:`,
+        `  ${msg}`,
+        "",
+        which === "claude" ? `  Try from a shell: agentbox claude start ${name}` : `  Try from a shell: agentbox shell ${name}`
+      ];
+      this.prevRows = null;
+      this.scheduleRender();
+    } finally {
+      this.busy = false;
+    }
+  }
+  handleCreateMenuKey(bytes) {
+    for (const b of bytes) {
+      if (b === 99 || b === 13 || b === 10) {
+        void this.chooseCreate(true);
+        return;
+      }
+      if (b === 110) {
+        void this.chooseCreate(false);
+        return;
+      }
+    }
+  }
+  async chooseCreate(withClaude) {
+    if (this.busy) return;
+    this.busy = true;
+    this.menu = null;
+    this.createMenu = null;
+    this.placeholder = ["", "  Creating box\u2026", ""];
+    this.prevRows = null;
+    this.drawChrome();
+    this.scheduleRender();
+    try {
+      const { boxId, attach } = await this.deps.createNewBox(withClaude, (line) => {
+        if (this.tornDown) return;
+        this.placeholder = ["", "  Creating box\u2026", "  " + line];
+        this.prevRows = null;
+        this.scheduleRender();
+      });
+      if (this.tornDown) return;
+      this.selectedId = boxId;
+      await this.refreshBoxes();
+      if (attach) {
+        this.applyTarget(attach);
+      } else {
+        await this.spawnActive();
+        this.flash("box created");
+      }
+    } catch (err) {
+      if (this.tornDown) return;
+      const msg = err instanceof Error ? err.message : String(err);
+      this.placeholder = ["", "  Failed to create box:", `  ${msg}`, "", "  Try from a shell: agentbox create"];
+      this.prevRows = null;
+      this.drawChrome();
+      this.scheduleRender();
+    } finally {
+      this.busy = false;
+    }
+  }
+  async doAction(name) {
+    if (this.selectedId === NEW_BOX_ID) {
+      this.flash("select a box first");
+      return;
+    }
+    const id = this.selectedId;
+    let msg;
+    try {
+      msg = name === "vnc" ? await this.deps.openVnc(id) : name === "code" ? await this.deps.openCode(id) : await this.deps.openWeb(id);
+    } catch (err) {
+      msg = err instanceof Error ? err.message : String(err);
+    }
+    this.flash(msg);
+  }
+  /** Briefly show `msg` in the status row, then revert. */
+  flash(msg) {
+    this.flashMsg = msg;
+    if (this.flashTimer) clearTimeout(this.flashTimer);
+    this.flashTimer = setTimeout(() => {
+      this.flashTimer = null;
+      this.flashMsg = null;
+      this.drawChrome();
+    }, 2500);
+    this.drawChrome();
+  }
+  onSessionExit() {
+    this.disposeSession();
+    this.placeholder = ["", "  session ended \u2014 Ctrl-a \u2191/\u2193 to switch boxes"];
+    this.prevRows = null;
+    this.scheduleRender();
+  }
+  switchBox(dir) {
+    if (this.boxes.length === 0) return;
+    const i = Math.max(
+      0,
+      this.boxes.findIndex((b) => b.id === this.selectedId)
+    );
+    const n = this.boxes.length;
+    const next = dir === "prev" ? (i - 1 + n) % n : (i + 1) % n;
+    this.selectedId = this.boxes[next].id;
+    this.drawChrome();
+    void this.spawnActive();
+  }
+  /** Blank the right pane and drop the diff cache (next paint is full). */
+  clearRightPane() {
+    const r = this.layout.right;
+    let s = SYNC_BEGIN + "\x1B[?25l";
+    for (let i = 0; i < r.h; i++) {
+      s += cursorTo2(r.x, r.y + i) + "\x1B[0m" + " ".repeat(r.w);
+    }
+    this.out.write(s + SYNC_END);
+    this.prevRows = null;
+  }
+  scheduleRender() {
+    if (this.renderTimer || this.tornDown) return;
+    this.renderTimer = setTimeout(() => {
+      this.renderTimer = null;
+      this.render();
+    }, FRAME_MS);
+  }
+  render() {
+    if (this.tornDown) return;
+    const r = this.layout.right;
+    if (this.layout.tooSmall) {
+      this.out.write(cursorTo2(0, 0) + "\x1B[2J" + cursorTo2(0, 0) + "terminal too small");
+      return;
+    }
+    if (this.session) {
+      const { out, rows } = diffFrame(this.prevRows, this.session.snapshot(), r);
+      this.prevRows = rows;
+      if (out) this.out.write(SYNC_BEGIN + out + SYNC_END);
+    } else if (this.menu) {
+      const lines = menuLines(this.menu.boxName, r.w, r.h);
+      let s = SYNC_BEGIN + "\x1B[?25l";
+      for (let i = 0; i < r.h; i++) s += cursorTo2(r.x, r.y + i) + "\x1B[0m" + (lines[i] ?? "");
+      this.out.write(s + SYNC_END);
+    } else if (this.createMenu) {
+      const lines = createMenuLines(this.createMenu.where, r.w, r.h);
+      let s = SYNC_BEGIN + "\x1B[?25l";
+      for (let i = 0; i < r.h; i++) s += cursorTo2(r.x, r.y + i) + "\x1B[0m" + (lines[i] ?? "");
+      this.out.write(s + SYNC_END);
+    } else if (this.placeholder) {
+      let s = SYNC_BEGIN + "\x1B[?25l";
+      for (let i = 0; i < r.h; i++) {
+        const line = (this.placeholder[i] ?? "").slice(0, r.w);
+        s += cursorTo2(r.x, r.y + i) + "\x1B[0m" + line + " ".repeat(Math.max(0, r.w - line.length));
+      }
+      this.out.write(s + SYNC_END);
+    }
+  }
+  drawChrome() {
+    if (this.tornDown || this.layout.tooSmall) return;
+    const { sidebar, sepX, statusY } = this.layout;
+    const lines = sidebarLines(this.boxes, this.selectedId, sidebar.w, sidebar.h);
+    const selIdx = this.boxes.findIndex((b) => b.id === this.selectedId);
+    const selRow = selIdx >= 0 ? SIDEBAR_HEADER_LINES + selIdx : -1;
+    let s = SYNC_BEGIN + "\x1B[0m";
+    for (let i = 0; i < lines.length; i++) {
+      const style = i === 0 ? SB_HEADER : i === selRow ? SB_SELECTED : SB_BODY;
+      s += cursorTo2(0, i) + style + lines[i] + SGR_RESET;
+    }
+    for (let y = 0; y < sidebar.h; y++) s += cursorTo2(sepX, y) + "\u2502";
+    let status;
+    if (this.flashMsg) {
+      const w = this.layout.cols;
+      const txt = ` ${this.flashMsg} `.slice(0, w).padEnd(w);
+      status = `\x1B[7m${txt}\x1B[0m`;
+    } else {
+      const stateLabel = this.selectedId === NEW_BOX_ID ? "create" : this.menu ? "menu" : this.session && this.activeMode === "shell" ? "shell" : void 0;
+      status = statusLine(this.selectedBox(), this.layout.cols, stateLabel);
+    }
+    s += cursorTo2(0, statusY) + status;
+    this.out.write(s + SYNC_END);
+  }
+  scheduleResize() {
+    if (this.resizeTimer) clearTimeout(this.resizeTimer);
+    this.resizeTimer = setTimeout(() => {
+      this.resizeTimer = null;
+      this.layout = computeLayout(this.out.columns ?? 100, this.out.rows ?? 30);
+      this.prevRows = null;
+      const r = this.layout.right;
+      if (this.session && !this.layout.tooSmall) {
+        this.session.resize(Math.max(1, r.w), Math.max(1, r.h));
+      }
+      this.out.write(SYNC_BEGIN + "\x1B[2J" + SYNC_END);
+      this.drawChrome();
+      this.render();
+    }, RESIZE_DEBOUNCE_MS);
+  }
+  teardown() {
+    if (this.tornDown) return;
+    this.tornDown = true;
+    if (this.renderTimer) clearTimeout(this.renderTimer);
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    if (this.resizeTimer) clearTimeout(this.resizeTimer);
+    if (this.flashTimer) clearTimeout(this.flashTimer);
+    this.parser.dispose();
+    this.disposeSession();
+    this.inp.off("data", this.onData);
+    this.out.off("resize", this.onResize);
+    if (this.inp.isTTY) this.inp.setRawMode(false);
+    this.inp.pause();
+    this.out.write(MOUSE_DISABLE_SEQ + "\x1B[?25h\x1B[0m\x1B[?1049l");
+    this.resolveDone?.();
+  }
+};
+
+// src/commands/dashboard.ts
+function sortBoxes(boxes) {
+  return [...boxes].sort((a, b) => {
+    const ap = a.projectRoot ?? "";
+    const bp = b.projectRoot ?? "";
+    if (ap !== bp) return ap.localeCompare(bp);
+    const ai = a.projectIndex ?? Number.POSITIVE_INFINITY;
+    const bi = b.projectIndex ?? Number.POSITIVE_INFINITY;
+    if (ai !== bi) return ai - bi;
+    return a.name.localeCompare(b.name);
+  });
+}
+function scoped(all, projectRoot, boxes) {
+  return sortBoxes(all ? boxes : boxes.filter((b) => b.projectRoot === projectRoot));
+}
+function toSidebar(b) {
+  return { id: b.id, name: b.name, state: b.state, claudeActivity: b.claudeActivity };
+}
+var dashboardCommand = new Command7("dashboard").description("Box list + the selected box live Agent session").argument("[box]", "initial box (default: first running box; -p restricts to the cwd project)").option("-p, --project", "only this project's boxes (default: all boxes globally)").action(async (idOrName, opts) => {
+  try {
+    if (!process.stdout.isTTY || !process.stdin.isTTY) {
+      log9.error("agentbox dashboard needs an interactive terminal");
+      process.exit(2);
+    }
+    let ptySpawn;
+    let termCtor;
+    try {
+      const ptyMod = await import("@homebridge/node-pty-prebuilt-multiarch");
+      const xtermMod = await import("@xterm/headless");
+      const spawn5 = ptyMod["spawn"] ?? ptyMod["default"]?.["spawn"];
+      const Terminal = xtermMod["Terminal"] ?? xtermMod["default"]?.["Terminal"];
+      if (typeof spawn5 !== "function" || typeof Terminal !== "function") {
+        throw new Error("terminal backend missing expected exports");
+      }
+      ptySpawn = spawn5;
+      termCtor = Terminal;
+    } catch {
+      log9.error(
+        "agentbox dashboard is unavailable here (native terminal backend failed to load)"
+      );
+      log9.info("use `agentbox claude` / `agentbox claude attach` instead");
+      process.exit(2);
+    }
+    const project = await findProjectRoot(process.cwd());
+    let showAll = !opts.project;
+    const full = await listBoxes();
+    const scoped0 = scoped(showAll, project.root, full);
+    let initialId;
+    if (idOrName !== void 0) {
+      const picked = await resolveBoxOrExit(idOrName);
+      initialId = picked.id;
+      if (!scoped0.some((b) => b.id === picked.id)) showAll = true;
+    } else if (scoped0.length === 0) {
+      initialId = NEW_BOX_ID;
+    } else {
+      initialId = (scoped0.find((b) => b.state === "running") ?? scoped0[0]).id;
+    }
+    const newBoxEntry = { id: NEW_BOX_ID, name: NEW_BOX_LABEL, state: "new" };
+    const listCandidates = async () => [
+      newBoxEntry,
+      ...scoped(showAll, project.root, await listBoxes()).map(toSidebar)
+    ];
+    const resolveTarget = async (boxId) => {
+      if (boxId === NEW_BOX_ID) return { kind: "create-menu", where: project.root };
+      const box = (await listBoxes()).find((b) => b.id === boxId);
+      if (!box) return { kind: "placeholder", lines: ["", "  box not found"] };
+      if (box.state !== "running") {
+        return {
+          kind: "placeholder",
+          lines: [
+            "",
+            `  box ${box.name} is ${box.state}.`,
+            `  Start it: agentbox start ${box.name}`
+          ]
+        };
+      }
+      const info = await claudeSessionInfo(box.container);
+      if (info.running) {
+        return {
+          kind: "attach",
+          argv: buildClaudeDashboardAttachArgv(box.container, info.sessionName)
+        };
+      }
+      return { kind: "menu" };
+    };
+    const findBox2 = async (boxId) => {
+      const box = (await listBoxes()).find((b) => b.id === boxId);
+      if (!box) throw new Error("box not found");
+      if (box.state !== "running") throw new Error(`box is ${box.state}`);
+      return box;
+    };
+    const startClaude = async (boxId) => {
+      const box = await findBox2(boxId);
+      await rebuildPluginNativeDeps(box.container, {
+        volume: box.claudeConfigVolume
+      });
+      await startClaudeSession({ container: box.container, claudeArgs: [], boxName: box.name });
+      const info = await claudeSessionInfo(box.container);
+      return {
+        kind: "attach",
+        argv: buildClaudeDashboardAttachArgv(box.container, info.sessionName),
+        mode: "claude"
+      };
+    };
+    const openShell = async (boxId) => {
+      const box = await findBox2(boxId);
+      return { kind: "attach", argv: buildShellArgv(box.container), mode: "shell" };
+    };
+    const createNewBox = async (withClaude, onProgress) => {
+      const cfg = await loadEffectiveConfig(project.root);
+      const auth = await resolveClaudeAuth(process.env);
+      const checkpointRef = cfg.effective.box.defaultCheckpoint.length > 0 ? cfg.effective.box.defaultCheckpoint : void 0;
+      const result = await createBox({
+        workspacePath: project.root,
+        useSnapshot: cfg.effective.box.hostSnapshot ?? true,
+        checkpointRef,
+        image: cfg.effective.box.image,
+        claudeConfig: { isolate: cfg.effective.box.isolateClaudeConfig },
+        claudeEnv: auth.env,
+        withPlaywright: cfg.effective.box.withPlaywright || cfg.effective.browser.default !== "agent-browser",
+        withEnv: cfg.effective.box.withEnv,
+        vnc: { enabled: cfg.effective.box.vnc },
+        docker: { sharedCache: cfg.effective.box.dockerCacheShared },
+        limits: resolveLimits(cfg.effective.box, {}),
+        projectRoot: project.root,
+        onLog: onProgress
+      });
+      if (!withClaude) return { boxId: result.record.id };
+      await rebuildPluginNativeDeps(result.record.container, {
+        volume: result.record.claudeConfigVolume
+      });
+      await startClaudeSession({
+        container: result.record.container,
+        claudeArgs: [],
+        boxName: result.record.name
+      });
+      const info = await claudeSessionInfo(result.record.container);
+      return {
+        boxId: result.record.id,
+        attach: {
+          kind: "attach",
+          argv: buildClaudeDashboardAttachArgv(result.record.container, info.sessionName),
+          mode: "claude"
+        }
+      };
+    };
+    const detach = (cmd, args) => {
+      spawn2(cmd, args, { detached: true, stdio: "ignore" }).unref();
+    };
+    const findEndpointUrl = async (boxId, kind) => {
+      const box = (await listBoxes()).find((b) => b.id === boxId);
+      if (!box) return { name: boxId, url: null };
+      const ep = box.endpoints.endpoints.find((e) => e.kind === kind);
+      return { name: box.name, url: ep && ep.reachable && ep.url ? ep.url : null };
+    };
+    const openVnc = async (boxId) => {
+      const { url } = await findEndpointUrl(boxId, "vnc");
+      if (!url) return "VNC not available for this box";
+      try {
+        const box = await findBox2(boxId);
+        const br = await ensureBoxBrowser(box.container);
+        if (!br.up) return `VNC: in-box browser unavailable (${br.reason ?? "box not running?"})`;
+      } catch {
+      }
+      detach("open", [url]);
+      return "Opening VNC in browser\u2026";
+    };
+    const openWeb = async (boxId) => {
+      const box = (await listBoxes()).find((b) => b.id === boxId);
+      if (!box) return "box not found";
+      const ep = box.endpoints.endpoints.find((e) => e.kind === "web");
+      const url = ep && ep.reachable && ep.url ? ep.url : `http://${box.endpoints.domain}`;
+      detach("open", [url]);
+      return `Opening ${url.replace(/^https?:\/\//, "")}\u2026`;
+    };
+    const openCode = async (boxId) => {
+      const box = (await listBoxes()).find((b) => b.id === boxId);
+      if (!box) return "box not found";
+      detach(process.execPath, [process.argv[1], "code", box.name, "--no-wait"]);
+      return "Launching VS Code / Cursor\u2026";
+    };
+    const compositor = new Compositor(
+      {
+        ptySpawn,
+        termCtor,
+        listCandidates,
+        resolveTarget,
+        startClaude,
+        openShell,
+        createNewBox,
+        openVnc,
+        openCode,
+        openWeb
+      },
+      initialId
+    );
+    await compositor.run();
+    process.exit(0);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/destroy.ts
+import { confirm as confirm4, isCancel as isCancel4, log as log10 } from "@clack/prompts";
+import { Command as Command8 } from "commander";
+var destroyCommand = new Command8("destroy").alias("rm").description("Destroy a box and discard its upper volume").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("-y, --yes", "skip the confirmation prompt").option("--keep-snapshot", "don't delete the snapshot dir under ~/.agentbox/snapshots/").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    if (!opts.yes) {
+      log10.warn(`This will discard the upper volume \u2014 agent work-in-progress is lost.`);
+      log10.info(`id:        ${box.id}`);
+      log10.info(`container: ${box.container}`);
+      log10.info(`upper:     ${box.upperVolume}`);
+      if (box.snapshotDir) {
+        log10.info(`snapshot:  ${box.snapshotDir}${opts.keepSnapshot ? " (will be kept)" : ""}`);
+      }
+      const ok = await confirm4({
+        message: "Destroy this box?",
+        initialValue: false
+      });
+      if (isCancel4(ok) || !ok) {
+        log10.info("cancelled");
+        return;
+      }
+    }
+    const result = await destroyBox(box.id, { keepSnapshot: opts.keepSnapshot });
+    const out = [`destroyed ${result.record.container}`];
+    if (result.removedContainer) out.push("  \u2713 container removed");
+    out.push(`  \u2713 volumes removed: ${result.removedVolumes.join(", ")}`);
+    if (result.removedSnapshot) out.push(`  \u2713 snapshot removed: ${result.removedSnapshot}`);
+    else if (box.snapshotDir && opts.keepSnapshot) {
+      out.push(`  \xB7 snapshot kept: ${box.snapshotDir}`);
+    }
+    process.stdout.write(out.join("\n") + "\n");
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/list.ts
+import { log as log11 } from "@clack/prompts";
+import { Command as Command9 } from "commander";
+import { pathToFileURL } from "url";
+
+// src/hyperlink.ts
+import { supportsHyperlink } from "supports-hyperlinks";
+var ESC2 = "\x1B";
+var ST = `${ESC2}\\`;
+function hyperlink(label, url, stream) {
+  const out = stream ?? process.stdout;
+  if (!supportsHyperlink(out)) return label;
+  return `${ESC2}]8;;${url}${ST}${label}${ESC2}]8;;${ST}`;
+}
+
+// src/watch.ts
+function withWatchOptions(cmd) {
+  return cmd.option("-w, --watch", "redraw continuously until interrupted (Ctrl-C)").option("--interval <seconds>", "refresh interval for --watch", "2");
+}
+function parseIntervalMs(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return 2e3;
+  return Math.max(250, Math.round(n * 1e3));
+}
+async function watchRender(produce, rawInterval) {
+  const ms = parseIntervalMs(rawInterval);
+  const intervalLabel = `${String(ms / 1e3)}s`;
+  process.stdout.write("\x1B[?25l");
+  process.once("exit", () => process.stdout.write("\x1B[?25h"));
+  process.once("SIGINT", () => process.exit(0));
+  const sleep = (d) => new Promise((r) => setTimeout(r, d));
+  for (; ; ) {
+    let body;
+    try {
+      body = await produce();
+    } catch (err) {
+      body = `error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const ts = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+    process.stdout.write("\x1B[2J\x1B[3J\x1B[H");
+    process.stdout.write(
+      `watching every ${intervalLabel} \u2014 ${ts} \u2014 Ctrl-C to exit
+
+${body.replace(/\n+$/, "")}
+`
+    );
+    await sleep(ms);
+  }
+}
+
+// src/commands/list.ts
+var plain = (s) => ({ text: s, width: s.length });
+function middleTruncate(s, n) {
+  if (s.length <= n) return s;
+  if (n <= 1) return s.length > 0 ? "\u2026" : "";
+  const slash = s.lastIndexOf("/");
+  const tail = slash >= 0 ? s.slice(slash) : "";
+  if (tail.length > 0 && tail.length + 2 <= n) {
+    const head = s.slice(0, n - 1 - tail.length);
+    return `${head}\u2026${tail}`;
+  }
+  return s.slice(0, n - 1) + "\u2026";
+}
+function urlCell(box, stream) {
+  const eps = box.endpoints.endpoints;
+  const vnc = eps.find((e) => e.kind === "vnc" && e.url);
+  const primary = eps.find((e) => e.kind === "web" && e.url) ?? eps.find((e) => e.kind === "service" && e.url) ?? vnc;
+  if (!primary?.url) return plain("");
+  let display;
+  try {
+    display = new URL(primary.url).host;
+  } catch {
+    display = primary.url;
+  }
+  const parts = [
+    { text: hyperlink(display, primary.url, stream), width: display.length }
+  ];
+  if (vnc?.url && vnc !== primary) {
+    const label = "(VNC)";
+    parts.push({ text: hyperlink(label, vnc.url, stream), width: label.length });
+  }
+  const sep = " ";
+  return {
+    text: parts.map((p) => p.text).join(sep),
+    width: parts.reduce((a, p) => a + p.width, 0) + sep.length * (parts.length - 1)
+  };
+}
+function workspaceCell(path, target, stream) {
+  const display = middleTruncate(path, target);
+  let url;
+  try {
+    url = pathToFileURL(path).href;
+  } catch {
+    return { text: display, width: display.length };
+  }
+  return { text: hyperlink(display, url, stream), width: display.length };
+}
+function renderTable(boxes, stream) {
+  const header = ["N", "NAME", "STATE", "CLAUDE", "URL", "WORKSPACE"];
+  const lead = boxes.map((b) => [
+    plain(typeof b.projectIndex === "number" ? String(b.projectIndex) : ""),
+    plain(b.name),
+    plain(b.state),
+    plain(b.claudeActivity ?? ""),
+    urlCell(b, stream)
+  ]);
+  const leadHeader = header.slice(0, 5).map(plain);
+  const fixedWidths = [0, 1, 2, 3, 4].map(
+    (col) => Math.max(leadHeader[col]?.width ?? 0, ...lead.map((r) => r[col]?.width ?? 0))
+  );
+  const term2 = stream.columns && stream.columns > 0 ? stream.columns : 120;
+  const fixedTotal = fixedWidths.reduce((a, b) => a + b, 0) + header.length * 2;
+  const naturalWs = Math.max(
+    header[5]?.length ?? 0,
+    ...boxes.map((b) => b.workspacePath.length)
+  );
+  const wsWidth = Math.min(naturalWs, Math.max(16, term2 - fixedTotal));
+  const widths = [...fixedWidths, wsWidth];
+  const rows = boxes.map((b, idx) => [
+    ...lead[idx],
+    workspaceCell(b.workspacePath, wsWidth, stream)
+  ]);
+  const all = [[...leadHeader, plain(header[5])], ...rows];
+  const padCell = (cell, col) => {
+    const target = widths[col] ?? 0;
+    return cell.text + " ".repeat(Math.max(0, target - cell.width));
+  };
+  return all.map(
+    (row2) => row2.map((cell, i) => padCell(cell ?? plain(""), i)).join("  ").trimEnd()
+  ).join("\n");
+}
+async function buildListText() {
+  const boxes = await listBoxes();
+  if (boxes.length === 0) return "no boxes \u2014 run `agentbox create` to make one";
+  return renderTable(boxes, process.stdout);
+}
+var listCommand2 = withWatchOptions(
+  new Command9("list").alias("ls").description("List all known agent boxes").option("-j, --json", "machine-readable JSON output")
+).action(async (opts) => {
+  if (opts.json && opts.watch) {
+    log11.error("cannot combine --json with --watch");
+    process.exit(2);
+  }
+  if (opts.watch) {
+    await watchRender(buildListText, opts.interval);
+    return;
+  }
+  if (opts.json) {
+    const boxes = await listBoxes();
+    process.stdout.write(JSON.stringify(boxes, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(await buildListText() + "\n");
+});
+
+// src/commands/logs.ts
+import { log as log12 } from "@clack/prompts";
+import { Command as Command10 } from "commander";
+import { spawn as spawn3 } from "child_process";
+var logsCommand = new Command10("logs").description("Print recent log lines from a box service; -f to stream").argument(
+  "[box]",
+  "box ref (optional when cwd has exactly 1 box): project index, id, id prefix, name, or container"
+).argument("[service]", "service name from agentbox.yaml").option("-n, --tail <n>", "how many recent lines to print first", "200").option("-f, --follow", "keep the connection open and stream new lines").action(async (boxArg, serviceArg, opts) => {
+  try {
+    let idOrName;
+    let service;
+    if (serviceArg !== void 0) {
+      idOrName = boxArg;
+      service = serviceArg;
+    } else {
+      idOrName = void 0;
+      service = boxArg;
+    }
+    if (!service) {
+      log12.error("missing <service> argument");
+      log12.info("usage: agentbox logs [box] <service> [-n N] [-f]");
+      process.exit(2);
+    }
+    const box = await resolveBoxOrExit(idOrName);
+    const tail = String(Number.parseInt(opts.tail, 10) || 200);
+    const args = ["agentbox-ctl", "logs", service, "--tail", tail];
+    if (opts.follow) args.push("--follow");
+    if (!opts.follow) {
+      const proc = await execInBox(box.container, args, { user: "vscode" });
+      if (proc.exitCode !== 0) {
+        log12.error(`agentbox-ctl logs failed: ${proc.stderr || proc.stdout}`);
+        process.exit(1);
+      }
+      process.stdout.write(proc.stdout);
+      if (!proc.stdout.endsWith("\n")) process.stdout.write("\n");
+      return;
+    }
+    const child = spawn3("docker", ["exec", "--user", "vscode", box.container, ...args], {
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/open.ts
+import { log as log13 } from "@clack/prompts";
+import { Command as Command11 } from "commander";
+
+// src/commands/path.ts
+async function runPath(box, opts) {
+  try {
+    const layer = opts.upper ? "upper" : "merged";
+    const { record, paths } = await getBoxHostPaths(box.id);
+    if (opts.refresh) {
+      const refreshed = await refreshExport(record, {
+        layer,
+        includeNodeModules: opts.includeNodeModules
+      });
+      process.stdout.write(`${refreshed.hostPath}
+`);
+      return;
+    }
+    const path = layer === "upper" ? paths.upperLiveOnHost ?? paths.upperExport : paths.mergedExport;
+    process.stdout.write(`${path}
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+}
+
+// src/commands/open.ts
+var openCommand = new Command11("open").description("Open a box's merged workspace in Finder (snapshot of the agent's view)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--upper", "open just the writes layer (live on OrbStack, snapshot on Docker Desktop)").option("--no-refresh", "skip the rsync; open whatever's already on disk").option(
+  "--include-node-modules",
+  "include /workspace/node_modules in the merged export (off by default)"
+).option("--path", "print the host workspace path instead of launching Finder").option("--print", "alias of --path").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    if (opts.path || opts.print) {
+      await runPath(box, {
+        upper: opts.upper,
+        refresh: opts.refresh,
+        // print refreshes by default; --no-refresh skips
+        includeNodeModules: opts.includeNodeModules
+      });
+      return;
+    }
+    const layer = opts.upper ? "upper" : "merged";
+    const result = await openBoxInFinder(box.id, {
+      layer,
+      includeNodeModules: opts.includeNodeModules,
+      noRefresh: !opts.refresh,
+      noOpen: false
+    });
+    const liveNote = !result.copied ? " (live)" : result.usedFallback ? " (tar fallback)" : "";
+    process.stdout.write(`opened ${result.hostPath}${liveNote}
+`);
+    if (opts.upper && result.engine !== "orbstack" && result.copied) {
+      log13.info(
+        "Tip: live upper-layer browsing requires OrbStack. Re-run `agentbox open --upper` to refresh."
+      );
+    }
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/pause.ts
+import { Command as Command12 } from "commander";
+var pauseCommand = new Command12("pause").description("Freeze a box (docker pause \u2014 0 CPU, RAM stays mapped)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).action(async (idOrName) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const record = await pauseBox(box.id);
+    process.stdout.write(`paused ${record.container}
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/prune.ts
+import { confirm as confirm5, isCancel as isCancel5, log as log14 } from "@clack/prompts";
+import { Command as Command13 } from "commander";
+function totalRemovals(r, projectConfigs) {
+  return r.removedRecords.length + r.removedContainers.length + r.removedVolumes.length + r.removedSnapshotDirs.length + r.removedBoxDirs.length + projectConfigs.length;
+}
+function summary(r, projectConfigs) {
+  const lines = [];
+  if (r.removedRecords.length > 0) {
+    lines.push(
+      `  state records (${String(r.removedRecords.length)}): ${r.removedRecords.join(", ")}`
+    );
+  }
+  if (r.removedContainers.length > 0) {
+    lines.push(
+      `  containers    (${String(r.removedContainers.length)}): ${r.removedContainers.join(", ")}`
+    );
+  }
+  if (r.removedVolumes.length > 0) {
+    lines.push(
+      `  volumes       (${String(r.removedVolumes.length)}): ${r.removedVolumes.join(", ")}`
+    );
+  }
+  if (r.removedSnapshotDirs.length > 0) {
+    lines.push(
+      `  snapshot dirs (${String(r.removedSnapshotDirs.length)}): ${r.removedSnapshotDirs.join(", ")}`
+    );
+  }
+  if (r.removedBoxDirs.length > 0) {
+    lines.push(
+      `  box dirs      (${String(r.removedBoxDirs.length)}): ${r.removedBoxDirs.join(", ")}`
+    );
+  }
+  if (projectConfigs.length > 0) {
+    lines.push(
+      `  project configs (${String(projectConfigs.length)}): ${projectConfigs.join(", ")}`
+    );
+  }
+  return lines.length > 0 ? lines.join("\n") : "  (nothing to remove)";
+}
+async function liveProjectRoots() {
+  try {
+    const boxes = await listBoxes();
+    return boxes.map((b) => b.projectRoot).filter((p) => typeof p === "string");
+  } catch {
+    return [];
+  }
+}
+var pruneCommand = new Command13("prune").description("Clean up orphan state.json records (and with --all, orphan docker resources)").option("--dry-run", "show what would be removed, don't change anything").option(
+  "--all",
+  "also remove orphan agentbox-* containers, volumes, snapshot dirs, and orphan per-project config dirs"
+).option("-y, --yes", "skip the confirmation prompt").action(async (opts) => {
+  try {
+    const dryRun = opts.dryRun ?? false;
+    const protectedPaths = opts.all ? await liveProjectRoots() : [];
+    const preview = await pruneBoxes({ dryRun: true, all: opts.all });
+    const previewProjects = opts.all ? (await pruneOrphanProjectConfigs({ dryRun: true, protectedPaths })).removed.map(
+      (r) => r.originalPath
+    ) : [];
+    if (totalRemovals(preview, previewProjects) === 0) {
+      process.stdout.write("nothing to prune\n");
+      return;
+    }
+    log14.info(`would remove:
+${summary(preview, previewProjects)}`);
+    if (dryRun) return;
+    if (!opts.yes) {
+      const ok = await confirm5({ message: "Proceed with prune?", initialValue: true });
+      if (isCancel5(ok) || !ok) {
+        log14.info("cancelled");
+        return;
+      }
+    }
+    const result = await pruneBoxes({ all: opts.all });
+    const removedProjects = opts.all ? (await pruneOrphanProjectConfigs({ protectedPaths })).removed.map((r) => r.originalPath) : [];
+    process.stdout.write(`pruned:
+${summary(result, removedProjects)}
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/pull.ts
+import { confirm as confirm9, isCancel as isCancel9, log as log18 } from "@clack/prompts";
+import { Command as Command17 } from "commander";
+
+// src/commands/pull-claude.ts
+import { confirm as confirm6, isCancel as isCancel6, log as log15 } from "@clack/prompts";
+import { Command as Command14 } from "commander";
+function tag(item) {
+  const noun = item.category === "plugins" ? "plugin" : item.category.replace(/s$/, "");
+  return `  ${item.category}/${item.name} (new ${noun})`;
+}
+var pullClaudeCommand = new Command14("claude").description(
+  "Pull box-installed Claude skills/plugins/agents/commands back to host ~/.claude (additive)"
+).argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("-y, --yes", "skip the confirmation prompt").option("--dry-run", "list new items and exit; don't write").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const volume = box.claudeConfigVolume ?? resolveClaudeVolume({ isolate: false, boxId: box.id }).volume;
+    if (volume === SHARED_CLAUDE_VOLUME) {
+      log15.warn(
+        `Reading the shared ${SHARED_CLAUDE_VOLUME} volume \u2014 it aggregates Claude extensions installed in ANY box, not just ${box.name}.`
+      );
+    }
+    const image = box.image || DEFAULT_BOX_IMAGE;
+    const preview = await pullClaudeExtras({ volume }, { image, dryRun: true });
+    if (preview.newItems.length === 0 && preview.mergedRegistries.length === 0) {
+      process.stdout.write("no new Claude extensions to pull into ~/.claude\n");
+      return;
+    }
+    for (const item of preview.newItems) process.stdout.write(`${tag(item)}
+`);
+    for (const reg of preview.mergedRegistries) {
+      process.stdout.write(`  plugins/${reg} (merge new entries)
+`);
+    }
+    if (opts.dryRun) {
+      process.stdout.write(
+        `
+[dry-run] ${preview.newItems.length} item(s)${preview.mergedRegistries.length > 0 ? ` + ${preview.mergedRegistries.length} registry merge(s)` : ""} would be pulled into ~/.claude
+`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm6({
+        message: `Pull ${preview.newItems.length} new Claude extension(s) into ~/.claude? (existing items are never overwritten)`,
+        initialValue: false
+      });
+      if (isCancel6(ok) || !ok) {
+        log15.info("cancelled");
+        return;
+      }
+    }
+    const result = await pullClaudeExtras({ volume }, { image, dryRun: false });
+    process.stdout.write(
+      `pulled ${result.newItems.length} extension(s)${result.mergedRegistries.length > 0 ? `, merged ${result.mergedRegistries.join(", ")}` : ""} into ~/.claude
+`
+    );
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/pull-config.ts
+import { confirm as confirm7, isCancel as isCancel7, log as log16 } from "@clack/prompts";
+import { Command as Command15 } from "commander";
+function tagChange(line) {
+  const sp = line.indexOf(" ");
+  const code = sp === -1 ? line : line.slice(0, sp);
+  const path = sp === -1 ? "" : line.slice(sp + 1);
+  const isNew = /^>f\++$/.test(code);
+  return `  ${path} ${isNew ? "(new)" : "(overwrites host)"}`;
+}
+var CONFIG_PATTERNS = ["agentbox.yaml"];
+var pullConfigCommand = new Command15("config").description("Pull agentbox.yaml box -> host").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("-y, --yes", "skip the confirmation prompt").option("--dry-run", "list matched files and exit; don't write").option("--no-refresh", "skip the box->scratch-dir rsync step").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log16.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log16.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    log16.info(`agentbox.yaml bypasses gitignore and copies directly into ${box.workspacePath}`);
+    const preview = await pullToHost(box, {
+      dryRun: true,
+      respectGitignore: false,
+      envPatterns: CONFIG_PATTERNS,
+      noRefresh: !opts.refresh
+    });
+    if (preview.changes.length === 0) {
+      process.stdout.write(`no config file to pull into ${box.workspacePath}
+`);
+      return;
+    }
+    for (const line of preview.changes) process.stdout.write(`${tagChange(line)}
+`);
+    if (opts.dryRun) {
+      process.stdout.write(
+        `
+[dry-run] ${preview.changes.length} config file(s) would change in ${box.workspacePath}
+`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm7({
+        message: `Pull ${preview.changes.length} config file(s) into ${box.workspacePath}? (existing files will be overwritten)`,
+        initialValue: false
+      });
+      if (isCancel7(ok) || !ok) {
+        log16.info("cancelled");
+        return;
+      }
+    }
+    const result = await pullToHost(box, {
+      dryRun: false,
+      respectGitignore: false,
+      envPatterns: CONFIG_PATTERNS,
+      // The dry-run pass above already refreshed (or intentionally skipped)
+      // the scratch dir — don't rsync box->scratch a second time.
+      noRefresh: true
+    });
+    process.stdout.write(
+      `pulled ${result.changes.length} config file(s) into ${result.hostPath}
+`
+    );
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/pull-env.ts
+import { confirm as confirm8, isCancel as isCancel8, log as log17 } from "@clack/prompts";
+import { Command as Command16 } from "commander";
+function tagChange2(line) {
+  const sp = line.indexOf(" ");
+  const code = sp === -1 ? line : line.slice(0, sp);
+  const path = sp === -1 ? "" : line.slice(sp + 1);
+  const isNew = /^>f\++$/.test(code);
+  return `  ${path} ${isNew ? "(new)" : "(overwrites host)"}`;
+}
+var pullEnvCommand = new Command16("env").description(
+  "Pull gitignored env/config files (.env*, .envrc, secrets.toml, agentbox.yaml, ...) box -> host"
+).argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("-y, --yes", "skip the confirmation prompt").option("--dry-run", "list matched files and exit; don't write").option(
+  "--pattern <glob>",
+  "extra basename glob to match (repeatable, adds to defaults)",
+  (v, acc) => [...acc, v],
+  []
+).option("--no-refresh", "skip the box->scratch-dir rsync step").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log17.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log17.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    log17.info(
+      `env/config files bypass gitignore and copy directly into ${box.workspacePath}`
+    );
+    const patterns = [...DEFAULT_ENV_PATTERNS, ...opts.pattern];
+    const preview = await pullToHost(box, {
+      dryRun: true,
+      respectGitignore: false,
+      envPatterns: patterns,
+      noRefresh: !opts.refresh
+    });
+    if (preview.changes.length === 0) {
+      process.stdout.write(`no env/config files to pull into ${box.workspacePath}
+`);
+      return;
+    }
+    for (const line of preview.changes) process.stdout.write(`${tagChange2(line)}
+`);
+    if (opts.dryRun) {
+      process.stdout.write(
+        `
+[dry-run] ${preview.changes.length} env/config file(s) would change in ${box.workspacePath}
+`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm8({
+        message: `Pull ${preview.changes.length} env/config file(s) into ${box.workspacePath}? (existing files will be overwritten)`,
+        initialValue: false
+      });
+      if (isCancel8(ok) || !ok) {
+        log17.info("cancelled");
+        return;
+      }
+    }
+    const result = await pullToHost(box, {
+      dryRun: false,
+      respectGitignore: false,
+      envPatterns: patterns,
+      // The dry-run pass above already refreshed (or intentionally skipped)
+      // the scratch dir — don't rsync box->scratch a second time.
+      noRefresh: true
+    });
+    process.stdout.write(
+      `pulled ${result.changes.length} env/config file(s) into ${result.hostPath}
+`
+    );
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/pull.ts
+var pullCommand = new Command17("pull").enablePositionalOptions().description("Pull a box's /workspace back into your host workspace dir (gitignore-aware)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("-y, --yes", "skip the confirmation prompt").option("--dry-run", "print the change list and exit; don't write").option(
+  "--no-respect-gitignore",
+  "disable git ls-files mode; use --exclude=node_modules,.git instead"
+).option(
+  "--include-node-modules",
+  "do not exclude node_modules in fallback mode (no effect in gitignore mode)"
+).option("--no-refresh", "skip the box->scratch-dir rsync step (use whatever's already there)").option(
+  "--with-env",
+  "also pull env/config files (.env*, .envrc, secrets.toml, agentbox.yaml, ...) ignoring gitignore"
+).option(
+  "--pattern <glob>",
+  "extra env basename glob; only effective with --with-env (repeatable)",
+  (v, acc) => [...acc, v],
+  []
+).action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log18.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log18.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    const rootWorktree = box.gitWorktrees?.find((w) => w.kind === "root");
+    if (rootWorktree) {
+      log18.warn(
+        `This box has been committing to branch \`${rootWorktree.branch}\` in a separate worktree.
+For a git-aware merge instead of a file copy, run from your checkout:
+  git merge ${rootWorktree.branch}
+Continuing with rsync into ${box.workspacePath}`
+      );
+    }
+    const envPatterns = opts.withEnv ? [...DEFAULT_ENV_PATTERNS, ...opts.pattern] : void 0;
+    const preview = await pullToHost(box, {
+      dryRun: true,
+      respectGitignore: opts.respectGitignore,
+      includeNodeModules: opts.includeNodeModules,
+      envPatterns,
+      noRefresh: !opts.refresh
+    });
+    if (preview.changes.length === 0) {
+      process.stdout.write(`no changes to pull into ${box.workspacePath}
+`);
+      return;
+    }
+    if (opts.dryRun) {
+      for (const line of preview.changes) process.stdout.write(`${line}
+`);
+      process.stdout.write(
+        `
+[dry-run] ${preview.changes.length} file(s) would change in ${box.workspacePath}
+`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm9({
+        message: `Pull ${preview.changes.length} changed file(s)${opts.withEnv ? " (incl. env/config)" : ""} into ${box.workspacePath}?`,
+        initialValue: false
+      });
+      if (isCancel9(ok) || !ok) {
+        log18.info("cancelled");
+        return;
+      }
+    }
+    const result = await pullToHost(box, {
+      dryRun: false,
+      respectGitignore: opts.respectGitignore,
+      includeNodeModules: opts.includeNodeModules,
+      envPatterns,
+      // The dry-run pass above already refreshed (or intentionally skipped)
+      // the scratch dir — don't rsync box->scratch a second time.
+      noRefresh: true
+    });
+    process.stdout.write(
+      `updated ${result.changes.length} file(s) in ${result.hostPath}${result.usedGitignore ? "" : " (exclude-list mode)"}
+`
+    );
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+pullCommand.addCommand(pullEnvCommand);
+pullCommand.addCommand(pullClaudeCommand);
+pullCommand.addCommand(pullConfigCommand);
+
+// src/commands/screen.ts
+import { spawnSync as spawnSync5 } from "child_process";
+import { log as log19 } from "@clack/prompts";
+import { Command as Command18 } from "commander";
+var screenCommand = new Command18("screen").description("Open a box's VNC (noVNC) viewer in the browser (auto-unpause/start)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--print", "print the URL to stdout instead of launching the browser").option("--loopback", "use the 127.0.0.1 URL instead of the OrbStack .orb.local URL").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    if (!box.vncEnabled) {
+      throw new Error(`VNC is disabled for box ${box.name} \u2014 recreate without \`--no-vnc\``);
+    }
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log19.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log19.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    const br = await ensureBoxBrowser(box.container);
+    if (br.up && !br.alreadyRunning) log19.info("started in-box browser");
+    else if (!br.up) log19.warn(`could not start in-box browser: ${br.reason ?? "unknown"}`);
+    const engine = await detectEngine();
+    const urls = buildVncUrls(box, engine);
+    const url = opts.loopback ? urls.loopbackUrl : urls.orbUrl ?? urls.loopbackUrl;
+    if (!url) {
+      throw new Error(
+        `VNC URL unavailable (daemon may not be up); try \`agentbox inspect ${box.name}\``
+      );
+    }
+    if (opts.print) {
+      process.stdout.write(`${url}
+`);
+      return;
+    }
+    const opened = spawnSync5("open", [url], { stdio: "inherit" });
+    if (opened.status !== 0) {
+      throw new Error(`open ${url} failed (exit ${String(opened.status ?? "n/a")})`);
+    }
+    process.stdout.write(`opened ${url}
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/shell.ts
+import { spawnSync as spawnSync6 } from "child_process";
+import { log as log20 } from "@clack/prompts";
+import { Command as Command19 } from "commander";
+function buildShellCliOverrides(opts) {
+  const shell = {};
+  if (opts.user !== void 0) shell.user = opts.user;
+  if (opts.login === false) shell.login = false;
+  return Object.keys(shell).length > 0 ? { shell } : {};
+}
+var shellCommand = new Command19("shell").description("Open an interactive bash shell in a box (auto-unpause/start)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).argument(
+  "[cmd...]",
+  "optional one-shot command to run instead of an interactive shell; place after `--`, e.g. `agentbox shell smoke -- ls /workspace`"
+).option("--user <name>", "user inside the container (default from config; built-in: vscode)").option("--no-login", "invoke `bash` instead of `bash -l` (skip login profile)").action(async (idOrName, cmd, opts) => {
+  try {
+    const { box, shifted } = await resolveBoxOrShift(idOrName);
+    const effectiveCmd = shifted && idOrName ? [idOrName, ...cmd] : cmd;
+    const cfg = await loadEffectiveConfig(box.workspacePath, {
+      cliOverrides: buildShellCliOverrides(opts)
+    });
+    const user = cfg.effective.shell.user;
+    const login = cfg.effective.shell.login;
+    const insp = await inspectBox(box.id);
+    if (insp.state === "paused") {
+      log20.info("box is paused; unpausing");
+      await unpauseBox(box.id);
+    } else if (insp.state === "stopped") {
+      log20.info("box is stopped; starting (remounting overlay)");
+      await startBox(box.id);
+    } else if (insp.state === "missing") {
+      throw new Error(`box ${box.name} has no container; was it destroyed?`);
+    }
+    const term2 = process.env["TERM"] ?? "xterm-256color";
+    const bashArgs = [];
+    if (login) bashArgs.push("-l");
+    if (effectiveCmd.length > 0) bashArgs.push("-c", effectiveCmd.join(" "));
+    const ttyFlag = process.stdout.isTTY && process.stdin.isTTY ? "-it" : "-i";
+    const child = spawnSync6(
+      "docker",
+      [
+        "exec",
+        ttyFlag,
+        "-e",
+        `TERM=${term2}`,
+        "--user",
+        user,
+        box.container,
+        "bash",
+        ...bashArgs
+      ],
+      { stdio: "inherit" }
+    );
+    process.exit(child.status ?? 0);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/start.ts
+import { Command as Command20 } from "commander";
+var startCommand = new Command20("start").description("Start a stopped box (docker start + re-mount the FUSE overlay)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).action(async (idOrName) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const { record, overlayChecks } = await startBox(box.id);
+    process.stdout.write(`started ${record.container}
+`);
+    const failed = overlayChecks.filter((c) => !c.ok);
+    if (failed.length > 0) {
+      for (const c of failed) {
+        process.stderr.write(`  \u2717 ${c.name}: ${c.detail}
+`);
+      }
+      process.exit(1);
+    }
+    for (const c of overlayChecks) {
+      process.stdout.write(`  \u2713 ${c.name}
+`);
+    }
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/status.ts
+import { log as log22 } from "@clack/prompts";
+import { Command as Command21 } from "commander";
+
+// src/endpoints-render.ts
+function renderEndpointLines(endpoints, stream) {
+  if (endpoints.endpoints.length === 0) return [];
+  const entries = [
+    { name: "domain", value: endpoints.domain }
+  ];
+  for (const ep of endpoints.endpoints) {
+    if (ep.url) {
+      entries.push({ name: ep.name, value: hyperlink(ep.url, ep.url, stream) });
+    } else if (ep.kind === "vnc") {
+      entries.push({ name: ep.name, value: "enabled (URL unavailable \u2014 daemon may not be up)" });
+    } else if (ep.kind === "web") {
+      entries.push({
+        name: "web",
+        value: "reserved (set a service `expose:` in agentbox.yaml)"
+      });
+    } else {
+      entries.push({
+        name: ep.name,
+        value: `port ${String(ep.containerPort)} (box-only \u2014 not reachable from host)`
+      });
+    }
+  }
+  const nameWidth = Math.max(...entries.map((e) => e.name.length));
+  return entries.map((e) => `  ${e.name.padEnd(nameWidth)}  ${e.value}`);
+}
+
+// src/fmt.ts
+function fmtBytes(n) {
+  if (n === null || n === void 0) return "n/a";
+  if (n < 1024) return `${String(n)} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KiB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MiB`;
+  return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}
+function fmtPercent(n) {
+  return n === null || n === void 0 ? "\u2014" : `${n.toFixed(1)}%`;
+}
+function fmtAgo(iso) {
+  if (!iso) return null;
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return null;
+  const secs = Math.round((Date.now() - then) / 1e3);
+  if (secs < 0) return "just now";
+  if (secs < 45) return "just now";
+  const units = [
+    ["day", 86400],
+    ["hour", 3600],
+    ["minute", 60],
+    ["second", 1]
+  ];
+  for (const [name, size] of units) {
+    if (secs >= size) {
+      const n = Math.round(secs / size);
+      return `${String(n)} ${name}${n === 1 ? "" : "s"} ago`;
+    }
+  }
+  return "just now";
+}
+
+// src/commands/inspect.ts
+import { log as log21 } from "@clack/prompts";
+function fmtLimit(n, unit) {
+  return n && n > 0 ? `${String(n)}${unit}` : "unlimited";
+}
+async function renderText(i) {
+  const lim = i.record.resourceLimits;
+  const projectRoot = i.record.projectRoot ?? i.record.workspacePath;
+  const ckptBytes = await projectCheckpointVolumeBytes(projectRoot);
+  const upperHost = i.hostPaths.upperLiveOnHost ? `${i.hostPaths.upperLiveOnHost}  (live)` : `${i.hostPaths.upperExport}  (run \`agentbox open --upper\` to refresh)`;
+  const lines = [
+    `id            ${i.record.id}`,
+    `name          ${i.record.name}`,
+    `container     ${i.record.container}`,
+    `image         ${i.record.image}`,
+    `state         ${i.state}`,
+    `overlay       ${i.overlayMounted ? "mounted at /workspace" : "not mounted"}`,
+    `workspace     ${i.record.workspacePath}`,
+    `project       ${i.record.projectRoot ?? "(unset \u2014 pre-feature box)"}`,
+    `n             ${typeof i.record.projectIndex === "number" ? String(i.record.projectIndex) : "(none)"}`,
+    `lower         ${i.record.lowerPath}`,
+    `upper volume  ${i.upperVolume.name}${i.upperVolume.mountpoint ? `  (${i.upperVolume.mountpoint})` : ""}`,
+    `claude config ${i.record.claudeConfigVolume ?? "(none)"}`,
+    `claude session ${renderClaudeSession(i)}`,
+    `claude activity ${renderClaudeActivity(i)}`,
+    `persisted     ${renderPersisted(i)}`,
+    `playwright    ${i.record.withPlaywright ? "yes" : "no"}`,
+    `env files     ${i.record.withEnv ? "yes" : "no"}`,
+    "endpoints",
+    ...renderEndpoints(i),
+    `mem limit     ${lim?.memoryBytes ? fmtBytes(lim.memoryBytes) : "unlimited"}`,
+    `cpu limit     ${fmtLimit(lim?.cpus, "")}`,
+    `pids limit    ${fmtLimit(lim?.pidsLimit, "")}`,
+    `disk limit    ${lim?.disk ? `${lim.disk} (best-effort; no-op on overlay2/macOS)` : "unlimited"}`,
+    `snapshot dir  ${i.record.snapshotDir ?? "(none \u2014 live workspace mount)"}`,
+    `snapshot size ${fmtBytes(i.snapshotSizeBytes)}`,
+    `checkpoint vol ${ckptBytes === null ? "(none)" : fmtBytes(ckptBytes)}`,
+    `host export   ${i.hostPaths.mergedExport}  (run \`agentbox open\` to refresh)`,
+    `upper host    ${upperHost}`,
+    `created       ${i.record.createdAt}`
+  ];
+  return lines.join("\n");
+}
+function renderClaudeSession(i) {
+  if (i.claudeSession === null) return "(n/a \u2014 box not running)";
+  if (!i.claudeSession.running) return `not running ("${i.claudeSession.sessionName}")`;
+  const since = i.claudeSession.startedAt ? ` since ${i.claudeSession.startedAt}` : "";
+  return `running ("${i.claudeSession.sessionName}")${since}`;
+}
+function renderClaudeActivity(i) {
+  const c = i.persistedStatus?.claude;
+  if (!c) return "(none)";
+  return `${c.state}${c.updatedAt ? ` (updated ${c.updatedAt})` : ""}`;
+}
+function renderPersisted(i) {
+  const s = i.persistedStatus;
+  if (!s) return "(none)";
+  return `${s.timestamp} (${String(s.services.length)} svc, ${String(s.tasks.length)} tasks, ${String(s.ports.length)} ports)`;
+}
+function renderEndpoints(i) {
+  const lines = renderEndpointLines(i.endpoints, process.stdout);
+  return lines.length > 0 ? lines : ["  (none)"];
+}
+async function runInspect(box, opts) {
+  try {
+    if (opts.json && opts.watch) {
+      log21.error("cannot combine --json with --watch");
+      process.exit(2);
+    }
+    if (opts.watch) {
+      await watchRender(async () => renderText(await inspectBox(box.id)), opts.interval);
+      return;
+    }
+    const result = await inspectBox(box.id);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      process.stdout.write(await renderText(result) + "\n");
+    }
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+}
+
+// src/commands/status.ts
+var statusCommand = withWatchOptions(
+  new Command21("status").description("Show service + task status from a box's agentbox-ctl daemon").argument(
+    "[box]",
+    "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+  ).option("-j, --json", "machine-readable JSON output").option("--inspect", "show detailed box info (volumes, limits, paths) instead of service/task status")
+).action(async (idOrName, opts) => {
+  try {
+    if (opts.json && opts.watch) {
+      log22.error("cannot combine --json with --watch");
+      process.exit(2);
+    }
+    const box = await resolveBoxOrExit(idOrName);
+    if (opts.inspect) {
+      await runInspect(box, { json: opts.json, watch: opts.watch, interval: opts.interval });
+      return;
+    }
+    if (opts.watch) {
+      await watchRender(() => buildStatusText(box.id, box.container), opts.interval);
+      return;
+    }
+    if (opts.json) {
+      const inspected = await inspectBox(box.id);
+      const live = await fetchLive(inspected.state, box.container);
+      const resources = await boxResourceStats(inspected.record);
+      process.stdout.write(
+        JSON.stringify(
+          {
+            state: inspected.state,
+            source: live ? "live" : "persisted",
+            ...live ?? {},
+            resources,
+            claudeSession: inspected.claudeSession,
+            persisted: inspected.persistedStatus,
+            endpoints: inspected.endpoints
+          },
+          null,
+          2
+        ) + "\n"
+      );
+      return;
+    }
+    process.stdout.write(await buildStatusText(box.id, box.container) + "\n");
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+async function fetchLive(state, container) {
+  if (state !== "running") return null;
+  const proc = await execInBox(container, ["agentbox-ctl", "status", "--json"], {
+    user: "vscode"
+  });
+  if (proc.exitCode !== 0) return null;
+  try {
+    return JSON.parse(proc.stdout);
+  } catch {
+    return null;
+  }
+}
+async function buildStatusText(id, container) {
+  const inspected = await inspectBox(id);
+  const { state, endpoints, persistedStatus } = inspected;
+  const live = await fetchLive(state, container);
+  const out = [];
+  const epLines = renderEndpointLines(endpoints, process.stdout);
+  if (epLines.length > 0) {
+    out.push("ENDPOINTS", epLines.join("\n"), "");
+  }
+  out.push("RESOURCES", renderResources(await boxResourceStats(inspected.record)), "");
+  out.push("CLAUDE", renderClaude(inspected, persistedStatus));
+  if (live) {
+    if (live.tasks.length > 0) {
+      out.push("", "TASKS", renderTaskTable(live.tasks));
+    }
+    out.push("", "SERVICES", renderStatusTable(live.services));
+    out.push("", "PORTS", renderPortsTable(live.ports));
+    return out.join("\n");
+  }
+  if (!persistedStatus) {
+    out.push(
+      "",
+      `box is ${state}; no persisted status (box predates this feature, or the relay never received a snapshot)`
+    );
+    return out.join("\n");
+  }
+  out.push("", renderPersisted2(persistedStatus, state));
+  return out.join("\n");
+}
+function renderResources(s) {
+  const lim = (v) => v ? ` (limit ${typeof v === "number" ? String(v) : v})` : "";
+  const seg = [];
+  if (s.live) {
+    seg.push(`cpu ${fmtPercent(s.cpuPercent)}${lim(s.limits.cpus)}`);
+    seg.push(
+      `mem ${fmtBytes(s.memUsedBytes)} / ${fmtBytes(s.memLimitBytes)} (${fmtPercent(s.memPercent)})${lim(s.limits.memoryBytes ? fmtBytes(s.limits.memoryBytes) : null)}`
+    );
+    seg.push(`pids ${s.pids === null ? "\u2014" : String(s.pids)}${lim(s.limits.pidsLimit)}`);
+  } else {
+    seg.push("not running");
+    if (s.limits.memoryBytes) seg.push(`mem limit ${fmtBytes(s.limits.memoryBytes)}`);
+    if (s.limits.cpus) seg.push(`cpu limit ${String(s.limits.cpus)}`);
+    if (s.limits.pidsLimit) seg.push(`pids limit ${String(s.limits.pidsLimit)}`);
+  }
+  seg.push(
+    `disk ${fmtBytes(s.diskUsedBytes)}${s.limits.disk ? ` (limit ${s.limits.disk}, no-op on overlay2/macOS)` : ""}`
+  );
+  if (s.snapshotDiskBytes !== null) seg.push(`snapshot ${fmtBytes(s.snapshotDiskBytes)}`);
+  if (s.checkpointVolumeBytes !== null) seg.push(`ckpt ${fmtBytes(s.checkpointVolumeBytes)}`);
+  let line = `  ${seg.join("  ")}`;
+  for (const w of s.warnings) line += `
+  note: ${w}`;
+  return line;
+}
+function renderClaude(i, persisted) {
+  const s = i.claudeSession;
+  let session;
+  if (s === null) {
+    session = "no session (box not running)";
+  } else if (!s.running) {
+    session = `no session ("${s.sessionName}")`;
+  } else {
+    const ago = fmtAgo(s.startedAt);
+    session = `running ("${s.sessionName}")${ago ? `, started ${ago}` : ""}`;
+  }
+  const lines = [`  session   ${session}`];
+  if (persisted) {
+    const c = persisted.claude;
+    const ago = fmtAgo(c.updatedAt);
+    lines.push(`  activity  ${c.state}${ago ? ` (${ago})` : ""}`);
+  }
+  return lines.join("\n");
+}
+function renderPersisted2(s, state) {
+  const out = [`(persisted snapshot from ${s.timestamp}; box is ${state})`, ""];
+  if (s.tasks.length > 0) {
+    out.push("TASKS");
+    out.push(...s.tasks.map((t) => `  ${t.name}  ${t.state}`));
+    out.push("");
+  }
+  out.push("SERVICES");
+  if (s.services.length === 0) {
+    out.push("  (none)");
+  } else {
+    out.push(
+      ...s.services.map(
+        (svc) => `  ${svc.name}  ${svc.state}${svc.port !== null ? `  :${String(svc.port)}` : ""}`
+      )
+    );
+  }
+  out.push("");
+  out.push("PORTS");
+  if (s.ports.length === 0) {
+    out.push("  (none listening)");
+  } else {
+    const other = s.ports.filter((p) => !p.service).map((p) => p.port).sort((a, b) => a - b);
+    out.push(
+      ...s.ports.filter((p) => p.service).map((p) => `  :${String(p.port)}  (${p.service})`)
+    );
+    if (other.length > 0) out.push(`  other (${other.length}): ${other.join(", ")}`);
+  }
+  return out.join("\n");
+}
+
+// src/commands/stop.ts
+import { Command as Command22 } from "commander";
+var stopCommand = new Command22("stop").description("Stop a box (docker stop; preserves upper + node_modules volumes)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).action(async (idOrName) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const record = await stopBox(box.id);
+    process.stdout.write(
+      `stopped ${record.container}
+restart with: agentbox start ${record.name}
+`
+    );
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/top.ts
+import { Command as Command23 } from "commander";
+var COLS = ["BOX", "STATE", "CPU%", "MEM USAGE / LIMIT", "MEM%", "PIDS", "DISK", "NET I/O"];
+function row(name, state, s) {
+  const mem = `${fmtBytes(s.memUsedBytes)} / ${fmtBytes(s.memLimitBytes)}`;
+  const net = s.netRxBytes === null && s.netTxBytes === null ? "\u2014" : `${fmtBytes(s.netRxBytes)} / ${fmtBytes(s.netTxBytes)}`;
+  return [
+    name,
+    state,
+    fmtPercent(s.cpuPercent),
+    s.live ? mem : "\u2014",
+    fmtPercent(s.memPercent),
+    s.pids === null ? "\u2014" : String(s.pids),
+    fmtBytes(s.diskUsedBytes),
+    s.live ? net : "\u2014"
+  ];
+}
+function renderTable2(rows) {
+  const all = [COLS, ...rows];
+  const widths = COLS.map((_, c) => Math.max(...all.map((r) => r[c].length)));
+  return all.map((r) => r.map((cell, c) => cell.padEnd(widths[c])).join("  ").trimEnd()).join("\n");
+}
+async function selectBoxes(idOrName, opts) {
+  const boxes = await listBoxes();
+  if (idOrName === void 0) {
+    if (!opts.project) return boxes;
+    const project = await findProjectRoot(process.cwd());
+    return boxes.filter((b) => b.projectRoot === project.root);
+  }
+  const picked = await resolveBoxOrExit(idOrName);
+  return boxes.filter((b) => b.id === picked.id);
+}
+async function snapshot(idOrName, opts) {
+  const boxes = await selectBoxes(idOrName, opts);
+  const stats = await Promise.all(boxes.map((b) => boxResourceStats(b)));
+  return { boxes, stats };
+}
+async function renderProjectFooters() {
+  const parts = [];
+  const [ckpt, home] = await Promise.all([
+    allCheckpointVolumesBytes(),
+    agentboxHomeBytes()
+  ]);
+  if (home !== null) parts.push(`~/.agentbox: ${fmtBytes(home)}`);
+  if (ckpt !== null) parts.push(`checkpoints: ${fmtBytes(ckpt)}`);
+  return parts.length > 0 ? `
+
+SYSTEM: ${parts.join(" - ")}` : "";
+}
+var topCommand = new Command23("top").description("Live resource monitor (cpu/mem/pids/disk) for a box, the project, or every box").argument(
+  "[box]",
+  "box ref (default: every box on the host; --project narrows to the cwd's project)"
+).option("-p, --project", "show only boxes in the cwd's project").option("--once", "print a single snapshot instead of watching").option("-j, --json", "machine-readable JSON (implies --once)").option("--interval <seconds>", "refresh interval", "2").action(async (idOrName, opts) => {
+  try {
+    if (opts.json) {
+      const { boxes, stats } = await snapshot(idOrName, opts);
+      process.stdout.write(
+        JSON.stringify(
+          boxes.map((b, i) => ({ box: b.name, state: b.state, ...stats[i] })),
+          null,
+          2
+        ) + "\n"
+      );
+      return;
+    }
+    const produce = async (watching) => {
+      const { boxes, stats } = await snapshot(idOrName, opts);
+      const scope = opts.project ? "no boxes for this project" : "no boxes";
+      const header = boxes.length === 0 ? watching ? `${scope} (waiting...)` : scope : renderTable2(boxes.map((b, i) => row(b.name, b.state, stats[i])));
+      return header + await renderProjectFooters();
+    };
+    if (opts.once) {
+      process.stdout.write(await produce(false) + "\n");
+      return;
+    }
+    await watchRender(() => produce(true), opts.interval);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/unpause.ts
+import { Command as Command24 } from "commander";
+var unpauseCommand = new Command24("unpause").description("Resume a paused box (docker unpause \u2014 sub-second)").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).action(async (idOrName) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const record = await unpauseBox(box.id);
+    process.stdout.write(`unpaused ${record.container}
+`);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/update.ts
+import { spawn as spawn4 } from "child_process";
+import { confirm as confirm10, intro as intro3, isCancel as isCancel10, log as log23, outro as outro3, spinner as spinner3 } from "@clack/prompts";
+import { Command as Command25 } from "commander";
+
+// src/exec-method.ts
+function detectExecutionMethod(input) {
+  const ua = input.userAgent ?? "";
+  const argv1 = input.argv1 ?? "";
+  if (argv1.includes("/_npx/") || argv1.includes("/.npm/_npx") || /\bnpx\//.test(ua)) {
+    return "npx";
+  }
+  if (/\bpnpm\//.test(ua)) {
+    return "pnpm";
+  }
+  if (/\bnpm\//.test(ua)) {
+    return "npm";
+  }
+  return "direct";
+}
+
+// src/commands/update.ts
+var PKG = "@madarco/agentbox";
+function selfUpdateCommand(method) {
+  if (method === "npm") return { cmd: "npm", args: ["install", "-g", `${PKG}@latest`] };
+  if (method === "pnpm") return { cmd: "pnpm", args: ["add", "-g", `${PKG}@latest`] };
+  return null;
+}
+function describeSelfUpdate(method) {
+  switch (method) {
+    case "npm":
+      return "self-update: npm install -g @madarco/agentbox@latest";
+    case "pnpm":
+      return "self-update: pnpm add -g @madarco/agentbox@latest";
+    case "npx":
+      return "self-update: skipped (running via npx \u2014 always the latest version)";
+    case "direct":
+      return "self-update: skipped (running from source \u2014 no global install to update)";
+  }
+}
+function runInherit(cmd, args) {
+  return new Promise((resolveP, rejectP) => {
+    const child = spawn4(cmd, args, { stdio: "inherit" });
+    child.on("error", rejectP);
+    child.on("close", (code) => resolveP(code ?? 0));
+  });
+}
+var updateCommand = new Command25("self-update").description(
+  "Update agentbox: self-update via npm/pnpm (unless run via npx), wipe the box image so it rebuilds, and reload the relay"
+).option("-y, --yes", "skip the confirmation prompt").option("--dry-run", "show what would happen, don't change anything").option("--skip-self", "skip the package self-update; only refresh the image + relay").action(async (opts) => {
+  try {
+    const method = detectExecutionMethod({
+      userAgent: process.env.npm_config_user_agent,
+      argv1: process.argv[1]
+    });
+    intro3("agentbox self-update");
+    const selfStep = opts.skipSelf ? "self-update: skipped (--skip-self)" : describeSelfUpdate(method);
+    log23.info(
+      [
+        "plan:",
+        `  ${selfStep}`,
+        `  image: docker image rm -f ${DEFAULT_BOX_IMAGE} (rebuilds on next create/claude)`,
+        "  relay: stop, then respawn unless a self-update ran"
+      ].join("\n")
+    );
+    if (opts.dryRun) {
+      outro3("dry run \u2014 nothing changed");
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm10({ message: "Proceed with update?", initialValue: true });
+      if (isCancel10(ok) || !ok) {
+        log23.info("cancelled");
+        return;
+      }
+    }
+    let selfUpdated = false;
+    if (opts.skipSelf) {
+      log23.info("skipping self-update (--skip-self)");
+    } else {
+      const cmd = selfUpdateCommand(method);
+      if (cmd === null) {
+        log23.info(describeSelfUpdate(method));
+      } else {
+        log23.info(`running: ${cmd.cmd} ${cmd.args.join(" ")}`);
+        const code = await runInherit(cmd.cmd, cmd.args);
+        if (code !== 0) {
+          throw new Error(`${cmd.cmd} exited with code ${String(code)}`);
+        }
+        selfUpdated = true;
+        log23.success(`updated ${PKG} via ${cmd.cmd}`);
+      }
+    }
+    const s = spinner3();
+    s.start(`removing image ${DEFAULT_BOX_IMAGE}`);
+    const removed = await removeImage(DEFAULT_BOX_IMAGE);
+    s.stop(
+      removed ? `removed image ${DEFAULT_BOX_IMAGE} (rebuilds on next create/claude)` : `image ${DEFAULT_BOX_IMAGE} not present (nothing to remove)`
+    );
+    const sr = spinner3();
+    sr.start("stopping relay");
+    const stop = await stopRelay();
+    sr.stop(
+      stop.stopped ? `stopped relay (pid ${String(stop.pid)})` : "relay was not running"
+    );
+    if (selfUpdated) {
+      log23.info(
+        "relay will restart automatically (with the updated build) on your next `agentbox create` / `agentbox claude`"
+      );
+    } else {
+      const sr2 = spinner3();
+      sr2.start("restarting relay");
+      try {
+        const ep = await ensureRelay();
+        sr2.stop(`relay back up on ${ep.hostUrl}`);
+      } catch (err) {
+        sr2.stop("relay restart failed");
+        log23.warn(
+          `${err instanceof Error ? err.message : String(err)} \u2014 it will retry on the next box command`
+        );
+      }
+    }
+    outro3("update complete");
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/commands/wait.ts
+import { log as log24 } from "@clack/prompts";
+import { Command as Command26 } from "commander";
+var waitCommand = new Command26("wait").description("Block until the box reports all autostart units ready").argument(
+  "[box]",
+  "box ref: project index, id, id prefix, name, or container (default: the only box in this project)"
+).option("--timeout <ms>", "overall timeout in milliseconds", "120000").option("--units <names...>", "restrict to the named units").option("-j, --json", "machine-readable JSON output").action(async (idOrName, opts) => {
+  try {
+    const box = await resolveBoxOrExit(idOrName);
+    const ctlArgs = ["agentbox-ctl", "wait-ready", "--json", "--timeout", opts.timeout];
+    if (opts.units && opts.units.length > 0) {
+      ctlArgs.push("--units", ...opts.units);
+    }
+    const proc = await execInBox(box.container, ctlArgs, { user: "vscode" });
+    let parsed;
+    try {
+      parsed = JSON.parse(proc.stdout);
+    } catch {
+      log24.error(`agentbox-ctl wait-ready failed: ${proc.stderr || proc.stdout}`);
+      process.exit(1);
+    }
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(parsed, null, 2) + "\n");
+    } else if (parsed.ready) {
+      process.stdout.write("ready\n");
+    } else {
+      const lines = ["not ready"];
+      if (parsed.timedOut.length > 0) lines.push(`  timed out: ${parsed.timedOut.join(", ")}`);
+      if (parsed.failed.length > 0) lines.push(`  failed: ${parsed.failed.join(", ")}`);
+      process.stdout.write(lines.join("\n") + "\n");
+    }
+    process.exit(parsed.ready ? 0 : 1);
+  } catch (err) {
+    handleLifecycleError(err);
+  }
+});
+
+// src/index.ts
+var program = new Command27();
+program.name("agentbox").description("Launch coding agents in isolated sandboxes").version("0.0.0");
+program.enablePositionalOptions();
+program.addCommand(createCommand);
+program.addCommand(claudeCommand);
+program.addCommand(codeCommand);
+program.addCommand(shellCommand);
+program.addCommand(listCommand2);
+program.addCommand(openCommand);
+program.addCommand(browserCommand);
+program.addCommand(screenCommand);
+program.addCommand(pullCommand);
+program.addCommand(statusCommand);
+program.addCommand(topCommand);
+program.addCommand(dashboardCommand);
+program.addCommand(waitCommand);
+program.addCommand(logsCommand);
+program.addCommand(pauseCommand);
+program.addCommand(unpauseCommand);
+program.addCommand(stopCommand);
+program.addCommand(startCommand);
+program.addCommand(destroyCommand);
+program.addCommand(pruneCommand);
+program.addCommand(checkpointCommand);
+program.addCommand(configCommand);
+program.addCommand(updateCommand);
+program.configureHelp({ visibleCommands: () => [] });
+program.addHelpText("after", () => "\n" + buildGroupedHelp(program));
+await applyEngineOverrideAtStartup();
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map