@mifune/agro 0.15.0-minimal.1 → 0.15.0

package/dist/agro.js

@@ -8,7 +8,7 @@ var __export = (target, all) => {
 // src/cli.ts
 import { fileURLToPath } from "node:url";
 import { dirname as dirname10, join as join17, resolve as resolve11 } from "node:path";
-import { existsSync as existsSync21, mkdtempSync as mkdtempSync5, readFileSync as readFileSync12, rmSync as rmSync5 } from "node:fs";
+import { existsSync as existsSync21, mkdtempSync as mkdtempSync5, readFileSync as readFileSync12, rmSync as rmSync6 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
 
 // src/commands/update.ts
@@ -1479,6 +1479,11 @@ fi
 # shellcheck source=paths.sh
 . "$PATHS_SH"
 
+MIGRATOR="$SCRIPT_DIR/migrate-harness-yaml.sh"
+if [ -f "$REPO_DIR/harness.yaml" ] && [ -f "$MIGRATOR" ]; then
+  sh "$MIGRATOR" "$REPO_DIR" >&2 || true
+fi
+
 ENV_FILE="$REPO_DIR/.env"
 [ -f "$ENV_FILE" ] || ENV_FILE="$REPO_DIR/.devcontainer/.env"
 
@@ -2217,7 +2222,7 @@ function resolveExecutionTarget(opts) {
 }
 
 // src/lib/version.ts
-var AGRO_VERSION = true ? "0.15.0-minimal.1" : "0.0.0-dev";
+var AGRO_VERSION = true ? "0.15.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) {
@@ -4205,14 +4210,15 @@ function assertCloned(result, root) {
     throw new Error(`could not clone ${AGRO_REPO_URL} into ${root} (exit status ${String(status)})`);
   }
 }
-function cloneInto(target, run, root) {
-  assertCloned(run("git", ["clone", AGRO_REPO_URL, target], { stdio: "inherit" }), root);
+function cloneInto(target, run, root, ref) {
+  const branch = ref !== void 0 ? ["--branch", ref] : [];
+  assertCloned(run("git", ["clone", ...branch, AGRO_REPO_URL, target], { stdio: "inherit" }), root);
 }
-function cloneThroughStaging(root, run) {
+function cloneThroughStaging(root, run, ref) {
   const staging = mkdtempSync4(join13(dirname9(root), "agro-clone-"));
   try {
     const checkout = join13(staging, "agro");
-    cloneInto(checkout, run, root);
+    cloneInto(checkout, run, root, ref);
     for (const name of readdirSync3(checkout)) {
       const destination = join13(root, name);
       if (existsSync17(destination)) {
@@ -4224,13 +4230,13 @@ function cloneThroughStaging(root, run) {
     rmSync4(staging, { recursive: true, force: true });
   }
 }
-function ensureHostWorkspace(path4, run = spawnRunner) {
+function ensureHostWorkspace(path4, run = spawnRunner, ref) {
   const root = resolve9(path4);
   if (existsSync17(join13(root, ".git"))) return { root, action: "reused" };
   const stats = statSync5(root, { throwIfNoEntry: false });
   if (stats === void 0) {
     mkdirSync9(dirname9(root), { recursive: true });
-    cloneInto(root, run, root);
+    cloneInto(root, run, root, ref);
     return { root, action: "cloned" };
   }
   if (!stats.isDirectory()) {
@@ -4242,7 +4248,7 @@ function ensureHostWorkspace(path4, run = spawnRunner) {
       `${root} holds files but no git checkout (${blocking.sort().join(", ")}) \u2014 choose an empty directory or an existing AGRO checkout`
     );
   }
-  cloneThroughStaging(root, run);
+  cloneThroughStaging(root, run, ref);
   return { root, action: "cloned" };
 }
 function listHostWorkspaces(env, home) {
@@ -4431,6 +4437,19 @@ async function runHarnessStatus(name, opts, io) {
 function hermesTargetRoot(target) {
   return target.kind === "docker-compose" ? "/home/sandbox/harness" : target.workspace.targetRoot;
 }
+async function reconcileHermes(target, io, bin, user, root = hermesTargetRoot(target)) {
+  const result = await target.exec({
+    argv: remoteControlDirScript(root, "scripts/link-providers.sh", ["--init", "--hermes-only"]),
+    env: agroEnvPair("PROJECT_ROOT", root),
+    ...user ? { user } : {},
+    stdio: "inherit"
+  });
+  if (result.exitCode !== 0) {
+    io.stderr(`${bin} harness: Hermes integration failed (exit ${result.exitCode}); no installation success reported.
+`);
+  }
+  return result.exitCode;
+}
 function unreachableReason(status) {
   return runtimeIsAbsent(status) ? "No container runtime is on PATH." : `The sandbox is not running (${status}).`;
 }
@@ -4513,7 +4532,7 @@ async function installOnHost(entry, opts, io, run, status) {
   });
   if (linked.exitCode !== 0) {
     io.stderr(
-      `${bin} harness: could not link provider hooks in ${root} (exit ${linked.exitCode}); nothing was installed.
+      `${bin} harness: could not link provider skills in ${root} (exit ${linked.exitCode}); nothing was installed.
 Run: bash ${root}/.agro/scripts/link-providers.sh --init
 `
     );
@@ -4524,6 +4543,10 @@ Run: bash ${root}/.agro/scripts/link-providers.sh --init
     ...agroEnvPair("PROJECT_ROOT", root),
     HERMES_HOME: `${root}/.hermes`
   } : void 0;
+  if (hermes) {
+    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) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
 `);
@@ -4554,6 +4577,8 @@ Run: bash ${root}/.agro/scripts/link-providers.sh --init
 `);
       return 1;
     }
+    const code = await reconcileHermes(target, io, bin, void 0, root);
+    if (code !== 0) return code;
   }
   const receipt = {
     prefix,
@@ -4707,6 +4732,10 @@ async function runHarnessInstall(name, opts, io) {
     ...agroEnvPair("PROJECT_ROOT", hermesTargetRoot(target)),
     HERMES_HOME: `${hermesTargetRoot(target)}/.hermes`
   } : void 0;
+  if (hermes) {
+    const code = await reconcileHermes(target, io, opts.bin, "sandbox");
+    if (code !== 0) return code;
+  }
   const already = await probeInstalled(target, entry, SANDBOX_HARNESS_PREFIX, "sandbox", installEnv);
   if (already === true) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
@@ -4736,6 +4765,8 @@ async function runHarnessInstall(name, opts, io) {
 `);
       return 1;
     }
+    const code = await reconcileHermes(target, io, opts.bin, "sandbox");
+    if (code !== 0) return code;
   }
   io.stdout(`${entry.id}: installed \u2014 see ${sourceDocsUrl(entry.docsPath)} for authentication
 `);
@@ -4743,7 +4774,7 @@ async function runHarnessInstall(name, opts, io) {
 }
 
 // src/commands/workspace.ts
-import { existsSync as existsSync19 } from "node:fs";
+import { existsSync as existsSync19, rmSync as rmSync5 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join15, resolve as resolve10 } from "node:path";
 function homeOf2(opts) {
@@ -4791,15 +4822,25 @@ async function runWorkspaceCreate(name, opts, io) {
     return 1;
   }
   let action;
+  const preexisting = existsSync19(root);
   try {
     if (!opts.json && !existsSync19(join15(root, ".git"))) {
-      io.stdout(`cloning ${AGRO_REPO_URL} into ${root}\u2026
+      const at = opts.ref !== void 0 ? ` at ${opts.ref}` : "";
+      io.stdout(`cloning ${AGRO_REPO_URL}${at} into ${root}\u2026
 `);
     }
-    const created = ensureHostWorkspace(root, run);
+    const created = ensureHostWorkspace(root, run, opts.ref);
     root = created.root;
     action = created.action;
   } catch (err) {
+    if (opts.ref !== void 0) {
+      if (!preexisting) rmSync5(root, { recursive: true, force: true });
+      io.stderr(
+        `${bin} workspace: could not clone ref "${opts.ref}" \u2014 the ref does not exist in ${AGRO_REPO_URL} or the clone failed (${messageOf2(err)})
+`
+      );
+      return 1;
+    }
     io.stderr(`${bin} workspace: ${messageOf2(err)}
 `);
     return 1;
@@ -4854,7 +4895,7 @@ async function runWorkspaceList(opts, io) {
 
 // src/commands/tool.ts
 import { existsSync as existsSync20 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
+import { homedir as homedir5, userInfo as userInfo2 } from "node:os";
 import { delimiter as delimiter3, join as join16 } from "node:path";
 
 // src/lib/tools/catalog.ts
@@ -5076,6 +5117,178 @@ install -d -m 0700 "$HOME/.tailscale"`
       `${HARNESS_PREFIX_TOKEN}/bin/tailscaled`
     ]),
     docsPath: TOOLS_DOC
+  }),
+  Object.freeze({
+    id: "code-server",
+    title: "code-server",
+    kind: "installable",
+    binary: "code-server",
+    verifyArgv: Object.freeze(["bash", "-lc", "command -v code-server >/dev/null"]),
+    versionArgv: Object.freeze(["code-server", "--version"]),
+    installArgv: Object.freeze([
+      "bash",
+      "-lc",
+      [
+        "set -e",
+        "version=4.129.0",
+        'arch="$(dpkg --print-architecture)"',
+        'case "$arch" in',
+        "  amd64) sha=889b09ff3a167a293f53cb68a5a7f38dbab6bd2b50d7a5951c757e56ba51a2b0 ;;",
+        "  arm64) sha=62f7886018923a18cc16112ccfbcd51aee80f8e0c1bb7abc48773d1fd32a7617 ;;",
+        '  *) echo "no pinned code-server build for $arch" >&2; exit 1 ;;',
+        "esac",
+        'prefix="${NPM_USER_PREFIX:-$HOME/.local}"',
+        'dest="$prefix/lib/code-server-$version"',
+        'tmp="$(mktemp -d)"',
+        `trap 'rm -rf "$tmp"' EXIT`,
+        'curl -fsSL "https://github.com/coder/code-server/releases/download/v$version/code-server-$version-linux-$arch.tar.gz" -o "$tmp/code-server.tar.gz"',
+        'echo "$sha  $tmp/code-server.tar.gz" | sha256sum -c -',
+        'install -d "$tmp/release" "$prefix/lib" "$prefix/bin"',
+        'tar -xzf "$tmp/code-server.tar.gz" -C "$tmp/release" --strip-components=1',
+        'rm -rf "$dest"',
+        'mv "$tmp/release" "$dest"',
+        'ln -sfn "$dest/bin/code-server" "$prefix/bin/code-server"',
+        'if ! "$prefix/bin/code-server" --version | grep -q "^$version "; then',
+        '  echo "$prefix/bin/code-server does not report version $version" >&2',
+        "  exit 1",
+        "fi"
+      ].join("\n")
+    ]),
+    installUser: "sandbox",
+    hostCapable: true,
+    uninstallArgv: Object.freeze([
+      "rm",
+      "-rf",
+      `${HARNESS_PREFIX_TOKEN}/bin/code-server`,
+      `${HARNESS_PREFIX_TOKEN}/lib/code-server-4.129.0`
+    ]),
+    docsPath: TOOLS_DOC
+  }),
+  Object.freeze({
+    id: "docker-engine",
+    title: "Docker Engine + Compose",
+    kind: "installable",
+    binary: "docker",
+    verifyArgv: Object.freeze([
+      "bash",
+      "-lc",
+      'command -v docker >/dev/null && docker compose version >/dev/null && systemctl is-enabled --quiet docker && id -nG "${SUDO_USER:-$(id -un)}" | tr " " "\\n" | grep -qx docker'
+    ]),
+    versionArgv: Object.freeze(["docker", "--version"]),
+    hostInstallArgv: Object.freeze([
+      "bash",
+      "-lc",
+      [
+        "set -e",
+        ". /etc/os-release",
+        'if [ "${ID:-}" != ubuntu ]; then',
+        '  echo "docker-engine installs from Docker\'s Ubuntu repository; this host is ${ID:-unknown}" >&2',
+        "  exit 1",
+        "fi",
+        "fingerprint=9DC858229FC7DD38854AE2D88D81803C0EBFCD88",
+        'user="${SUDO_USER:-$(id -un)}"',
+        "export DEBIAN_FRONTEND=noninteractive",
+        'tmp="$(mktemp -d)"',
+        `trap 'rm -rf "$tmp"' EXIT`,
+        "apt-get update",
+        "apt-get install -y ca-certificates curl gnupg",
+        "install -m 0755 -d /etc/apt/keyrings",
+        'curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o "$tmp/docker.asc"',
+        `actual="$(gpg --homedir "$tmp" --show-keys --with-colons "$tmp/docker.asc" | awk -F: '$1 == "fpr" { print $10; exit }')"`,
+        'if [ "$actual" != "$fingerprint" ]; then',
+        '  echo "Docker\'s repository key has fingerprint ${actual:-none}, expected $fingerprint" >&2',
+        "  exit 1",
+        "fi",
+        'install -m 0644 "$tmp/docker.asc" /etc/apt/keyrings/docker.asc',
+        'echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${UBUNTU_CODENAME:-$VERSION_CODENAME} stable" > /etc/apt/sources.list.d/docker.list',
+        "apt-get update",
+        "apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin",
+        'usermod -aG docker "$user"',
+        "systemctl enable --now docker",
+        'echo "$user is in the docker group. Log out and back in before you run docker without sudo."'
+      ].join("\n")
+    ]),
+    hostInstallUser: "root",
+    notInstallableReason: (bin) => `Docker Engine installs on the host only, with \`${bin} tool install docker-engine --host\`. To use Docker inside the sandbox, set \`access.dockerSocket\` to true in agro.json on the host and recreate the sandbox. That mounts the host Docker socket, which is effectively host root.`,
+    hostCapable: true,
+    uninstallArgv: null,
+    docsPath: TOOLS_DOC
+  }),
+  Object.freeze({
+    id: "desktop",
+    title: "XFCE desktop over XRDP",
+    kind: "installable",
+    binary: "xrdp",
+    verifyArgv: Object.freeze([
+      "bash",
+      "-lc",
+      'command -v xrdp >/dev/null && systemctl is-enabled --quiet xrdp && systemctl is-enabled --quiet tailscaled && test -f /etc/systemd/system/xrdp.service.d/agro-tailscale-only.conf && grep -qx xfce4-session "$HOME/.xsession"'
+    ]),
+    hostInstallArgv: Object.freeze([
+      "bash",
+      "-lc",
+      [
+        "set -e",
+        ". /etc/os-release",
+        'if [ "${ID:-}" != ubuntu ]; then',
+        '  echo "desktop installs Ubuntu packages; this host is ${ID:-unknown}" >&2',
+        "  exit 1",
+        "fi",
+        'user="${SUDO_USER:-$(id -un)}"',
+        'home="$(getent passwd "$user" | cut -d: -f6)"',
+        'codename="${UBUNTU_CODENAME:-$VERSION_CODENAME}"',
+        "export DEBIAN_FRONTEND=noninteractive",
+        'tmp="$(mktemp -d)"',
+        `trap 'rm -rf "$tmp"' EXIT`,
+        "apt-get update",
+        "apt-get install -y ca-certificates curl gnupg nftables",
+        "if ! systemctl cat tailscaled.service >/dev/null 2>&1; then",
+        "  fingerprint=2596A99EAAB33821893C0A79458CA832957F5868",
+        '  curl -fsSL "https://pkgs.tailscale.com/stable/ubuntu/$codename.noarmor.gpg" -o "$tmp/tailscale.gpg"',
+        `  actual="$(gpg --homedir "$tmp" --show-keys --with-colons "$tmp/tailscale.gpg" | awk -F: '$1 == "fpr" { print $10; exit }')"`,
+        '  if [ "$actual" != "$fingerprint" ]; then',
+        '    echo "Tailscale\'s repository key has fingerprint ${actual:-none}, expected $fingerprint" >&2',
+        "    exit 1",
+        "  fi",
+        '  install -m 0644 "$tmp/tailscale.gpg" /usr/share/keyrings/tailscale-archive-keyring.gpg',
+        '  echo "deb [signed-by=/usr/share/keyrings/tailscale-archive-keyring.gpg] https://pkgs.tailscale.com/stable/ubuntu $codename main" > /etc/apt/sources.list.d/tailscale.list',
+        "  apt-get update",
+        "  apt-get install -y tailscale",
+        "fi",
+        "systemctl enable --now tailscaled",
+        "install -d -m 0755 /etc/xrdp /etc/systemd/system/xrdp.service.d",
+        "cat > /etc/xrdp/agro-tailscale-only.nft <<'EOF'",
+        "table inet agro_xrdp",
+        "delete table inet agro_xrdp",
+        "table inet agro_xrdp {",
+        "  chain input {",
+        "    type filter hook input priority filter; policy accept;",
+        '    iifname { "lo", "tailscale0" } accept',
+        "    tcp dport 3389 reject with tcp reset",
+        "  }",
+        "}",
+        "EOF",
+        "nft -f /etc/xrdp/agro-tailscale-only.nft",
+        `printf '[Service]\\nExecStartPre=%s -f /etc/xrdp/agro-tailscale-only.nft\\n' "$(command -v nft)" > /etc/systemd/system/xrdp.service.d/agro-tailscale-only.conf`,
+        "systemctl daemon-reload",
+        "apt-get install -y xfce4 xfce4-goodies xrdp xorgxrdp",
+        `printf '%s\\n' xfce4-session > "$home/.xsession"`,
+        'chown "$user:$(id -gn "$user")" "$home/.xsession"',
+        "adduser xrdp ssl-cert",
+        "systemctl daemon-reload",
+        "systemctl enable xrdp",
+        "systemctl restart xrdp",
+        "systemctl is-active --quiet xrdp",
+        'echo "The desktop is installed. Two steps remain:"',
+        'echo "  sudo tailscale up"',
+        'echo "  sudo passwd $user"'
+      ].join("\n")
+    ]),
+    hostInstallUser: "root",
+    notInstallableReason: (bin) => `The desktop installs on the host only, with \`${bin} tool install desktop --host\`. It installs Tailscale and serves XFCE over XRDP on TCP 3389 through Tailscale only.`,
+    hostCapable: true,
+    uninstallArgv: null,
+    docsPath: TOOLS_DOC
   })
 ]);
 function findTool(id) {
@@ -5138,6 +5351,10 @@ function homeOf3(opts) {
 function platformOf(opts) {
   return opts.platform ?? process.platform;
 }
+function isRootUser(opts) {
+  const identity = opts.identity ?? (() => ({ name: userInfo2().username, uid: userInfo2().uid }));
+  return identity().uid === 0;
+}
 function isInteractive2(opts) {
   return opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
 }
@@ -5176,6 +5393,7 @@ function rowOf(entry, installed, version, location) {
     version,
     installable: entry.installArgv !== void 0,
     hostCapable: entry.hostCapable,
+    hostRoot: entry.hostInstallUser === "root",
     location,
     docs: sourceDocsUrl(entry.docsPath)
   };
@@ -5223,13 +5441,20 @@ function cell2(value, absent) {
 function renderTable3(collected, io, bin) {
   const rows = collected.rows;
   const header2 = ["TOOL", "KIND", "INSTALLED"];
-  const body = rows.map((r) => [r.id, r.kind, cell2(r.installed, "?")]);
+  const body = rows.map((r) => [
+    r.id,
+    r.hostRoot ? `${r.kind} (root)` : r.kind,
+    cell2(r.installed, "?")
+  ]);
   const widths = header2.map(
     (h, i) => Math.max(h.length, ...body.map((b) => b[i].length))
   );
   const line = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd() + "\n";
   io.stdout(line(header2));
   for (const row of body) io.stdout(line(row));
+  if (rows.some((r) => r.hostRoot)) {
+    io.stdout("\n(root) installs on the host as root through `sudo -n`.\n");
+  }
   if (rows.some((r) => r.location === "host")) {
     io.stdout(
       `
@@ -5409,11 +5634,21 @@ Every tool installer in the catalog is Debian-specific. Install ${entry.id} with
     }
     return 0;
   }
+  const sudo = entry.hostInstallUser === "root" && !isRootUser(opts);
+  if (sudo && (await tryExec(target, ["sudo", "-n", "true"], void 0))?.exitCode !== 0) {
+    io.stderr(
+      `${bin} tool: ${entry.id} installs as root on the host and needs passwordless \`sudo\`.
+\`sudo -n true\` failed. Configure passwordless sudo for this user, or run as root.
+`
+    );
+    return 1;
+  }
   if (!await confirmDownload(entry, opts, io, true)) return 1;
   io.stdout(`installing ${entry.title} on the host\u2026
 `);
+  const argv = resolveToolInstallArgv(entry, true);
   const r = await target.exec({
-    argv: resolveToolInstallArgv(entry, true),
+    argv: sudo ? ["sudo", "-n", "--", ...argv] : argv,
     stdio: "inherit",
     env: installEnv
   });
@@ -5445,6 +5680,11 @@ Every tool installer in the catalog is Debian-specific. Install ${entry.id} with
 `);
     return 1;
   }
+  if (entry.hostInstallUser === "root") {
+    io.stdout(`${entry.id} installed on the host \u2014 see ${sourceDocsUrl(entry.docsPath)}
+`);
+    return 0;
+  }
   io.stdout(`${entry.id}: installed at ${prefix} \u2014 see ${sourceDocsUrl(entry.docsPath)}
 `);
   if (!onPath2(prefix, env)) {
@@ -5460,7 +5700,8 @@ async function runToolInstall(name, opts, io) {
   const root = resolveProjectRoot(opts.cwd);
   const entry = findTool(name);
   if (!entry) return unknownTool(name, io, opts.bin);
-  if (entry.installArgv === void 0) {
+  const hostOnly = entry.installArgv === void 0 && entry.hostInstallArgv !== void 0;
+  const refuseContainer = () => {
     io.stderr(`${opts.bin} tool: ${entry.id} cannot be installed by this command.
 
 `);
@@ -5471,12 +5712,16 @@ async function runToolInstall(name, opts, io) {
 ${installableToolIds().map((t) => `  ${t}`).join("\n")}
 `);
     return 1;
+  };
+  if (entry.installArgv === void 0 && (!hostOnly || runningInsideSandbox(opts.env ?? process.env))) {
+    return refuseContainer();
   }
   const target = targetFor2(root, run, opts.env);
   const status = await resolveTargetStatus(target);
-  if (!isReachable2(status)) {
+  if (!isReachable2(status) || hostOnly && opts.host === true) {
     return await installOnHost2(entry, opts, io, run, status);
   }
+  if (entry.installArgv === void 0) return refuseContainer();
   const already = await probeInstalled2(target, entry, "sandbox");
   if (already === true) {
     io.stdout(`${entry.id}: already installed (${entry.binary})
@@ -5951,7 +6196,8 @@ function printWorkspaceHelp(bin = AGRO_PRODUCT.bin) {
   process.stdout.write(`${bin} workspace \u2014 Create and list host AGRO workspaces
 
 Usage:
-  ${bin} workspace create [<name>]   Clone the AGRO repository into a registry entry
+  ${bin} workspace create [<name>] [--ref <ref>]
+                                   Clone the AGRO repository into a registry entry
   ${bin} workspace list              List every host workspace
 
 A host workspace is an AGRO checkout under \`~/.agro/workspaces/<name>\`. \`create\`
@@ -5966,6 +6212,9 @@ root as \`harnessRoot\`. \`list\` marks the recorded root.
 Flags:
   --json           Machine-readable output
   --path <dir>     Create the workspace at a directory outside the registry
+  --ref <ref>      Clone this branch or tag instead of the default branch (create
+                   only). A missing ref exits 1 and leaves no target directory.
+                   An existing checkout is reused as is.
 `);
 }
 function printGatewayHelp(bin = AGRO_PRODUCT.bin) {
@@ -6469,16 +6718,24 @@ function parseWorkspaceArgs(rest, bin = AGRO_PRODUCT.bin) {
   }
   const positionals = [];
   let expectPath = false;
+  let expectRef = false;
   for (const token of rest) {
     if (expectPath) {
       expectPath = false;
       args.path = token;
+    } else if (expectRef) {
+      expectRef = false;
+      args.ref = token;
     } else if (token === "--json") {
       args.json = true;
     } else if (token === "--path") {
       expectPath = true;
     } else if (token.startsWith("--path=")) {
       args.path = token.slice("--path=".length);
+    } else if (token === "--ref") {
+      expectRef = true;
+    } else if (token.startsWith("--ref=")) {
+      args.ref = token.slice("--ref=".length);
     } else if (token.startsWith("-")) {
       return { ok: false, error: `${bin} workspace: unknown flag "${token}"` };
     } else {
@@ -6488,6 +6745,9 @@ function parseWorkspaceArgs(rest, bin = AGRO_PRODUCT.bin) {
   if (expectPath || args.path === "") {
     return { ok: false, error: `${bin} workspace: --path requires a directory` };
   }
+  if (expectRef || args.ref === "") {
+    return { ok: false, error: `${bin} workspace: --ref requires a branch or tag` };
+  }
   const [sub, name, ...extra] = positionals;
   if (sub !== "create" && sub !== "list") {
     return {
@@ -6505,6 +6765,9 @@ function parseWorkspaceArgs(rest, bin = AGRO_PRODUCT.bin) {
   if (sub === "list" && args.path !== void 0) {
     return { ok: false, error: `${bin} workspace list: --path applies to create only` };
   }
+  if (sub === "list" && args.ref !== void 0) {
+    return { ok: false, error: `${bin} workspace list: --ref applies to create only` };
+  }
   if (args.path !== void 0 && name !== void 0) {
     return {
       ok: false,
@@ -6695,7 +6958,7 @@ function readPayloadVersion(checkoutDir) {
 async function runWithRemoteSource(hooks, fn) {
   const fetch2 = hooks.fetch ?? fetchRemoteSource;
   const mkdtemp = hooks.mkdtemp ?? (() => mkdtempSync5(join17(tmpdir4(), "oh-remote-")));
-  const rm = hooks.rm ?? ((dir) => rmSync5(dir, { recursive: true, force: true }));
+  const rm = hooks.rm ?? ((dir) => rmSync6(dir, { recursive: true, force: true }));
   const out = hooks.stdout ?? ((s) => process.stdout.write(s));
   const checkoutDir = mkdtemp();
   try {
@@ -6957,7 +7220,12 @@ async function main(argv) {
     }
     return await runWorkspaceCreate(
       a.name,
-      { bin, json: a.json, ...a.path !== void 0 ? { path: a.path } : {} },
+      {
+        bin,
+        json: a.json,
+        ...a.path !== void 0 ? { path: a.path } : {},
+        ...a.ref !== void 0 ? { ref: a.ref } : {}
+      },
       io
     );
   }

package/package.json

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