@mifune/agro 0.15.1 → 0.16.1

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
@@ -611,6 +611,15 @@ ${detail}`);
 function copyFile(deps, from, to) {
   deps.writeFile(to, deps.readFile(from), deps.stat(from).mode & 511);
 }
+var ABSOLUTE_NODE_SHEBANG = /^#!\/\S*\/node$/;
+function withPinnedShebang(current, artifact) {
+  const currentEnd = current.indexOf(10);
+  const artifactEnd = artifact.indexOf(10);
+  if (currentEnd < 0 || artifactEnd < 0) return artifact;
+  const firstLine = current.subarray(0, currentEnd);
+  if (!ABSOLUTE_NODE_SHEBANG.test(firstLine.toString("utf8"))) return artifact;
+  return Buffer.concat([firstLine, artifact.subarray(artifactEnd)]);
+}
 function removeQuietly(deps, path4, io) {
   try {
     deps.unlink(path4);
@@ -645,11 +654,11 @@ async function upgradeStandalone(installation, opts, deps, io) {
   let prevPresent = false;
   let replaced = false;
   try {
-    deps.writeFile(tmp, artifact, 493);
-    tmpPresent = true;
     if (artifact.subarray(0, 2).toString("utf8") !== "#!") {
       throw new Error(`invalid artifact from ${url}: no #! shebang`);
     }
