@mifune/agro 0.19.0 → 0.20.0-rc.1

package/dist/agro.js

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 
 // src/cli.ts
 import { fileURLToPath } from "node:url";
-import { dirname as dirname10, join as join19, resolve as resolve11 } from "node:path";
+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";
 
@@ -844,6 +844,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/overview.md"
+  },
+  {
+    id: "microsandbox",
+    title: "MicroSandbox",
+    tier: "microvm",
+    state: "planned",
+    provisionable: false,
+    notProvisionableReason: (bin) => `microsandbox is not a provisionable runtime yet; see https://github.com/mifunedev/agro/issues/592. Inside a sandbox run \`${bin} tool install microsandbox\`.`,
+    docsPath: "docs/runtimes/microsandbox.md"
+  },
+  {
+    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 = [
@@ -865,7 +908,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;
@@ -894,6 +937,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;
@@ -1283,8 +1333,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();
@@ -1296,7 +1346,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);
@@ -1314,7 +1364,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) {
@@ -1364,10 +1414,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 {
@@ -1752,6 +1802,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-";
@@ -1808,10 +1861,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,
@@ -1823,6 +1878,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)) {
@@ -1981,12 +2040,28 @@ 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.20.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 = "/etc/agro/sandbox";
 var DOCKERENV_FILE = "/.dockerenv";
+var EXECUTION_TARGET_ENV = "AGRO_EXECUTION_TARGET";
 function detectSandbox(env = process.env, fileExists = existsSync9) {
   const override = agroEnvValue(env, "EXECUTION_TARGET");
   if (override === "local") return { inside: true, rule: "override" };
@@ -2224,6 +2299,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) {
@@ -2247,19 +2559,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.19.0" : "0.0.0-dev";
-var OFFICIAL_IMAGE = "ghcr.io/mifunedev/agro";
-var RELEASE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-z][a-z0-9]*\.[0-9]+)?$/;
-function parseReleaseVersion(value) {
-  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
@@ -2325,13 +2641,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"
@@ -2389,7 +2795,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(
@@ -2470,25 +2876,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;
 }
@@ -2505,6 +2913,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], {
@@ -2517,6 +2926,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" });
@@ -2527,7 +2937,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 [];
   }
