hilos-agent 0.11.15 → 0.11.17

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`,
@@ -509,3 +544,19 @@ real tagged release proves OIDC end to end. After that proof, remove the
 workflow fallback, revoke the npm token, and delete the GitHub secret (1094,
 1211, 1228). Because the source repository is private, npm will not attach a
 public provenance attestation even when the publish itself uses OIDC.
+
+## Browser agents and WebMCP
+
+A WebMCP-enabled browser can use the signed-in hilos workspace directly.
+Open Settings → Connections to check page-tool registration. Start with
+`get_hilos_context`, then `navigate_hilos`; Docs, Tasks, rooms, activity and
+onboarding register their own commands. No personal token or plugin is needed
+for that browser session. See [WebMCP setup](https://hilos.sh/docs/webmcp).
+
+The plugin and coding-client skills use remote MCP. They do not make Claude
+Code, Codex, or Cursor into browser WebMCP consumers. For background work, keep
+the personal or named-agent MCP connection. The local daemon's optional
+`hilos-agent webmcp` bridge uses an isolated signed-in profile and exact
+person-approved read tools. Its `tools` response distinguishes native from
+limited imperative compatibility mode. Rediscover after navigation; calls bind
+to the inspected page and never retry on site-provided error text.

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.15",
+  "version": "0.11.17",
   "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": {
@@ -27,6 +27,7 @@
   "keywords": [
     "hilos",
     "mcp",
+    "webmcp",
     "agent",
     "claude-code",
     "codex",

package/skills/hilos-connect/SKILL.md

@@ -0,0 +1,41 @@
+---
+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
+
+If the person wants a browser agent to use the hilos page already open, use
+[WebMCP setup](https://hilos.sh/docs/webmcp): sign in in a supported browser,
+check Settings → Connections, then discover `get_hilos_context` and
+`navigate_hilos`. No token or daemon is needed for that page session. Do not
+claim this plugin adds browser WebMCP to a coding client. Personal remote MCP
+uses Settings → Connections; a named local agent uses the steps below.
+
+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

@@ -90,14 +90,16 @@ export function spawnPlan(cmd, args, opts = {}) {
  * 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);

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/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

@@ -16,6 +16,7 @@ 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,
@@ -32,15 +33,6 @@ 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`
@@ -77,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
@@ -164,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;
@@ -954,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.",
+  };
+}

package/src/webmcp-bridge.mjs

@@ -18,8 +18,8 @@ const AGENT_BROWSER_BIN = "agent-browser/bin/agent-browser.js";
 const AGENT_BROWSER_MISSING =
   "WebMCP needs Node.js 24 or newer and agent-browser. Upgrade Node.js, reinstall hilos-agent, then run `agent-browser install`.";
 const MAX_CAPTURE_CHARS = 256 * 1024;
-const MAX_INPUT_CHARS = 16 * 1024;
-const MAX_RESULT_CHARS = 64 * 1024;
+const MAX_INPUT_BYTES = 16 * 1024;
+const MAX_RESULT_BYTES = 64 * 1024;
 const MAX_ORIGINS = 32;
 const MAX_READ_TOOLS_PER_ORIGIN = 64;
 const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
