hilos-agent 0.11.14 → 0.11.16

package/README.md

@@ -28,6 +28,11 @@ after you Approve.
 
 ## Quick start
 
+Run `npx hilos-agent@latest doctor` first if you already have a saved config.
+For a new connection, use `npx hilos-agent@latest doctor --join-stdin` with the
+private join code and the same command settings you will use to run the daemon.
+Read the JSON and resolve each failed check before starting it.
+
 In hilos: open your agent's profile → **Connect agent** → **Run in channel**. Copy the
 terminal command and run it from inside your repo's folder. It waits at a hidden
 prompt; copy the private join code from Hilos and paste it there. The daemon
@@ -36,12 +41,29 @@ credential never enters shell history or the process list:
 
 ```sh
 cd ~/code/your-repo
+npx hilos-agent@latest doctor --join-stdin  # check setup with the private join code
 npx hilos-agent@latest --join-stdin  # then paste the private join code when asked
 ```
 
 Previously copied `--join <blob>` commands remain compatible. New commands use
 stdin because the blob contains the agent token and should not live in argv.
 
+The daemon prints `log: <path>` when it starts. Its local diagnostic log lives
+at `~/.hilos/logs/<handle>.log`, with one previous file at `<handle>.log.1`.
+Each file is capped at 2 MB, private to your user, and redacted for
+credential-shaped text. Before identity discovery, the name is `agent-<pid>`;
+those startup lines move to the handle's log after connection. The final
+`exit:` line records a signal, authentication stop, fatal error with its stack,
+or normal shutdown. A forced kill or power loss cannot write an exit line.
+An IDE agent can read these files when diagnosing a daemon that went quiet.
+
+After three minutes without a daemon heartbeat, hilos posts one notice in the
+last room that mentioned the agent (falling back to its latest run's room).
+The notice names who can restart it with the same join code. For hilos-hosted
+agents, it also explains that hosted mentions use workspace credits until the
+daemon returns. The owner gets the existing quick-connect card; everyone in
+the room can read the notice.
+
 Running from elsewhere, or want to map several repos explicitly? Save this as
 `~/.hilos/agent.json` (or `./hilos-agent.json`). The file is strict JSON, so it
 cannot contain comments:
@@ -485,7 +507,20 @@ arguments can be visible to other processes on the machine, so use
 Likewise, prefer `--join-stdin` over the legacy `--join <blob>` form for a new
 connection.
 
-See `hilos-agent --help` for the `init`, `webmcp`, `web doctor`, and `hooks`
+`hilos-agent doctor` checks Node against the package's minimum version, both
+configured CLIs, native web configuration, the hilos connection, the local seat
+lock, and the config file and working folder. It returns JSON and exits with
+code 1 if any check fails; add `--human` for one readable line per check. It
+accepts the same join code, `--config`, and command overrides as the daemon.
+Missing CLI checks include an install hint. The Cursor CLI (`cursor-agent`)
+is installed separately from the Cursor app. The lock is released immediately
+after the check; `contended` means another daemon holds that seat.
+
+Keep the daemon in a separate terminal or a detached process that survives
+your IDE agent's tool call. Confirm `watching: @-mentions` before calling it
+online. The `hilos-connect` skill walks IDE agents through this setup.
+
+See `hilos-agent --help` for the `doctor`, `init`, `webmcp`, `web doctor`, and `hooks`
 subcommands.
 
 Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`,

package/bin/hilos-agent.mjs

@@ -19,7 +19,6 @@
 // codingCmd in hilos-agent.json to change it and the daemon picks it up on its
 // next poll — no restart needed.
 
-import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
@@ -28,9 +27,10 @@ import { readPrivateJoin } from "../src/join-input.mjs";
 import { run } from "../src/run.mjs";
 import { hookMain, hooksMain } from "../src/hook.mjs";
 import { runWebMcpCommand } from "../src/webmcp-bridge.mjs";
-import { detectVendor, fastChatCmd, webCapability } from "../src/progress-emitter.mjs";
-import { commandArgv } from "../src/argv.mjs";
+import { doctor, humanDoctor } from "../src/doctor.mjs";
+import { webDoctor } from "../src/web-doctor.mjs";
 import { runWithTerminalSignals } from "../src/cli.mjs";
+import { createDaemonLog } from "../src/daemon-log.mjs";
 
 // 1251 — the plugin writes `hook --claude --personal`, so the client flags name
 // the vendor for `hook` the same way they choose a target for `hooks install`.
@@ -54,13 +54,13 @@ function requiredOptionValue(argv, index, option) {
 }
 
 function validateCommand(cmd, positional, { skipShape = false } = {}) {
-  const commands = new Set(["run", "init", "hook", "hooks", "webmcp", "web", "help", "version"]);
+  const commands = new Set(["run", "init", "doctor", "hook", "hooks", "webmcp", "web", "help", "version"]);
   if (!commands.has(cmd)) {
     throw new Error(`Unknown command: ${cmd}. Try \`hilos-agent --help\`.`);
   }
   if (skipShape) return;
 
