@mifune/agro 0.15.1 → 0.17.0-rc.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 join20, resolve as resolve13 } 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
@@ -835,6 +835,49 @@ import { resolve as resolve3, sep } from "node:path";
 // src/lib/agro-config.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { basename as basename3, dirname as dirname2, resolve as resolve2 } from "node:path";
+
+// src/lib/runtimes/catalog.ts
+var CATALOG = [
+  {
+    id: "docker",
+    title: "Docker container",
+    tier: "container",
+    state: "active",
+    provisionable: true,
+    docsPath: "docs/runtimes/docker.md"
+  },
+  {
+    id: "microsandbox",
+    title: "MicroSandbox",
+    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\`.`,
+    docsPath: "docs/runtimes/microsandbox.md"
+  },
+  {
+    id: "openshell",
+    title: "NVIDIA OpenShell",
+    tier: "container",
+    state: "active",
+    provisionable: true,
+    docsPath: "docs/runtimes/openshell.md"
+  }
+];
+var RUNTIME_CATALOG = Object.freeze(
+  CATALOG.map((entry) => Object.freeze({ ...entry }))
+);
+var PROVISIONABLE_RUNTIMES = Object.freeze(
+  CATALOG.filter((entry) => entry.provisionable).map((entry) => entry.id)
+);
+function findRuntime(id) {
+  return RUNTIME_CATALOG.find((r) => r.id === id);
+}
+function runtimeIds() {
+  return RUNTIME_CATALOG.map((r) => r.id);
+}
+
+// src/lib/agro-config.ts
 var AGRO_CONFIG_FILE = NAMES.configFile;
 var AGRO_CONFIG_MODE = 420;
 var RESERVED_HOME_PATHS = [
@@ -856,7 +899,7 @@ var RESERVED_HOME_PATHS = [
   "/usr",
   "/var"
 ];
-var SANDBOX_RUNTIMES = ["docker"];
+var SANDBOX_RUNTIMES = PROVISIONABLE_RUNTIMES;
 function configCheckout(config) {
   const value = config.checkout ?? config.repo;
   return typeof value === "string" && value !== "" ? value : void 0;
@@ -885,6 +928,13 @@ function defaultAgroConfig(name) {
     composeOverrides: []
   };
 }
+function entryRuntime(root) {
+  try {
+    return readAgroConfig(agroConfigPath(root)).runtime ?? "docker";
+  } catch {
+    return "docker";
+  }
+}
 function readAgroConfig(path4) {
   if (!existsSync4(path4)) return defaultAgroConfig(basename3(dirname2(resolve2(path4))));
   let raw;
@@ -1274,8 +1324,8 @@ function redact(token) {
 async function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return await new Promise((resolve12) => {
-      rl.question(`  ${question} `, (answer) => resolve12(answer.trim()));
+    return await new Promise((resolve14) => {
+      rl.question(`  ${question} `, (answer) => resolve14(answer.trim()));
     });
   } finally {
     rl.close();
@@ -1287,7 +1337,7 @@ async function askSecret(question) {
   process.stdin.setRawMode(true);
   process.stdin.resume();
   const bytes = [];
-  return await new Promise((resolve12) => {
+  return await new Promise((resolve14) => {
     const cleanup = () => {
       try {
         process.stdin.setRawMode(false);
@@ -1305,7 +1355,7 @@ async function askSecret(question) {
         } else if (byte === 13 || byte === 10) {
           cleanup();
           process.stdout.write("\n");
-          resolve12(Buffer.from(bytes).toString("utf8").trim());
+          resolve14(Buffer.from(bytes).toString("utf8").trim());
           return;
         } else if (byte === 127 || byte === 8) {
           if (bytes.length > 0) {
@@ -1355,10 +1405,10 @@ async function askSecretPiped(question) {
   };
   process.on("SIGINT", onSigint);
   try {
-    return await new Promise((resolve12) => {
+    return await new Promise((resolve14) => {
       rl.question(`  ${question} `, (answer) => {
         process.stdout.write("\n");
-        resolve12(answer.trim());
+        resolve14(answer.trim());
       });
     });
   } finally {
@@ -1736,6 +1786,9 @@ printf 'free\\n'
 exit 0
 `;
 
+// agro-asset:/home/runner/work/agro/agro/.devcontainer/openshell-policy.yaml
+var openshell_policy_default = "version: 1\n\nfilesystem_policy:\n  include_workdir: true\n  read_only:\n    - /bin\n    - /usr\n    - /lib\n    - /etc\n    - /opt\n    - /proc\n    - /var/log\n    - /dev/urandom\n  read_write:\n    - /home/sandbox\n    - /tmp\n    - /dev/null\n\nprocess:\n  run_as_user: sandbox\n  run_as_group: sandbox\n\nnetwork_policies:\n  github:\n    endpoints:\n      - host: github.com\n        port: 443\n        protocol: rest\n        enforcement: enforce\n        access: read-write\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        enforcement: enforce\n        access: read-write\n      - host: release-assets.githubusercontent.com\n        port: 443\n        protocol: rest\n        enforcement: enforce\n        access: read-only\n    binaries:\n      - path: /usr/bin/git\n      - path: /usr/bin/gh\n      - path: /usr/bin/curl\n  npm:\n    endpoints:\n      - host: registry.npmjs.org\n        port: 443\n        protocol: rest\n        enforcement: enforce\n        access: read-only\n        allow_encoded_slash: true\n    binaries:\n      - path: /usr/local/bin/node\n  anthropic:\n    endpoints:\n      - host: api.anthropic.com\n        port: 443\n        protocol: rest\n        enforcement: enforce\n        access: read-write\n    binaries:\n      - path: /home/sandbox/.local/lib/node_modules/@anthropic-ai/claude-code/bin/*\n";
+
 // src/lib/registry.ts
 var SANDBOX_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 var DEFAULT_NAME_PREFIX = "agro-sbx-";
@@ -1792,10 +1845,12 @@ function nextDefaultName(run = spawnRunner) {
     if (!taken.has(candidate)) return candidate;
   }
 }
-function materialize(root, opts = {}) {
-  const entry = resolve5(root);
+function openshellFiles(entry) {
+  return [{ dest: join4(entry, "openshell-policy.yaml"), body: openshell_policy_default, mode: 420 }];
+}
+function dockerFiles(entry, opts) {
   const scripts = join4(resolveProjectLayout(entry).controlDir, "scripts");
-  const files = [
+  return [
     {
       dest: join4(entry, ".devcontainer", "docker-compose.yml"),
       body: (opts.checkout ?? opts.repo) === void 0 ? docker_compose_image_only_default : docker_compose_default,
@@ -1807,6 +1862,10 @@ function materialize(root, opts = {}) {
     { dest: join4(scripts, "paths.sh"), body: paths_default, mode: 420 },
     { dest: join4(scripts, "check-host-port.sh"), body: check_host_port_default, mode: 493 }
   ];
+}
+function materialize(root, opts = {}) {
+  const entry = resolve5(root);
+  const files = entryRuntime(entry) === "openshell" ? openshellFiles(entry) : dockerFiles(entry, opts);
   for (const file of files) {
     const dest = resolve5(file.dest);
     if (!dest.startsWith(entry + sep2)) {
@@ -1965,11 +2024,27 @@ function stripQuotes2(s) {
 // src/commands/lifecycle.ts
 import { existsSync as existsSync10, mkdtempSync, readFileSync as readFileSync7, rmSync, writeFileSync as writeFileSync5 } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename as basename4, join as join5, sep as sep3 } from "node:path";
+import { basename as basename6, join as join6, sep as sep3 } from "node:path";
+
+// src/lib/execution/index.ts
+import { basename as basename4, resolve as resolve7 } from "node:path";
+
+// src/lib/version.ts
+var AGRO_VERSION = true ? "0.17.0-rc.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) {
+  const bare = value.startsWith("v") ? value.slice(1) : value;
+  return RELEASE_VERSION.test(bare) ? bare : void 0;
+}
+function officialImageRef(version) {
+  return `${OFFICIAL_IMAGE}:${RELEASE_VERSION.test(version) ? version : "latest"}`;
+}
 
 // src/lib/execution/detect.ts
 import { existsSync as existsSync9 } from "node:fs";
 var SANDBOX_MARKER_FILE = "/.dockerenv";
+var EXECUTION_TARGET_ENV = "AGRO_EXECUTION_TARGET";
 function runningInsideSandbox(env = process.env, fileExists = existsSync9) {
   const override = agroEnvValue(env, "EXECUTION_TARGET");
   if (override === "local") return true;
@@ -2195,6 +2270,243 @@ function defaultIdentity() {
   return { name: info2.username, uid: info2.uid };
 }
 
+// src/lib/execution/openshell-target.ts
+import { join as join5 } from "node:path";
+var OPENSHELL_BIN = "openshell";
+var OPENSHELL_POLICY_FILE = "openshell-policy.yaml";
+var OPENSHELL_MAIN = "/usr/local/bin/openshell-main.sh";
+var OPENSHELL_WORKDIR = "/home/sandbox/harness";
+var OPENSHELL_USER = "sandbox";
+var OPENSHELL_PINNED_VERSION = "v0.1.2";
+var OPENSHELL_LOCAL_GATEWAY = "https://127.0.0.1:17670";
+var OPENSHELL_INSTALL_URL = "https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh";
+var LOGIN_SHELLS = /* @__PURE__ */ new Set(["zsh", "bash"]);
+var NOT_FOUND = /sandbox (?:'[^']*' )?not found/;
+var OPENSHELL_PHASES = [
+  "Unspecified",
+  "Provisioning",
+  "Ready",
+  "Error",
+  "Deleting",
+  "Unknown",
+  "Stopping",
+  "Stopped",
+  "Starting",
+  "Completed"
+];
+var OPENSHELL_PHASE_STATUS = Object.freeze({
+  Ready: "ready",
+  Provisioning: "starting",
+  Starting: "starting",
+  Stopping: "stopped",
+  Stopped: "stopped",
+  Deleting: "stopped",
+  Completed: "stopped",
+  Error: "failed",
+  Unknown: "failed",
+  Unspecified: "failed"
+});
+function createArgv(opts) {
+  return [
+    "sandbox",
+    "create",
+    "--name",
+    opts.name,
+    "--from",
+    opts.image,
+    "--policy",
+    join5(opts.entryRoot, OPENSHELL_POLICY_FILE),
+    "--env",
+    `${EXECUTION_TARGET_ENV}=local`,
+    "--env",
+    `SANDBOX_NAME=${opts.name}`,
+    "--detach",
+    "--",
+    OPENSHELL_MAIN
+  ];
+}
+function attachArgv(name, request = { argv: ["zsh"] }) {
+  return [
+    "sandbox",
+    "exec",
+    "-n",
+    name,
+    "--tty",
+    "--workdir",
+    request.cwd ?? OPENSHELL_WORKDIR,
+    ...envFlags(request.env),
+    "--",
+    ...asLoginShell(request.argv)
+  ];
+}
+function execArgv(name, request) {
+  return [
+    "sandbox",
+    "exec",
+    "-n",
+    name,
+    ...request.cwd !== void 0 ? ["--workdir", request.cwd] : [],
+    ...envFlags(request.env),
+    ...request.timeoutMs !== void 0 ? ["--timeout", String(Math.ceil(request.timeoutMs / 1e3))] : [],
+    "--",
+    ...request.argv
+  ];
+}
+function getArgv(name) {
+  return ["sandbox", "get", name, "-o", "json"];
+}
+function deleteArgv(name) {
+  return ["sandbox", "delete", name];
+}
+function parseOpenShellPhase(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return "Unknown";
+  }
+  const phase = typeof parsed === "object" && parsed !== null ? parsed.phase : void 0;
+  return OPENSHELL_PHASES.find((known) => known === phase) ?? "Unknown";
+}
+function openshellSandboxMissing(output) {
+  return NOT_FOUND.test(output);
+}
+var OPENSHELL_VERB_HINTS = Object.freeze({
+  stop: (name) => `openshell sandbox stop ${name}`,
+  restart: (name) => `openshell sandbox stop ${name} && openshell sandbox start ${name}`,
+  logs: (name) => `openshell logs ${name}`,
+  ps: (name) => `openshell sandbox get ${name}`,
+  config: (name) => `openshell policy get ${name}`
+});
+function openshellInstallHint() {
+  return [
+    "install the OpenShell CLI on the host, then run the command again:",
+    `  curl -LsSf ${OPENSHELL_INSTALL_URL} | OPENSHELL_VERSION=${OPENSHELL_PINNED_VERSION} sh`,
+    "review-first alternative \u2014 download the script, inspect it, then run it:",
+    `  curl -LsSf -o openshell-install.sh ${OPENSHELL_INSTALL_URL}`,
+    "  less openshell-install.sh",
+    `  OPENSHELL_VERSION=${OPENSHELL_PINNED_VERSION} sh openshell-install.sh`
+  ].join("\n");
+}
+function openshellGatewayHint() {
+  return [
+    "the OpenShell gateway is not connected; start the local gateway and register it:",
+    "  systemctl --user restart openshell-gateway",
+    `  openshell gateway add ${OPENSHELL_LOCAL_GATEWAY} --local --name openshell`,
+    "then confirm with: openshell status"
+  ].join("\n");
+}
+function openshellCleanupHint(name) {
+  return `the OpenShell gateway can keep a failed sandbox record in the Error phase; if ${name} is not another sandbox, remove it with: openshell sandbox delete ${name}`;
+}
+function openshellPreflight(run) {
+  const version = run(OPENSHELL_BIN, ["--version"], { stdio: "capture" });
+  if (version.error?.code === "ENOENT") {
+    return { ok: false, reason: "missing-binary", hint: openshellInstallHint() };
+  }
+  assertSpawned(version, `${OPENSHELL_BIN} --version`);
+  const status = run(OPENSHELL_BIN, ["status", "-o", "json"], { stdio: "capture" });
+  assertSpawned(status, `${OPENSHELL_BIN} status`);
+  if (status.status !== 0 || !gatewayConnected(status.stdout ?? "")) {
+    return { ok: false, reason: "gateway-unreachable", hint: openshellGatewayHint() };
+  }
+  return { ok: true };
+}
+var OpenShellExecutionTarget = class {
+  kind = "openshell";
+  contractVersion = 1;
+  workspace;
+  name;
+  entryRoot;
+  image;
+  run;
+  env;
+  constructor(opts) {
+    this.name = opts.name;
+    this.entryRoot = opts.entryRoot;
+    this.image = opts.image;
+    this.run = opts.run ?? spawnRunner;
+    this.env = opts.env;
+    this.workspace = { hostRoot: opts.entryRoot, targetRoot: OPENSHELL_WORKDIR };
+  }
+  async provision() {
+    const argv = createArgv({ name: this.name, image: this.image, entryRoot: this.entryRoot });
+    this.runInherited(argv, "sandbox create");
+  }
+  async destroy() {
+    this.runInherited(deleteArgv(this.name), "sandbox delete");
+  }
+  async status() {
+    const r = this.run(OPENSHELL_BIN, getArgv(this.name), { stdio: "capture", ...this.childEnv() });
+    assertSpawned(r, this.what("sandbox get"));
+    if (r.status !== 0) {
+      if (openshellSandboxMissing(`${r.stdout ?? ""}
+${r.stderr ?? ""}`)) return "absent";
+      throw new ExecutionExitError(this.what("sandbox get"), r.status ?? 1);
+    }
+    return OPENSHELL_PHASE_STATUS[parseOpenShellPhase(r.stdout ?? "")];
+  }
+  async capabilities() {
+    return /* @__PURE__ */ new Set(["exec", "pty"]);
+  }
+  async exec(request) {
+    requireSandboxUser(request);
+    const inherit = request.stdio === "inherit";
+    const r = this.run(OPENSHELL_BIN, execArgv(this.name, request), {
+      stdio: inherit ? "inherit" : "capture",
+      ...this.childEnv()
+    });
+    assertSpawned(r, this.what("sandbox exec"));
+    return {
+      exitCode: r.status ?? 1,
+      stdout: r.stdout ?? "",
+      stderr: r.stderr ?? ""
+    };
+  }
+  attach(request) {
+    requireSandboxUser(request);
+    const r = this.run(OPENSHELL_BIN, attachArgv(this.name, request), { stdio: "inherit", ...this.childEnv() });
+    assertSpawned(r, this.what("sandbox exec"));
+    return r.status ?? 1;
+  }
+  describe() {
+    return `openshell sandbox ${this.name} (entry ${this.entryRoot})`;
+  }
+  runInherited(argv, verb) {
+    const r = this.run(OPENSHELL_BIN, argv, { stdio: "inherit", ...this.childEnv() });
+    assertSpawned(r, this.what(verb));
+    const code = r.status ?? 1;
+    if (code !== 0) throw new ExecutionExitError(this.what(verb), code);
+  }
+  childEnv() {
+    return this.env ? { env: this.env } : {};
+  }
+  what(verb) {
+    return `${OPENSHELL_BIN} ${verb} ${this.name}`;
+  }
+};
+function asLoginShell(argv) {
+  return argv.length === 1 && LOGIN_SHELLS.has(argv[0]) ? [argv[0], "-l"] : [...argv];
+}
+function envFlags(env) {
+  return Object.entries(env ?? {}).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+}
+function gatewayConnected(json) {
+  try {
+    const parsed = JSON.parse(json);
+    return typeof parsed === "object" && parsed !== null && parsed.status === "connected";
+  } catch {
+    return false;
+  }
+}
+function requireSandboxUser(request) {
+  if (request.user !== void 0 && request.user !== OPENSHELL_USER) {
+    throw new Error(
+      `the openshell runtime runs every command as "${OPENSHELL_USER}" and cannot run as "${request.user}"`
+    );
+  }
+}
+
 // src/lib/execution/status.ts
 var RUNTIME_ABSENT_STATUS = "no container runtime";
 async function resolveTargetStatus(target) {
@@ -2218,19 +2530,23 @@ function resolveExecutionTarget(opts) {
       ...opts.env ? { env: opts.env } : {}
     });
   }
+  if (entryRuntime(opts.projectRoot) === "openshell") {
+    const config = readAgroConfig(agroConfigPath(opts.projectRoot));
+    return new OpenShellExecutionTarget({
+      name: opts.container ?? nonEmpty(config.name) ?? basename4(resolve7(opts.projectRoot)),
+      entryRoot: opts.projectRoot,
+      image: openshellImage(config),
+      ...opts.run ? { run: opts.run } : {},
+      ...opts.env ? { env: opts.env } : {}
+    });
+  }
   return new DockerComposeExecutionTarget(opts);
 }
-
-// src/lib/version.ts
-var AGRO_VERSION = true ? "0.15.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) {
-  const bare = value.startsWith("v") ? value.slice(1) : value;
-  return RELEASE_VERSION.test(bare) ? bare : void 0;
+function openshellImage(config) {
+  return nonEmpty(config.image?.ref) ?? officialImageRef(AGRO_VERSION);
 }
-function officialImageRef(version) {
-  return `${OFFICIAL_IMAGE}:${RELEASE_VERSION.test(version) ? version : "latest"}`;
+function nonEmpty(value) {
+  return value === void 0 || value === "" ? void 0 : value;
 }
 
 // src/lib/config-render.ts
@@ -2296,13 +2612,103 @@ function renderComposeEnv(config) {
 `;
 }
 
+// src/lib/runtimes/verbs.ts
+import { basename as basename5, resolve as resolve8 } from "node:path";
+var viaCompose = Object.freeze({ action: "route", via: "compose" });
+var viaTarget = Object.freeze({ action: "route", via: "target" });
+function refuse(hint) {
+  return Object.freeze({ action: "refuse", hint });
+}
+var LIFECYCLE_COMMANDS = Object.freeze({
+  shell: "shell",
+  stop: "stop",
+  restart: "restart",
+  logs: "logs",
+  ps: "ps",
+  destroy: "destroy",
+  config: "compose config",
+  upgrade: "sandbox upgrade"
+});
+var DOCKER_VERBS = Object.freeze({
+  shell: viaTarget,
+  stop: viaCompose,
+  restart: viaCompose,
+  logs: viaCompose,
+  ps: viaCompose,
+  destroy: viaCompose,
+  config: viaCompose,
+  upgrade: viaTarget
+});
+var OPENSHELL_VERBS = Object.freeze({
+  shell: viaTarget,
+  stop: refuse(OPENSHELL_VERB_HINTS.stop),
+  restart: refuse(OPENSHELL_VERB_HINTS.restart),
+  logs: refuse(OPENSHELL_VERB_HINTS.logs),
+  ps: refuse(OPENSHELL_VERB_HINTS.ps),
+  destroy: viaTarget,
+  config: refuse(OPENSHELL_VERB_HINTS.config),
+  upgrade: refuse(
+    (name) => `${activeBin()} destroy ${name}, then ${activeBin()} sandbox install openshell --name ${name} --image=<ref>`
+  )
+});
+var RUNTIME_VERBS = Object.freeze({
+  docker: DOCKER_VERBS,
+  openshell: OPENSHELL_VERBS
+});
+function configuredEntryName(root) {
+  try {
+    const name = readAgroConfig(agroConfigPath(root)).name;
+    return name === "" ? void 0 : name;
+  } catch {
+    return void 0;
+  }
+}
+function entryDeclaredName(root) {
+  return configuredEntryName(root) ?? basename5(resolve8(root));
+}
+var RUNTIME_NAMING = Object.freeze({
+  docker: Object.freeze({
+    entryName: () => void 0,
+    shellFailure: (bin, name) => `container \`${name}\` not running? start it with \`${bin} sandbox install docker\``
+  }),
+  openshell: Object.freeze({
+    entryName: entryDeclaredName,
+    shellFailure: (bin, name) => `sandbox \`${name}\` did not accept the shell; check its status with \`${bin} sandbox list\``
+  })
+});
+function entrySandboxName(root) {
+  return RUNTIME_NAMING[entryRuntime(root)].entryName(root);
+}
+function shellFailureHint(runtime, bin, name) {
+  return RUNTIME_NAMING[runtime].shellFailure(bin, name);
+}
+var RuntimeUnsupportedError = class extends Error {
+  runtime;
+  verb;
+  hint;
+  constructor(runtime, verb, hint) {
+    const command = LIFECYCLE_COMMANDS[verb];
+    super(`${activeBin()} ${command}: the ${runtime} runtime does not support ${command}; run: ${hint}`);
+    this.name = "RuntimeUnsupportedError";
+    this.runtime = runtime;
+    this.verb = verb;
+    this.hint = hint;
+  }
+};
+function routeVerb(root, verb, name) {
+  const runtime = entryRuntime(root);
+  const policy = RUNTIME_VERBS[runtime][verb];
+  if (policy.action === "refuse") throw new RuntimeUnsupportedError(runtime, verb, policy.hint(name));
+  return { runtime, via: policy.via };
+}
+
 // src/commands/lifecycle.ts
 var COMPOSE_ENV_DIR_PREFIX = "oh-compose-env-";
 function composeEnvDir() {
-  return mkdtempSync(join5(tmpdir(), COMPOSE_ENV_DIR_PREFIX));
+  return mkdtempSync(join6(tmpdir(), COMPOSE_ENV_DIR_PREFIX));
 }
 function writeComposeEnv(root, dir) {
-  const file = join5(dir, "compose.env");
+  const file = join6(dir, "compose.env");
   writeFileSync5(file, renderComposeEnv(readAgroConfig(agroConfigPath(root))), {
     mode: 384,
     encoding: "utf8"
@@ -2360,7 +2766,7 @@ async function maybePromptDockerSocket(root, io, bin) {
   if (dockerSocketConfigured(root)) return;
   const interactive = process.stdin.isTTY === true || io.ask !== void 0;
   if (!interactive) return;
-  const envDir = join5(root, ".devcontainer");
+  const envDir = join6(root, ".devcontainer");
   if (!existsSync10(envDir)) return;
   const askFn = io.ask ?? ask;
   const answer = (await askFn(
@@ -2441,25 +2847,27 @@ async function runSandbox(opts, io) {
 function configuredContainerName(root) {
   return fromProcessEnv("SANDBOX_NAME") ?? configuredString(root, "name");
 }
+function sandboxName(root) {
+  return entrySandboxName(root) ?? configuredContainerName(root) ?? DEFAULT_CONTAINER_NAME;
+}
 function runShell(opts, io) {
   const run = opts.run ?? spawnRunner;
   const root = sandboxRoot(opts);
-  const name = configuredContainerName(root) ?? DEFAULT_CONTAINER_NAME;
+  const name = sandboxName(root);
+  const { runtime } = routeVerb(root, "shell", name);
   const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
   let code;
   try {
     code = target.attach({ argv: ["zsh"], user: "sandbox" });
   } catch (err) {
     if (err instanceof ExecutionSpawnError && err.code === "ENOENT") {
-      throw new Error(`docker is required for \`${opts.bin} shell\` but was not found on PATH`);
+      throw new Error(`${runtime} is required for \`${opts.bin} shell\` but was not found on PATH`);
     }
     throw err;
   }
   if (code !== 0) {
-    io.stderr(
-      `container \`${name}\` not running? start it with \`${opts.bin} sandbox install docker\`
-`
-    );
+    io.stderr(`${shellFailureHint(runtime, opts.bin, name)}
+`);
   }
   return code;
 }
@@ -2476,6 +2884,7 @@ function composeVerbs() {
 function runComposeVerb(verb, opts, extra = []) {
   const run = opts.run ?? spawnRunner;
   const root = sandboxRoot(opts);
+  routeVerb(root, verb, sandboxName(root));
   const script = requireLifecycleScript(root, "docker-compose.sh");
   return withComposeEnvFile(root, (extraArgs) => {
     const r = run("bash", [script, ...extraArgs, ...COMPOSE_VERBS[verb], ...extra], {
@@ -2488,6 +2897,7 @@ function runComposeVerb(verb, opts, extra = []) {
 function runComposeConfig(opts, extra = []) {
   const run = opts.run ?? spawnRunner;
   const root = sandboxRoot(opts);
+  routeVerb(root, "config", sandboxName(root));
   const script = requireLifecycleScript(root, "docker-compose.sh");
   return withComposeEnvFile(root, (extraArgs) => {
     const r = run("bash", [script, ...extraArgs, "config", ...extra], { stdio: "inherit" });
@@ -2498,7 +2908,7 @@ function runComposeConfig(opts, extra = []) {
 function namedVolumes(root) {
   let text;
   try {
-    text = readFileSync7(join5(root, ".devcontainer", "docker-compose.yml"), "utf8");
+    text = readFileSync7(join6(root, ".devcontainer", "docker-compose.yml"), "utf8");
   } catch {
     return [];
   }
@@ -2514,11 +2924,23 @@ function namedVolumes(root) {
   return names;
 }
 function destroyConfirmationPhrase(root) {
-  return configuredContainerName(root) ?? DEFAULT_CONTAINER_NAME;
+  return sandboxName(root);
+}
+async function destroyThroughTarget(root, name, run) {
+  const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
+  if (target.destroy === void 0) throw new Error(`${target.describe()} cannot destroy its sandbox`);
+  try {
+    await target.destroy();
+    return 0;
+  } catch (err) {
+    if (err instanceof ExecutionExitError) return err.exitCode;
+    throw err;
+  }
 }
 async function runDestroy(opts, io) {
   const root = sandboxRoot(opts);
   const name = destroyConfirmationPhrase(root);
+  const { via } = routeVerb(root, "destroy", name);
   if (opts.yes !== true) {
     const interactive = process.stdin.isTTY === true || io.ask !== void 0;
     if (!interactive) {
@@ -2533,7 +2955,14 @@ async function runDestroy(opts, io) {
 ${bold(`${opts.bin} destroy \u2014 ${name}`)}
 
 `);
-    if (homePath !== void 0 && homePath !== "") {
+    if (via === "target") {
+      io.stdout(
+        `This deletes the sandbox \`${name}\` and everything inside it \u2014 every agent CLI
+login, the gh CLI token, and the SSH keys. Sign-in starts over.
+
+`
+      );
+    } else if (homePath !== void 0 && homePath !== "") {
       io.stdout("`docker compose down -v` removes the containers.\n");
       io.stdout(
         `This sandbox keeps its home on a host bind at ${homePath}, which \`down -v\`
@@ -2564,7 +2993,7 @@ stay there. Delete that directory yourself if you also want them gone.
       return 1;
     }
   }
-  const code = runComposeVerb("destroy", { ...opts, name: basename4(root) });
+  const code = via === "target" ? await destroyThroughTarget(root, name, opts.run ?? spawnRunner) : runComposeVerb("destroy", { ...opts, name: basename6(root) });
   if (code === 0 && root.startsWith(registryRoot() + sep3)) {
     rmSync(root, { recursive: true, force: true });
     io.stdout(`removed the sandbox entry ${root}
@@ -2853,13 +3282,13 @@ function sameRemote(url, owner, name) {
 
 // src/commands/secret.ts
 import { existsSync as existsSync12 } from "node:fs";
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 
 // src/lib/gitignore.ts
 import { existsSync as existsSync11, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname5, join as join6 } from "node:path";
+import { dirname as dirname5, join as join7 } from "node:path";
 function appendGitignoreLines(root, lines) {
-  const target = join6(root, ".gitignore");
+  const target = join7(root, ".gitignore");
   const existing = existsSync11(target) ? readFileSync8(target, "utf8") : "";
   const present = new Set(existing.split("\n").map((line) => line.trimEnd()));
   const added = [];
@@ -2884,7 +3313,7 @@ function secretsRoot(opts) {
   return opts.sandbox === void 0 ? resolveProjectRoot(opts.cwd) : resolveSandboxRoot({ name: opts.sandbox });
 }
 function ignoreSecretsFile(root) {
-  if (!existsSync12(join7(root, ".git"))) return;
+  if (!existsSync12(join8(root, ".git"))) return;
   appendGitignoreLines(root, [".env"]);
 }
 function secretKeyList() {
@@ -2942,10 +3371,10 @@ async function runSecretList(opts, io) {
 // src/commands/langfuse.ts
 import { copyFileSync as copyFileSync2, existsSync as existsSync14, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync10, rmSync as rmSync2, unlinkSync as unlinkSync4 } from "node:fs";
 import { homedir as homedir2, tmpdir as tmpdir2 } from "node:os";
-import { dirname as dirname7, join as join10, relative } from "node:path";
+import { dirname as dirname7, join as join11, relative } from "node:path";
 
 // src/lib/tracing/harness-writers.ts
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 
 // src/lib/tracing/writer.ts
 import { chmodSync, existsSync as existsSync13, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync7 } from "node:fs";
@@ -2990,13 +3419,13 @@ function isPlainObject(value) {
 // src/lib/tracing/harness-writers.ts
 var CODEX_TRACING_TAGS = ["codex"];
 function claudeCodeSettingsPath(home) {
-  return join8(home, ".claude", "settings.json");
+  return join9(home, ".claude", "settings.json");
 }
 function piTracingConfigPath(home) {
-  return join8(home, ".pi", "agent", "langfuse.json");
+  return join9(home, ".pi", "agent", "langfuse.json");
 }
 function codexTracingConfigPath(home) {
-  return join8(home, ".codex", "langfuse.json");
+  return join9(home, ".codex", "langfuse.json");
 }
 var claudeCodeTracingWriter = (home, settings) => {
   const path4 = claudeCodeSettingsPath(home);
@@ -3129,7 +3558,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"],
@@ -3206,7 +3635,7 @@ function harnessBinPath(prefix) {
 }
 
 // src/lib/tracing/providers/langfuse.ts
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 var LANGFUSE_FRAGMENT_KEYS = [
   "LANGFUSE_PUBLIC_KEY",
   "LANGFUSE_SECRET_KEY",
@@ -3214,7 +3643,7 @@ var LANGFUSE_FRAGMENT_KEYS = [
   "LANGFUSE_TRACING_ENVIRONMENT"
 ];
 function langfuseFragmentPath(home) {
-  return join9(home, ".config", "agro", "langfuse.env");
+  return join10(home, ".config", "agro", "langfuse.env");
 }
 function loadLangfuseCredentials(root) {
   const publicKey = readSecret(root, "LANGFUSE_PUBLIC_KEY");
@@ -3378,7 +3807,7 @@ function displayPath(home, path4) {
   return rel.startsWith("..") ? path4 : `~/${rel}`;
 }
 function withTempHome(fn) {
-  const dir = mkdtempSync2(join10(tmpdir2(), "agro-langfuse-"));
+  const dir = mkdtempSync2(join11(tmpdir2(), "agro-langfuse-"));
   try {
     return fn(dir);
   } finally {
@@ -3387,10 +3816,10 @@ function withTempHome(fn) {
 }
 function probeGeneratedFile(home, render) {
   const rel = withTempHome((scratch) => relative(scratch, render(scratch).path));
-  const path4 = join10(home, rel);
+  const path4 = join11(home, rel);
   if (!existsSync14(path4)) return { path: path4, state: "missing" };
   const outcome = withTempHome((scratch) => {
-    const copy = join10(scratch, rel);
+    const copy = join11(scratch, rel);
     mkdirSync6(dirname7(copy), { recursive: true });
     copyFileSync2(path4, copy);
     return render(scratch).outcome;
@@ -3453,7 +3882,7 @@ async function runLangfuseApply(opts, io) {
   return renderAll(ctx, resolved, io, opts.bin, "apply");
 }
 function zshenvWarning(home) {
-  const zshenv = join10(home, ".zshenv");
+  const zshenv = join11(home, ".zshenv");
   if (!existsSync14(zshenv)) return void 0;
   if (readFileSync10(zshenv, "utf8").includes("langfuse.env")) return void 0;
   return `~/.zshenv exists but does not source ${LANGFUSE_FRAGMENT_LABEL} \u2014 non-interactive shells will carry no Langfuse credentials; add the source block from .agro/install/.zshenv
@@ -3734,45 +4163,18 @@ async function runLangfuseSetup(opts, io) {
 // src/commands/sandbox.ts
 import { existsSync as existsSync16, mkdirSync as mkdirSync8, mkdtempSync as mkdtempSync3, rmSync as rmSync3, statSync as statSync4 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join12, resolve as resolve7 } from "node:path";
-
-// src/lib/runtimes/catalog.ts
-var RUNTIME_CATALOG = Object.freeze([
-  Object.freeze({
-    id: "docker",
-    title: "Docker container",
-    tier: "container",
-    state: "active",
-    provisionable: true,
-    docsPath: "docs/runtimes/docker.md"
-  }),
-  Object.freeze({
-    id: "microsandbox",
-    title: "MicroSandbox",
-    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\`.`,
-    docsPath: "docs/runtimes/microsandbox.md"
-  })
-]);
-function findRuntime(id) {
-  return RUNTIME_CATALOG.find((r) => r.id === id);
-}
-function runtimeIds() {
-  return RUNTIME_CATALOG.map((r) => r.id);
-}
+import { join as join13, resolve as resolve9 } from "node:path";
 
 // src/lib/star-prompt.ts
 import { existsSync as existsSync15, mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "node:fs";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 var STAR_PROMPT_LINE = "\u2B50 If AGRO helps, star https://github.com/mifunedev/agro";
 var MARKER = "star-prompt-shown";
 function maybePrintStarPrompt(io, env = process.env, isTTY = process.stdout.isTTY === true, stateHome = resolveUserStateHome(env)) {
   if (env.AGRO_NO_STAR_PROMPT === "1") return;
   if (env.CI !== void 0 && env.CI !== "") return;
   if (!isTTY) return;
-  const marker = join11(stateHome, MARKER);
+  const marker = join12(stateHome, MARKER);
   if (existsSync15(marker)) return;
   io.stdout(`${STAR_PROMPT_LINE}
 `);
@@ -3784,39 +4186,88 @@ function maybePrintStarPrompt(io, env = process.env, isTTY = process.stdout.isTT
   }
 }
 
-// src/commands/sandbox.ts
-function hostTimezone() {
-  const tz = process.env.TZ;
-  return tz !== void 0 && tz !== "" ? tz : "UTC";
-}
-function gitIdentity(run, key) {
-  let result;
+// src/commands/sandbox-list.ts
+async function entryStatus(root, name, run) {
   try {
-    result = run("git", ["config", "--global", key], { stdio: "capture" });
+    const target = resolveExecutionTarget({ projectRoot: root, container: entrySandboxName(root) ?? name, run });
+    return await target.status();
   } catch {
-    return "";
+    return "unknown";
   }
-  if (result.error || result.status !== 0) return "";
-  return (result.stdout ?? "").trim();
-}
-function isBuildCapable(repo) {
-  return repo !== void 0 && existsSync16(join12(repo, ".devcontainer", "Dockerfile"));
 }
-function prepareHomeMount(value) {
-  const path4 = resolve7(value);
-  if (existsSync16(path4)) {
-    if (!statSync4(path4).isDirectory()) {
-      throw new Error(`--home-mount path exists and is not a directory: ${path4}`);
-    }
-    return path4;
+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)
+    });
   }
-  mkdirSync8(path4, { recursive: true });
-  return path4;
-}
-function readSeedConfig(repo) {
-  if (repo === void 0) return void 0;
-  const file = agroConfigPath(repo);
-  return existsSync16(file) ? readAgroConfig(file) : void 0;
+  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;
+  return tz !== void 0 && tz !== "" ? tz : "UTC";
+}
+function gitIdentity(run, key) {
+  let result;
+  try {
+    result = run("git", ["config", "--global", key], { stdio: "capture" });
+  } catch {
+    return "";
+  }
+  if (result.error || result.status !== 0) return "";
+  return (result.stdout ?? "").trim();
+}
+function isBuildCapable(repo) {
+  return repo !== void 0 && existsSync16(join13(repo, ".devcontainer", "Dockerfile"));
+}
+function prepareHomeMount(value) {
+  const path4 = resolve9(value);
+  if (existsSync16(path4)) {
+    if (!statSync4(path4).isDirectory()) {
+      throw new Error(`--home-mount path exists and is not a directory: ${path4}`);
+    }
+    return path4;
+  }
+  mkdirSync8(path4, { recursive: true });
+  return path4;
+}
+function readSeedConfig(repo) {
+  if (repo === void 0) return void 0;
+  const file = agroConfigPath(repo);
+  return existsSync16(file) ? readAgroConfig(file) : void 0;
 }
 function readEntryConfig(name) {
   const file = agroConfigPath(entryRoot(name));
@@ -3847,18 +4298,18 @@ function mergeSettings(...sources) {
   for (const source of present) overlaySettings(merged, source);
   return merged;
 }
-function nonEmpty(value) {
+function nonEmpty2(value) {
   return value === void 0 || value === "" ? void 0 : value;
 }
-function seedConfig(name, checkout, seed, run) {
+function seedConfig(name, checkout, seed, run, runtime = "docker") {
   const config = overlaySettings(defaultAgroConfig(name), seed);
   config.name = name;
-  config.runtime = "docker";
+  config.runtime = runtime;
   if (checkout !== void 0) config.checkout = checkout;
-  config.timezone = nonEmpty(seed?.timezone) ?? hostTimezone();
+  config.timezone = nonEmpty2(seed?.timezone) ?? hostTimezone();
   config.git = {
-    userName: nonEmpty(seed?.git?.userName) ?? gitIdentity(run, "user.name"),
-    userEmail: nonEmpty(seed?.git?.userEmail) ?? gitIdentity(run, "user.email")
+    userName: nonEmpty2(seed?.git?.userName) ?? gitIdentity(run, "user.name"),
+    userEmail: nonEmpty2(seed?.git?.userEmail) ?? gitIdentity(run, "user.email")
   };
   config.image = {
     ...config.image,
@@ -3899,7 +4350,7 @@ async function runWizard(config, io) {
     "Host path for /home/sandbox (blank keeps the Docker-managed volume)",
     config.storage?.homePath ?? ""
   );
-  if (homePath !== "") config.storage = { ...config.storage, homePath: resolve7(homePath) };
+  if (homePath !== "") config.storage = { ...config.storage, homePath: resolve9(homePath) };
 }
 async function runSandboxInstall(opts, io) {
   const run = opts.run ?? spawnRunner;
@@ -3916,7 +4367,8 @@ async function runSandboxInstall(opts, io) {
 `);
     return 1;
   }
-  const checkout = opts.checkout === void 0 ? void 0 : resolve7(opts.checkout);
+  if (runtime.id === "openshell") return await installOpenShell(opts, io, run);
+  const checkout = opts.checkout === void 0 ? void 0 : resolve9(opts.checkout);
   if (checkout !== void 0 && !existsSync16(checkout)) {
     io.stderr(`${opts.bin} sandbox install: --checkout directory does not exist: ${checkout}
 `);
@@ -3934,9 +4386,9 @@ async function runSandboxInstall(opts, io) {
   const config = seedConfig(name, checkout, mergeSettings(readEntryConfig(name), repoSeed), run);
   const buildRequested = config.image?.mode === "build" && opts.noBuild !== true && opts.image !== true && opts.imageRef === void 0;
   if (buildRequested && !isBuildCapable(configCheckout(config))) {
-    const target = configCheckout(config) ?? resolve7(opts.checkout ?? ".");
+    const target = configCheckout(config) ?? resolve9(opts.checkout ?? ".");
     io.stderr(
-      `${opts.bin} sandbox install: image.mode is "build" but ${join12(target, ".devcontainer", "Dockerfile")} does not exist \u2014 point --checkout <dir> at a harness checkout that has .devcontainer/Dockerfile, or set image.mode to "image" to run the prebuilt image
+      `${opts.bin} sandbox install: image.mode is "build" but ${join13(target, ".devcontainer", "Dockerfile")} does not exist \u2014 point --checkout <dir> at a harness checkout that has .devcontainer/Dockerfile, or set image.mode to "image" to run the prebuilt image
 `
     );
     return 1;
@@ -3980,7 +4432,7 @@ async function runSandboxInstall(opts, io) {
     ...useNoBuild ? { noBuild: true } : {}
   };
   if (opts.printArgv === true) {
-    const preview = mkdtempSync3(join12(tmpdir3(), "oh-sandbox-preview-"));
+    const preview = mkdtempSync3(join13(tmpdir3(), "oh-sandbox-preview-"));
     try {
       writeAgroConfig(preview, config);
       materialize(preview, { ...configCheckout(config) !== void 0 ? { checkout: configCheckout(config) } : {} });
@@ -4001,58 +4453,450 @@ async function runSandboxInstall(opts, io) {
   }
   return code;
 }
-async function entryStatus(root, name, run) {
+async function installOpenShell(opts, io, run) {
+  const fail2 = (message) => {
+    io.stderr(`${opts.bin} sandbox install: ${message}
+`);
+    return 1;
+  };
+  const unsupported = (what) => fail2(`${what} is not supported on the openshell runtime`);
+  if (opts.checkout !== void 0) return unsupported("--checkout");
+  if (opts.homeMount !== void 0) return unsupported("--home-mount");
+  const name = opts.name ?? nextDefaultName(run);
   try {
-    const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
-    return await target.status();
-  } catch {
-    return "unknown";
+    assertSandboxName(name);
+  } catch (error) {
+    return fail2(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)
-    });
+  const config = seedConfig(name, void 0, readEntryConfig(name), run, "openshell");
+  if (configCheckout(config) !== void 0) return unsupported("checkout");
+  if (nonEmpty2(config.storage?.homePath) !== void 0) return unsupported("storage.homePath");
+  const imageChosen = opts.image === true || opts.imageRef !== void 0;
+  if (config.image?.mode === "build" && !imageChosen) {
+    return unsupported('image.mode "build"');
   }
-  if (opts.json === true) {
-    io.stdout(`${JSON.stringify(rows, null, 2)}
+  config.image = {
+    ...config.image,
+    mode: "image",
+    ...opts.imageRef !== void 0 ? { ref: opts.imageRef } : {}
+  };
+  const root = entryRoot(name);
+  const image = openshellImage(config);
+  if (opts.printArgv === true) {
+    io.stdout(`${[OPENSHELL_BIN, ...createArgv({ name, image, entryRoot: root })].join(" ")}
 `);
     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;
+  if (runningInsideSandbox()) return fail2(new HostOnlyError(`\`${opts.bin} sandbox\``).message);
+  try {
+    const preflight = openshellPreflight(run);
+    if (!preflight.ok) return fail2(preflight.hint);
+  } catch (error) {
+    return fail2(error instanceof Error ? error.message : String(error));
   }
-  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 created = !existsSync16(root);
+  mkdirSync8(root, { recursive: true });
+  writeAgroConfig(root, config);
+  materialize(root);
+  try {
+    await new OpenShellExecutionTarget({ name, entryRoot: root, image, run }).provision();
+  } catch (error) {
+    if (created) rmSync3(root, { recursive: true, force: true });
+    io.stderr(`${opts.bin} sandbox install: ${error instanceof Error ? error.message : String(error)}
+`);
+    if (!(error instanceof ExecutionExitError)) return 1;
+    io.stderr(`${opts.bin} sandbox install: ${openshellCleanupHint(name)}
+`);
+    return error.exitCode;
   }
+  io.stdout(`next: ${opts.bin} shell ${name}
+`);
+  maybePrintStarPrompt(io);
   return 0;
 }
 
+// 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 join14 } from "node:path";
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function conflictingDotenvImage(root, imageRef) {
+  const rootEnv = join14(root, ".env");
+  const fallbackEnv = join14(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 {
+    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;
+  }
+  routeVerb(root, "upgrade", entrySandboxName(root) ?? opts.name);
+  const lock = join14(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);
+  }
+}
+
+// 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}.
+
+\`install openshell\` never prompts. The command needs the host \`openshell\` CLI
+and a connected gateway, and runs the prebuilt image. The command refuses
+--checkout, --home-mount, and image.mode "build".
+
+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 or openshell 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 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 join17 } from "node:path";
 
 // src/lib/docs.ts
 var SOURCE_DOCS_BASE = "https://github.com/mifunedev/agro/blob/main/";
@@ -4065,17 +4909,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 basename7, dirname as dirname8, isAbsolute, join as join15, resolve as resolve10 } 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 join15(hostStateHome(env, home), HOST_CONFIG_FILE);
 }
 function assertWorkspaceName(name) {
   if (!SANDBOX_NAME_PATTERN.test(name)) {
@@ -4085,14 +4932,14 @@ function assertWorkspaceName(name) {
   }
 }
 function workspacesRoot(env, home) {
-  return join13(hostStateHome(env, home), WORKSPACES_SUBDIR);
+  return join15(hostStateHome(env, home), WORKSPACES_SUBDIR);
 }
 function workspaceRoot(name, env, home) {
   assertWorkspaceName(name);
-  return join13(workspacesRoot(env, home), name);
+  return join15(workspacesRoot(env, home), name);
 }
 function defaultHarnessRoot(env, home) {
-  return join13(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
+  return join15(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
 }
 function validateHostConfig(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -4114,7 +4961,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 +4971,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`);
   }
@@ -4135,8 +4982,15 @@ function validateReceipts(value, field, noun) {
       throw fieldError2(at, "must be a JSON object");
     }
     const entry = receipt;
-    absoluteField(entry.prefix, `${at}.prefix`);
-    absoluteField(entry.binPath, `${at}.binPath`);
+    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 +5004,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}`);
@@ -4162,7 +5016,7 @@ function readHostConfig(env, home) {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    throw new Error(`${basename5(path4)} is not valid JSON: ${path4}`);
+    throw new Error(`${basename7(path4)} is not valid JSON: ${path4}`);
   }
   return validateHostConfig(parsed);
 }
@@ -4178,22 +5032,22 @@ function writeHostConfig(config, env, home) {
     renameSync4(tmp, path4);
   } catch (error) {
     try {
-      unlinkSync5(tmp);
+      unlinkSync6(tmp);
     } catch {
     }
     throw error;
   }
 }
 function resolveHarnessRoot(explicit, env, home) {
-  if (typeof explicit === "string" && explicit !== "") return resolve8(explicit);
+  if (typeof explicit === "string" && explicit !== "") return resolve10(explicit);
   const configured = readHostConfig(env, home).harnessRoot;
-  if (typeof configured === "string" && configured !== "") return resolve8(configured);
+  if (typeof configured === "string" && configured !== "") return resolve10(configured);
   return defaultHarnessRoot(env, home);
 }
 function recordHarnessRoot(root, env, home) {
   const config = readHostConfig(env, home);
   const recorded = config.harnessRoot;
-  if (typeof recorded === "string" && recorded !== "" && resolve8(recorded) === root) return;
+  if (typeof recorded === "string" && recorded !== "" && resolve10(recorded) === root) return;
   writeHostConfig({ ...config, harnessRoot: root }, env, home);
 }
 function fieldError2(path4, requirement) {
@@ -4201,8 +5055,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 join16, resolve as resolve11 } from "node:path";
 var AGRO_REPO_URL = "https://github.com/mifunedev/agro.git";
 var IGNORABLE_ENTRIES = [
   REGISTRY_SUBDIR,
@@ -4214,15 +5068,15 @@ 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) => join16(home, name));
 }
 function stateHomeRootRefusal(bin, root, home, verb = "harness") {
-  const target = resolve9(root);
+  const target = resolve11(root);
   const enclosing = stateHomes(home).find((state) => target === state);
   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} ${join16(home, "agro")}\` \u2014 then re-run this command.
 `;
 }
 function isIgnorableEntry(name) {
@@ -4239,24 +5093,24 @@ 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(join16(dirname9(root), "agro-clone-"));
   try {
-    const checkout = join14(staging, "agro");
+    const checkout = join16(staging, "agro");
     cloneInto(checkout, run, root, ref);
     for (const name of readdirSync3(checkout)) {
-      const destination = join14(root, name);
-      if (existsSync18(destination)) {
+      const destination = join16(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(join16(checkout, name), destination);
     }
   } finally {
     rmSync4(staging, { recursive: true, force: true });
   }
 }
 function ensureHostWorkspace(path4, run = spawnRunner, ref) {
-  const root = resolve9(path4);
-  if (existsSync18(join14(root, ".git"))) return { root, action: "reused" };
+  const root = resolve11(path4);
+  if (existsSync19(join16(root, ".git"))) return { root, action: "reused" };
   const stats = statSync5(root, { throwIfNoEntry: false });
   if (stats === void 0) {
     mkdirSync10(dirname9(root), { recursive: true });
@@ -4278,11 +5132,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(join16(root, name, ".git"))).sort();
 }
 function resolveExistingWorkspace(bin, verb, path4, env, home) {
-  const root = resolve9(path4);
-  if (existsSync18(join14(root, ".git"))) return { ok: true, root };
+  const root = resolve11(path4);
+  if (existsSync19(join16(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 +5166,7 @@ function targetFor(root, run, env) {
   });
 }
 function hostPrefix(home) {
-  return join15(home, ".local");
+  return join17(home, ".local");
 }
 function pathEntries(env) {
   return (env.PATH ?? "").split(delimiter2).filter((part) => part !== "");
@@ -4346,6 +5200,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(join17(harnessBinPath(prefix), entry.binary));
+}
 function stateOf(entry, installed, location) {
   return {
     id: entry.id,
@@ -4365,7 +5234,7 @@ function probeableHost(env, home) {
     return void 0;
   }
   const prefix = hostPrefix(home);
-  if (!existsSync19(join15(root, ".git")) && !existsSync19(prefix)) return void 0;
+  if (!existsSync20(join17(root, ".git")) && !existsSync20(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectStates(root, run, home, env, only) {
@@ -4571,7 +5440,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 +5612,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 +5651,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 +5682,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 join18, resolve as resolve12 } from "node:path";
 function homeOf2(opts) {
   return (opts.homedir ?? homedir4)();
 }
@@ -4809,7 +5710,7 @@ function messageOf2(error) {
 }
 function recordedRoot(env, home) {
   const configured = readHostConfig(env, home).harnessRoot;
-  return typeof configured === "string" && configured !== "" ? resolve10(configured) : void 0;
+  return typeof configured === "string" && configured !== "" ? resolve12(configured) : void 0;
 }
 function renderTable2(rows, io) {
   const header2 = ["WORKSPACE", "DEFAULT", "PATH"];
@@ -4834,7 +5735,7 @@ async function runWorkspaceCreate(name, opts, io) {
   let root;
   const chosen = name ?? DEFAULT_WORKSPACE_NAME;
   try {
-    root = opts.path !== void 0 ? resolve10(opts.path) : workspaceRoot(chosen, env, home);
+    root = opts.path !== void 0 ? resolve12(opts.path) : workspaceRoot(chosen, env, home);
   } catch (err) {
     io.stderr(`${bin} workspace: ${messageOf2(err)}
 `);
@@ -4846,9 +5747,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(join18(root, ".git"))) {
       const at = opts.ref !== void 0 ? ` at ${opts.ref}` : "";
       io.stdout(`cloning ${AGRO_REPO_URL}${at} into ${root}\u2026
 `);
@@ -4893,7 +5794,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 = join18(registry, name);
       return { name, root, default: recorded === root };
     });
   } catch (err) {
@@ -4918,9 +5819,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 join19 } from "node:path";
 
 // src/lib/tools/catalog.ts
 var TOOLS_DOC = "docs/installation.md";
@@ -5337,6 +6238,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 +6252,21 @@ function targetFor2(root, run, env) {
   });
 }
 function hostPrefix2(home) {
-  return join17(home, ".local");
+  return join19(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(join19(harnessBinPath(prefix), entry.binary));
 }
 function pathEntries2(env) {
   return (env.PATH ?? "").split(delimiter3).filter((part) => part !== "");
@@ -5430,7 +6346,7 @@ function probeableHost2(env, home) {
     return void 0;
   }
   const prefix = hostPrefix2(home);
-  if (!existsSync21(join17(root, ".git")) && !existsSync21(prefix)) return void 0;
+  if (!existsSync22(join19(root, ".git")) && !existsSync22(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectRows(root, run, home, env, only) {
@@ -5646,7 +6562,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 +6605,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 +6666,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 +6688,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 +6759,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 +6782,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 +6803,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
@@ -5931,7 +6883,7 @@ function fetchRemoteSource(opts) {
 }
 
 // src/cli.ts
-var DEFAULT_SOURCE_CONTROL_DIR = resolve11(
+var DEFAULT_SOURCE_CONTROL_DIR = resolve13(
   dirname10(fileURLToPath(import.meta.url)),
   "../.."
 );
@@ -5944,7 +6896,7 @@ var INTEGRATIONS = {
     )
   }
 };
-function isHelpFlag(arg) {
+function isHelpFlag2(arg) {
   return arg === "--help" || arg === "-h" || arg === "help";
 }
 function isVersionFlag(arg) {
@@ -5961,7 +6913,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 +7063,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 +7187,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 +7278,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 +7287,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 +7305,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 +7322,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 +7354,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 +7366,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 +7387,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 +7406,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 +7418,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 +7444,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 +7486,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 +7503,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 +7519,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 +7591,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 +7672,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,19 +7730,19 @@ 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(join20(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) };
+    return { kind: "local", fromDir: resolve13(args.fromDir) };
   }
   if (args.fromRemote) {
     return { kind: "remote", ref: args.ref };
   }
   if (bundledPayloadExists(bundled, exists)) {
-    return { kind: "local", fromDir: resolve11(bundled.sourceControlDir, "..") };
+    return { kind: "local", fromDir: resolve13(bundled.sourceControlDir, "..") };
   }
   return {
     kind: "remote",
@@ -6972,7 +7754,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(join20(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
     );
     if (parsed && typeof parsed.version === "string") return parsed.version;
   } catch {
@@ -6981,7 +7763,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(join20(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 +7780,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 +7923,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 +8008,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;
     }
@@ -7371,7 +8123,19 @@ function lifecycleIo() {
     stderr: (s) => process.stderr.write(s)
   };
 }
-main(process.argv.slice(2)).then(
+async function runCli(argv) {
+  try {
+    return await main(argv);
+  } catch (err) {
+    if (err instanceof RuntimeUnsupportedError) {
+      process.stderr.write(`${err.message}
+`);
+      return 1;
+    }
+    throw err;
+  }
+}
+runCli(process.argv.slice(2)).then(
   (code) => process.exit(code),
   (err) => {
     const msg = err instanceof Error ? err.message : String(err);
@@ -7386,7 +8150,7 @@ export {
   SECRET_VERBS,
   bundledPayloadExists,
   extractSandboxFlag,
-  isHelpFlag,
+  isHelpFlag2 as isHelpFlag,
   isVersionFlag,
   parseComposeArgs,
   parseConfigArgs,
@@ -7416,6 +8180,7 @@ export {
   printVendorHelp,
   printWorkspaceHelp,
   resolveVendorSource,
+  runCli,
   runWithRemoteSource,
   runtimeLines
 };