@mifune/agro 0.15.0-minimal.1 → 0.15.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 join17, resolve as resolve11 } from "node:path";
-import { existsSync as existsSync21, mkdtempSync as mkdtempSync5, readFileSync as readFileSync12, rmSync as rmSync5 } from "node:fs";
+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 { 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.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) {
@@ -3727,9 +3732,9 @@ async function runLangfuseSetup(opts, io) {
 }
 
 // src/commands/sandbox.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync7, mkdtempSync as mkdtempSync3, rmSync as rmSync3, statSync as statSync4 } from "node:fs";
+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 join11, resolve as resolve7 } from "node:path";
+import { join as join12, resolve as resolve7 } from "node:path";
 
 // src/lib/runtimes/catalog.ts
 var RUNTIME_CATALOG = Object.freeze([
@@ -3758,6 +3763,27 @@ function runtimeIds() {
   return RUNTIME_CATALOG.map((r) => r.id);
 }
 
+// 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";
+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);
+  if (existsSync15(marker)) return;
+  io.stdout(`${STAR_PROMPT_LINE}
+`);
+  try {
+    mkdirSync7(stateHome, { recursive: true });
+    writeFileSync8(marker, "");
+  } catch {
+    return;
+  }
+}
+
 // src/commands/sandbox.ts
 function hostTimezone() {
   const tz = process.env.TZ;
@@ -3774,27 +3800,27 @@ function gitIdentity(run, key) {
   return (result.stdout ?? "").trim();
 }
 function isBuildCapable(repo) {
-  return repo !== void 0 && existsSync15(join11(repo, ".devcontainer", "Dockerfile"));
+  return repo !== void 0 && existsSync16(join12(repo, ".devcontainer", "Dockerfile"));
 }
 function prepareHomeMount(value) {
   const path4 = resolve7(value);
-  if (existsSync15(path4)) {
+  if (existsSync16(path4)) {
     if (!statSync4(path4).isDirectory()) {
       throw new Error(`--home-mount path exists and is not a directory: ${path4}`);
     }
     return path4;
   }
-  mkdirSync7(path4, { recursive: true });
+  mkdirSync8(path4, { recursive: true });
   return path4;
 }
 function readSeedConfig(repo) {
   if (repo === void 0) return void 0;
   const file = agroConfigPath(repo);
-  return existsSync15(file) ? readAgroConfig(file) : void 0;
+  return existsSync16(file) ? readAgroConfig(file) : void 0;
 }
 function readEntryConfig(name) {
   const file = agroConfigPath(entryRoot(name));
-  return existsSync15(file) ? readAgroConfig(file) : void 0;
+  return existsSync16(file) ? readAgroConfig(file) : void 0;
 }
 function assignSetting(target, path4, value) {
   const segments = path4.split(".");
@@ -3891,7 +3917,7 @@ async function runSandboxInstall(opts, io) {
     return 1;
   }
   const checkout = opts.checkout === void 0 ? void 0 : resolve7(opts.checkout);
-  if (checkout !== void 0 && !existsSync15(checkout)) {
+  if (checkout !== void 0 && !existsSync16(checkout)) {
     io.stderr(`${opts.bin} sandbox install: --checkout directory does not exist: ${checkout}
 `);
     return 1;
@@ -3910,7 +3936,7 @@ async function runSandboxInstall(opts, io) {
   if (buildRequested && !isBuildCapable(configCheckout(config))) {
     const target = configCheckout(config) ?? resolve7(opts.checkout ?? ".");
     io.stderr(
-      `${opts.bin} sandbox install: image.mode is "build" but ${join11(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 ${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
 `
     );
     return 1;
@@ -3954,7 +3980,7 @@ async function runSandboxInstall(opts, io) {
     ...useNoBuild ? { noBuild: true } : {}
   };
   if (opts.printArgv === true) {
-    const preview = mkdtempSync3(join11(tmpdir3(), "oh-sandbox-preview-"));
+    const preview = mkdtempSync3(join12(tmpdir3(), "oh-sandbox-preview-"));
     try {
       writeAgroConfig(preview, config);
       materialize(preview, { ...configCheckout(config) !== void 0 ? { checkout: configCheckout(config) } : {} });
@@ -3964,12 +3990,15 @@ async function runSandboxInstall(opts, io) {
     }
   }
   const root = entryRoot(config.name);
-  mkdirSync7(root, { recursive: true });
+  mkdirSync8(root, { recursive: true });
   writeAgroConfig(root, config);
   materialize(root, { ...configCheckout(config) !== void 0 ? { checkout: configCheckout(config) } : {} });
   const code = await runSandbox({ ...sandboxOpts, cwd: root }, io);
-  if (code === 0) io.stdout(`next: ${opts.bin} shell ${config.name}
+  if (code === 0) {
+    io.stdout(`next: ${opts.bin} shell ${config.name}
 `);
+    maybePrintStarPrompt(io);
+  }
   return code;
 }
 async function entryStatus(root, name, run) {
@@ -4021,9 +4050,9 @@ async function runSandboxList(opts, io) {
 }
 
 // src/commands/harness.ts
-import { existsSync as existsSync18 } from "node:fs";
+import { existsSync as existsSync19 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { delimiter as delimiter2, join as join14 } from "node:path";
+import { delimiter as delimiter2, join as join15 } from "node:path";
 
 // src/lib/docs.ts
 var SOURCE_DOCS_BASE = "https://github.com/mifunedev/agro/blob/main/";
@@ -4036,17 +4065,17 @@ function sourceDocsUrl(docsPath) {
 }
 
 // src/lib/host-config.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync8, readFileSync as readFileSync11, renameSync as renameSync4, unlinkSync as unlinkSync5, writeFileSync as writeFileSync8 } from "node:fs";
-import { basename as basename5, dirname as dirname8, isAbsolute, join as join12, resolve as resolve8 } from "node:path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync9, readFileSync as readFileSync11, renameSync as renameSync4, unlinkSync as unlinkSync5, writeFileSync as writeFileSync9 } from "node:fs";
+import { basename as basename5, dirname as dirname8, isAbsolute, join as join13, resolve as resolve8 } from "node:path";
 var HOST_CONFIG_MODE = 420;
 var HOST_CONFIG_FILE = "config.json";
 var WORKSPACES_SUBDIR = "workspaces";
-var DEFAULT_WORKSPACE_NAME = "default";
+var DEFAULT_WORKSPACE_NAME = "harness";
 function hostStateHome(env, home) {
   return resolveUserStateHome(env, home);
 }
 function hostConfigPath(env, home) {
-  return join12(hostStateHome(env, home), HOST_CONFIG_FILE);
+  return join13(hostStateHome(env, home), HOST_CONFIG_FILE);
 }
 function assertWorkspaceName(name) {
   if (!SANDBOX_NAME_PATTERN.test(name)) {
@@ -4056,14 +4085,14 @@ function assertWorkspaceName(name) {
   }
 }
 function workspacesRoot(env, home) {
-  return join12(hostStateHome(env, home), WORKSPACES_SUBDIR);
+  return join13(hostStateHome(env, home), WORKSPACES_SUBDIR);
 }
 function workspaceRoot(name, env, home) {
   assertWorkspaceName(name);
-  return join12(workspacesRoot(env, home), name);
+  return join13(workspacesRoot(env, home), name);
 }
 function defaultHarnessRoot(env, home) {
-  return join12(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
+  return join13(workspacesRoot(env, home), DEFAULT_WORKSPACE_NAME);
 }
 function validateHostConfig(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -4121,7 +4150,7 @@ function validateReceipts(value, field, noun) {
 }
 function readHostConfig(env, home) {
   const path4 = hostConfigPath(env, home);
-  if (!existsSync16(path4)) return { version: 1 };
+  if (!existsSync17(path4)) return { version: 1 };
   let raw;
   try {
     raw = readFileSync11(path4, "utf8");
@@ -4143,9 +4172,9 @@ function writeHostConfig(config, env, home) {
   const body = `${JSON.stringify(validated, null, 2)}
 `;
   const tmp = `${path4}.tmp.${process.pid}`;
-  mkdirSync8(dirname8(path4), { recursive: true });
+  mkdirSync9(dirname8(path4), { recursive: true });
   try {
-    writeFileSync8(tmp, body, { mode: HOST_CONFIG_MODE, encoding: "utf8" });
+    writeFileSync9(tmp, body, { mode: HOST_CONFIG_MODE, encoding: "utf8" });
     renameSync4(tmp, path4);
   } catch (error) {
     try {
@@ -4172,8 +4201,8 @@ function fieldError2(path4, requirement) {
 }
 
 // src/lib/host-workspace.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync9, mkdtempSync as mkdtempSync4, readdirSync as readdirSync3, renameSync as renameSync5, rmSync as rmSync4, statSync as statSync5 } from "node:fs";
-import { dirname as dirname9, join as join13, resolve as resolve9 } from "node:path";
+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";
 var AGRO_REPO_URL = "https://github.com/mifunedev/agro.git";
 var IGNORABLE_ENTRIES = [
   REGISTRY_SUBDIR,
@@ -4185,7 +4214,7 @@ function isDirectory3(path4) {
   return statSync5(path4, { throwIfNoEntry: false })?.isDirectory() === true;
 }
 function stateHomes(home) {
-  return STATE_HOME_DIRS.map((name) => join13(home, name));
+  return STATE_HOME_DIRS.map((name) => join14(home, name));
 }
 function stateHomeRootRefusal(bin, root, home, verb = "harness") {
   const target = resolve9(root);
@@ -4193,7 +4222,7 @@ function stateHomeRootRefusal(bin, root, home, verb = "harness") {
   if (enclosing === void 0) return void 0;
   return `${bin} ${verb}: the ${verb} root ${target} is the state home ${enclosing} itself.
 A workspace there collides with AGRO state and blocks every command run from ${home}.
-Move it out \u2014 for example \`mv ${enclosing} ${join13(home, "agro")}\` \u2014 then re-run this command.
+Move it out \u2014 for example \`mv ${enclosing} ${join14(home, "agro")}\` \u2014 then re-run this command.
 `;
 }
 function isIgnorableEntry(name) {
@@ -4205,32 +4234,33 @@ 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) {
-  const staging = mkdtempSync4(join13(dirname9(root), "agro-clone-"));
+function cloneThroughStaging(root, run, ref) {
+  const staging = mkdtempSync4(join14(dirname9(root), "agro-clone-"));
   try {
-    const checkout = join13(staging, "agro");
-    cloneInto(checkout, run, root);
+    const checkout = join14(staging, "agro");
+    cloneInto(checkout, run, root, ref);
     for (const name of readdirSync3(checkout)) {
-      const destination = join13(root, name);
-      if (existsSync17(destination)) {
+      const destination = join14(root, name);
+      if (existsSync18(destination)) {
         throw new Error(`could not move ${name} into ${root} \u2014 the path already exists`);
       }
-      renameSync5(join13(checkout, name), destination);
+      renameSync5(join14(checkout, name), destination);
     }
   } finally {
     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" };
+  if (existsSync18(join14(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);
+    mkdirSync10(dirname9(root), { recursive: true });
+    cloneInto(root, run, root, ref);
     return { root, action: "cloned" };
   }
   if (!stats.isDirectory()) {
@@ -4242,17 +4272,17 @@ 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) {
   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) => existsSync17(join13(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) => existsSync18(join14(root, name, ".git"))).sort();
 }
 function resolveExistingWorkspace(bin, verb, path4, env, home) {
   const root = resolve9(path4);
-  if (existsSync17(join13(root, ".git"))) return { ok: true, root };
+  if (existsSync18(join14(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(", ")}
 `;
@@ -4282,7 +4312,7 @@ function targetFor(root, run, env) {
   });
 }
 function hostPrefix(home) {
-  return join14(home, ".local");
+  return join15(home, ".local");
 }
 function pathEntries(env) {
   return (env.PATH ?? "").split(delimiter2).filter((part) => part !== "");
@@ -4335,7 +4365,7 @@ function probeableHost(env, home) {
     return void 0;
   }
   const prefix = hostPrefix(home);
-  if (!existsSync18(join14(root, ".git")) && !existsSync18(prefix)) return void 0;
+  if (!existsSync19(join15(root, ".git")) && !existsSync19(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectStates(root, run, home, env, only) {
@@ -4431,6 +4461,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 +4556,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 +4567,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 +4601,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 +4756,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 +4789,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,9 +4798,9 @@ async function runHarnessInstall(name, opts, io) {
 }
 
 // src/commands/workspace.ts
-import { existsSync as existsSync19 } from "node:fs";
+import { existsSync as existsSync20, rmSync as rmSync5 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-import { join as join15, resolve as resolve10 } from "node:path";
+import { join as join16, resolve as resolve10 } from "node:path";
 function homeOf2(opts) {
   return (opts.homedir ?? homedir4)();
 }
@@ -4791,15 +4846,25 @@ async function runWorkspaceCreate(name, opts, io) {
     return 1;
   }
   let action;
+  const preexisting = existsSync20(root);
   try {
-    if (!opts.json && !existsSync19(join15(root, ".git"))) {
-      io.stdout(`cloning ${AGRO_REPO_URL} into ${root}\u2026
+    if (!opts.json && !existsSync20(join16(root, ".git"))) {
+      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;
@@ -4828,7 +4893,7 @@ async function runWorkspaceList(opts, io) {
     const recorded = recordedRoot(env, home);
     const registry = workspacesRoot(env, home);
     rows = listHostWorkspaces(env, home).map((name) => {
-      const root = join15(registry, name);
+      const root = join16(registry, name);
       return { name, root, default: recorded === root };
     });
   } catch (err) {
@@ -4853,9 +4918,9 @@ async function runWorkspaceList(opts, io) {
 }
 
 // src/commands/tool.ts
-import { existsSync as existsSync20 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { delimiter as delimiter3, join as join16 } from "node:path";
+import { existsSync as existsSync21 } from "node:fs";
+import { homedir as homedir5, userInfo as userInfo2 } from "node:os";
+import { delimiter as delimiter3, join as join17 } from "node:path";
 
 // src/lib/tools/catalog.ts
 var TOOLS_DOC = "docs/installation.md";
@@ -5076,6 +5141,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) {
@@ -5113,7 +5350,7 @@ function targetFor2(root, run, env) {
   });
 }
 function hostPrefix2(home) {
-  return join16(home, ".local");
+  return join17(home, ".local");
 }
 function pathEntries2(env) {
   return (env.PATH ?? "").split(delimiter3).filter((part) => part !== "");
@@ -5138,6 +5375,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 +5417,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)
   };
@@ -5188,7 +5430,7 @@ function probeableHost2(env, home) {
     return void 0;
   }
   const prefix = hostPrefix2(home);
-  if (!existsSync20(join16(root, ".git")) && !existsSync20(prefix)) return void 0;
+  if (!existsSync21(join17(root, ".git")) && !existsSync21(prefix)) return void 0;
   return { root, prefix };
 }
 async function collectRows(root, run, home, env, only) {
@@ -5223,13 +5465,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 +5658,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 +5704,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 +5724,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 +5736,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})
@@ -5926,8 +6195,8 @@ Usage:
 
 \`install\` and \`uninstall\` act on the running sandbox. When no sandbox is
 reachable they act on the host. A host install needs an existing AGRO workspace
-and creates none \u2014 run \`${bin} workspace create <name>\` first. The default root is
-the workspace registry entry \`~/.agro/workspaces/default\`. \`--workspace <name>\`
+and creates none \u2014 run \`${bin} workspace create\` first. The fallback root is
+the workspace registry entry \`~/.agro/workspaces/harness\`. \`--workspace <name>\`
 chooses another entry and \`--path <dir>\` a directory outside the registry. A
 successful install records the root as \`harnessRoot\` in \`~/.agro/config.json\`. The
 install prefix is always \`~/.local\`.
@@ -5951,13 +6220,14 @@ 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\`
 clones ${AGRO_REPO_URL} into that entry, and reuses an existing checkout. The
-default name is \`default\`. \`--path <dir>\` creates the workspace outside the
-registry instead.
+implicit name is \`harness\`. Pass \`default\` to create that named workspace.
+\`--path <dir>\` creates the workspace outside the registry instead.
 
 \`create\` records no default. A host install selects its root with
 \`${bin} harness install <harness> --workspace <name>\`, and that install records the
@@ -5966,6 +6236,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) {
@@ -6017,8 +6290,8 @@ only on these tools:
 ${hostCapableToolIds().map((t) => `  ${t}`).join("\n")}
 
 A host install needs an existing AGRO workspace \u2014 \`--path <dir>\`, then
-\`harnessRoot\` in \`~/.agro/config.json\`, then \`~/.agro/workspaces/default\`. It creates
-no workspace: run \`${bin} workspace create <name>\` first. It installs into
+\`harnessRoot\` in \`~/.agro/config.json\`, then \`~/.agro/workspaces/harness\`. It creates
+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.
@@ -6469,16 +6742,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 +6769,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 +6789,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,
@@ -6661,11 +6948,11 @@ function parseGatewayArgs(rest) {
   }
   return { ok: true, args: { help: false, passthrough: [...rest] } };
 }
-function bundledPayloadExists(bundled, exists = existsSync21) {
-  return exists(join17(bundled.sourceControlDir, "manifest.json"));
+function bundledPayloadExists(bundled, exists = existsSync22) {
+  return exists(join18(bundled.sourceControlDir, "manifest.json"));
 }
 function resolveVendorSource(args, bundled, bin = AGRO_PRODUCT.bin) {
-  const exists = bundled.exists ?? existsSync21;
+  const exists = bundled.exists ?? existsSync22;
   if (args.fromDir !== void 0) {
     return { kind: "local", fromDir: resolve11(args.fromDir) };
   }
@@ -6685,7 +6972,7 @@ function resolveVendorSource(args, bundled, bin = AGRO_PRODUCT.bin) {
 function readPayloadVersion(checkoutDir) {
   try {
     const parsed = JSON.parse(
-      readFileSync12(join17(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
+      readFileSync12(join18(resolveControlDir(checkoutDir), "cli", "package.json"), "utf8")
     );
     if (parsed && typeof parsed.version === "string") return parsed.version;
   } catch {
@@ -6694,8 +6981,8 @@ 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 mkdtemp = hooks.mkdtemp ?? (() => mkdtempSync5(join18(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();
   try {
@@ -6957,7 +7244,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.1",
   "description": "AGRO CLI — create and manage sandboxes for coding agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/mifunedev/agro#readme",