-  if (["run", "init", "hook", "help", "version"].includes(cmd) && positional.length > 1) {
+  if (["run", "init", "doctor", "hook", "help", "version"].includes(cmd) && positional.length > 1) {
     throw new Error(`Unexpected argument for ${cmd}: ${positional[1]}. Try \`hilos-agent --help\`.`);
   }
 
@@ -110,6 +110,9 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === "--join") flags.join = requiredOptionValue(argv, i++, a);
     else if (a === "--join-stdin") flags.joinStdin = true;
+    else if (a === "--human") flags.human = true;
+    // Internal test seam: probe a temporary lock root, never a real seat.
+    else if (a === "--lock-dir") flags.lockDir = requiredOptionValue(argv, i++, a);
     else if (a === "--config") flags.config = requiredOptionValue(argv, i++, a);
     else if (a === "--channel") flags.channelId = requiredOptionValue(argv, i++, a);
     else if (a === "--url") flags.url = requiredOptionValue(argv, i++, a);
@@ -151,6 +154,7 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent --join <blob>      legacy argv-compatible connect link
   hilos-agent --join-stdin       paste the private link at a no-echo prompt
   hilos-agent init               write a starter config to ~/.hilos/agent.json
+  hilos-agent doctor             check Node, CLIs, web, connection, lock and config
   hilos-agent webmcp doctor      verify the local WebMCP browser bridge
   hilos-agent webmcp login <url> open the isolated profile for person sign-in
   hilos-agent webmcp open <url>  open a person-allowlisted site for an agent
@@ -173,6 +177,7 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent hooks print        preview the hook configuration without writing
 
 Options:
+  --human            print doctor checks as a readable table (default: JSON)
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
   --url <endpoint>   override the MCP endpoint (or use HILOS_URL/config)
@@ -262,6 +267,15 @@ async function main() {
     return;
   }
 
