@mifune/agro 0.15.1 → 0.16.0

package/dist/agro.js

@@ -7,8 +7,8 @@ var __export = (target, all) => {
 
 // src/cli.ts
 import { fileURLToPath } from "node:url";
-import { dirname as dirname10, join as join18, resolve as resolve11 } from "node:path";
-import { existsSync as existsSync22, mkdtempSync as mkdtempSync5, readFileSync as readFileSync12, rmSync as rmSync6 } from "node:fs";
+import { dirname as dirname10, join as join19, resolve as resolve11 } from "node:path";
+import { existsSync as existsSync23, mkdtempSync as mkdtempSync5, readFileSync as readFileSync13, rmSync as rmSync6 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
 
 // src/commands/update.ts
@@ -2222,7 +2222,7 @@ function resolveExecutionTarget(opts) {
 }
 
 // src/lib/version.ts
-var AGRO_VERSION = true ? "0.15.1" : "0.0.0-dev";
+var AGRO_VERSION = true ? "0.16.0" : "0.0.0-dev";
 var OFFICIAL_IMAGE = "ghcr.io/mifunedev/agro";
 var RELEASE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-z][a-z0-9]*\.[0-9]+)?$/;
 function parseReleaseVersion(value) {
@@ -3129,7 +3129,7 @@ var HARNESS_CATALOG = [
     installArgv: [
       "bash",
       "-lc",
-      `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | HERMES_INSTALL_DIR="${HARNESS_PREFIX_TOKEN}/lib/hermes-agent" bash -s -- --skip-setup --skip-browser && uv pip install --python "${HARNESS_PREFIX_TOKEN}/lib/hermes-agent/venv/bin/python" 'hermes-agent[slack,teams,web,pty]'`
+      `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | HERMES_INSTALL_DIR="${HARNESS_PREFIX_TOKEN}/lib/hermes-agent" bash -s -- --skip-setup --skip-browser && "${HARNESS_PREFIX_TOKEN}/bin/hermes" pm install --extra slack --extra teams`
     ],
     installUser: "sandbox",
     verifyArgv: ["hermes", "--version"],
@@ -3784,6 +3784,55 @@ function maybePrintStarPrompt(io, env = process.env, isTTY = process.stdout.isTT
   }
 }
 
+// src/commands/sandbox-list.ts
+async function entryStatus(root, name, run) {
+  try {
+    const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
+    return await target.status();
+  } catch {
+    return "unknown";
+  }
+}
+async function runSandboxList(opts, io) {
+  const run = opts.run ?? spawnRunner;
+  const rows = [];
+  for (const name of listEntries()) {
+    const root = entryRoot(name);
+    const config = readAgroConfig(agroConfigPath(root));
+    const checkout = configCheckout(config) ?? "-";
+    rows.push({
+      name,
+      runtime: config.runtime ?? "docker",
+      checkout,
+      repo: checkout,
+      status: await entryStatus(root, name, run)
+    });
+  }
+  if (opts.json === true) {
+    io.stdout(`${JSON.stringify(rows, null, 2)}
+`);
+    return 0;
+  }
+  if (rows.length === 0) {
+    io.stdout(
+      `no sandbox is registered in ${registryRoot()} \u2014 create one with \`${opts.bin} sandbox install docker\`
+`
+    );
+    return 0;
+  }
+  const width = (pick) => Math.max(...rows.map((row) => pick(row).length));
+  const nameWidth = width((row) => row.name);
+  const runtimeWidth = width((row) => row.runtime);
+  const statusWidth = width((row) => row.status);
+  for (const row of rows) {
+    io.stdout(
+      `${row.name.padEnd(nameWidth)}  ${row.runtime.padEnd(runtimeWidth)}  ${row.status.padEnd(statusWidth)}  ${row.checkout}
+`
+    );
+  }
+  return 0;
+}
+
 // src/commands/sandbox.ts
 function hostTimezone() {
   const tz = process.env.TZ;
@@ -4001,58 +4050,384 @@ async function runSandboxInstall(opts, io) {
   }
   return code;
 }
-async function entryStatus(root, name, run) {
+
+// src/services/sandbox-upgrade.ts
+import { closeSync as closeSync2, existsSync as existsSync17, openSync as openSync2, readFileSync as readFileSync11, unlinkSync as unlinkSync5, writeSync } from "node:fs";
+import { join as join13 } from "node:path";
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function conflictingDotenvImage(root, imageRef) {
+  const rootEnv = join13(root, ".env");
+  const fallbackEnv = join13(root, ".devcontainer", ".env");
+  const file = existsSync17(rootEnv) ? rootEnv : fallbackEnv;
+  if (!existsSync17(file)) return void 0;
+  for (const line of readFileSync11(file, "utf8").split(/\r?\n/)) {
+    const match = /^AGRO_SANDBOX_IMAGE=(.*)$/.exec(line);
+    if (!match) continue;
+    const value = match[1].trim().replace(/^(?:"(.*)"|'(.*)')$/, (_whole, double, single) => double ?? single ?? "");
+    if (value !== imageRef) return file;
+  }
+  return void 0;
+}
+async function runSandboxUpgrade(opts, io) {
+  const prefix = `${opts.bin} sandbox upgrade:`;
+  const version = parseReleaseVersion(opts.version);
+  if (version === void 0) {
+    io.stderr(`${prefix} invalid release version "${opts.version}"
+`);
+    return 1;
+  }
+  if (runningInsideSandbox()) {
+    io.stderr(`${prefix} host-only \u2014 run this command on the host
+`);
+    return 1;
+  }
+  let root;
   try {
-    const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
-    return await target.status();
-  } catch {
-    return "unknown";
+    root = entryRoot(opts.name);
+  } catch (error) {
+    io.stderr(`${prefix} ${errorMessage(error)}
+`);
+    return 1;
+  }
+  const configFile = agroConfigPath(root);
+  if (!existsSync17(configFile)) {
+    io.stderr(`${prefix} no sandbox entry named "${opts.name}"
+`);
+    return 1;
+  }
+  const lock = join13(root, ".sandbox-upgrade.lock");
+  let fd;
+  try {
+    fd = openSync2(lock, "wx", 384);
+  } catch (error) {
+    const message = error instanceof Error && "code" in error && error.code === "EEXIST" ? `upgrade already in progress for ${opts.name}; lock: ${lock}. Confirm no upgrade process owns this entry before removing that lock and retrying` : errorMessage(error);
+    io.stderr(`${prefix} ${message}
+`);
+    return 1;
+  }
+  try {
+    writeSync(fd, `${process.pid}
+`);
+    const config = readAgroConfig(configFile);
+    if (config.image?.mode !== "image") {
+      io.stderr(`${prefix} ${opts.name} requires image.mode "image"
+`);
+      return 1;
+    }
+    const imageRef = officialImageRef(version);
+    if (process.env.AGRO_SANDBOX_IMAGE !== void 0 && process.env.AGRO_SANDBOX_IMAGE !== "" && process.env.AGRO_SANDBOX_IMAGE !== imageRef) {
+      io.stderr(`${prefix} conflicting AGRO_SANDBOX_IMAGE in the host environment
+`);
+      return 1;
+    }
+    const dotenv = conflictingDotenvImage(root, imageRef);
+    if (dotenv !== void 0) {
+      io.stderr(`${prefix} conflicting AGRO_SANDBOX_IMAGE in ${dotenv}
+`);
+      return 1;
+    }
+    const run = opts.run ?? spawnRunner;
+    let priorRef = config.image.ref;
+    if (!priorRef) {
+      const name = configuredContainerName(root) ?? DEFAULT_CONTAINER_NAME;
+      const inspected = run("docker", ["inspect", "-f", "{{.Config.Image}}", name], { stdio: "capture" });
+      priorRef = inspected.status === 0 && !inspected.error ? inspected.stdout?.trim() : void 0;
+      if (!priorRef) {
+        io.stderr(`${prefix} cannot determine previous image for ${name}; no changes made
+`);
+        return 1;
+      }
+    }
+    const apply = (ref) => runSandbox({ bin: opts.bin, cwd: root, imageRef: ref, run }, io);
+    let failure;
+    try {
+      const code = await apply(imageRef);
+      if (code !== 0) failure = `exit ${code}`;
+    } catch (error) {
+      failure = errorMessage(error);
+    }
+    if (failure === void 0) {
+      try {
+        (opts.writeConfig ?? writeAgroConfig)(root, { ...config, image: { ...config.image, ref: imageRef } });
+        return 0;
+      } catch (error) {
+        failure = `config persistence failed (${errorMessage(error)})`;
+      }
+    } else {
+      failure = `provisioning failed (${failure})`;
+    }
+    io.stderr(`${prefix} ${failure}; restoring previous image
+`);
+    try {
+      const code = await apply(priorRef);
+      if (code !== 0) io.stderr(`${prefix} restoration failed (exit ${code})
+`);
+    } catch (error) {
+      io.stderr(`${prefix} restoration failed (${errorMessage(error)})
+`);
+    }
+    return 1;
+  } catch (error) {
+    io.stderr(`${prefix} ${errorMessage(error)}
+`);
+    return 1;
+  } finally {
+    closeSync2(fd);
+    unlinkSync5(lock);
   }
 }
-async function runSandboxList(opts, io) {
-  const run = opts.run ?? spawnRunner;
-  const rows = [];
-  for (const name of listEntries()) {
-    const root = entryRoot(name);
-    const config = readAgroConfig(agroConfigPath(root));
-    const checkout = configCheckout(config) ?? "-";
-    rows.push({
-      name,
-      runtime: config.runtime ?? "docker",
-      checkout,
-      repo: checkout,
-      status: await entryStatus(root, name, run)
-    });
+
+// src/controllers/sandbox.ts
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h" || arg === "help";
+}
+function runtimeLines() {
+  const width = Math.max(...RUNTIME_CATALOG.map((r) => r.id.length));
+  return RUNTIME_CATALOG.map(
+    (r) => `  ${r.id.padEnd(width)}  ${r.provisionable ? "provisionable" : "planned"}`
+  ).join("\n");
+}
+function printSandboxHelp(bin = AGRO_PRODUCT.bin) {
+  process.stdout.write(`${bin} sandbox \u2014 Create and list sandboxes
+
+Usage:
+  ${bin} sandbox install <runtime> [--name <name>] [--checkout <dir>]
+                               [--home-mount <dir>] [--yes]
+                               [--version <X.Y.Z> | --image[=<ref>]]
+                               [--no-build] [--print-argv]
+  ${bin} sandbox list [--json]
+  ${bin} sandbox upgrade <name> --version <X.Y.Z>
+
+\`install\` writes a sandbox entry under \${${stateNames(bin).envPrefix}HOME:-~/${stateNames(bin).userStateDir}}/sandboxes/<name>/,
+materialises the compose files and the compose wrapper into it, then starts the
+container. It needs no project checkout and runs from any directory. Without
+--checkout the sandbox runs the prebuilt image; with --checkout <dir> that
+checkout is bound at /home/sandbox/harness; the sandbox builds locally only
+when that directory holds .devcontainer/Dockerfile.
+
+On a terminal without --yes it asks for the sandbox name, the timezone, the git
+identity, SSH (with its host port), the host Docker socket, and the host path
+for /home/sandbox. With --checkout it seeds those answers from that
+checkout's ${stateNames(bin).configFile}.
+
+Flags:
+  --name <name>    Registry entry name (default: the lowest free ${DEFAULT_NAME_PREFIX}<n>)
+  --checkout <dir> Bind this checkout into the sandbox and seed the defaults
+                   from its ${stateNames(bin).configFile}. The sandbox builds
+                   locally only when that directory holds
+                   .devcontainer/Dockerfile
+  --repo <dir>     Deprecated alias for --checkout
+  --home-mount <dir>
+                   Bind this host directory at /home/sandbox instead of the
+                   Docker-managed volume. Relative paths resolve against the
+                   working directory. The directory is created when absent
+  --yes            Non-interactive: keep every default and ask nothing
+  --version <X.Y.Z>
+                   Run the official release image ghcr.io/mifunedev/agro:<X.Y.Z>
+                   (implies --image). A leading v and a -<channel>.<n>
+                   pre-release suffix are accepted
+  --image          Run the prebuilt image instead of building (implies
+                   --no-build). The ref resolves first-match: --version or
+                   --image=<ref> > ${stateNames(bin).envPrefix}SANDBOX_IMAGE >
+                   ${stateNames(bin).configFile} image.ref > ${officialImageRef(AGRO_VERSION)}
+  --image=<ref>    Run a custom image (implies --image); conflicts with --version
+  --no-build       Suppress the local build and reuse an existing image
+  --print-argv     Print the docker compose argv that would run, then exit
+                   without writing an entry
+  --json           Machine-readable output (list)
+
+Runtimes:
+${runtimeLines()}
+
+Next: ${bin} shell <name>
+`);
+}
+var SANDBOX_VALUE_FLAGS = {
+  "--name": "name",
+  "--checkout": "checkout",
+  "--repo": "checkout",
+  "--home-mount": "homeMount"
+};
+function parseSandboxArgs(rest, bin = AGRO_PRODUCT.bin) {
+  const args = {
+    help: false,
+    yes: false,
+    image: false,
+    noBuild: false,
+    printArgv: false,
+    json: false
+  };
+  if (rest.length === 0 || isHelpFlag(rest[0])) {
+    return { ok: true, args: { ...args, help: true } };
   }
-  if (opts.json === true) {
-    io.stdout(`${JSON.stringify(rows, null, 2)}
+  const [head, ...tail] = rest;
+  if (head === "upgrade") {
+    if (tail.length === 1 && isHelpFlag(tail[0])) {
+      return { ok: true, args: { ...args, subcommand: "upgrade", help: true } };
+    }
+    const [name, flag, value, ...extra] = tail;
+    if (name === void 0 || name === "" || name.startsWith("-")) {
+      return { ok: false, error: `${bin} sandbox upgrade: a name is required` };
+    }
+    if (flag === void 0) {
+      return { ok: false, error: `${bin} sandbox upgrade: --version is required` };
+    }
+    if (flag !== "--version") {
+      return { ok: false, error: `${bin} sandbox upgrade: ${flag.startsWith("-") ? "unknown flag" : "unexpected argument"} "${flag}"` };
+    }
+    if (value === void 0 || value === "") {
+      return { ok: false, error: `${bin} sandbox upgrade: --version requires a value` };
+    }
+    if (value.startsWith("-")) {
+      return { ok: false, error: `${bin} sandbox upgrade: unknown flag "${value}"` };
+    }
+    const version2 = parseReleaseVersion(value);
+    if (version2 === void 0) {
+      return { ok: false, error: `${bin} sandbox upgrade: --version "${value}" is not a release version \u2014 expected X.Y.Z` };
+    }
+    if (extra.length > 0) {
+      const token = extra[0];
+      return { ok: false, error: `${bin} sandbox upgrade: ${token.startsWith("-") && token !== "--version" ? "unknown flag" : "unexpected argument"} "${token}"` };
+    }
+    return { ok: true, args: { ...args, subcommand: "upgrade", name, version: version2 } };
+  }
+  if (head !== "install" && head !== "list") {
+    return {
+      ok: false,
+      error: `${bin} sandbox: unknown subcommand "${head}" \u2014 expected install or list`,
+      showHelp: true
+    };
+  }
+  args.subcommand = head;
+  if (isHelpFlag(tail[0])) return { ok: true, args: { ...args, help: true } };
+  const positionals = [];
+  const checkoutSpellings = /* @__PURE__ */ new Set();
+  let version;
+  for (let i = 0; i < tail.length; i++) {
+    const token = tail[i];
+    const valueFlag = SANDBOX_VALUE_FLAGS[token];
+    if (valueFlag !== void 0) {
+      const value = tail[i + 1];
+      if (value === void 0) {
+        return { ok: false, error: `${bin} sandbox ${head}: ${token} requires a value` };
+      }
+      if (valueFlag === "checkout") checkoutSpellings.add(token);
+      args[valueFlag] = value;
+      i++;
+    } else if (token === "--yes") {
+      args.yes = true;
+    } else if (token === "--no-build") {
+      args.noBuild = true;
+    } else if (token === "--print-argv") {
+      args.printArgv = true;
+    } else if (token === "--image") {
+      args.image = true;
+    } else if (token.startsWith("--image=")) {
+      const ref = token.slice("--image=".length);
+      if (ref === "") {
+        return { ok: false, error: `${bin} sandbox: --image=<ref> requires a non-empty image ref` };
+      }
+      args.image = true;
+      args.imageRef = ref;
+    } else if (token === "--version" || token.startsWith("--version=")) {
+      const value = token === "--version" ? tail[++i] : token.slice("--version=".length);
+      if (value === void 0 || value === "") {
+        return { ok: false, error: `${bin} sandbox ${head}: --version requires a value` };
+      }
+      version = parseReleaseVersion(value);
+      if (version === void 0) {
+        return {
+          ok: false,
+          error: `${bin} sandbox ${head}: --version "${value}" is not a release version \u2014 expected X.Y.Z`
+        };
+      }
+    } else if (token === "--json") {
+      args.json = true;
+    } else if (token.startsWith("-")) {
+      return { ok: false, error: `${bin} sandbox ${head}: unknown flag "${token}"` };
+    } else {
+      positionals.push(token);
+    }
+  }
+  if (checkoutSpellings.has("--checkout") && checkoutSpellings.has("--repo")) {
+    return {
+      ok: false,
+      error: `${bin} sandbox ${head}: --checkout conflicts with --repo \u2014 pass exactly one, and prefer --checkout`
+    };
+  }
+  if (version !== void 0) {
+    if (args.imageRef !== void 0) {
+      return {
+        ok: false,
+        error: `${bin} sandbox ${head}: --version conflicts with --image=<ref> \u2014 pass --version for an official release or --image=<ref> for a custom image`
+      };
+    }
+    args.image = true;
+    args.imageRef = officialImageRef(version);
+  }
+  if (head === "list") {
+    if (positionals.length > 0) {
+      return { ok: false, error: `${bin} sandbox list: unexpected argument "${positionals[0]}"` };
+    }
+    return { ok: true, args };
+  }
+  if (positionals.length === 0) {
+    return {
+      ok: false,
+      error: `${bin} sandbox install: a runtime is required, e.g. \`${bin} sandbox install docker\``,
+      showHelp: true
+    };
+  }
+  if (positionals.length > 1) {
+    return { ok: false, error: `${bin} sandbox install: unexpected argument "${positionals[1]}"` };
+  }
+  args.runtime = positionals[0];
+  return { ok: true, args };
+}
+async function runSandboxCommand(rest, bin) {
+  const parsed = parseSandboxArgs(rest, bin);
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}
 `);
-    return 0;
+    if (parsed.showHelp) printSandboxHelp(bin);
+    return 1;
   }
-  if (rows.length === 0) {
-    io.stdout(
-      `no sandbox is registered in ${registryRoot()} \u2014 create one with \`${opts.bin} sandbox install docker\`
-`
-    );
-    return 0;
+  const a = parsed.args;
+  if (a.help) {
+    printSandboxHelp(bin);
+    return a.subcommand === void 0 ? 1 : 0;
   }
-  const width = (pick) => Math.max(...rows.map((row) => pick(row).length));
-  const nameWidth = width((row) => row.name);
-  const runtimeWidth = width((row) => row.runtime);
-  const statusWidth = width((row) => row.status);
-  for (const row of rows) {
-    io.stdout(
-      `${row.name.padEnd(nameWidth)}  ${row.runtime.padEnd(runtimeWidth)}  ${row.status.padEnd(statusWidth)}  ${row.checkout}
-`
-    );
+  const io = {
+    stdout: (s) => process.stdout.write(s),
+    stderr: (s) => process.stderr.write(s)
+  };
+  if (a.subcommand === "list") return await runSandboxList({ bin, json: a.json }, io);
+  if (a.subcommand === "upgrade") {
+    return await runSandboxUpgrade({ bin, name: a.name, version: a.version }, io);
   }
-  return 0;
+  return await runSandboxInstall(
+    {
+      bin,
+      runtime: a.runtime,
+      ...a.name !== void 0 ? { name: a.name } : {},
+      ...a.checkout !== void 0 ? { checkout: a.checkout } : {},
+      ...a.homeMount !== void 0 ? { homeMount: a.homeMount } : {},
+      yes: a.yes,
+      image: a.image,
+      ...a.imageRef !== void 0 ? { imageRef: a.imageRef } : {},
+      noBuild: a.noBuild,
+      printArgv: a.printArgv
+    },
+    io
+  );
 }
 
 // src/commands/harness.ts
-import { existsSync as existsSync19 } from "node:fs";
+import { existsSync as existsSync20 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { delimiter as delimiter2, join as join15 } from "node:path";
+import { delimiter as delimiter2, join as join16 } from "node:path";
 
 // src/lib/docs.ts
 var SOURCE_DOCS_BASE = "https://github.com/mifunedev/agro/blob/main/";
@@ -4065,17 +4440,20 @@ function sourceDocsUrl(docsPath) {
 }
 
 // src/lib/host-config.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync9, readFileSync as readFileSync11, renameSync as renameSync4, unlinkSync as unlinkSync5, writeFileSync as writeFileSync9 } from "node:fs";
-import { basename as basename5, dirname as dirname8, isAbsolute, join as join13, resolve as resolve8 } from "node:path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync9, readFileSync as readFileSync12, renameSync as renameSync4, unlinkSync as unlinkSync6, writeFileSync as writeFileSync9 } from "node:fs";
+import { basename as basename5, dirname as dirname8, isAbsolute, join as join14, resolve as resolve8 } from "node:path";
 var HOST_CONFIG_MODE = 420;
 var HOST_CONFIG_FILE = "config.json";
 var WORKSPACES_SUBDIR = "workspaces";
 var DEFAULT_WORKSPACE_NAME = "harness";
+function isRootToolReceipt(receipt) {
+  return receipt.scope === "root";
+}
 function hostStateHome(env, home) {
   return resolveUserStateHome(env, home);
 }
 function hostConfigPath(env, home) {
-  return join13(hostStateHome(env, home), HOST_CONFIG_FILE);
+  return join14(hostStateHome(env, home), HOST_CONFIG_FILE);
 }
 function assertWorkspaceName(name) {
   if (!SANDBOX_NAME_PATTERN.test(name)) {
@@ -4085,14 +4463,14 @@ function assertWorkspaceName(name) {
   }
 }
 function workspacesRoot(env, home) {
-  return join13(hostStateHome(env, home), WORKSPACES_SUBDIR);
+  return join14(hostStateHome(env, home), WORKSPACES_SUBDIR);
 }
 function workspaceRoot(name, env, home) {
   assertWorkspaceName(name);
-  return join13(workspacesRoot(env, home), name);
+  return join14(workspacesRoot(env, home), name);
 }
 function defaultHarnessRoot(env, home) {
-  return join13(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
+  return join14(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
 }
 function validateHostConfig(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -4114,7 +4492,7 @@ function validateHostConfig(value) {
   const hostHarnesses = record.hostHarnesses;
   if (hostHarnesses !== void 0) validateReceipts(hostHarnesses, "hostHarnesses", "harness");
   const hostTools = record.hostTools;
-  if (hostTools !== void 0) validateReceipts(hostTools, "hostTools", "tool");
+  if (hostTools !== void 0) validateReceipts(hostTools, "hostTools", "tool", true);
   return { ...record, version: 1 };
 }
 function absoluteField(value, path4) {
@@ -4124,7 +4502,7 @@ function absoluteField(value, path4) {
   if (!isAbsolute(value)) throw fieldError2(path4, "must be an absolute path");
   return value;
 }
-function validateReceipts(value, field, noun) {
+function validateReceipts(value, field, noun, allowRootScope = false) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw fieldError2(field, `must be a JSON object keyed by ${noun} id`);
   }
@@ -4134,9 +4512,16 @@ function validateReceipts(value, field, noun) {
     if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
       throw fieldError2(at, "must be a JSON object");
     }
-    const entry = receipt;
-    absoluteField(entry.prefix, `${at}.prefix`);
-    absoluteField(entry.binPath, `${at}.binPath`);
+    const entry = receipt;
+    if (allowRootScope && entry.scope !== void 0) {
+      if (entry.scope !== "root") throw fieldError2(`${at}.scope`, 'must be "root" when present');
+      for (const key of ["prefix", "binPath"]) {
+        if (entry[key] !== void 0) throw fieldError2(`${at}.${key}`, 'must be absent when scope is "root"');
+      }
+    } else {
+      absoluteField(entry.prefix, `${at}.prefix`);
+      absoluteField(entry.binPath, `${at}.binPath`);
+    }
     if (typeof entry.binary !== "string" || entry.binary === "") {
       throw fieldError2(`${at}.binary`, "must be a non-empty string");
     }
@@ -4150,10 +4535,10 @@ function validateReceipts(value, field, noun) {
 }
 function readHostConfig(env, home) {
   const path4 = hostConfigPath(env, home);
-  if (!existsSync17(path4)) return { version: 1 };
+  if (!existsSync18(path4)) return { version: 1 };
   let raw;
   try {
-    raw = readFileSync11(path4, "utf8");
+    raw = readFileSync12(path4, "utf8");
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(`could not read ${path4}: ${detail}`);
@@ -4178,7 +4563,7 @@ function writeHostConfig(config, env, home) {
     renameSync4(tmp, path4);
   } catch (error) {
     try {
-      unlinkSync5(tmp);
+      unlinkSync6(tmp);
     } catch {
     }
     throw error;
@@ -4201,8 +4586,8 @@ function fieldError2(path4, requirement) {
 }
 
 // src/lib/host-workspace.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync10, mkdtempSync as mkdtempSync4, readdirSync as readdirSync3, renameSync as renameSync5, rmSync as rmSync4, statSync as statSync5 } from "node:fs";
-import { dirname as dirname9, join as join14, resolve as resolve9 } from "node:path";
+import { existsSync as existsSync19, mkdirSync as mkdirSync10, mkdtempSync as mkdtempSync4, readdirSync as readdirSync3, renameSync as renameSync5, rmSync as rmSync4, statSync as statSync5 } from "node:fs";
+import { dirname as dirname9, join as join15, resolve as resolve9 } from "node:path";
 var AGRO_REPO_URL = "https://github.com/mifunedev/agro.git";
 var IGNORABLE_ENTRIES = [
   REGISTRY_SUBDIR,
@@ -4214,7 +4599,7 @@ function isDirectory3(path4) {
   return statSync5(path4, { throwIfNoEntry: false })?.isDirectory() === true;
 }
 function stateHomes(home) {
-  return STATE_HOME_DIRS.map((name) => join14(home, name));
+  return STATE_HOME_DIRS.map((name) => join15(home, name));
 }
 function stateHomeRootRefusal(bin, root, home, verb = "harness") {
   const target = resolve9(root);
@@ -4222,7 +4607,7 @@ function stateHomeRootRefusal(bin, root, home, verb = "harness") {
   if (enclosing === void 0) return void 0;
   return `${bin} ${verb}: the ${verb} root ${target} is the state home ${enclosing} itself.
 A workspace there collides with AGRO state and blocks every command run from ${home}.
-Move it out \u2014 for example \`mv ${enclosing} ${join14(home, "agro")}\` \u2014 then re-run this command.
+Move it out \u2014 for example \`mv ${enclosing} ${join15(home, "agro")}\` \u2014 then re-run this command.
 `;
 }
 function isIgnorableEntry(name) {
@@ -4239,16 +4624,16 @@ function cloneInto(target, run, root, ref) {
   assertCloned(run("git", ["clone", ...branch, AGRO_REPO_URL, target], { stdio: "inherit" }), root);
 }
 function cloneThroughStaging(root, run, ref) {
-  const staging = mkdtempSync4(join14(dirname9(root), "agro-clone-"));
+  const staging = mkdtempSync4(join15(dirname9(root), "agro-clone-"));
   try {
-    const checkout = join14(staging, "agro");
+    const checkout = join15(staging, "agro");
     cloneInto(checkout, run, root, ref);
     for (const name of readdirSync3(checkout)) {
-      const destination = join14(root, name);
-      if (existsSync18(destination)) {
+      const destination = join15(root, name);
+      if (existsSync19(destination)) {
         throw new Error(`could not move ${name} into ${root} \u2014 the path already exists`);
       }
-      renameSync5(join14(checkout, name), destination);
+      renameSync5(join15(checkout, name), destination);
     }
   } finally {
     rmSync4(staging, { recursive: true, force: true });
@@ -4256,7 +4641,7 @@ function cloneThroughStaging(root, run, ref) {
 }
 function ensureHostWorkspace(path4, run = spawnRunner, ref) {
   const root = resolve9(path4);
-  if (existsSync18(join14(root, ".git"))) return { root, action: "reused" };
+  if (existsSync19(join15(root, ".git"))) return { root, action: "reused" };
   const stats = statSync5(root, { throwIfNoEntry: false });
   if (stats === void 0) {
     mkdirSync10(dirname9(root), { recursive: true });
@@ -4278,11 +4663,11 @@ function ensureHostWorkspace(path4, run = spawnRunner, ref) {
 function listHostWorkspaces(env, home) {
   const root = workspacesRoot(env, home);
   if (!isDirectory3(root)) return [];
-  return readdirSync3(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => SANDBOX_NAME_PATTERN.test(name)).filter((name) => existsSync18(join14(root, name, ".git"))).sort();
+  return readdirSync3(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => SANDBOX_NAME_PATTERN.test(name)).filter((name) => existsSync19(join15(root, name, ".git"))).sort();
 }
 function resolveExistingWorkspace(bin, verb, path4, env, home) {
   const root = resolve9(path4);
-  if (existsSync18(join14(root, ".git"))) return { ok: true, root };
+  if (existsSync19(join15(root, ".git"))) return { ok: true, root };
   const existing = listHostWorkspaces(env, home);
   const inventory = existing.length === 0 ? "No host workspace exists yet.\n" : `Workspaces that exist: ${existing.join(", ")}
 `;
@@ -4312,7 +4697,7 @@ function targetFor(root, run, env) {
   });
 }
 function hostPrefix(home) {
-  return join15(home, ".local");
+  return join16(home, ".local");
 }
 function pathEntries(env) {
   return (env.PATH ?? "").split(delimiter2).filter((part) => part !== "");
@@ -4346,6 +4731,21 @@ async function probeInstalled(target, entry, prefix, user, env) {
     throw err;
   }
 }
+function sandboxMarkerPath(entry) {
+  return `${SANDBOX_HARNESS_PREFIX}/share/agro/harnesses/${entry.id}.installed`;
+}
+async function sandboxMarkerExists(target, entry) {
+  const r = await target.exec({
+    argv: ["test", "-f", sandboxMarkerPath(entry)],
+    user: "sandbox",
+    stdio: "capture",
+    timeoutMs: PROBE_TIMEOUT_MS
+  });
+  return r.exitCode === 0;
+}
+function hostBinaryUnderPrefix(entry, prefix) {
+  return existsSync20(join16(harnessBinPath(prefix), entry.binary));
+}
 function stateOf(entry, installed, location) {
   return {
     id: entry.id,
@@ -4365,7 +4765,7 @@ function probeableHost(env, home) {
     return void 0;
   }
   const prefix = hostPrefix(home);
-  if (!existsSync19(join15(root, ".git")) && !existsSync19(prefix)) return void 0;
+  if (!existsSync20(join16(root, ".git")) && !existsSync20(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectStates(root, run, home, env, only) {
@@ -4571,7 +4971,15 @@ Run: bash ${root}/.agro/scripts/link-providers.sh --init
     const code = await reconcileHermes(target, io, bin, void 0, root);
     if (code !== 0) return code;
   }
-  if (await probeInstalled(target, entry, prefix, void 0, installEnv) === true) {
+  let hasReceipt;
+  try {
+    hasReceipt = readHostConfig(env, home).hostHarnesses?.[entry.id] !== void 0;
+  } catch (err) {
+    io.stderr(`${bin} harness: ${messageOf(err)}
+`);
+    return 1;
+  }
+  if (await probeInstalled(target, entry, prefix, void 0, installEnv) === true && (hasReceipt || !hostBinaryUnderPrefix(entry, prefix))) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
 `);
     try {
@@ -4735,7 +5143,20 @@ async function runHarnessUninstall(name, opts, io) {
   if (!isReachable(await resolveTargetStatus(target))) {
     return await uninstallOnHost(entry, opts, io, run);
   }
-  return (await removeHarness(entry, target, SANDBOX_HARNESS_PREFIX, "sandbox", opts, io)).code;
+  const outcome = await removeHarness(entry, target, SANDBOX_HARNESS_PREFIX, "sandbox", opts, io);
+  if (outcome.dropReceipt) {
+    const cleared = await target.exec({
+      argv: ["rm", "-f", sandboxMarkerPath(entry)],
+      user: "sandbox",
+      stdio: "capture"
+    });
+    if (cleared.exitCode !== 0) {
+      io.stderr(`${opts.bin} harness: could not clear the install record (exit ${cleared.exitCode}).
+`);
+      return 1;
+    }
+  }
+  return outcome.code;
 }
 async function runHarnessInstall(name, opts, io) {
   const run = opts.run ?? spawnRunner;
@@ -4761,7 +5182,7 @@ async function runHarnessInstall(name, opts, io) {
     if (code !== 0) return code;
   }
   const already = await probeInstalled(target, entry, SANDBOX_HARNESS_PREFIX, "sandbox", installEnv);
-  if (already === true) {
+  if (already === true && await sandboxMarkerExists(target, entry)) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
 `);
     return 0;
@@ -4792,15 +5213,26 @@ async function runHarnessInstall(name, opts, io) {
     const code = await reconcileHermes(target, io, opts.bin, "sandbox");
     if (code !== 0) return code;
   }
+  const marker = sandboxMarkerPath(entry);
+  const marked = await target.exec({
+    argv: ["sh", "-c", `mkdir -p "$(dirname "$1")" && : > "$1"`, "sh", marker],
+    user: "sandbox",
+    stdio: "capture"
+  });
+  if (marked.exitCode !== 0) {
+    io.stderr(`${opts.bin} harness: could not record the install at ${marker} (exit ${marked.exitCode}).
+`);
+    return 1;
+  }
   io.stdout(`${entry.id}: installed \u2014 see ${sourceDocsUrl(entry.docsPath)} for authentication
 `);
   return 0;
 }
 
 // src/commands/workspace.ts
-import { existsSync as existsSync20, rmSync as rmSync5 } from "node:fs";
+import { existsSync as existsSync21, rmSync as rmSync5 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-import { join as join16, resolve as resolve10 } from "node:path";
+import { join as join17, resolve as resolve10 } from "node:path";
 function homeOf2(opts) {
   return (opts.homedir ?? homedir4)();
 }
@@ -4846,9 +5278,9 @@ async function runWorkspaceCreate(name, opts, io) {
     return 1;
   }
   let action;
-  const preexisting = existsSync20(root);
+  const preexisting = existsSync21(root);
   try {
-    if (!opts.json && !existsSync20(join16(root, ".git"))) {
+    if (!opts.json && !existsSync21(join17(root, ".git"))) {
       const at = opts.ref !== void 0 ? ` at ${opts.ref}` : "";
       io.stdout(`cloning ${AGRO_REPO_URL}${at} into ${root}\u2026
 `);
@@ -4893,7 +5325,7 @@ async function runWorkspaceList(opts, io) {
     const recorded = recordedRoot(env, home);
     const registry = workspacesRoot(env, home);
     rows = listHostWorkspaces(env, home).map((name) => {
-      const root = join16(registry, name);
+      const root = join17(registry, name);
       return { name, root, default: recorded === root };
     });
   } catch (err) {
@@ -4918,9 +5350,9 @@ async function runWorkspaceList(opts, io) {
 }
 
 // src/commands/tool.ts
-import { existsSync as existsSync21 } from "node:fs";
+import { existsSync as existsSync22 } from "node:fs";
 import { homedir as homedir5, userInfo as userInfo2 } from "node:os";
-import { delimiter as delimiter3, join as join17 } from "node:path";
+import { delimiter as delimiter3, join as join18 } from "node:path";
 
 // src/lib/tools/catalog.ts
 var TOOLS_DOC = "docs/installation.md";
@@ -5337,6 +5769,7 @@ function resolveToolInstallArgv(entry, host) {
 }
 
 // src/commands/tool.ts
+var ROOT_TOOL_REMOVAL_DOCS = `${sourceDocsUrl("docs/installation.md")}#remove-a-root-level-tool`;
 function isReachable2(status) {
   return status === "ready" || status === "starting";
 }
@@ -5350,7 +5783,21 @@ function targetFor2(root, run, env) {
   });
 }
 function hostPrefix2(home) {
-  return join17(home, ".local");
+  return join18(home, ".local");
+}
+function sandboxMarkerPath2(entry) {
+  return `${SANDBOX_HARNESS_PREFIX}/share/agro/tools/${entry.id}.installed`;
+}
+async function sandboxMarkerExists2(target, entry) {
+  const r = await target.exec({
+    argv: ["test", "-f", sandboxMarkerPath2(entry)],
+    user: "sandbox",
+    stdio: "capture"
+  });
+  return r.exitCode === 0;
+}
+function hostBinaryUnderPrefix2(entry, prefix) {
+  return existsSync22(join18(harnessBinPath(prefix), entry.binary));
 }
 function pathEntries2(env) {
   return (env.PATH ?? "").split(delimiter3).filter((part) => part !== "");
@@ -5430,7 +5877,7 @@ function probeableHost2(env, home) {
     return void 0;
   }
   const prefix = hostPrefix2(home);
-  if (!existsSync21(join17(root, ".git")) && !existsSync21(prefix)) return void 0;
+  if (!existsSync22(join18(root, ".git")) && !existsSync22(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectRows(root, run, home, env, only) {
@@ -5646,7 +6093,15 @@ Every tool installer in the catalog is Debian-specific. Install ${entry.id} with
   const prefix = hostPrefix2(home);
   const installEnv = { NPM_USER_PREFIX: prefix };
   const target = hostTargetFor2(root, prefix, run, env);
-  if (await probeInstalled2(target, entry, void 0, installEnv) === true) {
+  let hasReceipt;
+  try {
+    hasReceipt = readHostConfig(env, home).hostTools?.[entry.id] !== void 0;
+  } catch (err) {
+    io.stderr(`${bin} tool: ${messageOf3(err)}
+`);
+    return 1;
+  }
+  if (await probeInstalled2(target, entry, void 0, installEnv) === true && (hasReceipt || entry.hostInstallUser === "root" || !hostBinaryUnderPrefix2(entry, prefix))) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
 `);
     try {
@@ -5681,13 +6136,8 @@ Every tool installer in the catalog is Debian-specific. Install ${entry.id} with
 `);
     return r.exitCode;
   }
-  const receipt = {
-    prefix,
-    binary: entry.binary,
-    binPath: harnessBinPath(prefix),
-    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    workspaceRoot: root
-  };
+  const installedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const receipt = entry.hostInstallUser === "root" ? { scope: "root", binary: entry.binary, installedAt, workspaceRoot: root } : { prefix, binary: entry.binary, binPath: harnessBinPath(prefix), installedAt, workspaceRoot: root };
   try {
     const config = readHostConfig(env, home);
     writeHostConfig(
@@ -5747,7 +6197,7 @@ ${installableToolIds().map((t) => `  ${t}`).join("\n")}
   }
   if (entry.installArgv === void 0) return refuseContainer();
   const already = await probeInstalled2(target, entry, "sandbox");
-  if (already === true) {
+  if (already === true && await sandboxMarkerExists2(target, entry)) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
 `);
     return 0;
@@ -5769,6 +6219,17 @@ ${installableToolIds().map((t) => `  ${t}`).join("\n")}
 `);
     return r.exitCode;
   }
+  const marker = sandboxMarkerPath2(entry);
+  const marked = await target.exec({
+    argv: ["sh", "-c", `mkdir -p "$(dirname "$1")" && : > "$1"`, "sh", marker],
+    user: "sandbox",
+    stdio: "capture"
+  });
+  if (marked.exitCode !== 0) {
+    io.stderr(`${opts.bin} tool: could not record the install at ${marker} (exit ${marked.exitCode}).
+`);
+    return 1;
+  }
   io.stdout(`${entry.id}: installed \u2014 see ${sourceDocsUrl(entry.docsPath)}
 `);
   return 0;
@@ -5829,7 +6290,7 @@ Removing it could delete a tool you installed yourself. Re-run with \`--force\`
     );
     return 1;
   }
-  const prefix = receipt?.prefix ?? computed;
+  const prefix = receipt === void 0 || isRootToolReceipt(receipt) ? computed : receipt.prefix;
   const target = hostTargetFor2(receipt?.workspaceRoot ?? workspace, prefix, run, env);
   const outcome = await removeTool(entry, target, prefix, void 0, opts, io, true);
   if (outcome.dropReceipt && receipt !== void 0) {
@@ -5852,6 +6313,15 @@ async function runToolUninstall(name, opts, io) {
   const root = resolveProjectRoot(opts.cwd);
   const entry = findTool(name);
   if (!entry) return unknownTool(name, io, opts.bin);
+  if (entry.hostInstallUser === "root") {
+    io.stderr(
+      `${opts.bin} tool: ${entry.id} cannot be removed by this command.
+${opts.bin} does not remove system packages that it installed as root.
+Remove ${entry.id} by hand: ${ROOT_TOOL_REMOVAL_DOCS}
+`
+    );
+    return 1;
+  }
   if (entry.uninstallArgv === null) {
     io.stderr(`${opts.bin} tool: ${entry.id} cannot be removed by this command.
 
@@ -5864,7 +6334,20 @@ async function runToolUninstall(name, opts, io) {
   if (!isReachable2(await resolveTargetStatus(target))) {
     return await uninstallOnHost2(entry, opts, io, run);
   }
-  return (await removeTool(entry, target, SANDBOX_HARNESS_PREFIX, "sandbox", opts, io)).code;
+  const outcome = await removeTool(entry, target, SANDBOX_HARNESS_PREFIX, "sandbox", opts, io);
+  if (outcome.dropReceipt) {
+    const cleared = await target.exec({
+      argv: ["rm", "-f", sandboxMarkerPath2(entry)],
+      user: "sandbox",
+      stdio: "capture"
+    });
+    if (cleared.exitCode !== 0) {
+      io.stderr(`${opts.bin} tool: could not clear the install record (exit ${cleared.exitCode}).
+`);
+      return 1;
+    }
+  }
+  return outcome.code;
 }
 
 // src/lib/remote.ts
@@ -5944,7 +6427,7 @@ var INTEGRATIONS = {
     )
   }
 };
-function isHelpFlag(arg) {
+function isHelpFlag2(arg) {
   return arg === "--help" || arg === "-h" || arg === "help";
 }
 function isVersionFlag(arg) {
@@ -5961,7 +6444,7 @@ function printAgroHelp(product = AGRO_PRODUCT) {
   process.stdout.write(`${bin} \u2014 ${title} (v${AGRO_VERSION})
 
 Usage:
-  ${bin} sandbox <args...>      Create and list sandboxes (install|list)
+  ${bin} sandbox <args...>      Create, list, and upgrade sandboxes (install|list|upgrade)
   ${bin} shell [name]           Open a zsh shell in the running sandbox container
   ${bin} config <args...>       Read and write ${stateNames(bin).configFile} (show|set), or run a wizard
   ${bin} secret <args...>       Read and write the gitignored root .env (set|list)
@@ -6111,66 +6594,6 @@ Flags:
   --force         Override the up-to-date / downgrade gate.
 `);
 }
-function runtimeLines() {
-  const width = Math.max(...RUNTIME_CATALOG.map((r) => r.id.length));
-  return RUNTIME_CATALOG.map(
-    (r) => `  ${r.id.padEnd(width)}  ${r.provisionable ? "provisionable" : "planned"}`
-  ).join("\n");
-}
-function printSandboxHelp(bin = AGRO_PRODUCT.bin) {
-  process.stdout.write(`${bin} sandbox \u2014 Create and list sandboxes
-
-Usage:
-  ${bin} sandbox install <runtime> [--name <name>] [--checkout <dir>]
-                               [--home-mount <dir>] [--yes]
-                               [--version <X.Y.Z> | --image[=<ref>]]
-                               [--no-build] [--print-argv]
-  ${bin} sandbox list [--json]
-
-\`install\` writes a sandbox entry under \${${stateNames(bin).envPrefix}HOME:-~/${stateNames(bin).userStateDir}}/sandboxes/<name>/,
-materialises the compose files and the compose wrapper into it, then starts the
-container. It needs no project checkout and runs from any directory. Without
---checkout the sandbox runs the prebuilt image; with --checkout <dir> that
-checkout is bound at /home/sandbox/harness; the sandbox builds locally only
-when that directory holds .devcontainer/Dockerfile.
-
-On a terminal without --yes it asks for the sandbox name, the timezone, the git
-identity, SSH (with its host port), the host Docker socket, and the host path
-for /home/sandbox. With --checkout it seeds those answers from that
-checkout's ${stateNames(bin).configFile}.
-
-Flags:
-  --name <name>    Registry entry name (default: the lowest free ${DEFAULT_NAME_PREFIX}<n>)
-  --checkout <dir> Bind this checkout into the sandbox and seed the defaults
-                   from its ${stateNames(bin).configFile}. The sandbox builds
-                   locally only when that directory holds
-                   .devcontainer/Dockerfile
-  --repo <dir>     Deprecated alias for --checkout
-  --home-mount <dir>
-                   Bind this host directory at /home/sandbox instead of the
-                   Docker-managed volume. Relative paths resolve against the
-                   working directory. The directory is created when absent
-  --yes            Non-interactive: keep every default and ask nothing
-  --version <X.Y.Z>
-                   Run the official release image ghcr.io/mifunedev/agro:<X.Y.Z>
-                   (implies --image). A leading v and a -<channel>.<n>
-                   pre-release suffix are accepted
-  --image          Run the prebuilt image instead of building (implies
-                   --no-build). The ref resolves first-match: --version or
-                   --image=<ref> > ${stateNames(bin).envPrefix}SANDBOX_IMAGE >
-                   ${stateNames(bin).configFile} image.ref > ${officialImageRef(AGRO_VERSION)}
-  --image=<ref>    Run a custom image (implies --image); conflicts with --version
-  --no-build       Suppress the local build and reuse an existing image
-  --print-argv     Print the docker compose argv that would run, then exit
-                   without writing an entry
-  --json           Machine-readable output (list)
-
-Runtimes:
-${runtimeLines()}
-
-Next: ${bin} shell <name>
-`);
-}
 function printShellHelp(bin = AGRO_PRODUCT.bin) {
   process.stdout.write(`${bin} shell \u2014 Open a shell in the running sandbox container
 
@@ -6295,6 +6718,8 @@ no workspace: run \`${bin} workspace create\` first. It installs into
 \`~/.local\` and records the install as \`hostTools\` in that same file. On the host,
 \`uninstall\` removes only what \`install\` recorded, from the prefix in that record.
 Without a record it refuses, and \`--force\` overrides.
+\`uninstall\` refuses each root-level tool, marked \`(root)\` in \`${bin} tool list\`,
+with and without \`--force\`. The refusal links the manual removal steps.
 
 Flags:
   --yes            Accept a large download without prompting
@@ -6384,7 +6809,7 @@ function extractSandboxFlag(command, rest) {
 }
 var LANGFUSE_VERBS = ["apply", "status", "disable"];
 function parseLangfuseArgs(rest, bin = AGRO_PRODUCT.bin) {
-  if (rest.length === 0 || isHelpFlag(rest[0])) return { ok: true, args: { help: true } };
+  if (rest.length === 0 || isHelpFlag2(rest[0])) return { ok: true, args: { help: true } };
   const [head, ...tail] = rest;
   if (!LANGFUSE_VERBS.includes(head)) {
     return {
@@ -6393,7 +6818,7 @@ function parseLangfuseArgs(rest, bin = AGRO_PRODUCT.bin) {
       showHelp: true
     };
   }
-  if (isHelpFlag(tail[0])) return { ok: true, args: { help: true } };
+  if (isHelpFlag2(tail[0])) return { ok: true, args: { help: true } };
   if (tail.length > 0) {
     return { ok: false, error: `${bin} langfuse ${head}: unexpected argument "${tail[0]}"` };
   }
@@ -6411,12 +6836,12 @@ function parseConfigArgs(input, bin = AGRO_PRODUCT.bin) {
     ...scoped.args.sandbox === void 0 ? {} : { sandbox: scoped.args.sandbox },
     ...forced ? { force: true } : {}
   };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
+  if (rest.length === 0 || isHelpFlag2(rest[0])) {
     return { ok: true, args: { ...args, help: true } };
   }
   const [head, ...tail] = rest;
   if (!CONFIG_VERBS.includes(head)) {
-    if (tail.length > 0 && isHelpFlag(tail[0])) {
+    if (tail.length > 0 && isHelpFlag2(tail[0])) {
       return { ok: true, args: { ...args, integration: head, integrationHelp: true } };
     }
     if (tail.length > 0) {
@@ -6428,7 +6853,7 @@ function parseConfigArgs(input, bin = AGRO_PRODUCT.bin) {
     return { ok: true, args: { ...args, integration: head } };
   }
   const verb = head;
-  if (isHelpFlag(tail[0])) return { ok: true, args: { ...args, help: true } };
+  if (isHelpFlag2(tail[0])) return { ok: true, args: { ...args, help: true } };
   if (verb === "show" || verb === "repo") {
     if (tail.length > 0) {
       return { ok: false, error: `${bin} config ${verb}: unexpected argument "${tail[0]}"` };
@@ -6460,7 +6885,7 @@ function parseSecretArgs(input, bin = AGRO_PRODUCT.bin) {
     help: false,
     ...scoped.args.sandbox === void 0 ? {} : { sandbox: scoped.args.sandbox }
   };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
+  if (rest.length === 0 || isHelpFlag2(rest[0])) {
     return { ok: true, args: { ...args, help: true } };
   }
   const [head, ...tail] = rest;
@@ -6472,7 +6897,7 @@ function parseSecretArgs(input, bin = AGRO_PRODUCT.bin) {
     };
   }
   const verb = head;
-  if (isHelpFlag(tail[0])) return { ok: true, args: { ...args, help: true } };
+  if (isHelpFlag2(tail[0])) return { ok: true, args: { ...args, help: true } };
   if (verb === "list") {
     if (tail.length > 0) {
       return { ok: false, error: `${bin} secret list: unexpected argument "${tail[0]}"` };
@@ -6493,7 +6918,7 @@ function parseSecretArgs(input, bin = AGRO_PRODUCT.bin) {
 }
 function parseDestroyArgs(rest, bin = AGRO_PRODUCT.bin) {
   const args = { help: false, yes: false };
-  if (isHelpFlag(rest[0])) return { ok: true, args: { ...args, help: true } };
+  if (isHelpFlag2(rest[0])) return { ok: true, args: { ...args, help: true } };
   for (const token of rest) {
     if (token === "--yes") {
       args.yes = true;
@@ -6512,7 +6937,7 @@ function parseDestroyArgs(rest, bin = AGRO_PRODUCT.bin) {
 }
 function parseComposeArgs(rest, bin = AGRO_PRODUCT.bin) {
   const args = { help: false, passthrough: [] };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
+  if (rest.length === 0 || isHelpFlag2(rest[0])) {
     return { ok: true, args: { ...args, help: true } };
   }
   if (rest[0] !== "config") {
@@ -6524,7 +6949,7 @@ function parseComposeArgs(rest, bin = AGRO_PRODUCT.bin) {
   }
   args.subcommand = "config";
   const tail = rest.slice(1);
-  if (isHelpFlag(tail[0])) return { ok: true, args: { ...args, help: true } };
+  if (isHelpFlag2(tail[0])) return { ok: true, args: { ...args, help: true } };
   const sep4 = tail.indexOf("--");
   if (sep4 === -1 && tail.length > 0) {
     return {
@@ -6550,7 +6975,7 @@ function parseSelfUpgradeArgs(rest, bin = AGRO_PRODUCT.bin) {
       args.dryRun = true;
       continue;
     }
-    if (isHelpFlag(arg)) {
+    if (isHelpFlag2(arg)) {
       args.help = true;
       return { ok: true, args };
     }
@@ -6592,7 +7017,7 @@ function parseVendorArgs(rest, bin = AGRO_PRODUCT.bin) {
       args.force = true;
       continue;
     }
-    if (isHelpFlag(arg)) {
+    if (isHelpFlag2(arg)) {
       args.help = true;
       return { ok: true, args };
     }
@@ -6609,121 +7034,9 @@ function parseVendorArgs(rest, bin = AGRO_PRODUCT.bin) {
   }
   return { ok: true, args };
 }
-var SANDBOX_VALUE_FLAGS = {
-  "--name": "name",
-  "--checkout": "checkout",
-  "--repo": "checkout",
-  "--home-mount": "homeMount"
-};
-function parseSandboxArgs(rest, bin = AGRO_PRODUCT.bin) {
-  const args = {
-    help: false,
-    yes: false,
-    image: false,
-    noBuild: false,
-    printArgv: false,
-    json: false
-  };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
-    return { ok: true, args: { ...args, help: true } };
-  }
-  const [head, ...tail] = rest;
-  if (head !== "install" && head !== "list") {
-    return {
-      ok: false,
-      error: `${bin} sandbox: unknown subcommand "${head}" \u2014 expected install or list`,
-      showHelp: true
-    };
-  }
-  args.subcommand = head;
-  if (isHelpFlag(tail[0])) return { ok: true, args: { ...args, help: true } };
-  const positionals = [];
-  const checkoutSpellings = /* @__PURE__ */ new Set();
-  let version;
-  for (let i = 0; i < tail.length; i++) {
-    const token = tail[i];
-    const valueFlag = SANDBOX_VALUE_FLAGS[token];
-    if (valueFlag !== void 0) {
-      const value = tail[i + 1];
-      if (value === void 0) {
-        return { ok: false, error: `${bin} sandbox ${head}: ${token} requires a value` };
-      }
-      if (valueFlag === "checkout") checkoutSpellings.add(token);
-      args[valueFlag] = value;
-      i++;
-    } else if (token === "--yes") {
-      args.yes = true;
-    } else if (token === "--no-build") {
-      args.noBuild = true;
-    } else if (token === "--print-argv") {
-      args.printArgv = true;
-    } else if (token === "--image") {
-      args.image = true;
-    } else if (token.startsWith("--image=")) {
-      const ref = token.slice("--image=".length);
-      if (ref === "") {
-        return { ok: false, error: `${bin} sandbox: --image=<ref> requires a non-empty image ref` };
-      }
-      args.image = true;
-      args.imageRef = ref;
-    } else if (token === "--version" || token.startsWith("--version=")) {
-      const value = token === "--version" ? tail[++i] : token.slice("--version=".length);
-      if (value === void 0 || value === "") {
-        return { ok: false, error: `${bin} sandbox ${head}: --version requires a value` };
-      }
-      version = parseReleaseVersion(value);
-      if (version === void 0) {
-        return {
-          ok: false,
-          error: `${bin} sandbox ${head}: --version "${value}" is not a release version \u2014 expected X.Y.Z`
-        };
-      }
-    } else if (token === "--json") {
-      args.json = true;
-    } else if (token.startsWith("-")) {
-      return { ok: false, error: `${bin} sandbox ${head}: unknown flag "${token}"` };
-    } else {
-      positionals.push(token);
-    }
-  }
-  if (checkoutSpellings.has("--checkout") && checkoutSpellings.has("--repo")) {
-    return {
-      ok: false,
-      error: `${bin} sandbox ${head}: --checkout conflicts with --repo \u2014 pass exactly one, and prefer --checkout`
-    };
-  }
-  if (version !== void 0) {
-    if (args.imageRef !== void 0) {
-      return {
-        ok: false,
-        error: `${bin} sandbox ${head}: --version conflicts with --image=<ref> \u2014 pass --version for an official release or --image=<ref> for a custom image`
-      };
-    }
-    args.image = true;
-    args.imageRef = officialImageRef(version);
-  }
-  if (head === "list") {
-    if (positionals.length > 0) {
-      return { ok: false, error: `${bin} sandbox list: unexpected argument "${positionals[0]}"` };
-    }
-    return { ok: true, args };
-  }
-  if (positionals.length === 0) {
-    return {
-      ok: false,
-      error: `${bin} sandbox install: a runtime is required, e.g. \`${bin} sandbox install docker\``,
-      showHelp: true
-    };
-  }
-  if (positionals.length > 1) {
-    return { ok: false, error: `${bin} sandbox install: unexpected argument "${positionals[1]}"` };
-  }
-  args.runtime = positionals[0];
-  return { ok: true, args };
-}
 function parseShellArgs(rest, bin = AGRO_PRODUCT.bin) {
   const args = { help: false };
-  if (isHelpFlag(rest[0])) return { ok: true, args: { help: true } };
+  if (isHelpFlag2(rest[0])) return { ok: true, args: { help: true } };
   for (const token of rest) {
     if (token.startsWith("-")) {
       return { ok: false, error: `${bin} shell: unknown flag "${token}"` };
@@ -6737,7 +7050,7 @@ function parseShellArgs(rest, bin = AGRO_PRODUCT.bin) {
 }
 function parseWorkspaceArgs(rest, bin = AGRO_PRODUCT.bin) {
   const args = { help: false, json: false };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
+  if (rest.length === 0 || isHelpFlag2(rest[0])) {
     return { ok: true, args: { ...args, help: true } };
   }
   const positionals = [];
@@ -6809,7 +7122,7 @@ function parseHarnessArgs(rest, bin = AGRO_PRODUCT.bin) {
     host: false,
     force: false
   };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
+  if (rest.length === 0 || isHelpFlag2(rest[0])) {
     return { ok: true, args: { ...args, help: true } };
   }
   const positionals = [];
@@ -6890,7 +7203,7 @@ function parseHarnessArgs(rest, bin = AGRO_PRODUCT.bin) {
 }
 function parseToolArgs(rest, bin = AGRO_PRODUCT.bin) {
   const args = { help: false, yes: false, json: false, host: false, force: false };
-  if (rest.length === 0 || isHelpFlag(rest[0])) {
+  if (rest.length === 0 || isHelpFlag2(rest[0])) {
     return { ok: true, args: { ...args, help: true } };
   }
   const positionals = [];
@@ -6948,11 +7261,11 @@ function parseGatewayArgs(rest) {
   }
   return { ok: true, args: { help: false, passthrough: [...rest] } };
 }
-function bundledPayloadExists(bundled, exists = existsSync22) {
-  return exists(join18(bundled.sourceControlDir, "manifest.json"));
+function bundledPayloadExists(bundled, exists = existsSync23) {
+  return exists(join19(bundled.sourceControlDir, "manifest.json"));
 }
 function resolveVendorSource(args, bundled, bin = AGRO_PRODUCT.bin) {
-  const exists = bundled.exists ?? existsSync22;
+  const exists = bundled.exists ?? existsSync23;
   if (args.fromDir !== void 0) {
     return { kind: "local", fromDir: resolve11(args.fromDir) };
   }
@@ -6972,7 +7285,7 @@ function resolveVendorSource(args, bundled, bin = AGRO_PRODUCT.bin) {
 function readPayloadVersion(checkoutDir) {
   try {
     const parsed = JSON.parse(
-      readFileSync12(join18(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
+      readFileSync13(join19(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
     );
     if (parsed && typeof parsed.version === "string") return parsed.version;
   } catch {
@@ -6981,7 +7294,7 @@ function readPayloadVersion(checkoutDir) {
 }
 async function runWithRemoteSource(hooks, fn) {
   const fetch2 = hooks.fetch ?? fetchRemoteSource;
-  const mkdtemp = hooks.mkdtemp ?? (() => mkdtempSync5(join18(tmpdir4(), "oh-remote-")));
+  const mkdtemp = hooks.mkdtemp ?? (() => mkdtempSync5(join19(tmpdir4(), "oh-remote-")));
   const rm = hooks.rm ?? ((dir) => rmSync6(dir, { recursive: true, force: true }));
   const out = hooks.stdout ?? ((s) => process.stdout.write(s));
   const checkoutDir = mkdtemp();
@@ -6998,7 +7311,7 @@ async function main(argv) {
   const product = resolveProduct(process.argv[1]);
   const bin = product.bin;
   const [first, second] = argv;
-  if (!first || isHelpFlag(first)) {
+  if (!first || isHelpFlag2(first)) {
     printAgroHelp(product);
     return 0;
   }
@@ -7141,37 +7454,7 @@ async function main(argv) {
       (checkoutDir) => runUpdate({ bin, targetDir, fromDir: checkoutDir, force, dryRun }, io)
     );
   }
-  if (first === "sandbox") {
-    const parsed = parseSandboxArgs(argv.slice(1), bin);
-    if (!parsed.ok) {
-      process.stderr.write(`${parsed.error}
-`);
-      if (parsed.showHelp) printSandboxHelp(bin);
-      return 1;
-    }
-    const a = parsed.args;
-    if (a.help) {
-      printSandboxHelp(bin);
-      return a.subcommand === void 0 ? 1 : 0;
-    }
-    const io = lifecycleIo();
-    if (a.subcommand === "list") return await runSandboxList({ bin, json: a.json }, io);
-    return await runSandboxInstall(
-      {
-        bin,
-        runtime: a.runtime,
-        ...a.name !== void 0 ? { name: a.name } : {},
-        ...a.checkout !== void 0 ? { checkout: a.checkout } : {},
-        ...a.homeMount !== void 0 ? { homeMount: a.homeMount } : {},
-        yes: a.yes,
-        image: a.image,
-        ...a.imageRef !== void 0 ? { imageRef: a.imageRef } : {},
-        noBuild: a.noBuild,
-        printArgv: a.printArgv
-      },
-      io
-    );
-  }
+  if (first === "sandbox") return runSandboxCommand(argv.slice(1), bin);
   if (first === "shell") {
     const parsed = parseShellArgs(argv.slice(1), bin);
     if (!parsed.ok) {
@@ -7256,7 +7539,7 @@ async function main(argv) {
   if (composeVerbs().includes(first)) {
     const verb = first;
     const rest = argv.slice(1);
-    if (isHelpFlag(rest[0])) {
+    if (isHelpFlag2(rest[0])) {
       printComposeVerbHelp(verb, bin);
       return 0;
     }
@@ -7386,7 +7669,7 @@ export {
   SECRET_VERBS,
   bundledPayloadExists,
   extractSandboxFlag,
-  isHelpFlag,
+  isHelpFlag2 as isHelpFlag,
   isVersionFlag,
   parseComposeArgs,
   parseConfigArgs,