@@ -130,7 +130,8 @@ const SCHEMA_KEYS = new Set([
 
 /** Strip prose-bearing schema fields so tool poisoning never becomes instructions. */
 export function sanitizeWebMcpSchema(value, depth = 0) {
-  if (depth > 12 || value == null || typeof value !== "object") return value;
+  if (depth > 12) return undefined;
+  if (value == null || typeof value !== "object") return value;
   if (Array.isArray(value)) return value.slice(0, 64).map((item) => sanitizeWebMcpSchema(item, depth + 1));
   const out = {};
   for (const [key, child] of Object.entries(value).slice(0, 256)) {
@@ -144,6 +145,7 @@ export function sanitizeWebMcpSchema(value, depth = 0) {
       continue;
     }
     if (!SCHEMA_KEYS.has(key)) continue;
+    if (key === "$ref" && (typeof child !== "string" || !child.startsWith("#"))) continue;
     out[key] = sanitizeWebMcpSchema(child, depth + 1);
   }
   return out;
@@ -293,9 +295,9 @@ function evalResult(run) {
   return run?.json?.data?.result;
 }
 
-function encodedCall(name, input) {
-  const payload = Buffer.from(JSON.stringify({ name, input }), "utf8").toString("base64");
-  return `(() => { const p = JSON.parse(atob("${payload}")); return window.__hilosWebMcpBridge.call(p.name, p.input); })()`;
+function encodedCall(name, input, expected) {
+  const payload = Buffer.from(JSON.stringify({ name, input, expected }), "utf8").toString("base64");
+  return `(() => { const bytes = Uint8Array.from(atob("${payload}"), c => c.charCodeAt(0)); const p = JSON.parse(new TextDecoder().decode(bytes)); return window.__hilosWebMcpBridge.call(p.name, p.input, p.expected); })()`;
 }
 
 async function listTools(policy, runner) {
@@ -315,16 +317,18 @@ async function listTools(policy, runner) {
     : "/";
   const registered = Array.isArray(raw?.tools) ? raw.tools : [];
   const allowed = registered
-    .filter((tool) => originPolicy.readTools.has(tool?.name))
+    .filter((tool) => originPolicy.readTools.has(tool?.name) && !tool.schemaOmitted && tool.annotations?.consequentialHint !== true)
     .map((tool) => ({
       name: tool.name,
-      inputSchema: tool.schemaOmitted ? undefined : sanitizeWebMcpSchema(tool.inputSchema || {}),
+      inputSchema: sanitizeWebMcpSchema(tool.inputSchema || {}),
       personApprovedRisk: "read",
       siteReadOnlyHint: tool.annotations?.readOnlyHint === true,
     }));
   return {
     ok: true,
     source: { origin, pagePath },
+    discoveryId: typeof raw?.discoveryId === "string" ? raw.discoveryId : null,
+    mode: raw?.mode === "native" ? "native" : "compatibility",
     tools: allowed,
     blockedToolCount: Math.max(0, registered.length - allowed.length),
     untrusted: true,
@@ -377,7 +381,7 @@ export async function runWebMcpCommand(cfg, operation, args = [], options = {})
     let input;
     try {
       const text = args[1] == null ? "{}" : String(args[1]);
-      if (text.length > MAX_INPUT_CHARS) throw new Error("too large");
+      if (Buffer.byteLength(text, "utf8") > MAX_INPUT_BYTES) throw new Error("too large");
       input = JSON.parse(text);
       if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("not an object");
     } catch {
@@ -395,9 +399,10 @@ export async function runWebMcpCommand(cfg, operation, args = [], options = {})
         tool: name,
       };
     }
+    if (!available.discoveryId) return { ok: false, code: "stale_bridge", error: "Close and reopen the WebMCP browser to load the current bridge." };
     const run = await runner(
       policy.browserCommand,
-      browserArgs(policy, ["eval", encodedCall(name, input)]),
+      browserArgs(policy, ["eval", encodedCall(name, input, { ...available.source, discoveryId: available.discoveryId })]),
     );
     if (!run.ok) {
       return {
@@ -414,12 +419,12 @@ export async function runWebMcpCommand(cfg, operation, args = [], options = {})
     if (
       origin !== available.source.origin ||
       resultPagePath !== available.source.pagePath ||
-      raw?.tool !== name
+      raw?.tool !== name || raw?.discoveryId !== available.discoveryId
     ) {
       return { ok: false, code: "provenance_mismatch", error: "The page changed while the WebMCP tool was running; its result was discarded." };
     }
     const resultJson = typeof raw?.resultJson === "string" ? raw.resultJson : "null";
-    if (resultJson.length > MAX_RESULT_CHARS) {
+    if (Buffer.byteLength(resultJson, "utf8") > MAX_RESULT_BYTES) {
       return { ok: false, code: "result_too_large", error: "The WebMCP tool result exceeded the 64 KB limit." };
     }
     let result;

package/src/webmcp-init.js

@@ -10,8 +10,8 @@
 
   const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
   const MAX_TOOLS = 64;
-  const MAX_SCHEMA_CHARS = 32 * 1024;
-  const MAX_RESULT_CHARS = 64 * 1024;
+  const MAX_SCHEMA_BYTES = 32 * 1024;
+  const MAX_RESULT_BYTES = 64 * 1024;
 
   const copyJson = (value) => {
     if (value === undefined) return undefined;
@@ -29,12 +29,7 @@
   };
 
   function installFallbackModelContext() {
-    if (
-      document.modelContext &&
-      typeof document.modelContext.registerTool === "function" &&
-      typeof document.modelContext.getTools === "function" &&
-      typeof document.modelContext.executeTool === "function"
-    ) {
+    if (document.modelContext && typeof document.modelContext.registerTool === "function") {
       return document.modelContext;
     }
 
@@ -78,9 +73,13 @@
             throw options.signal.reason || domError("Registration aborted", "AbortError");
           }
 
+          if (tools.size >= MAX_TOOLS) throw new RangeError("Too many WebMCP tools");
           const inputSchema = copyJson(tool.inputSchema);
+          if (inputSchema !== undefined && (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema) || (inputSchema.type && inputSchema.type !== "object"))) {
+            throw new TypeError("WebMCP input schema must describe an object");
+          }
           const schemaText = JSON.stringify(inputSchema ?? {});
-          if (schemaText.length > MAX_SCHEMA_CHARS) {
+          if (new TextEncoder().encode(schemaText).length > MAX_SCHEMA_BYTES) {
             throw new TypeError("WebMCP input schema is too large");
           }
           const entry = {
@@ -92,6 +91,7 @@
               ? {
                   readOnlyHint: tool.annotations.readOnlyHint === true,
                   untrustedContentHint: tool.annotations.untrustedContentHint === true,
+                  consequentialHint: tool.annotations.consequentialHint === true,
                 }
               : undefined,
             execute: tool.execute,
@@ -117,7 +117,10 @@
         }
       },
 
-      async getTools() {
+      async getTools(options = {}) {
+        if (options.fromOrigins?.some((origin) => origin !== location.origin)) {
+          throw domError("The hilos compatibility bridge supports this document only", "NotSupportedError");
+        }
         return [...tools.values()]
           .sort((a, b) => a.name.localeCompare(b.name))
           .map((tool) => ({
@@ -142,12 +145,26 @@
         const tool = tools.get(name);
         if (!tool) throw domError(`WebMCP tool ${name} is not registered`, "NotFoundError");
 
+        if (registeredTool.origin !== location.origin || registeredTool.window !== window) {
+          throw domError("WebMCP tool belongs to another document", "SecurityError");
+        }
         const controller = new AbortController();
-        const onAbort = () => controller.abort(options.signal?.reason);
+        let rejectAbort;
+        const aborted = new Promise((_, reject) => { rejectAbort = reject; });
+        const onAbort = () => {
+          controller.abort(options.signal?.reason);
+          rejectAbort(controller.signal.reason);
+        };
         options.signal?.addEventListener("abort", onAbort, { once: true });
         try {
-          const value = await tool.execute(copyJson(inputObject), { signal: controller.signal });
-          return JSON.stringify(value);
+          const value = await Promise.race([
+            Promise.resolve().then(() => {
+              controller.signal.throwIfAborted();
+              return tool.execute(copyJson(inputObject), { signal: controller.signal });
+            }),
+            aborted,
+          ]);
+          return JSON.stringify(value) ?? "null";
         } finally {
           options.signal?.removeEventListener("abort", onAbort);
         }
@@ -179,7 +196,11 @@
     return context;
   }
 
+  const native = Boolean(document.modelContext?.registerTool);
   const modelContext = installFallbackModelContext();
+  let epoch = 0;
+  let discovery = null;
+  modelContext.addEventListener?.("toolchange", () => { epoch++; });
 
   const source = () => ({
     origin: location.origin,
@@ -187,24 +208,30 @@
   });
 
   async function registeredTools() {
+    if (typeof modelContext.getTools !== "function" || typeof modelContext.executeTool !== "function") {
+      throw domError("This native WebMCP build has no in-page consumer API. Update the browser; hilos will not replace its native provider.", "NotSupportedError");
+    }
     const tools = await modelContext.getTools();
     return (Array.isArray(tools) ? tools : [])
-      .filter((tool) => tool && tool.origin === location.origin)
+      .filter((tool) => tool && tool.origin === location.origin && tool.window === window)
       .slice(0, MAX_TOOLS);
   }
 
   const bridge = Object.freeze({
     version: 1,
-    mode:
-      document.modelContext === modelContext &&
-      Object.prototype.hasOwnProperty.call(document, "modelContext")
-        ? "polyfill"
-        : "native",
+    mode: native ? "native" : "compatibility",
 
     async list() {
+      const before = { href: location.href, epoch };
       const tools = await registeredTools();
+      if (before.href !== location.href || before.epoch !== epoch) {
+        throw domError("The page changed during discovery. List its tools again.", "InvalidStateError");
+      }
+      discovery = { id: crypto.randomUUID(), href: before.href, epoch: before.epoch, tools };
       return {
         ...source(),
+        discoveryId: discovery.id,
+        mode: native ? "native" : "compatibility",
         tools: tools.map((tool) => {
           let inputSchema = tool.inputSchema;
           let schemaOmitted = false;
@@ -213,7 +240,7 @@
             // schema as the draft's serialized JSON string; the current report
             // exposes an object. Normalize both without passing site prose on.
             if (typeof inputSchema === "string") inputSchema = JSON.parse(inputSchema);
-            if (JSON.stringify(inputSchema ?? {}).length > MAX_SCHEMA_CHARS) {
+            if (new TextEncoder().encode(JSON.stringify(inputSchema ?? {})).length > MAX_SCHEMA_BYTES) {
               inputSchema = undefined;
               schemaOmitted = true;
             }
@@ -229,6 +256,7 @@
               ? {
                   readOnlyHint: tool.annotations.readOnlyHint === true,
                   untrustedContentHint: tool.annotations.untrustedContentHint === true,
+                  consequentialHint: tool.annotations.consequentialHint === true,
                 }
               : undefined,
           };
@@ -236,9 +264,11 @@
       };
     },
 
-    async call(name, inputObject, timeoutMs = 30_000) {
-      const tools = await registeredTools();
-      const tool = tools.find((candidate) => candidate.name === name);
+    async call(name, inputObject, expected, timeoutMs = 30_000) {
+      if (!expected || expected.origin !== location.origin || expected.pagePath !== location.pathname || !discovery || expected.discoveryId !== discovery.id || discovery.href !== location.href || discovery.epoch !== epoch) {
+        throw domError("The page or tool inventory changed. Discover tools again before calling.", "InvalidStateError");
+      }
+      const tool = discovery.tools.find((candidate) => candidate.name === name);
       if (!tool) throw domError(`WebMCP tool ${name} is not registered`, "NotFoundError");
 
       const controller = new AbortController();
@@ -247,25 +277,16 @@
         Math.max(1_000, Math.min(Number(timeoutMs) || 30_000, 60_000)),
       );
       try {
-        let result;
-        try {
-          result = await modelContext.executeTool(tool, inputObject, {
-            signal: controller.signal,
-          });
-        } catch (error) {
-          // Chromium's early draft expected a serialized input string. Only
-          // retry the pre-execution parse failure; an arbitrary tool failure
-          // might follow a side effect and must never be executed twice.
-          if (!/failed to parse input arguments/i.test(String(error?.message || error))) throw error;
-          result = await modelContext.executeTool(tool, JSON.stringify(inputObject), {
-            signal: controller.signal,
-          });
-        }
-        const resultJson = typeof result === "string" ? result : JSON.stringify(result);
-        if (resultJson.length > MAX_RESULT_CHARS) {
+        // Never infer a protocol version from a site's error message and retry:
+        // that error may have followed a side effect.
+        const result = await modelContext.executeTool(tool, inputObject, {
+          signal: controller.signal,
+        });
+        const resultJson = (typeof result === "string" ? result : JSON.stringify(result)) ?? "null";
+        if (new TextEncoder().encode(resultJson).length > MAX_RESULT_BYTES) {
           throw new RangeError("WebMCP tool result exceeds the 64 KB bridge limit");
         }
-        return { ...source(), tool: name, resultJson };
+        return { ...source(), discoveryId: expected.discoveryId, tool: name, resultJson };
       } finally {
         clearTimeout(timer);
       }