+  if (cmd === "doctor") {
+    const { join: _join, joinStdin: _joinStdin, help: _help, human, lockDir, ...cliFlags } = flags;
+    const cfg = resolveConfig({ flags: cliFlags, join: joinPayload });
+    const result = await doctor(cfg, { lockDir });
+    console.log(human ? humanDoctor(result) : JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
   if (cmd === "webmcp") {
     const cliFlags = { ...flags };
     delete cliFlags.help;
@@ -281,35 +295,9 @@ async function main() {
     const cliFlags = { ...flags };
     delete cliFlags.help;
     const cfg = resolveConfig({ flags: cliFlags });
-    const codingCommand = cfg.codingCmd;
-    const chatCommand = cfg.chatCmd || fastChatCmd(detectVendor(codingCommand)) || codingCommand;
-    const describe = (command) => {
-      const argv = commandArgv(command);
-      const vendor = detectVendor(command);
-      const capability = webCapability(vendor, {
-        enabled: cfg.webSearch !== false,
-        args: argv.slice(1),
-      });
-      const binary = argv[0] || "";
-      const probed = binary
-        ? spawnSync(binary, ["--version"], { encoding: "utf8", timeout: 5_000 })
-        : null;
-      const binaryAvailable = Boolean(binary) && !probed?.error;
-      const version = String(probed?.stdout || probed?.stderr || "").trim().split("\n")[0] || null;
-      return { vendor, binary, binaryAvailable, version, command, ...capability };
-    };
-    const chat = describe(chatCommand);
-    const code = codingCommand === chatCommand ? chat : describe(codingCommand);
-    console.log(JSON.stringify({
-      ok: [chat, code].every((lane) => lane.status === "enabled" && lane.binaryAvailable),
-      chat,
-      code,
-      note: !chat.binaryAvailable || !code.binaryAvailable
-        ? "One or more selected CLI binaries are not installed or not on PATH."
-        : chat.verified && code.verified
-          ? "Configured by hilos-agent; this does not spend a model call or test provider credentials."
-          : "Custom commands keep their own tool configuration; hilos-agent does not guess flags.",
-    }, null, 2));
+    const result = webDoctor(cfg);
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
     return;
   }
 
@@ -319,7 +307,39 @@ async function main() {
   delete cliFlags.joinStdin;
   delete cliFlags.help;
   const cfg = resolveConfig({ flags: cliFlags, join: joinPayload });
-  await runWithTerminalSignals((signal) => run(cfg, { signal }));
+  const log = createDaemonLog();
+  let announced = false;
+  const announceLog = () => {
+    if (announced) return;
+    announced = true;
+    console.log(`log: ${log.path}`);
+  };
+  const setName = log.setName;
+  log.setName = (name) => { setName(name); announceLog(); };
+  const fatalReason = (error) => error?.name === "McpAuthStopError"
+    ? `auth stop: ${error.message}`
+    : `fatal: ${error?.message || error}\n${error?.stack || ""}`;
+  const onFatal = (error) => {
+    announceLog();
+    log.close(fatalReason(error));
+    console.error(error?.message || error);
+    process.exit(1);
+  };
+  process.on("uncaughtException", onFatal);
+  process.on("unhandledRejection", onFatal);
+  try {
+    await runWithTerminalSignals((signal) => run(cfg, { signal, log }), process, {
+      onSignal: (name) => { announceLog(); log.close(name); },
+    });
+  } catch (error) {
+    log.close(fatalReason(error));
+    throw error;
+  } finally {
+    announceLog();
+    log.close("normal stop");
+    process.removeListener("uncaughtException", onFatal);
+    process.removeListener("unhandledRejection", onFatal);
+  }
 }
 
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.14",
+  "version": "0.11.16",
   "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/skills/hilos-connect/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: hilos-connect
+description: Connect a named agent to a hilos room with the local daemon. Use when a person asks an IDE agent to "connect me to hilos" or "join the room" using a private join code.
+---
+
+# Connect
+
+1. Get the private join code from the person or the agent's connection dialog.
+   Treat it as a credential. Never paste it into chat, reports, or logs.
+2. From the folder the daemon will work in, run
+   `npx hilos-agent@latest doctor --join-stdin` and supply the code through
+   stdin. Read the JSON before starting anything. Keep the same `--coding-cmd`,
+   `--chat-cmd`, `--config`, and other settings as the dialog's run command.
+   A supplied `--join <blob>` also works, but exposes the credential in argv;
+   prefer stdin. A saved config can use `npx hilos-agent@latest doctor`.
+3. If `chat` or `code` fails, install the vendor CLI using that check's `fix`,
+   then rerun doctor. The Cursor app is not the Cursor CLI; `cursor-agent` is
+   installed separately. Refresh PATH in the launching shell if needed.
+4. If `lock` reports `contended`, find the other daemon holding this seat
+   before starting a second. Do not delete its lock or stop it without the
+   person's direction. For a filesystem error, fix the reported directory.
+   Resolve other failed checks and rerun until the JSON says `ok: true`.
+5. Start `npx hilos-agent@latest --join-stdin` with the same credentials and
+   settings in a process that survives your tool call ending: detach it with
+   persistent output capture, or open a separate terminal the person keeps
+   open. On Windows use PowerShell `Start-Process` to open that terminal.
+   Feed the private code through stdin or let the person paste it at the
+   hidden prompt. Never leave the daemon inside a tool call that exits and
+   kills its children.
+6. Only after doctor is all-ok AND the daemon prints `watching: @-mentions`
+   tell the person it is online. If you cannot observe that line, say startup
+   is unconfirmed. Give the daemon's diagnostic log path,
+   `~/.hilos/logs/<handle>.log`, also printed as `log: <path>` at startup.
+   Tell them to keep its terminal open when that is how it is running.

package/src/cli.mjs

@@ -6,20 +6,100 @@
 // 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
  * @param {import("node:events").EventEmitter & { exitCode?: number | string }} signalSource
+ * @param {{ onSignal?: (name: string) => void }} options
  */
-export async function runWithTerminalSignals(task, signalSource = process) {
+export async function runWithTerminalSignals(task, signalSource = process, { onSignal } = {}) {
   const controller = new AbortController();
   const interrupt = () => stop("SIGINT", 130);
   const terminate = () => stop("SIGTERM", 143);
   const stop = (name, code) => {
     if (controller.signal.aborted) return;
     signalSource.exitCode = code;
+    onSignal?.(name);
     controller.abort(new Error(`Daemon received ${name}`));
   };
   signalSource.once("SIGINT", interrupt);
@@ -279,11 +359,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/daemon-log.mjs

@@ -0,0 +1,84 @@
+// Local diagnostic log. Synchronous, bounded writes also survive process.exit;
+// logging must never become a reason the daemon stops serving its room.
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { format } from "node:util";
+import { redactSecrets } from "./redact.mjs";
+
+export function createDaemonLog({
+  dir = join(homedir(), ".hilos", "logs"),
+  name = `agent-${process.pid}`,
+  console: base = console,
+  redact = redactSecrets,
+  maxBytes = 2 * 1024 * 1024,
+} = {}) {
+  const logPath = (value) => join(dir, `${String(value || "").replace(/[^a-zA-Z0-9-]/g, "") || `agent-${process.pid}`}.log`);
+  let path = logPath(name);
+  let warned = false;
+  let closed = false;
+  const bestEffort = (write) => {
+    try { write(); } catch {
+      if (warned) return;
+      warned = true;
+      base.error("hilos-agent: could not write the local daemon log; continuing without it.");
+    }
+  };
+  const append = (target, text) => {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    let bytes = Buffer.from(text);
+    // Redaction happens before this cap, so truncating cannot reveal a secret.
+    if (bytes.length > maxBytes) bytes = bytes.subarray(bytes.length - maxBytes);
+    if (existsSync(target) && statSync(target).size + bytes.length > maxBytes) {
+      if (existsSync(`${target}.1`)) unlinkSync(`${target}.1`);
+      renameSync(target, `${target}.1`);
+    }
+    appendFileSync(target, bytes, { mode: 0o600 });
+    chmodSync(target, 0o600);
+  };
+  const write = (level, args) => bestEffort(() => {
+    const timestamp = new Date().toISOString();
+    const message = redact(format(...args));
+    const prefix = `${timestamp} ${level} `;
+    const available = Math.max(0, maxBytes - Buffer.byteLength(prefix) - 1);
+    for (const line of message.split(/\r?\n/)) {
+      // Keep the timestamp/level (and the beginning of an exit reason) even
+      // when one diagnostic line is larger than the entire file budget.
+      const bounded = Buffer.from(line).subarray(0, available).toString("utf8").replace(/\uFFFD$/, "");
+      append(path, `${prefix}${bounded}\n`);
+    }
+  });
+  // Make the provisional path readable even if startup fails before whoami.
+  bestEffort(() => append(path, ""));
+  return {
+    get path() { return path; },
+    log(...args) {
+      base.log(...args);
+      if (!closed) write("INFO", args);
+    },
+    error(...args) {
+      base.error(...args);
+      if (!closed) write("ERROR", args);
+    },
+    setName(value) {
+      if (closed) return;
+      const next = logPath(value);
+      if (next === path) return;
+      bestEffort(() => {
+        // Append to an earlier session's log instead of overwriting it. Include
+        // a provisional rotation too, oldest first, under the same size bound.
+        for (const source of [`${path}.1`, path]) {
+          if (!existsSync(source)) continue;
+          append(next, readFileSync(source));
+          unlinkSync(source);
+        }
+        path = next;
+      });
+    },
+    close(reason = "normal stop") {
+      if (closed) return;
+      write("INFO", [`exit: ${reason}`]);
+      closed = true; // A signal/fatal reason must not become "normal stop".
+    },
+  };
+}

package/src/doctor.mjs

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { commandArgv } from "./argv.mjs";
+import { resolveCommand } from "./cli.mjs";
+import { GLOBAL_CONFIG, LOCAL_CONFIG } from "./config.mjs";
+import { mentionHandle } from "./daemon.mjs";
+import { installHint } from "./install-hint.mjs";
+import { createIterateClaimRecoveryStore } from "./iterate-claim-recovery.mjs";
+import { makeClient } from "./mcp.mjs";
+import { detectVendor, fastChatCmd } from "./progress-emitter.mjs";
+import { webDoctor } from "./web-doctor.mjs";
+
+const nodeEngine = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).engines.node;
+
+export function checkNode(version = process.versions.node) {
+  const floor = nodeEngine.replace(/^>=\s*/, "").split(".").map(Number);
+  const current = version.split(".").map(Number);
+  let comparison = 0;
+  for (let i = 0; i < 3 && comparison === 0; i++) {
+    comparison = (current[i] || 0) - (floor[i] || 0);
+  }
+  const ok = comparison >= 0;
+  return {
+    name: "node", ok, detail: `Node ${version}; requires ${nodeEngine}`,
+    ...(!ok ? { fix: `Install Node.js ${nodeEngine}.` } : {}),
+  };
+}
+
+/** A pre-flight only: whoami, then briefly own and release the local seat. */
+export async function doctor(cfg, { lockDir } = {}) {
+  const checks = [checkNode()];
+  const chatCommand = cfg.chatCmd || fastChatCmd(detectVendor(cfg.codingCmd)) || cfg.codingCmd;
+  for (const [name, command] of [["chat", chatCommand], ["code", cfg.codingCmd]]) {
+    const binary = commandArgv(command)[0] || "";
+    const vendor = detectVendor(command);
+    const resolved = resolveCommand(binary);
+    checks.push({
+      name, ok: Boolean(resolved),
+      detail: `${resolved || `${binary || "(empty command)"} is not installed or not on PATH`}${vendor === "cursor" ? "; the Cursor CLI is separate from the Cursor app" : ""}`,
+      ...(!resolved ? { fix: installHint(vendor) } : {}),
+    });
+  }
+
+  const web = webDoctor(cfg);
+  checks.push({
+    name: "web", ok: web.ok,
+    detail: `chat: ${web.chat.vendor} ${web.chat.version || "(version unavailable)"}, ${web.chat.source} (${web.chat.status}); code: ${web.code.vendor} ${web.code.version || "(version unavailable)"}, ${web.code.source} (${web.code.status}). ${web.note}`,
+  });
+
+  let who;
+  try {
+    if (!cfg.token) throw new Error("No agent token configured. Get a private join code from hilos (Connect agent).");
+    const client = makeClient({
+      url: cfg.url, token: cfg.token, timeoutMs: 5_000,
+      // A one-shot diagnostic is activity, never proof of a live daemon.
+      connectionMode: "on_demand",
+      // The daemon's default retry timer is unref'd. Doctor has no poll loop
+      // to keep it alive, so retain this timer until the JSON can be printed.
+      delay: (ms) => new Promise((done) => setTimeout(done, ms)),
+    });
+    const identity = await client.tool("whoami");
+    const handle = mentionHandle(identity?.agentName);
+    if (!identity?.agentId || !handle || !identity?.workspaceId) {
+      throw new Error("whoami did not return a named agent with a workspace. Use the agent's private join code.");
+    }
+    who = identity;
+    checks.push({
+      name: "connection", ok: true,
+      detail: `${who.agentName} (@${handle}); workspace: ${who.workspaceId}; server: ${cfg.url}`,
+    });
+  } catch (error) {
+    checks.push({ name: "connection", ok: false, detail: `${cfg.url}: ${error?.message || error}` });
+  }
+
+  if (!who) {
+    checks.push({ name: "lock", ok: false, detail: "Not checked: connection must identify the agent first." });
+  } else {
+    let store;
+    let acquired = false;
+    let check;
+    try {
+      store = createIterateClaimRecoveryStore({
+        agentId: who.agentId, url: cfg.url, token: cfg.token,
+        ...(lockDir ? { dir: lockDir } : {}),
+      });
+      acquired = store.acquireLock();
+      const failure = store.acquireFailure();
+      check = {
+        name: "lock", ok: acquired,
+        detail: acquired ? "Seat acquired and released." : failure || "Could not acquire the local run lock.",
+        ...(!acquired ? { fix: failure === "contended"
+          ? "another daemon holds this seat; find it before starting a second daemon"
+          : "Make the lock directory writable, then rerun doctor." } : {}),
+      };
+    } catch (error) {
+      check = { name: "lock", ok: false, detail: String(error?.message || error) };
+    } finally {
+      if (acquired && !store.releaseLock()) {
+        check = { name: "lock", ok: false, detail: "The local run lock could not be released." };
+      }
+    }
+    checks.push(check);
+  }
+
+  const path = cfg.configPath && existsSync(cfg.configPath) ? resolve(cfg.configPath) : null;
+  const source = !path ? "none" : path === resolve(GLOBAL_CONFIG) ? "global"
+    : path === resolve(LOCAL_CONFIG) ? "local" : "explicit";
+  checks.push({
+    name: "config", ok: true,
+    detail: `${source}${path ? `: ${path}` : " (defaults, environment, join code and flags)"}; working folder: ${process.cwd()}`,
+  });
+  return { ok: checks.every((check) => check.ok), checks };
+}
+
+export function humanDoctor(result) {
+  return result.checks.map(({ name, ok, detail, fix }) =>
+    `${ok ? "ok  " : "fail"} ${name.padEnd(10)} ${[detail, fix && `Fix: ${fix}`].filter(Boolean).join(" ").replace(/\s+/g, " ")}`,
+  ).join("\n");
+}

package/src/install-hint.mjs

@@ -0,0 +1,8 @@
+/** Where to get the vendor CLI a daemon command names (1330). */
+export 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 "";
+}

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/mcp.mjs

@@ -203,6 +203,7 @@ function assertJsonRpcResponse(json, expectedId) {
 export function makeClient({
   url,
   token,
+  connectionMode = "daemon",
   timeoutMs = DEFAULT_TIMEOUT_MS,
   retryDelayMs = RETRY_DELAY_MS,
   delay = defaultDelay,
@@ -235,7 +236,7 @@ export function makeClient({
       "content-type": "application/json",
       accept: "application/json, text/event-stream",
       authorization: `Bearer ${token}`,
-      "x-hilos-connection-mode": "daemon",
+      "x-hilos-connection-mode": connectionMode,
       ...(DAEMON_CLIENT ? { "x-hilos-client": DAEMON_CLIENT } : {}),
       ...(options.ambientBinding
         ? { "x-hilos-ambient-binding": options.ambientBinding }

package/src/run.mjs

@@ -15,6 +15,8 @@ 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 { installHint } from "./install-hint.mjs";
 import {
   createIterateClaimRecoveryStore,
   reconcileDaemonIterateClaims,
@@ -67,6 +69,8 @@ export async function run(
     iterateClaimShutdownReconcileTimeoutMs = 1000,
   } = {},
 ) {
+  let exitError = null;
+  try {
   if (!cfg.token) {
     // Throw, don't process.exit — the CLI's main().catch prints + exits 1 exactly
     // as before, and an embedding host (the desktop Local Agents runner) must
@@ -154,6 +158,7 @@ export async function run(
     // Throw for the same reason as the token guard above — embed-safe, CLI-equal.
     throw new Error("This agent has no display name / handle — set one in hilos, then reconnect.");
   }
+  log.setName?.(me.handle);
   // Initialized after discovery so the recovery lock is scoped to this agent.
   let iterateClaimRecoveryStore = null;
   let queue = null;
@@ -188,6 +193,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 +236,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 {
@@ -926,4 +949,14 @@ export async function run(
     iterateClaimRecoveryStore?.releaseLock();
     if (isAuthStop(stopSignal.reason)) throw stopSignal.reason;
   }
+  } catch (error) {
+    exitError = error;
+    throw error;
+  } finally {
+    log.close?.(exitError?.name === "McpAuthStopError"
+      ? `auth stop: ${exitError.message}`
+      : exitError
+        ? `fatal: ${exitError.message || exitError}\n${exitError.stack || ""}`
+        : "normal stop");
+  }
 }

package/src/web-doctor.mjs

@@ -0,0 +1,49 @@
+import { spawnSync } from "node:child_process";
+import { commandArgv } from "./argv.mjs";
+import { resolveCommand, spawnPlan } from "./cli.mjs";
+import { detectVendor, fastChatCmd, webCapability } from "./progress-emitter.mjs";
+
+/** Inspect native web configuration without a model call or provider login. */
+export function webDoctor(cfg) {
+  const codingCommand = cfg.codingCmd;
+  const chatCommand = cfg.chatCmd || fastChatCmd(detectVendor(codingCommand)) || codingCommand;
+  const describe = (command) => {
+    const argv = commandArgv(command);
+    const vendor = detectVendor(command);
+    const capability = webCapability(vendor, {
+      enabled: cfg.webSearch !== false,
+      args: argv.slice(1),
+    });
+    const binary = argv[0] || "";
+    const resolved = resolveCommand(binary);
+    // npm's Windows .cmd shims need the same ComSpec plan as an actual run.
+    const plan = resolved ? spawnPlan(resolved, ["--version"]) : null;
+    const probed = plan
+      ? spawnSync(plan.file, plan.args, {
+          encoding: "utf8", timeout: 5_000,
+          windowsVerbatimArguments: plan.windowsVerbatimArguments,
+        })
+      : null;
+    const binaryAvailable = Boolean(resolved) && !probed?.error && probed?.status === 0;
+    const version = String(probed?.stdout || probed?.stderr || "").trim().split("\n")[0] || null;
+    return { vendor, binary, binaryAvailable, version, command, ...capability };
+  };
+  const chat = describe(chatCommand);
+  const code = codingCommand === chatCommand ? chat : describe(codingCommand);
+  const lanes = [chat, code];
+  return {
+    // Disabling web or keeping the CLI's own policy is a valid setup choice.
+    // Every command still has to exist and pass its version probe.
+    ok: lanes.every((lane) => lane.binaryAvailable &&
+      ["enabled", "disabled", "operator-controlled", "inherited"].includes(lane.status)),
+    chat,
+    code,
+    note: !chat.binaryAvailable || !code.binaryAvailable
+      ? "One or more selected CLI binaries are not installed, not on PATH, or failed their version probe."
+      : lanes.some((lane) => ["disabled", "operator-controlled"].includes(lane.status))
+        ? "Web enablement is off by choice in one or more commands; the CLI's own policy still applies."
+        : lanes.some((lane) => lane.status === "inherited")
+          ? "Web configuration is inherited by choice from the selected CLI; hilos-agent does not guess flags."
+          : "Configured by hilos-agent; this does not spend a model call or test provider credentials.",
+  };
+}