tryharness 0.7.18 → 0.7.23

package/cli.mjs

@@ -14,7 +14,7 @@ import { daemonRequest } from "./lib/control-client.mjs";
 import { ensureDir, readJson, writeJsonAtomic } from "./lib/files.mjs";
 import { paths } from "./lib/paths.mjs";
 import { currentRuntime, installRuntime } from "./lib/runtime-install.mjs";
-import { ensureModel, modelPresent } from "./lib/embedder.mjs";
+import { MODELS, ensureLlama, ensureModels, modelsPresent } from "./lib/localmodels.mjs";
 import { installService, serviceInfo, uninstallService } from "./lib/service.mjs";
 import { canShowDesktop, openDesktop, retireDesktop, setupDesktop } from "./lib/desktop.mjs";
 
@@ -173,14 +173,23 @@ async function connect() {
     const shown = await desktop();
     spin.stop(shown.text, shown.ok ? 0 : 2);
   }
-  // The context space's embedder lives with the daemon and comes down with setup, so the machine
-  // can search a task by meaning before the first task exists. About 110 MB, once.
-  if (modelPresent(paths.models)) ui.success("Embedder ready");
+  // The relay's core local models (localmodels.mjs) and the server that runs them come down with setup, so agents get
+  // context packs, code search, the handoff firewall and images checked before they leave from the first task. Each file
+  // is checked against its pinned hash.
+  const core = MODELS.filter((entry) => entry.tier === "core").map((entry) => entry.id);
+  const localRoot = path.join(paths.home, "local");
+  if (modelsPresent(localRoot, core)) ui.success("Local models ready");
   else {
     const download = ui.spinner();
-    download.start("Downloading the embedder (about 110 MB, once)");
-    try { await ensureModel({ modelsDir: paths.models, log: (line) => download.message(`Downloading the embedder · ${line.slice(0, 30)}`) }); download.stop("Embedder ready"); }
-    catch (error) { download.stop(`Embedder not downloaded (${error.message}). Task search uses words until the next setup run`, 2); }
+    const size = Math.round(MODELS.filter((entry) => core.includes(entry.id)).flatMap((entry) => entry.files).reduce((sum, file) => sum + file.size, 0) / 1e6);
+    download.start(`Downloading the local models (about ${size} MB, once)`);
+    // The classifiers run without the model server, so one that cannot start here does not hold them back.
+    const failures = [];
+    for (const step of [() => ensureLlama({ root: localRoot, log: (line) => download.message(`Downloading the local models · ${line.slice(0, 40)}`) }), () => ensureModels({ root: localRoot, ids: core, log: (line) => download.message(`Downloading the local models · ${line.slice(0, 40)}`) })]) {
+      try { await step(); } catch (error) { failures.push(error.message); }
+    }
+    if (failures.length) download.stop(`Local models not ready (${failures.join("; ")}). Agents work as before until the next setup run`, 2);
+    else download.stop("Local models ready");
   }
   const failed = states.filter((state) => selected.includes(state.agent) && state.installed && !state.configured);
   if (failed.length) {
@@ -227,6 +236,55 @@ async function status() {
   }
 }
 