+    deps.writeFile(tmp, withPinnedShebang(deps.readFile(target), artifact), 493);
+    tmpPresent = true;
     const probe = deps.runNode(tmp, ["--version"]);
     const available = versionOf(probe);
     if (parseSemver(available) === void 0) {
@@ -1403,10 +1412,10 @@ import { existsSync as existsSync6, mkdirSync as mkdirSync3, readdirSync as read
 import { dirname as dirname4, join as join4, resolve as resolve5, sep as sep2 } from "node:path";
 
 // agro-asset:/home/runner/work/agro/agro/.devcontainer/docker-compose.yml
-var docker_compose_default = 'name: ${SANDBOX_NAME:-agro}\n\nservices:\n  sandbox:\n    image: ${AGRO_SANDBOX_IMAGE:-sandbox-${SANDBOX_NAME:-agro}}\n    pull_policy: ${AGRO_PULL_POLICY:-missing}\n    container_name: ${SANDBOX_NAME:-agro}\n    build:\n      context: ${AGRO_REPO_DIR:-..}\n      dockerfile: .devcontainer/Dockerfile\n    volumes:\n      - ${AGRO_HOME_MOUNT:-workspace}:/home/sandbox\n      - ${AGRO_REPO_DIR:-..}:/home/sandbox/harness\n    extra_hosts:\n      - "host.docker.internal:host-gateway"\n    environment:\n      - SANDBOX_NAME=${SANDBOX_NAME:-agro}\n      - SANDBOX_PASSWORD=${SANDBOX_PASSWORD:-test1234}\n      - TZ=${TZ:-America/Los_Angeles}\n      - CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=true\n      - CC_SAFETY_NET_STRICT=1\n      - CC_SAFETY_NET_WORKTREE=1\n      - GIT_USER_NAME=${GIT_USER_NAME:-}\n      - GIT_USER_EMAIL=${GIT_USER_EMAIL:-}\n      - GH_TOKEN=${GH_TOKEN:-}\n    stdin_open: true\n    tty: true\n    cgroup: private\n    cap_add:\n      - SYS_ADMIN\n    security_opt:\n      - apparmor=unconfined\n    tmpfs:\n      - /run\n      - /run/lock\n      - /sys/fs\n    healthcheck:\n      test: ["CMD", "bash", "-c", "exec bash /home/sandbox/harness/.agro/scripts/sandbox-healthcheck.sh"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 600s\n    restart: unless-stopped\n\nvolumes:\n  workspace:\n';
+var docker_compose_default = 'name: ${SANDBOX_NAME:-agro}\n\nservices:\n  sandbox:\n    image: ${AGRO_SANDBOX_IMAGE:-sandbox-${SANDBOX_NAME:-agro}}\n    pull_policy: ${AGRO_PULL_POLICY:-missing}\n    container_name: ${SANDBOX_NAME:-agro}\n    build:\n      context: ${AGRO_REPO_DIR:-..}\n      dockerfile: .devcontainer/Dockerfile\n    volumes:\n      - ${AGRO_HOME_MOUNT:-workspace}:/home/sandbox\n      - ${AGRO_REPO_DIR:-..}:/home/sandbox/harness\n    extra_hosts:\n      - "host.docker.internal:host-gateway"\n    environment:\n      - SANDBOX_NAME=${SANDBOX_NAME:-agro}\n      - SANDBOX_PASSWORD=${SANDBOX_PASSWORD:-test1234}\n      - TZ=${TZ:-America/Los_Angeles}\n      - CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=true\n      - CC_SAFETY_NET_STRICT=1\n      - CC_SAFETY_NET_WORKTREE=1\n      - GIT_USER_NAME=${GIT_USER_NAME:-}\n      - GIT_USER_EMAIL=${GIT_USER_EMAIL:-}\n      - GH_TOKEN=${GH_TOKEN:-}\n      - TYPESAFE_API_KEY=${TYPESAFE_API_KEY:-}\n    stdin_open: true\n    tty: true\n    cgroup: private\n    cap_add:\n      - SYS_ADMIN\n    security_opt:\n      - apparmor=unconfined\n    tmpfs:\n      - /run\n      - /run/lock\n      - /sys/fs\n    healthcheck:\n      test: ["CMD", "bash", "-c", "exec bash /home/sandbox/harness/.agro/scripts/sandbox-healthcheck.sh"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 600s\n    restart: unless-stopped\n\nvolumes:\n  workspace:\n';
 
 // agro-asset:/home/runner/work/agro/agro/.devcontainer/docker-compose.image-only.yml
-var docker_compose_image_only_default = 'name: ${SANDBOX_NAME:-agro}\n\nservices:\n  sandbox:\n    image: ${AGRO_SANDBOX_IMAGE:-ghcr.io/mifunedev/agro:latest}\n    pull_policy: ${AGRO_PULL_POLICY:-always}\n    container_name: ${SANDBOX_NAME:-agro}\n    volumes:\n      - ${AGRO_HOME_MOUNT:-workspace}:/home/sandbox\n    extra_hosts:\n      - "host.docker.internal:host-gateway"\n    environment:\n      - SANDBOX_NAME=${SANDBOX_NAME:-agro}\n      - SANDBOX_PASSWORD=${SANDBOX_PASSWORD:-test1234}\n      - TZ=${TZ:-America/Los_Angeles}\n      - CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=true\n      - CC_SAFETY_NET_STRICT=1\n      - CC_SAFETY_NET_WORKTREE=1\n      - GIT_USER_NAME=${GIT_USER_NAME:-}\n      - GIT_USER_EMAIL=${GIT_USER_EMAIL:-}\n      - GH_TOKEN=${GH_TOKEN:-}\n    stdin_open: true\n    tty: true\n    cgroup: private\n    cap_add:\n      - SYS_ADMIN\n    security_opt:\n      - apparmor=unconfined\n    tmpfs:\n      - /run\n      - /run/lock\n      - /sys/fs\n    healthcheck:\n      test: ["CMD", "bash", "-c", "exec bash /home/sandbox/harness/.agro/scripts/sandbox-healthcheck.sh"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 600s\n    restart: unless-stopped\n\nvolumes:\n  workspace:\n';
+var docker_compose_image_only_default = 'name: ${SANDBOX_NAME:-agro}\n\nservices:\n  sandbox:\n    image: ${AGRO_SANDBOX_IMAGE:-ghcr.io/mifunedev/agro:latest}\n    pull_policy: ${AGRO_PULL_POLICY:-always}\n    container_name: ${SANDBOX_NAME:-agro}\n    volumes:\n      - ${AGRO_HOME_MOUNT:-workspace}:/home/sandbox\n    extra_hosts:\n      - "host.docker.internal:host-gateway"\n    environment:\n      - SANDBOX_NAME=${SANDBOX_NAME:-agro}\n      - SANDBOX_PASSWORD=${SANDBOX_PASSWORD:-test1234}\n      - TZ=${TZ:-America/Los_Angeles}\n      - CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=true\n      - CC_SAFETY_NET_STRICT=1\n      - CC_SAFETY_NET_WORKTREE=1\n      - GIT_USER_NAME=${GIT_USER_NAME:-}\n      - GIT_USER_EMAIL=${GIT_USER_EMAIL:-}\n      - GH_TOKEN=${GH_TOKEN:-}\n      - TYPESAFE_API_KEY=${TYPESAFE_API_KEY:-}\n    stdin_open: true\n    tty: true\n    cgroup: private\n    cap_add:\n      - SYS_ADMIN\n    security_opt:\n      - apparmor=unconfined\n    tmpfs:\n      - /run\n      - /run/lock\n      - /sys/fs\n    healthcheck:\n      test: ["CMD", "bash", "-c", "exec bash /home/sandbox/harness/.agro/scripts/sandbox-healthcheck.sh"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 600s\n    restart: unless-stopped\n\nvolumes:\n  workspace:\n';
 
 // agro-asset:/home/runner/work/agro/agro/.devcontainer/docker-compose.ssh.yml
 var docker_compose_ssh_default = 'services:\n  sandbox:\n    ports:\n      - "127.0.0.1:${SANDBOX_SSH_PORT:-2222}:22"\n';
@@ -1484,8 +1493,7 @@ if [ -f "$REPO_DIR/harness.yaml" ] && [ -f "$MIGRATOR" ]; then
   sh "$MIGRATOR" "$REPO_DIR" >&2 || true
 fi
 
-ENV_FILE="$REPO_DIR/.env"
-[ -f "$ENV_FILE" ] || ENV_FILE="$REPO_DIR/.devcontainer/.env"
+ENV_FILE="$(agro_env_file "$REPO_DIR")"
 
 compose_path() {
   case "$1" in
@@ -1632,6 +1640,14 @@ agro_config_file() {
   printf '%s\\n' "$1/$AGRO_CONFIG_FILE"
 }
 
+agro_env_file() {
+  if [ -f "$1/.env" ]; then
+    printf '%s\\n' "$1/.env"
+  else
+    printf '%s\\n' "$1/.devcontainer/.env"
+  fi
+}
+
 agro_env_value() {
   local key="AGRO_$1"
   printf '%s\\n' "\${!key:-}"
@@ -2222,7 +2238,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.1" : "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) {
@@ -2852,6 +2868,7 @@ function sameRemote(url, owner, name) {
 }
 
 // src/commands/secret.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
 import { existsSync as existsSync12 } from "node:fs";
 import { join as join7 } from "node:path";
 
@@ -2883,8 +2900,16 @@ function appendGitignoreLines(root, lines) {
 function secretsRoot(opts) {
   return opts.sandbox === void 0 ? resolveProjectRoot(opts.cwd) : resolveSandboxRoot({ name: opts.sandbox });
 }
+function isGitIgnored(root, path4) {
+  const result = spawnSync3("git", ["check-ignore", "-q", "--no-index", path4], {
+    cwd: root,
+    stdio: "ignore"
+  });
+  return result.status === 0;
+}
 function ignoreSecretsFile(root) {
   if (!existsSync12(join7(root, ".git"))) return;
+  if (isGitIgnored(root, ".env")) return;
   appendGitignoreLines(root, [".env"]);
 }
 function secretKeyList() {
@@ -3129,7 +3154,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"],
@@ -3744,7 +3769,7 @@ var RUNTIME_CATALOG = Object.freeze([
     tier: "container",
     state: "active",
     provisionable: true,
-    docsPath: "docs/runtimes/docker.md"
+    docsPath: "docs/runtimes/overview.md"
   }),
   Object.freeze({
     id: "microsandbox",
@@ -3752,7 +3777,7 @@ var RUNTIME_CATALOG = Object.freeze([
     tier: "microvm",
     state: "planned",
     provisionable: false,
-    notProvisionableReason: (bin) => `microsandbox is not a provisionable runtime yet; see docs/rfcs/rfc-runtime-support.md. Inside a sandbox run \`${bin} tool install microsandbox\`.`,
+    notProvisionableReason: (bin) => `microsandbox is not a provisionable runtime yet; see https://github.com/mifunedev/agro/issues/592. Inside a sandbox run \`${bin} tool install microsandbox\`.`,
     docsPath: "docs/runtimes/microsandbox.md"
   })
 ]);
@@ -3784,6 +3809,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,191 +4075,527 @@ async function runSandboxInstall(opts, io) {
   }
   return code;
 }
-async function entryStatus(root, name, run) {
-  try {
-    const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
-    return await target.status();
-  } catch {
-    return "unknown";
-  }
+
+// 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);
 }
-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)
-    });
+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;
   }
-  if (opts.json === true) {
-    io.stdout(`${JSON.stringify(rows, null, 2)}
+  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 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 1;
   }
-  return 0;
-}
-
-// src/commands/harness.ts
-import { existsSync as existsSync19 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { delimiter as delimiter2, join as join15 } from "node:path";
-
-// src/lib/docs.ts
-var SOURCE_DOCS_BASE = "https://github.com/mifunedev/agro/blob/main/";
-function sourceDocsUrl(docsPath) {
-  const segments = docsPath.split("/");
-  if (segments[0] !== "docs" || segments.length < 2 || segments.some((segment) => segment === "" || segment === "." || segment === "..") || docsPath.includes("\\") || docsPath.includes("?") || docsPath.includes("#")) {
-    throw new Error(`source docs path must be a normalized docs/ path: ${docsPath}`);
+  if (runningInsideSandbox()) {
+    io.stderr(`${prefix} host-only \u2014 run this command on the host
+`);
+    return 1;
   }
-  return new URL(segments.map(encodeURIComponent).join("/"), SOURCE_DOCS_BASE).toString();
-}
-
-// 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";
-var HOST_CONFIG_MODE = 420;
-var HOST_CONFIG_FILE = "config.json";
-var WORKSPACES_SUBDIR = "workspaces";
-var DEFAULT_WORKSPACE_NAME = "harness";
-function hostStateHome(env, home) {
-  return resolveUserStateHome(env, home);
-}
-function hostConfigPath(env, home) {
-  return join13(hostStateHome(env, home), HOST_CONFIG_FILE);
-}
-function assertWorkspaceName(name) {
-  if (!SANDBOX_NAME_PATTERN.test(name)) {
-    throw new Error(
-      `invalid workspace name "${name}" \u2014 use lowercase letters, digits and dashes, starting with a letter or digit`
-    );
+  let root;
+  try {
+    root = entryRoot(opts.name);
+  } catch (error) {
+    io.stderr(`${prefix} ${errorMessage(error)}
+`);
+    return 1;
   }
-}
-function workspacesRoot(env, home) {
-  return join13(hostStateHome(env, home), WORKSPACES_SUBDIR);
-}
-function workspaceRoot(name, env, home) {
-  assertWorkspaceName(name);
-  return join13(workspacesRoot(env, home), name);
-}
-function defaultHarnessRoot(env, home) {
-  return join13(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
-}
-function validateHostConfig(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${HOST_CONFIG_FILE}: must contain a JSON object`);
+  const configFile = agroConfigPath(root);
+  if (!existsSync17(configFile)) {
+    io.stderr(`${prefix} no sandbox entry named "${opts.name}"
+`);
+    return 1;
   }
-  const record = value;
-  if (record.version !== void 0 && record.version !== 1) {
-    throw fieldError2("version", "must be 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;
   }
-  const harnessRoot = record.harnessRoot;
-  if (harnessRoot !== void 0) {
-    if (typeof harnessRoot !== "string" || harnessRoot === "") {
-      throw fieldError2("harnessRoot", "must be a non-empty string");
+  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;
     }
-    if (!isAbsolute(harnessRoot)) {
-      throw fieldError2("harnessRoot", "must be an absolute path");
+    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 hostHarnesses = record.hostHarnesses;
-  if (hostHarnesses !== void 0) validateReceipts(hostHarnesses, "hostHarnesses", "harness");
-  const hostTools = record.hostTools;
-  if (hostTools !== void 0) validateReceipts(hostTools, "hostTools", "tool");
-  return { ...record, version: 1 };
-}
-function absoluteField(value, path4) {
-  if (typeof value !== "string" || value === "") {
-    throw fieldError2(path4, "must be a non-empty string");
-  }
-  if (!isAbsolute(value)) throw fieldError2(path4, "must be an absolute path");
-  return value;
-}
-function validateReceipts(value, field, noun) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw fieldError2(field, `must be a JSON object keyed by ${noun} id`);
-  }
-  for (const [id, receipt] of Object.entries(value)) {
-    if (id === "") throw fieldError2(field, `must use a non-empty ${noun} id as each key`);
-    const at = `${field}.${id}`;
-    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
-      throw fieldError2(at, "must be a JSON object");
+    const dotenv = conflictingDotenvImage(root, imageRef);
+    if (dotenv !== void 0) {
+      io.stderr(`${prefix} conflicting AGRO_SANDBOX_IMAGE in ${dotenv}
+`);
+      return 1;
     }
-    const entry = receipt;
-    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");
+    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;
+      }
     }
-    if (typeof entry.installedAt !== "string" || entry.installedAt === "") {
-      throw fieldError2(`${at}.installedAt`, "must be a non-empty string");
+    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 (entry.workspaceRoot !== void 0) {
-      absoluteField(entry.workspaceRoot, `${at}.workspaceRoot`);
+    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})`;
     }
-  }
-}
-function readHostConfig(env, home) {
-  const path4 = hostConfigPath(env, home);
-  if (!existsSync17(path4)) return { version: 1 };
-  let raw;
-  try {
-    raw = readFileSync11(path4, "utf8");
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`could not read ${path4}: ${detail}`);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new Error(`${basename5(path4)} is not valid JSON: ${path4}`);
-  }
-  return validateHostConfig(parsed);
-}
-function writeHostConfig(config, env, home) {
-  const path4 = hostConfigPath(env, home);
-  const validated = validateHostConfig({ ...config, version: 1 });
-  const body = `${JSON.stringify(validated, null, 2)}
-`;
-  const tmp = `${path4}.tmp.${process.pid}`;
-  mkdirSync9(dirname8(path4), { recursive: true });
-  try {
-    writeFileSync9(tmp, body, { mode: HOST_CONFIG_MODE, encoding: "utf8" });
-    renameSync4(tmp, path4);
-  } catch (error) {
+    io.stderr(`${prefix} ${failure}; restoring previous image
+`);
     try {
-      unlinkSync5(tmp);
-    } catch {
+      const code = await apply(priorRef);
+      if (code !== 0) io.stderr(`${prefix} restoration failed (exit ${code})
+`);
+    } catch (error) {
+      io.stderr(`${prefix} restoration failed (${errorMessage(error)})
+`);
     }
-    throw error;
+    return 1;
+  } catch (error) {
+    io.stderr(`${prefix} ${errorMessage(error)}
+`);
+    return 1;
+  } finally {
+    closeSync2(fd);
+    unlinkSync5(lock);
   }
 }
-function resolveHarnessRoot(explicit, env, home) {
-  if (typeof explicit === "string" && explicit !== "") return resolve8(explicit);
+
+// 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 } };
+  }
+  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}
+`);
+    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 = {
+    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 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 existsSync20 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+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/";
+function sourceDocsUrl(docsPath) {
+  const segments = docsPath.split("/");
+  if (segments[0] !== "docs" || segments.length < 2 || segments.some((segment) => segment === "" || segment === "." || segment === "..") || docsPath.includes("\\") || docsPath.includes("?") || docsPath.includes("#")) {
+    throw new Error(`source docs path must be a normalized docs/ path: ${docsPath}`);
+  }
+  return new URL(segments.map(encodeURIComponent).join("/"), SOURCE_DOCS_BASE).toString();
+}
+
+// src/lib/host-config.ts
+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 join14(hostStateHome(env, home), HOST_CONFIG_FILE);
+}
+function assertWorkspaceName(name) {
+  if (!SANDBOX_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `invalid workspace name "${name}" \u2014 use lowercase letters, digits and dashes, starting with a letter or digit`
+    );
+  }
+}
+function workspacesRoot(env, home) {
+  return join14(hostStateHome(env, home), WORKSPACES_SUBDIR);
+}
+function workspaceRoot(name, env, home) {
+  assertWorkspaceName(name);
+  return join14(workspacesRoot(env, home), name);
+}
+function defaultHarnessRoot(env, home) {
+  return join14(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
+}
+function validateHostConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${HOST_CONFIG_FILE}: must contain a JSON object`);
+  }
+  const record = value;
+  if (record.version !== void 0 && record.version !== 1) {
+    throw fieldError2("version", "must be 1");
+  }
+  const harnessRoot = record.harnessRoot;
+  if (harnessRoot !== void 0) {
+    if (typeof harnessRoot !== "string" || harnessRoot === "") {
+      throw fieldError2("harnessRoot", "must be a non-empty string");
+    }
+    if (!isAbsolute(harnessRoot)) {
+      throw fieldError2("harnessRoot", "must be an absolute path");
+    }
+  }
+  const hostHarnesses = record.hostHarnesses;
+  if (hostHarnesses !== void 0) validateReceipts(hostHarnesses, "hostHarnesses", "harness");
+  const hostTools = record.hostTools;
+  if (hostTools !== void 0) validateReceipts(hostTools, "hostTools", "tool", true);
+  return { ...record, version: 1 };
+}
+function absoluteField(value, path4) {
+  if (typeof value !== "string" || value === "") {
+    throw fieldError2(path4, "must be a non-empty string");
+  }
+  if (!isAbsolute(value)) throw fieldError2(path4, "must be an absolute path");
+  return value;
+}
+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`);
+  }
+  for (const [id, receipt] of Object.entries(value)) {
+    if (id === "") throw fieldError2(field, `must use a non-empty ${noun} id as each key`);
+    const at = `${field}.${id}`;
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+      throw fieldError2(at, "must be a JSON object");
+    }
+    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");
+    }
+    if (typeof entry.installedAt !== "string" || entry.installedAt === "") {
+      throw fieldError2(`${at}.installedAt`, "must be a non-empty string");
+    }
+    if (entry.workspaceRoot !== void 0) {
+      absoluteField(entry.workspaceRoot, `${at}.workspaceRoot`);
+    }
+  }
+}
+function readHostConfig(env, home) {
+  const path4 = hostConfigPath(env, home);
+  if (!existsSync18(path4)) return { version: 1 };
+  let raw;
+  try {
+    raw = readFileSync12(path4, "utf8");
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`could not read ${path4}: ${detail}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${basename5(path4)} is not valid JSON: ${path4}`);
+  }
+  return validateHostConfig(parsed);
+}
+function writeHostConfig(config, env, home) {
+  const path4 = hostConfigPath(env, home);
+  const validated = validateHostConfig({ ...config, version: 1 });
+  const body = `${JSON.stringify(validated, null, 2)}
+`;
+  const tmp = `${path4}.tmp.${process.pid}`;
+  mkdirSync9(dirname8(path4), { recursive: true });
+  try {
+    writeFileSync9(tmp, body, { mode: HOST_CONFIG_MODE, encoding: "utf8" });
+    renameSync4(tmp, path4);
+  } catch (error) {
+    try {
+      unlinkSync6(tmp);
+    } catch {
+    }
+    throw error;
+  }
+}
+function resolveHarnessRoot(explicit, env, home) {
+  if (typeof explicit === "string" && explicit !== "") return resolve8(explicit);
   const configured = readHostConfig(env, home).harnessRoot;
   if (typeof configured === "string" && configured !== "") return resolve8(configured);
   return defaultHarnessRoot(env, home);
@@ -4201,8 +4611,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 +4624,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 +4632,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 +4649,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 +4666,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 +4688,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 +4722,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 +4756,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 +4790,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 +4996,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 +5168,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 +5207,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 +5238,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 +5303,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 +5350,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 +5375,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 +5794,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 +5808,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 +5902,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 +6118,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 +6161,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 +6222,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 +6244,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 +6315,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 +6338,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,15 +6359,28 @@ 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
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawnSync as spawnSync4 } from "node:child_process";
 var DEFAULT_REPO_URL = "https://github.com/mifunedev/agro";
 var DEFAULT_CLONE_TIMEOUT_MS = 12e4;
 var spawnRunner2 = (cmd, args, opts) => {
-  const r = spawnSync3(cmd, args, {
+  const r = spawnSync4(cmd, args, {
     env: opts.env,
     timeout: opts.timeoutMs,
     stdio: ["ignore", "ignore", "pipe"],
@@ -5930,6 +6438,35 @@ function fetchRemoteSource(opts) {
   return opts.destDir;
 }
 
+// src/command-table.ts
+var CONFIG_VERBS = ["show", "set", "repo"];
+var CONFIG_INTEGRATIONS = ["langfuse"];
+var SECRET_VERBS = ["set", "list"];
+var LANGFUSE_VERBS = ["apply", "status", "disable"];
+var SANDBOX_SUBCOMMANDS = ["install", "list", "upgrade"];
+var WORKSPACE_SUBCOMMANDS = ["create", "list"];
+var HARNESS_SUBCOMMANDS = ["list", "install", "status", "uninstall"];
+var TOOL_SUBCOMMANDS = ["list", "install", "status", "uninstall"];
+function isOneOf(values, value) {
+  return value !== void 0 && values.includes(value);
+}
+var AGRO_COMMANDS = Object.freeze({
+  config: [...CONFIG_VERBS, ...CONFIG_INTEGRATIONS],
+  secret: SECRET_VERBS,
+  langfuse: LANGFUSE_VERBS,
+  update: null,
+  "self-upgrade": null,
+  vendor: null,
+  sandbox: SANDBOX_SUBCOMMANDS,
+  shell: null,
+  compose: null,
+  workspace: WORKSPACE_SUBCOMMANDS,
+  harness: HARNESS_SUBCOMMANDS,
+  tool: TOOL_SUBCOMMANDS,
+  gateway: null,
+  ...Object.fromEntries(composeVerbs().map((verb) => [verb, null]))
+});
+
 // src/cli.ts
 var DEFAULT_SOURCE_CONTROL_DIR = resolve11(
   dirname10(fileURLToPath(import.meta.url)),
@@ -5944,7 +6481,7 @@ var INTEGRATIONS = {
     )
   }
 };
-function isHelpFlag(arg) {
+function isHelpFlag2(arg) {
   return arg === "--help" || arg === "-h" || arg === "help";
 }
 function isVersionFlag(arg) {
@@ -5961,7 +6498,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 +6648,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 +6772,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
@@ -6382,9 +6861,8 @@ function extractSandboxFlag(command, rest) {
   }
   return { ok: true, args: sandbox === void 0 ? { rest: kept } : { rest: kept, sandbox } };
 }
-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,13 +6871,12 @@ 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]}"` };
   }
   return { ok: true, args: { help: false, verb: head } };
 }
-var CONFIG_VERBS = ["show", "set", "repo"];
 function parseConfigArgs(input, bin = AGRO_PRODUCT.bin) {
   const scoped = extractSandboxFlag(`${bin} config`, input);
   if (!scoped.ok) return scoped;
@@ -6411,12 +6888,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 +6905,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]}"` };
@@ -6451,7 +6928,6 @@ function parseConfigArgs(input, bin = AGRO_PRODUCT.bin) {
   }
   return { ok: true, args: { ...args, verb, key, value } };
 }