@@ -2543,11 +2953,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) {
@@ -2562,7 +2984,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\`
@@ -2593,7 +3022,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}
@@ -2883,13 +3312,13 @@ function sameRemote(url, owner, name) {
 // src/commands/secret.ts
 import { spawnSync as spawnSync3 } from "node:child_process";
 import { existsSync as existsSync12 } from "node:fs";
-import { join as join7 } from "node:path";
+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 = [];
@@ -2921,7 +3350,7 @@ function isGitIgnored(root, path4) {
   return result.status === 0;
 }
 function ignoreSecretsFile(root) {
-  if (!existsSync12(join7(root, ".git"))) return;
+  if (!existsSync12(join8(root, ".git"))) return;
   if (isGitIgnored(root, ".env")) return;
   appendGitignoreLines(root, [".env"]);
 }
@@ -2980,10 +3409,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";
@@ -3028,13 +3457,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);
@@ -3278,7 +3707,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",
@@ -3286,7 +3715,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");
@@ -3450,7 +3879,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 {
@@ -3459,10 +3888,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;
@@ -3525,7 +3954,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
@@ -3806,45 +4235,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/overview.md"
-  }),
-  Object.freeze({
-    id: "microsandbox",
-    title: "MicroSandbox",
-    tier: "microvm",
-    state: "planned",
-    provisionable: false,
-    notProvisionableReason: (bin) => `microsandbox is not a provisionable runtime yet; see https://github.com/mifunedev/agro/issues/592. Inside a sandbox run \`${bin} tool install microsandbox\`.`,
-    docsPath: "docs/runtimes/microsandbox.md"
-  })
-]);
-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}
 `);
@@ -3859,7 +4261,7 @@ function maybePrintStarPrompt(io, env = process.env, isTTY = process.stdout.isTT
 // src/commands/sandbox-list.ts
 async function entryStatus(root, name, run) {
   try {
-    const target = resolveExecutionTarget({ projectRoot: root, container: name, run });
+    const target = resolveExecutionTarget({ projectRoot: root, container: entrySandboxName(root) ?? name, run });
     return await target.status();
   } catch {
     return "unknown";
@@ -3921,10 +4323,10 @@ function gitIdentity(run, key) {
   return (result.stdout ?? "").trim();
 }
 function isBuildCapable(repo) {
-  return repo !== void 0 && existsSync16(join12(repo, ".devcontainer", "Dockerfile"));
+  return repo !== void 0 && existsSync16(join13(repo, ".devcontainer", "Dockerfile"));
 }
 function prepareHomeMount(value) {
-  const path4 = resolve7(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}`);
@@ -3968,18 +4370,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,
@@ -4020,7 +4422,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;
@@ -4037,7 +4439,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}
 `);
@@ -4055,9 +4458,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;
@@ -4101,7 +4504,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) } : {} });
@@ -4122,16 +4525,77 @@ async function runSandboxInstall(opts, io) {
   }
   return code;
 }
+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 {
+    assertSandboxName(name);
+  } catch (error) {
+    return fail2(error instanceof Error ? error.message : String(error));
+  }
+  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"');
+  }
+  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 (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 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 join13 } from "node:path";
+import { join as join14 } from "node:path";
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function conflictingDotenvImage(root, imageRef) {
-  const rootEnv = join13(root, ".env");
-  const fallbackEnv = join13(root, ".devcontainer", ".env");
+  const 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/)) {
@@ -4169,7 +4633,8 @@ async function runSandboxUpgrade(opts, io) {
 `);
     return 1;
   }