+// The relay's local models: each one's job, licence, size and whether it is here, where they run, what the context engine
+// has indexed, and what the overnight learner last did. `tryharness local learn` starts the learner now; `local add
+// <folder>` and `local remove <folder>` name folders of recordings and screenshots for search_media and briefs.
+async function local() {
+  const root = path.join(paths.home, "local");
+  if (argv[0] === "add" || argv[0] === "remove") {
+    const response = await daemonRequest({ command: `local.${argv[0]}`, folder: path.resolve(argv[1] || process.cwd()) });
+    if (!response?.ok) throw new Error(response?.error || "the daemon did not answer");
+    console.log(argv[0] === "add" ? `Added. The relay reads the recordings and screenshots there in the background${response.downloading ? ", once the image and audio part of the search model has downloaded (555 MB)" : ""}.` : "Removed.");
+    return;
+  }
+  for (const entry of MODELS) {
+    const here = modelsPresent(root, [entry.id]);
+    const mb = Math.round(entry.files.reduce((sum, file) => sum + file.size, 0) / 1e6);
+    console.log(`${here ? "ready  " : "missing"}  ${entry.name} (${entry.tier}, ${entry.licence}, ${mb} MB): ${entry.purpose}`);
+  }
+  let current = null;
+  try { current = await daemonRequest({ command: argv[0] === "learn" ? "local.learn" : "local.status" }); }
+  catch (error) { console.log(`daemon: ${error.message}`); process.exitCode = 1; return; }
+  if (!current?.ok) { console.log(current?.error || "the daemon did not answer"); process.exitCode = 1; return; }
+  if (argv[0] === "learn") { console.log("Learning from your agents' runs now; tryharness local shows the result when it is done."); return; }
+  console.log(`runs on: ${current.device ? (current.device.gpu ? "GPU" : "CPU") : "not checked yet"}`);
+  for (const indexed of current.roots || []) console.log(`indexed: ${indexed.root} (${indexed.files} files)`);
+  if (current.pieces?.waiting) console.log(`waiting to be embedded: ${current.pieces.waiting} pieces`);
+  console.log(current.model ? `ranking: learned ${current.model.trainedAt}, held-out recall at 10 ${JSON.stringify(current.model.heldOut)}` : "ranking: the default until the learner has enough runs");
+  for (const folder of current.media?.folders || []) console.log(`recordings and screenshots: ${folder}`);
+  if (current.media?.folders?.length) console.log(`media files read: ${current.media.files}`);
+  if (current.learning) console.log(`last learning: ${current.learning.at} · ${current.learning.kept ? "kept a new model" : `kept the old one${current.learning.why ? ` (${current.learning.why})` : ""}`}`);
+}
+
+// Watches (watches.mjs): `tryharness watch` lists them and what each last read; `watch add` starts one; agents' suggestions
+// wait for `watch start`.
+async function watch() {
+  const sub = argv[0] || "list";
+  const minutes = (text) => { const found = String(text || "").match(/^(\d+(?:\.\d+)?)\s*(s|m|h)?$/); return found ? Number(found[1]) * ({ s: 1, m: 60, h: 3600 }[found[2] || "m"]) : null; };
+  const response = sub === "add" ? await daemonRequest({ command: "board.watch.add", agent: "user", name: argv[1], watchCommand: arg("--run", ""), folder: path.resolve(arg("--in", process.cwd())),
+    everySeconds: minutes(arg("--every", "5m")) ?? 300, field: arg("--field", undefined), age: arg("--age", undefined), count: arg("--count", undefined), above: arg("--above", undefined), below: arg("--below", undefined) })
+    : sub === "start" || sub === "remove" ? await daemonRequest({ command: `board.watch.${sub}`, agent: "user", id: argv[1] })
+    : await daemonRequest({ command: "board.watch.list", agent: "user" });
+  if (!response?.ok) throw new Error(response?.error || "the daemon did not answer");
+  if (sub === "add") { console.log(`Watching ${response.watch.name} every ${response.watch.everySeconds} s (${response.watch.id}).`); return; }
+  if (sub !== "list") { console.log("Done."); return; }
+  if (!response.watches.length) console.log("No watches. Add one: tryharness watch add \"keeper heartbeat\" --run \"<command>\" --age completedAt --above 900");
+  for (const entry of response.watches) {
+    const last = entry.samples.at(-1);
+    console.log(`${entry.state === "on" ? (entry.off ? "OFF  " : "ok   ") : "asks "} ${entry.name} · every ${entry.everySeconds} s · ${last ? (last.error ? `last check failed: ${last.error}` : `last read ${last.value} (${last.ms} ms)`) : "not checked yet"}${entry.state === "suggested" ? ` · suggested by ${entry.by}: tryharness watch start ${entry.id}` : ""}${entry.off ? ` · ${entry.off.text}` : ""}`);
+  }
+}
+
 async function doctor() {
   console.log(`tryharness ${VERSION}`);
   const config = readJson(paths.config, {});
@@ -341,6 +399,22 @@ async function board() {
     console.log(sub === "send" ? `Sent to ${response.message.recipient}.` : "Discarded.");
     return;
   }
+  // Code an agent elsewhere asked to see (snippets.mjs): list the requests waiting, or share or keep one.
+  if (sub === "snippet") {
+    const [id, choice] = argv.slice(argv.indexOf(sub) + 1);
+    if (!id) {
+      const response = await daemonRequest({ command: "board.snippet.list", agent: "user" });
+      if (!response?.ok) throw new Error(response?.error || "the daemon did not answer");
+      if (!response.snippets.length) { console.log("No agent is waiting to see code."); return; }
+      for (const each of response.snippets) console.log(`${each.id}  ${each.agent} asks to see ${each.path} lines ${each.from} to ${each.to} ("${each.about}")\n${each.text.split("\n").map((line) => `    ${line}`).join("\n")}\n  tryharness board snippet ${each.id} share|keep\n`);
+      return;
+    }
+    if (choice !== "share" && choice !== "keep") throw new Error("usage: tryharness board snippet <id> share|keep");
+    const response = await daemonRequest({ command: "board.snippet.decide", agent: "user", id, share: choice === "share" });
+    if (!response?.ok) throw new Error(response?.error || "the daemon did not answer");
+    console.log(choice === "share" ? "Shared in the thread." : "Kept on this computer.");
+    return;
+  }
   if (sub === "auto" || sub === "end") {
     const id = String(argv[argv.indexOf(sub) + 1] || "");
     const response = sub === "auto"
@@ -356,7 +430,7 @@ async function board() {
     if (!id || !query) throw new Error("usage: tryharness board context <task id> <what you are looking for>");
     const response = await daemonRequest({ command: "board.context.search", agent, id, query, limit: 8 }, 20_000);
     if (!response.ok) throw new Error(response.error || "search failed");
-    const how = response.retrieval === "vectors" ? "meaning" : response.embedder === "absent" ? "words (the embedder is not downloaded yet; run npx tryharness)" : `words (${response.context?.embedded ?? 0} of ${response.context?.total ?? 0} entries embedded so far)`;
+    const how = response.retrieval === "vectors" ? "meaning" : response.embedder === "absent" ? "words (the local models are not downloaded yet; run npx tryharness)" : `words (${response.context?.embedded ?? 0} of ${response.context?.total ?? 0} entries embedded so far)`;
     console.log(`${response.entries.length} result${response.entries.length === 1 ? "" : "s"} by ${how}`);
     for (const entry of response.entries) console.log(`\n[${entry.kind} · ${entry.author}${entry.source ? ` · ${entry.source}` : ""} · ${entry.score}]\n${entry.text.slice(0, 400)}`);
     return;
@@ -622,6 +696,36 @@ async function agents() {
     console.log(response.note ? `Every agent now reads this on ${response.agent}'s card: ${response.note}` : `${response.agent}'s card has no note now.`);
     return;
   }
+  // Each coding agent's models as it lists them, your choice for it, and your words on how Auto picks (models.mjs).
+  if (sub === "models") {
+    const response = await daemonRequest({ command: "board.swarm.models", agent: "user", ...(agent ? { target: agent } : {}), refresh: has("--refresh") });
+    if (!response.ok) throw new Error(response.error);
+    for (const entry of response.agents) {
+      const choice = entry.choice ? (entry.choice.auto ? "Auto" : [entry.choice.model, entry.choice.effort && `effort ${entry.choice.effort}`].filter(Boolean).join(", ")) : `its own settings${entry.ownModel ? ` (${entry.ownModel})` : ""}`;
+      console.log(`${entry.name}: runs on ${choice}`);
+      if (entry.error) console.log(`  its list could not be read: ${entry.error}`);
+      if (agent) for (const model of entry.models) console.log(`  ${model.id}${model.efforts.length ? `  effort ${model.efforts.join(", ")}` : ""}${model.about ? `  ${model.about}` : ""}`);
+      else console.log(`  ${entry.models.length} models; list them with: npx tryharness agents models ${entry.id}`);
+    }
+    console.log(`\nAuto picks by: ${response.routing ?? `${response.defaultRouting} (the default; change it with: npx tryharness agents routing "<your words>")`}`);
+    return;
+  }
+  if (sub === "model") {
+    const model = argv[2];
+    if (!agent || !model) throw new Error("usage: tryharness agents model <agent> <model from its list> [--effort <level>] | auto | default");
+    const response = await daemonRequest({ command: "board.swarm.model", agent: "user", target: agent, model, effort: arg("--effort") });
+    if (!response.ok) throw new Error(response.error);
+    console.log(!response.choice ? `${response.agent} runs on its own settings.` : response.choice.auto ? `Auto picks ${response.agent}'s model for each run.` : `${response.agent} runs on ${response.choice.model}${response.choice.effort ? `, effort ${response.choice.effort}` : ""}.`);
+    return;
+  }
+  if (sub === "routing") {
+    const text = argv.slice(1).filter((word) => word !== "--clear").join(" ").trim();
+    if (!text && !has("--clear")) throw new Error('usage: tryharness agents routing "<how Auto should pick models for your swarm>" | --clear');
+    const response = await daemonRequest({ command: "board.swarm.routing", agent: "user", text: has("--clear") ? "" : text });
+    if (!response.ok) throw new Error(response.error);
+    console.log(`Auto picks by: ${response.routing ?? `${response.defaultRouting} (the default)`}`);
+    return;
+  }
   const ui = createUi(), only = sub === "setup" ? agent || null : null;
   ui.intro(`${pc.bgCyan(pc.black(" tryharness "))}  ${only ? `Setting up ${only}` : "Your swarm"}`);
   await setupSwarm({ runtimeRoot: config.runtimeRoot, states: Object.values(config.agentStates || {}), daemonRequest, ui, only });
@@ -705,13 +809,15 @@ async function t3() {
 }
 
 function help() {
-  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness desktop         open the Harness desktop app (setup opens it too; --no-desktop skips it)\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness task <id> --follow\n                             follow a delegated agent run in this terminal\n  tryharness board [--all]   list open work on the machine's task board\n  tryharness board post --for <agent> --objective <text> [--file <brief.md>]\n  tryharness board show <id>\n  tryharness board post --for codex --objective <text> --run --workspace <dir>\n                             the daemon runs it and reports back on the task\n  tryharness board run <id>  authorize a run an agent asked for\n  tryharness board release <id>\n  tryharness board agents    when each agent last read the board\n  tryharness board --watch   follow the board in this terminal\n  tryharness notify on|off   desktop notifications for what waits on you\n  tryharness board send <task> <message>   send a held reply to another person's agent\n  tryharness board auto <task> on|off      auto-send replies on that thread\n  tryharness board end <task> --outcome <text>\n  tryharness board context <task> <query>  search everything written about a task\n  tryharness goal set --objective <text> [--team a,b] [--workspace <dir>]   a goal your agents work together in one room\n  tryharness goal [list | show <id> | stop <id> | resume <id>]\n  tryharness room <goal> | room post <goal> <text> [--ask agent,agent]\n  tryharness swarm rounds [<thread>]   what the coordinator saw, chose and cost each round\n  tryharness swarm coordinator [harness|local]   who coordinates your threads\n  tryharness connect <handle/agent> --about <text>   ask another person's agent to work an issue with yours, sealed to their computer\n  tryharness peers           the keys of other people's computers this one has worked with, to compare\n  tryharness agents          how Harness wakes each of your agents, and set up the rest\n  tryharness agents setup <agent> | agents test <agent>\n  tryharness agents cards     what each of your agents is told about the others\n  tryharness agents note <agent> <text> [--clear]   your own note on an agent's card, told to every other agent\n  tryharness mcp grok-bot    print the MCP snippet that puts Grok Bot on the board\n  tryharness link            connect the browser you use Harness in to this computer, end to end (--print shows the link)\n  tryharness phone pair      show a QR code that pairs your phone with this computer\n  tryharness phone list | revoke <id>\n  tryharness t3              approve Harness in T3 Code once, so your messages go into its threads (t3 status | t3 forget)\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
+  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness desktop         open the Harness desktop app (setup opens it too; --no-desktop skips it)\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness local [learn]   the relay's local models, where they run, what is indexed and the last learning\n  tryharness local add|remove <folder>   a folder of recordings and screenshots agents can search by what was said or shown\n  tryharness watch [add <name> --run <command> [--every 5m] [--field f | --age f | --count text] [--above n] [--below n] | start <id> | remove <id>]\n                             watches the relay checks and says out loud only when they are off\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness task <id> --follow\n                             follow a delegated agent run in this terminal\n  tryharness board [--all]   list open work on the machine's task board\n  tryharness board post --for <agent> --objective <text> [--file <brief.md>]\n  tryharness board show <id>\n  tryharness board post --for codex --objective <text> --run --workspace <dir>\n                             the daemon runs it and reports back on the task\n  tryharness board run <id>  authorize a run an agent asked for\n  tryharness board release <id>\n  tryharness board agents    when each agent last read the board\n  tryharness board --watch   follow the board in this terminal\n  tryharness notify on|off   desktop notifications for what waits on you\n  tryharness board send <task> <message>   send a held reply to another person's agent\n  tryharness board snippet [<id> share|keep]   code an agent elsewhere asked to see; nothing leaves until you share it\n  tryharness board auto <task> on|off      auto-send replies on that thread\n  tryharness board end <task> --outcome <text>\n  tryharness board context <task> <query>  search everything written about a task\n  tryharness goal set --objective <text> [--team a,b] [--workspace <dir>]   a goal your agents work together in one room\n  tryharness goal [list | show <id> | stop <id> | resume <id>]\n  tryharness room <goal> | room post <goal> <text> [--ask agent,agent]\n  tryharness swarm rounds [<thread>]   what the coordinator saw, chose and cost each round\n  tryharness swarm coordinator [harness|local]   who coordinates your threads\n  tryharness connect <handle/agent> --about <text>   ask another person's agent to work an issue with yours, sealed to their computer\n  tryharness peers           the keys of other people's computers this one has worked with, to compare\n  tryharness agents          how Harness wakes each of your agents, and set up the rest\n  tryharness agents setup <agent> | agents test <agent>\n  tryharness agents cards     what each of your agents is told about the others\n  tryharness agents note <agent> <text> [--clear]   your own note on an agent's card, told to every other agent\n  tryharness agents models [<agent>] [--refresh]   the models each coding agent lists and the one it runs on\n  tryharness agents model <agent> <model> [--effort <level>] | auto | default   the model it runs on; auto lets Harness pick per run\n  tryharness agents routing "<text>" [--clear]   how Auto picks models for your swarm\n  tryharness mcp grok-bot    print the MCP snippet that puts Grok Bot on the board\n  tryharness link            connect the browser you use Harness in to this computer, end to end (--print shows the link)\n  tryharness phone pair      show a QR code that pairs your phone with this computer\n  tryharness phone list | revoke <id>\n  tryharness t3              approve Harness in T3 Code once, so your messages go into its threads (t3 status | t3 forget)\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
 }
 
 try {
   if (command === "setup" || (command === "connect" && (!argv[0] || argv[0].startsWith("-")))) await connect();
   else if (command === "status" || command === "bridge") await status();
   else if (command === "doctor") await doctor();
+  else if (command === "local") await local();
+  else if (command === "watch") await watch();
   else if (command === "sync" || command === "backfill" || command === "drain") await sync();
   else if (command === "task") await task();
   else if (command === "board") await board();

package/lib/adapters.mjs

@@ -3,7 +3,6 @@ import os from "node:os";
 import path from "node:path";
 import { detectAgents, run } from "./commands.mjs";
 import { ensureDir, readJson } from "./files.mjs";
-import { paths } from "./paths.mjs";
 import { MACHINE_RUNNERS } from "./members.mjs";
 
 export const AGENTS = MACHINE_RUNNERS;
@@ -37,9 +36,12 @@ export function mcpClientSnippet({ runtimeRoot, client, nodePath = process.execP
   return { mcpServers: { harness: { command: nodePath, args: [path.join(runtimeRoot, "lib", "mcp-stdio.mjs"), "--agent", client] } } };
 }
 
-function installAsset(source, target) {
+// An extension or plugin runs inside its agent and starts Harness from the runtime and Node setup used, as the hooks
+// and MCP entries written here do.
+function installAsset(source, target, { runtimeRoot, nodePath = process.execPath }) {
   ensureDir(path.dirname(target));
-  fs.copyFileSync(source, target);
+  const text = fs.readFileSync(source, "utf8").replaceAll('"__HARNESS_RUNTIME__"', JSON.stringify(runtimeRoot)).replaceAll('"__HARNESS_NODE__"', JSON.stringify(nodePath));
+  fs.writeFileSync(target, text, { mode: 0o600 });
   try { fs.chmodSync(target, 0o600); } catch {}
 }
 
@@ -123,7 +125,7 @@ export function removeClaudeSessionHook(homeDir = os.homedir()) {
   fs.writeFileSync(file, JSON.stringify({ ...settings, hooks }, null, 2) + "\n");
 }
 
-export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.homedir(), detected = detectAgents(), execute = run, connection = readJson(paths.config, {}) }) {
+export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.homedir(), detected = detectAgents(), execute = run }) {
   const byAgent = new Map(detected.map((entry) => [entry.agent, entry]));
   const mcpPath = path.join(runtimeRoot, "lib", "mcp-stdio.mjs");
   const assets = integrationAssets(homeDir);
@@ -151,14 +153,13 @@ export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.h
       try { installCodexHooks({ runtimeRoot, homeDir }); } catch { hooked = false; }
       states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? (hooked ? "MCP and session hooks configured; in Codex run /hooks once to trust them" : "MCP configured; the session hooks could not be written") : diagnostic(added) });
     } else if (agent === "pi") {
-      installAsset(path.join(runtimeRoot, "assets", "pi-extension.ts"), assets.pi);
+      // pi has no MCP client: the extension starts the same stdio server and gives pi its tools.
+      installAsset(path.join(runtimeRoot, "assets", "pi-extension.ts"), assets.pi, { runtimeRoot });
       states.push({ agent, installed: true, configured: fs.existsSync(assets.pi), detail: "extension installed" });
     } else {
-      installAsset(path.join(runtimeRoot, "assets", "opencode-plugin.js"), assets.opencode);
-      // Keep opencode's already-working remote MCP configuration. The daemon/plugin path
-      // handles history; this command supplies Harness memory tools.
-      execute(found.path, ["mcp", "remove", "harness"]);
-      const added = execute(found.path, ["mcp", "add", "harness", "--url", String(connection.origin).replace(/\/$/, "") + "/api/mcp", "--header", "Authorization=Bearer " + connection.token]);
+      installAsset(path.join(runtimeRoot, "assets", "opencode-plugin.js"), assets.opencode, { runtimeRoot });
+      // The same stdio server as Claude Code and Codex. opencode has no `mcp remove`; `mcp add` replaces the entry.
+      const added = execute(found.path, ["mcp", "add", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
       states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP and plugin configured" : `plugin installed; MCP: ${diagnostic(added)}` });
     }
   }
@@ -174,7 +175,14 @@ export function removeAgentConfigurations({ homeDir = os.homedir(), detected = d
     if (!found.path) continue;
     if (found.agent === "claude-code") { execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]); removeClaudeSessionHook(homeDir); }
     else if (found.agent === "codex") { execute(found.path, ["mcp", "remove", "harness"]); removeCodexHooks(homeDir); }
-    else if (found.agent === "opencode") execute(found.path, ["mcp", "remove", "harness"]);
+  }
+  // opencode has no `mcp remove`, so its entry comes out of the config file `mcp add` wrote it to.
+  for (const name of ["opencode.json", "opencode.jsonc"]) {
+    const file = path.join(homeDir, ".config", "opencode", name);
+    const config = readJson(file, null);
+    if (!config?.mcp?.harness) continue;
+    delete config.mcp.harness;
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
   }
   const assets = integrationAssets(homeDir);
   for (const target of Object.values(assets)) {

package/lib/agentnode.mjs

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+// The Node an agent runs on. Some agents are Node programs with a minimum of their own (Pi 0.87.1 needs 22.19), while
+// Harness runs on whichever Node set it up and a person's default may be older. An agent that would not start on the
+// Node first on its PATH runs on the newest Node on this computer that it accepts, from wherever people install Node;
+// with none, its run says what to install instead of failing inside the agent. Native agents are left as they are.
+
+const WINDOWS = process.platform === "win32";
+
+/** The executable a command name runs on this PATH. */
+export function onPath(command, envPath = process.env.PATH || "") {
+  for (const dir of String(envPath).split(path.delimiter).filter(Boolean)) {
+    for (const name of WINDOWS ? [`${command}.exe`, `${command}.cmd`, command] : [command]) {
+      const file = path.join(dir, name);
+      try { if (fs.statSync(file).isFile()) { fs.accessSync(file, fs.constants.X_OK); return file; } } catch {}
+    }
+  }
+  return null;
+}
+
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
+const real = (file) => { try { return fs.realpathSync(file); } catch { return file; } };
+
+/** Whether a file is a script Node runs (`#!/usr/bin/env node`), not a native program. */
+function nodeScript(file) {
+  let head = "";
+  try { const fd = fs.openSync(file, "r"); const buffer = Buffer.alloc(200); fs.readSync(fd, buffer, 0, 200, 0); fs.closeSync(fd); head = buffer.toString("utf8"); } catch { return false; }
+  return head.startsWith("#!") && /\bnode\b/.test(head.split("\n")[0]);
+}
+
+/** A managed install's launcher (Pi's: <dir>/bin/<command> runs <dir>/install/releases/<current-version>/node_modules/.bin/<command>). */
+function managedEntry(launcher, command) {
+  const dir = path.dirname(path.dirname(launcher));
+  let version = "";
+  try { version = fs.readFileSync(path.join(dir, "install", "current-version"), "utf8").trim(); } catch { return null; }
+  if (!/^[\w.+-]+$/.test(version)) return null;
+  const entry = path.join(dir, "install", "releases", version, "node_modules", ".bin", command);
+  return fs.existsSync(entry) ? real(entry) : null;
+}
+
+/** The Node range an agent's own package asks for (its engines.node); null for a native program or one that says none. */
+export function nodeRange(command, envPath = process.env.PATH || "") {
+  const found = onPath(command, envPath);
+  if (!found) return null;
+  const entry = managedEntry(real(found), command) ?? real(found);
+  if (!nodeScript(entry)) return null;
+  for (let dir = path.dirname(entry); ; dir = path.dirname(dir)) {
+    const pkg = readJson(path.join(dir, "package.json"));
+    if (pkg?.name) return typeof pkg.engines?.node === "string" && pkg.engines.node.trim() ? pkg.engines.node.trim() : null;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+// ── Versions and ranges (the forms package.json engines use) ─────────────────
+
+const parse = (text) => { const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(text).trim()); return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null; };
+const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+/** One comparator (">=22.19.0", "^20", "~18.2", "22.x", "<23"); one it does not understand holds nothing back. */
+function holds(version, comparator) {
+  if (["", "*", "x", "X"].includes(comparator)) return true;
+  const m = /^(>=|<=|>|<|=|\^|~)?v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?$/.exec(comparator);
+  if (!m) return true;
+  const [, op = "", major, minor, patch] = m;
+  const part = (value) => (value === undefined || /^[xX*]$/.test(value) ? null : Number(value));
+  const low = [Number(major), part(minor) ?? 0, part(patch) ?? 0];
+  // The first version past a partial one: "22" ends before 23.0.0, "22.4" before 22.5.0.
+  const past = part(minor) === null ? [low[0] + 1, 0, 0] : part(patch) === null ? [low[0], low[1] + 1, 0] : [low[0], low[1], low[2] + 1];
+  const at = compare(version, low);
+  if (op === ">=") return at >= 0;
+  if (op === ">") return compare(version, past) >= 0;
+  if (op === "<") return at < 0;
+  if (op === "<=") return compare(version, past) < 0;
+  if (op === "^") return at >= 0 && compare(version, low[0] > 0 ? [low[0] + 1, 0, 0] : low[1] > 0 ? [0, low[1] + 1, 0] : [0, 0, low[2] + 1]) < 0;
+  if (op === "~") return at >= 0 && compare(version, part(minor) === null ? [low[0] + 1, 0, 0] : [low[0], low[1] + 1, 0]) < 0;
+  return at >= 0 && compare(version, past) < 0;
+}
+
+/** Whether a Node version is in an engines range ("a || b", comparators by space, "1.2.3 - 2.3.4"). */
+export function satisfies(version, range) {
+  const parsed = parse(version);
+  if (!parsed) return false;
+  return String(range).split("||").some((alternative) => {
+    const hyphen = /^\s*(\S+)\s+-\s+(\S+)\s*$/.exec(alternative);
+    const comparators = hyphen ? [`>=${hyphen[1]}`, `<=${hyphen[2]}`] : alternative.trim().split(/\s+/).filter(Boolean);
+    return comparators.every((comparator) => holds(parsed, comparator));
+  });
+}
+
+// ── The Nodes on this computer ───────────────────────────────────────────────
+
+const versions = new Map();
+/** A Node's version, asked once per file. */
+function versionOf(node) {
+  if (!versions.has(node)) {
+    const said = spawnSync(node, ["-v"], { encoding: "utf8", timeout: 5_000 });
+    versions.set(node, said.status === 0 && parse(said.stdout) ? said.stdout.trim() : null);
+  }
+  return versions.get(node);
+}
+
+/** Every Node installed where people put them: version managers, Homebrew, the system's, the one Harness runs on. */
+export function installedNodes(envPath = process.env.PATH || "") {
+  const home = os.homedir();
+  const bin = (dir) => (WINDOWS ? [path.join(dir, "node.exe")] : [path.join(dir, "bin", "node"), path.join(dir, "installation", "bin", "node")]);
+  const managers = [
+    process.env.NVM_DIR ? path.join(process.env.NVM_DIR, "versions", "node") : path.join(home, ".nvm", "versions", "node"),
+    path.join(process.env.FNM_DIR || path.join(home, ".local", "share", "fnm"), "node-versions"),
+    path.join(home, "Library", "Application Support", "fnm", "node-versions"),
+    path.join(process.env.VOLTA_HOME || path.join(home, ".volta"), "tools", "image", "node"),
+    path.join(process.env.ASDF_DATA_DIR || path.join(home, ".asdf"), "installs", "nodejs"),
+    path.join(home, ".local", "share", "mise", "installs", "node"),
+    path.join(process.env.N_PREFIX || "/usr/local", "n", "versions", "node"),
+    ...(process.env.NVM_HOME ? [process.env.NVM_HOME] : []),
+    ...(process.env.APPDATA ? [path.join(process.env.APPDATA, "nvm")] : []),
+  ];
+  const found = [process.execPath, onPath("node", envPath)];
+  for (const dir of managers) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    for (const entry of entries) found.push(...bin(path.join(dir, entry)));
+  }
+  for (const brew of ["/opt/homebrew/opt", "/usr/local/opt"]) {
+    let entries = [];
+    try { entries = fs.readdirSync(brew).filter((name) => /^node(@\d+)?$/.test(name)); } catch {}
+    for (const entry of entries) found.push(path.join(brew, entry, "bin", "node"));
+  }
+  found.push(...(WINDOWS ? [path.join(process.env.ProgramFiles || "C:\\Program Files", "nodejs", "node.exe")] : ["/opt/homebrew/bin/node", "/usr/local/bin/node", "/usr/bin/node"]));
+  const seen = new Set();
+  return found.filter((node) => node && fs.existsSync(node) && !seen.has(real(node)) && seen.add(real(node)))
+    .map((node) => ({ node, version: versionOf(node) })).filter((entry) => entry.version);
+}
+
+/**
+ * The environment an agent runs in: as given, unless it is a Node program whose range the Node first on the PATH misses;
+ * then the newest installed Node in its range leads the PATH. `bin` is the folder of a Node in its range (for a session
+ * resumed in the person's own shell, whatever their default), `error` when there is none, in the person's words.
+ */
+export function agentEnvironment(command, env = process.env) {
+  const range = nodeRange(command, env.PATH);
+  if (!range) return { env };
+  const current = onPath("node", env.PATH);
+  const have = current ? versionOf(current) : null;
+  if (have && satisfies(have, range)) return { env, bin: path.dirname(current) };
+  const fits = installedNodes(env.PATH).filter((entry) => satisfies(entry.version, range))
+    .sort((a, b) => compare(parse(b.version), parse(a.version)))[0];
+  if (!fits) {
+    return { env, error: `${command} needs Node ${range}, and this computer has ${have ? `Node ${have.replace(/^v/, "")}` : "no Node"} and no other in that range. Install one (for example: nvm install 22), then ask again.` };
+  }
+  return { env: { ...env, PATH: [path.dirname(fits.node), env.PATH || ""].join(path.delimiter) }, bin: path.dirname(fits.node), node: fits.version };
+}