-var SECRET_VERBS = ["set", "list"];
 function parseSecretArgs(input, bin = AGRO_PRODUCT.bin) {
   const scoped = extractSandboxFlag(`${bin} secret`, input);
   if (!scoped.ok) return scoped;
@@ -6460,7 +6936,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 +6948,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 +6969,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 +6988,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 +7000,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 +7026,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 +7068,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 +7085,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 +7101,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 = [];
@@ -6773,7 +7137,7 @@ function parseWorkspaceArgs(rest, bin = AGRO_PRODUCT.bin) {
     return { ok: false, error: `${bin} workspace: --ref requires a branch or tag` };
   }
   const [sub, name, ...extra] = positionals;
-  if (sub !== "create" && sub !== "list") {
+  if (!isOneOf(WORKSPACE_SUBCOMMANDS, sub)) {
     return {
       ok: false,
       error: `${bin} workspace: unknown subcommand "${sub}" \u2014 expected create or list`,
@@ -6809,7 +7173,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 = [];
@@ -6859,7 +7223,7 @@ function parseHarnessArgs(rest, bin = AGRO_PRODUCT.bin) {
     };
   }
   const [sub, name, ...extra] = positionals;
-  if (sub !== "list" && sub !== "install" && sub !== "status" && sub !== "uninstall") {
+  if (!isOneOf(HARNESS_SUBCOMMANDS, sub)) {
     return {
       ok: false,
       error: `${bin} harness: unknown subcommand "${sub}" \u2014 expected list, install, uninstall, or status`,
@@ -6890,7 +7254,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 = [];
@@ -6916,7 +7280,7 @@ function parseToolArgs(rest, bin = AGRO_PRODUCT.bin) {
     return { ok: false, error: `${bin} tool: --path requires a directory` };
   }
   const [sub, name, ...extra] = positionals;
-  if (sub !== "list" && sub !== "install" && sub !== "status" && sub !== "uninstall") {
+  if (!isOneOf(TOOL_SUBCOMMANDS, sub)) {
     return {
       ok: false,
       error: `${bin} tool: unknown subcommand "${sub}" \u2014 expected list, install, uninstall, or status`,
@@ -6948,11 +7312,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 +7336,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 +7345,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 +7362,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;
   }
@@ -7007,6 +7371,7 @@ async function main(argv) {
 `);
     return 0;
   }
+  if (!Object.hasOwn(AGRO_COMMANDS, first)) return unknownCommand(first, product);
   if (first === "config") {
     const parsed = parseConfigArgs(argv.slice(1), bin);
     if (!parsed.ok) {
@@ -7141,37 +7506,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 +7591,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;
     }
@@ -7359,7 +7694,10 @@ async function main(argv) {
     }
     return runGateway(parsed.args.passthrough, { bin });
   }
-  process.stderr.write(`${bin}: unknown command "${first}"
+  return unknownCommand(first, product);
+}
+function unknownCommand(first, product) {
+  process.stderr.write(`${product.bin}: unknown command "${first}"
 
 `);
   printAgroHelp(product);
@@ -7381,12 +7719,9 @@ main(process.argv.slice(2)).then(
   }
 );
 export {
-  CONFIG_VERBS,
-  LANGFUSE_VERBS,
-  SECRET_VERBS,
   bundledPayloadExists,
   extractSandboxFlag,
-  isHelpFlag,
+  isHelpFlag2 as isHelpFlag,
   isVersionFlag,
   parseComposeArgs,
   parseConfigArgs,