-  const lock = join13(root, ".sandbox-upgrade.lock");
+  routeVerb(root, "upgrade", entrySandboxName(root) ?? opts.name);
+  const lock = join14(root, ".sandbox-upgrade.lock");
   let fd;
   try {
     fd = openSync2(lock, "wx", 384);
@@ -4284,6 +4749,10 @@ 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
@@ -4306,7 +4775,7 @@ Flags:
                    ${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
+  --print-argv     Print the docker compose or openshell argv that would run, then exit
                    without writing an entry
   --json           Machine-readable output (list)
 
@@ -4499,7 +4968,7 @@ async function runSandboxCommand(rest, bin) {
 // src/commands/harness.ts
 import { existsSync as existsSync20 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { delimiter as delimiter2, join as join16 } from "node:path";
+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/";
@@ -4513,7 +4982,7 @@ function sourceDocsUrl(docsPath) {
 
 // src/lib/host-config.ts
 import { existsSync as existsSync18, mkdirSync as mkdirSync9, readFileSync as readFileSync12, renameSync as renameSync4, unlinkSync as unlinkSync6, writeFileSync as writeFileSync9 } from "node:fs";
-import { basename as basename5, dirname as dirname8, isAbsolute, join as join14, resolve as resolve8 } from "node:path";
+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";
@@ -4525,7 +4994,7 @@ function hostStateHome(env, home) {
   return resolveUserStateHome(env, home);
 }
 function hostConfigPath(env, home) {
-  return join14(hostStateHome(env, home), HOST_CONFIG_FILE);
+  return join15(hostStateHome(env, home), HOST_CONFIG_FILE);
 }
 function assertWorkspaceName(name) {
   if (!SANDBOX_NAME_PATTERN.test(name)) {
@@ -4535,14 +5004,14 @@ function assertWorkspaceName(name) {
   }
 }
 function workspacesRoot(env, home) {
-  return join14(hostStateHome(env, home), WORKSPACES_SUBDIR);
+  return join15(hostStateHome(env, home), WORKSPACES_SUBDIR);
 }
 function workspaceRoot(name, env, home) {
   assertWorkspaceName(name);
-  return join14(workspacesRoot(env, home), name);
+  return join15(workspacesRoot(env, home), name);
 }
 function defaultHarnessRoot(env, home) {
-  return join14(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)) {
@@ -4619,7 +5088,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);
 }
@@ -4642,15 +5111,15 @@ function writeHostConfig(config, env, home) {
   }
 }
 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) {
@@ -4659,7 +5128,7 @@ function fieldError2(path4, requirement) {
 
 // src/lib/host-workspace.ts
 import { existsSync as existsSync19, mkdirSync as mkdirSync10, mkdtempSync as mkdtempSync4, readdirSync as readdirSync3, renameSync as renameSync5, rmSync as rmSync4, statSync as statSync5 } from "node:fs";
-import { dirname as dirname9, join as join15, resolve as resolve9 } from "node:path";
+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,
@@ -4671,15 +5140,15 @@ function isDirectory3(path4) {
   return statSync5(path4, { throwIfNoEntry: false })?.isDirectory() === true;
 }
 function stateHomes(home) {
-  return STATE_HOME_DIRS.map((name) => join15(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} ${join15(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) {
@@ -4696,24 +5165,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(join15(dirname9(root), "agro-clone-"));
+  const staging = mkdtempSync4(join16(dirname9(root), "agro-clone-"));
   try {
-    const checkout = join15(staging, "agro");
+    const checkout = join16(staging, "agro");
     cloneInto(checkout, run, root, ref);
     for (const name of readdirSync3(checkout)) {
-      const destination = join15(root, name);
+      const destination = join16(root, name);
       if (existsSync19(destination)) {
         throw new Error(`could not move ${name} into ${root} \u2014 the path already exists`);
       }
-      renameSync5(join15(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 (existsSync19(join15(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 });
@@ -4735,11 +5204,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) => existsSync19(join15(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 (existsSync19(join15(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(", ")}
 `;
@@ -4776,7 +5245,7 @@ function targetFor(root, cwd, run, env) {
   });
 }
 function hostPrefix(home) {
-  return join16(home, ".local");
+  return join17(home, ".local");
 }
 function pathEntries(env) {
   return (env.PATH ?? "").split(delimiter2).filter((part) => part !== "");
@@ -4823,7 +5292,7 @@ async function sandboxMarkerExists(target, entry) {
   return r.exitCode === 0;
 }
 function hostBinaryUnderPrefix(entry, prefix) {
-  return existsSync20(join16(harnessBinPath(prefix), entry.binary));
+  return existsSync20(join17(harnessBinPath(prefix), entry.binary));
 }
 function stateOf(entry, installed, location) {
   return {
@@ -4844,7 +5313,7 @@ function probeableHost(env, home) {
     return void 0;
   }
   const prefix = hostPrefix(home);
-  if (!existsSync20(join16(root, ".git")) && !existsSync20(prefix)) return void 0;
+  if (!existsSync20(join17(root, ".git")) && !existsSync20(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectStates(root, cwd, run, home, env, only) {
@@ -5445,7 +5914,7 @@ async function runHarnessInstall(name, opts, io) {
 // src/commands/workspace.ts
 import { existsSync as existsSync21, rmSync as rmSync5 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-import { join as join17, resolve as resolve10 } from "node:path";
+import { join as join18, resolve as resolve12 } from "node:path";
 function homeOf2(opts) {
   return (opts.homedir ?? homedir4)();
 }
@@ -5454,7 +5923,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"];
@@ -5479,7 +5948,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)}
 `);
@@ -5493,7 +5962,7 @@ async function runWorkspaceCreate(name, opts, io) {
   let action;
   const preexisting = existsSync21(root);
   try {
-    if (!opts.json && !existsSync21(join17(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
 `);
@@ -5538,7 +6007,7 @@ async function runWorkspaceList(opts, io) {
     const recorded = recordedRoot(env, home);
     const registry = workspacesRoot(env, home);
     rows = listHostWorkspaces(env, home).map((name) => {
-      const root = join17(registry, name);
+      const root = join18(registry, name);
       return { name, root, default: recorded === root };
     });
   } catch (err) {
@@ -5565,7 +6034,7 @@ async function runWorkspaceList(opts, io) {
 // src/commands/tool.ts
 import { existsSync as existsSync22 } from "node:fs";
 import { homedir as homedir5, userInfo as userInfo2 } from "node:os";
-import { delimiter as delimiter3, join as join18 } from "node:path";
+import { delimiter as delimiter3, join as join19 } from "node:path";
 
 // src/lib/tools/catalog.ts
 var TOOLS_DOC = "docs/installation.md";
@@ -5996,7 +6465,7 @@ function targetFor2(root, run, env) {
   });
 }
 function hostPrefix2(home) {
-  return join18(home, ".local");
+  return join19(home, ".local");
 }
 function sandboxMarkerPath2(entry) {
   return `${SANDBOX_HARNESS_PREFIX}/share/agro/tools/${entry.id}.installed`;
@@ -6010,7 +6479,7 @@ async function sandboxMarkerExists2(target, entry) {
   return r.exitCode === 0;
 }
 function hostBinaryUnderPrefix2(entry, prefix) {
-  return existsSync22(join18(harnessBinPath(prefix), entry.binary));
+  return existsSync22(join19(harnessBinPath(prefix), entry.binary));
 }
 function pathEntries2(env) {
   return (env.PATH ?? "").split(delimiter3).filter((part) => part !== "");
@@ -6090,7 +6559,7 @@ function probeableHost2(env, home) {
     return void 0;
   }
   const prefix = hostPrefix2(home);
-  if (!existsSync22(join18(root, ".git")) && !existsSync22(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) {
@@ -6656,7 +7125,7 @@ var AGRO_COMMANDS = Object.freeze({
 });
 
 // src/cli.ts
-var DEFAULT_SOURCE_CONTROL_DIR = resolve11(
+var DEFAULT_SOURCE_CONTROL_DIR = resolve13(
   dirname10(fileURLToPath(import.meta.url)),
   "../.."
 );
@@ -7501,18 +7970,18 @@ function parseGatewayArgs(rest) {
   return { ok: true, args: { help: false, passthrough: [...rest] } };
 }
 function bundledPayloadExists(bundled, exists = existsSync23) {
-  return exists(join19(bundled.sourceControlDir, "manifest.json"));
+  return exists(join20(bundled.sourceControlDir, "manifest.json"));
 }
 function resolveVendorSource(args, bundled, bin = AGRO_PRODUCT.bin) {
   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",
@@ -7524,7 +7993,7 @@ function resolveVendorSource(args, bundled, bin = AGRO_PRODUCT.bin) {
 function readPayloadVersion(checkoutDir) {
   try {
     const parsed = JSON.parse(
-      readFileSync13(join19(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
+      readFileSync13(join20(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
     );
     if (parsed && typeof parsed.version === "string") return parsed.version;
   } catch {
@@ -7533,7 +8002,7 @@ function readPayloadVersion(checkoutDir) {
 }
 async function runWithRemoteSource(hooks, fn) {
   const fetch2 = hooks.fetch ?? fetchRemoteSource;
-  const mkdtemp = hooks.mkdtemp ?? (() => mkdtempSync5(join19(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();
@@ -7899,7 +8368,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);
@@ -7941,6 +8422,7 @@ export {
   printVendorHelp,
   printWorkspaceHelp,
   resolveVendorSource,
+  runCli,
   runWithRemoteSource,
   runtimeLines
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mifune/agro",
-  "version": "0.19.0",
+  "version": "0.20.0-rc.1",
   "description": "AGRO CLI — create and manage sandboxes for coding agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/mifunedev/agro#readme",