hilos-agent 0.11.14 → 0.11.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.14",
+  "version": "0.11.15",
   "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -6,8 +6,86 @@
 // logs a periodic "still working…" heartbeat so the run visibly stays alive.
 
 import { spawn } from "node:child_process";
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import { delimiter, extname, isAbsolute, join } from "node:path";
 import { truncate } from "./util.mjs";
 
+/**
+ * Where a bare command name resolves on this machine, or null when it is not
+ * on PATH. On Windows npm installs every CLI (`claude`, `codex`,
+ * `cursor-agent`) as a `.cmd` shim, and `PATHEXT` is what cmd.exe consults to
+ * find it; Node's spawn consults nothing, so `spawn("claude")` answers ENOENT
+ * on a machine where `claude` works in every terminal (1330). Used both by the
+ * spawn below and by the daemon's startup check.
+ * @param {string} cmd
+ * @param {{ env?: Record<string, string | undefined>, platform?: string, cwd?: string }} [opts]
+ * @returns {string | null}
+ */
+export function resolveCommand(cmd, { env = process.env, platform = process.platform, cwd } = {}) {
+  if (!cmd) return null;
+  const win = platform === "win32";
+  const runnable = (file) => {
+    try {
+      if (!statSync(file).isFile()) return false;
+      if (!win) accessSync(file, fsConstants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const exts = win
+    ? [...new Set(["", ...String(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.toLowerCase())])]
+    : [""];
+  const withExt = (base) => {
+    for (const ext of exts) {
+      // "claude" → claude.cmd, but "claude.cmd" stays as written.
+      if (ext && extname(base).toLowerCase() === ext) continue;
+      if (runnable(base + ext)) return base + ext;
+    }
+    return null;
+  };
+  if (isAbsolute(cmd) || /[\\/]/.test(cmd)) return withExt(cwd && !isAbsolute(cmd) ? join(cwd, cmd) : cmd);
+  for (const entry of String(env.PATH || env.Path || "").split(win ? ";" : delimiter)) {
+    if (!entry) continue;
+    const hit = withExt(join(entry.replace(/^"|"$/g, ""), cmd));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+// cmd.exe reads the whole command line back as text, so a `.cmd` shim has to be
+// launched through ComSpec with every argument re-quoted for that parser. This
+// is the same escaping cross-spawn ships (double quotes around the argument,
+// backslashes doubled before a quote, quotes escaped, cmd metacharacters
+// caret-escaped). Executables (`.exe`) keep the plain spawn.
+function cmdShellQuote(arg) {
+  let s = String(arg);
+  s = s.replace(/(\\*)"/g, '$1$1\\"');
+  s = s.replace(/(\\*)$/, "$1$1");
+  s = `"${s}"`;
+  return s.replace(/[()\][%!^"`<>&|;, *?]/g, "^$&");
+}
+
+/**
+ * The spawn plan for `cmd args`: the file to execute and the argv to pass.
+ * On Windows a `.cmd`/`.bat` shim goes through ComSpec; everything else is
+ * spawned as written (Node resolves `.exe` itself).
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ env?: Record<string, string | undefined>, platform?: string, cwd?: string }} [opts]
+ * @returns {{ file: string, args: string[], windowsVerbatimArguments?: boolean }}
+ */
+export function spawnPlan(cmd, args, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  if (platform !== "win32") return { file: cmd, args };
+  const resolved = resolveCommand(cmd, opts) || cmd;
+  const ext = extname(resolved).toLowerCase();
+  if (ext !== ".cmd" && ext !== ".bat") return { file: resolved, args };
+  const comspec = (opts.env ?? process.env).ComSpec || "cmd.exe";
+  const line = [resolved, ...args].map(cmdShellQuote).join(" ");
+  return { file: comspec, args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true };
+}
+
 /**
  * Let the daemon finish its existing abort/cleanup path before exiting.
  * @param {(signal: AbortSignal) => Promise<any>} task
@@ -279,11 +357,14 @@ async function runCliOnce(opts) {
       // from stdin…"). Nothing we spawn is ever fed via stdin.
       // Always strip hilos's own token from the child's env (see scrubHilosEnv),
       // and keep PWD honest about the directory we run in (see envForCwd).
-      child = spawn(cmd, args, {
+      const childEnv = envForCwd(scrubHilosEnv(env || process.env), cwd);
+      const plan = spawnPlan(cmd, args, { env: childEnv, cwd });
+      child = spawn(plan.file, plan.args, {
         cwd,
         detached: true,
         stdio: ["ignore", "pipe", "pipe"],
-        env: envForCwd(scrubHilosEnv(env || process.env), cwd),
+        env: childEnv,
+        ...(plan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
       });
     } catch (error) {
       resolve({ status: null, stdout: "", stderr: "", error });

package/src/iterate-claim-recovery.mjs

@@ -138,10 +138,23 @@ export function defaultProcessInstanceIdentity(
   }
 }
 
+// A directory fsync only hardens the rename/link against power loss; it never
+// decides who owns the seat. Windows refuses FlushFileBuffers on a directory
+// handle (EPERM), and some filesystems answer EINVAL or EBADF. Before 1330 that
+// throw was caught by acquireLock's publish step and reported as "another
+// local daemon already owns this agent", so every Windows daemon refused to
+// start against an empty lock directory.
 function syncDirectory(fs, path) {
-  const fd = fs.openSync(path, "r");
+  let fd;
+  try {
+    fd = fs.openSync(path, "r");
+  } catch {
+    return;
+  }
   try {
     fs.fsyncSync(fd);
+  } catch {
+    /* durability nicety only; the link/unlink already happened */
   } finally {
     fs.closeSync(fd);
   }
@@ -178,6 +191,10 @@ export function createIterateClaimRecoveryStore({
   const processInstanceIdentity = getProcessInstanceIdentity(pid);
   let lockHeld = false;
   let heldElectionPath = null;
+  // Why the last acquireLock() returned false: "contended" when a live daemon
+  // holds the seat, otherwise the filesystem error. run.mjs turns this into
+  // an honest startup message (1330).
+  let lastAcquireFailure = null;
 
   function ensureScope() {
     fs.mkdirSync(scopeDir, { recursive: true, mode: 0o700 });
@@ -360,9 +377,11 @@ export function createIterateClaimRecoveryStore({
     acquireLock() {
       if (lockHeld) return true;
       if (!ownerKey || !processInstanceIdentity) return false;
+      lastAcquireFailure = null;
       try {
         ensureScope();
       } catch (error) {
+        lastAcquireFailure = `lock directory unavailable (${scopeDir}): ${error?.message || error}`;
         log?.error?.(`iterate claim scope unavailable: ${error?.message || error}`);
         return false;
       }
@@ -392,12 +411,14 @@ export function createIterateClaimRecoveryStore({
           }
         }
         removeOwnCandidate();
+        lastAcquireFailure = `lock file not written (${scopeDir}): ${error?.message || error}`;
         log?.error?.(`iterate claim scope not locked: ${error?.message || error}`);
         return false;
       }
 
       if (!acquireElection()) {
         removeOwnCandidate();
+        lastAcquireFailure = "contended";
         return false;
       }
 
@@ -408,6 +429,7 @@ export function createIterateClaimRecoveryStore({
           .filter((name) => name.startsWith(".owner.") && name.endsWith(".lock"));
       } catch (error) {
         removeOwnPublishedLock();
+        lastAcquireFailure = `lock directory not readable (${scopeDir}): ${error?.message || error}`;
         log?.error?.(`iterate claim scope not inspected: ${error?.message || error}`);
         return false;
       }
@@ -440,6 +462,7 @@ export function createIterateClaimRecoveryStore({
 
       if (!ownSeen || liveContender) {
         removeOwnPublishedLock();
+        lastAcquireFailure = "contended";
         return false;
       }
 
@@ -460,6 +483,11 @@ export function createIterateClaimRecoveryStore({
       return true;
     },
 
+    /** Why the last acquireLock() failed: "contended" or a filesystem reason. */
+    acquireFailure() {
+      return lastAcquireFailure;
+    },
+
     releaseLock() {
       if (!ownsPublishedLock()) return false;
       if (!removeOwnPublishedLock()) {

package/src/run.mjs

@@ -15,6 +15,7 @@ import { startWake, createWakeGate } from "./wake.mjs";
 import { scanReplyBridge, handleReplyBridgeJob } from "./reply-bridge.mjs";
 import { detectVendor, fastChatCmd, webCapability } from "./progress-emitter.mjs";
 import { commandArgv } from "./argv.mjs";
+import { resolveCommand } from "./cli.mjs";
 import {
   createIterateClaimRecoveryStore,
   reconcileDaemonIterateClaims,
@@ -31,6 +32,15 @@ const HILOS_DAEMON_TOOLS = Object.freeze({
   decisionWaitMs: 20_000,
 });
 
+/** Where to get the vendor CLI a daemon command names (1330). */
+function installHint(vendor) {
+  if (vendor === "cursor") return "the Cursor CLI is separate from the Cursor app (macOS/Linux: curl https://cursor.com/install -fsS | bash; Windows: irm https://cursor.com/install -useb | iex)";
+  if (vendor === "claude_code") return "npm install -g @anthropic-ai/claude-code";
+  if (vendor === "codex") return "npm install -g @openai/codex";
+  if (vendor === "opencode") return "https://opencode.ai";
+  return "";
+}
+
 /**
  * The poll loop. Embeddable: pass a `signal` to stop it cleanly (interrupts the
  * inter-poll sleep, cancels the active job, then resolves) and an `onEvent`
@@ -188,6 +198,19 @@ export async function run(
     enabled: cfg.webSearch !== false,
     args: commandArgv(cfg.codingCmd).slice(1),
   });
+  // 1330 — say at startup, not at the first mention, when the CLI this daemon
+  // is configured to drive is not installed. A person who connected through an
+  // IDE agent read "Hilo is connected and online" and then got "(my chat
+  // command `cursor-agent …` isn't installed or on PATH.)" in the room.
+  for (const [role, command] of [["chat", chatCommand], ["code", cfg.codingCmd]]) {
+    const bin = commandArgv(command)[0];
+    if (!bin || resolveCommand(bin)) continue;
+    const hint = installHint(detectVendor(command));
+    log.error(
+      `${role} command not found: \`${bin}\` is not installed or not on PATH${hint ? ` — ${hint}` : ""}. Mentions will fail until it is.`,
+    );
+    emit({ type: "status", text: `${role} command missing: ${bin}` });
+  }
   log.log(
     chatVendor === codingVendor && web.status === codingWeb.status
       ? `web: ${web.status} — ${web.source}`
@@ -218,7 +241,12 @@ export async function run(
       log,
     });
     if (!iterateClaimRecoveryStore.acquireLock()) {
-      throw new Error("Another local daemon already owns this agent and server connection.");
+      const why = iterateClaimRecoveryStore.acquireFailure?.();
+      throw new Error(
+        why && why !== "contended"
+          ? `The local run lock could not be taken: ${why}. Make that directory writable and start again.`
+          : "Another local daemon already owns this agent and server connection.",
+      );
     }
     reconcileClaimsOnce = async (context) => {
       try {