heedvane 0.3.3 → 0.3.4

package/dist/dispatchers/posix.d.ts

@@ -7,22 +7,16 @@ import type { HeedGatingConfig } from "../heed-file.js";
  * configs, so policy updates rewrite only this file. Observe-only v1: every path
  * exits 0; the agent is never blocked and never sees stderr noise.
  *
- * Spool fallback (Orca's spool_hook_event): appends one JSON line to
- * <heed root>/spool/pane-<key>.jsonl, beside endpoint.env (HEED_AGENT_HOOK_ENDPOINT, else
- * $HEED_AGENT_HOOK_ROOT or ~/.heed), 5 MB cap per pane file, 7-day TTL via
- * `find -mtime`, 0600 perms, JSON-escaped envelope carrying
- * paneKey/tabId/worktreeId/launchToken/source/receivedAt/payload.
+ * Live path: curl POST to http://127.0.0.1:$HEED_AGENT_HOOK_PORT/hook/<agent> with X-Heed-Agent-Hook-Token and
+ * X-Heed-Hook-Version: 1, within the timeouts of src/hook-fallback.ts. The listener answers from this machine alone;
+ * only a session start waits longer, for the session's one fetch of the steering policy.
  *
- * Live path: curl POST to http://127.0.0.1:$HEED_AGENT_HOOK_PORT/hook/<agent> with
- * X-Heed-Agent-Hook-Token and X-Heed-Hook-Version: 1, 0.5s connect / 0.8s max, falling back to spool
- * on any failure. The listener answers from this machine alone; only a session start waits (2s max)
- * for the session's one fetch of the steering policy.
- *
- * Start on the fly: when nothing listens on the port (curl exit 7, connection refused), the event is
- * spooled and `npx -y heedvane listener start` is started in the background, at most once a minute
- * (a `listener.starting` lock directory older than a minute is cleared). The listener replays the
- * spool when it starts, so steering comes back by itself after a restart; no login service is needed.
- * `HEED_LISTENER_AUTOSTART=0` in the agent's environment turns this off.
+ * Fallback: when the listener gives no answer (no endpoint, nothing listens, it times out, or it answers an error),
+ * the script runs Heedvane's one fallback, `fallback.mjs` beside it (src/guard.ts), with the Node that installed the
+ * hooks (named in `node` beside it), or with node on PATH once that one is gone. That keeps the event in the spool beside endpoint.env for the listener to replay, starts
+ * `npx -y heedvane listener start` (which decides itself whether a listener must start or take over), and adds the
+ * notice the first time in a session. When the fallback itself fails, the agent still gets the fallback answer.
+ * `HEED_LISTENER_AUTOSTART=0` in the agent's environment turns the start off.
  */
 export interface DispatcherOptions {
     /** heed.yaml `heedvane.skills.whenUnknown: deny`: with no listener to check it, deny a skill use. */
@@ -30,12 +24,15 @@ export interface DispatcherOptions {
     /** heed.yaml `gating.mode`: `pane` (the default) runs the hooks only in sessions launched with
      *  HEED_SESSION set; `always` runs them in every session. */
     gating?: HeedGatingConfig["mode"];
-    /** The folder holding node and npx at install time, appended to PATH for the start on the fly:
-     *  an agent launched from a desktop app may run its hooks without them on PATH. */
-    nodeDir?: string;
 }
 export declare function dispatcherScript(agentId: string, options?: DispatcherOptions): string;
 /** The on-disk dispatcher directory under the heed root. */
 export declare function agentHooksDir(home: string): string;
-/** Write (or update) the dispatcher script for one agent. Idempotent, mode 0700. */
+/** Write (or update) the dispatcher script for one agent, mode 0700, and the fallback it runs beside it. Idempotent. */
 export declare function writeDispatcherScript(home: string, agent: string, options?: DispatcherOptions): Promise<void>;
+/**
+ * Names the Node running this install in `node` beside the dispatchers, for every hook's fallback (the dispatchers' and
+ * Hermes'). It is the PATH entry that links to that Node when there is one: Homebrew's /opt/homebrew/bin/node outlives
+ * `brew upgrade`, the Cellar path it links to does not. Git Bash on Windows runs C:/… paths, so no backslashes.
+ */
+export declare function writeHookNode(home: string, path?: string): Promise<void>;

package/dist/dispatchers/posix.js

@@ -1,6 +1,10 @@
+import { realpathSync } from "node:fs";
 import { chmod, mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, delimiter, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
+import { guardSource } from "../clients/pi-extension.js";
+import { FALLBACK_FILE, HOOK_CONNECT_TIMEOUT_MS, HOOK_NODE_FILE, HOOK_TIMEOUT_MS, PROOF_KEY, RETRY_AFTER_MS, SESSION_START_TIMEOUT_MS, UNANSWERED_FLAG } from "../hook-fallback.js";
+import { USER_NOTICE_FIELD } from "../reply/harness-output.js";
 import { validateAgentId } from "./snippets.js";
 /** The stdout a Claude Code PreToolUse hook prints to deny (src/reply/harness-output.ts owns the shape). */
 const UNCHECKED_SKILL_DENY = JSON.stringify({
@@ -15,7 +19,7 @@ export function dispatcherScript(agentId, options = {}) {
     // Only Claude Code's deny shape is verified; other agents keep the fail-open fallback.
     const denySkills = options.denySkillsWhenUnchecked === true && agentId === "claude";
     const gating = options.gating ?? "always";
-    const nodeDir = (options.nodeDir ?? "").replaceAll("'", "'\\''");
+    const noticeField = USER_NOTICE_FIELD[agentId];
     return `#!/bin/sh
 # heedvane-agent-hook dispatcher for ${agentId} — generated by heedvane-hook. Do not hand-edit.
 # Rewritten wholesale by \`npx heedvane setup\`; policy updates never touch agent configs.
@@ -28,9 +32,6 @@ umask 077
 
 HEED_HOOK_AGENT="${agentId}"
 HEED_HOOK_VERSION=1
-HEED_HOOK_SPOOL_CAP=5242880
-HEED_HOOK_SPOOL_TTL_DAYS=7
-HEED_HOOK_NODE_DIR='${nodeDir}'
 
 [ -n "\${HOME:-}" ] || exit 0
 
@@ -42,70 +43,21 @@ HEED_HOOK_GATING="${gating}"
 # endpoint.env (written by init/setup/listener start) sits in the heed root; the spool beside it.
 HEED_HOOK_ENDPOINT_FILE="\${HEED_AGENT_HOOK_ENDPOINT:-\${HEED_AGENT_HOOK_ROOT:-$HOME/.heed}/endpoint.env}"
 
-heed_spool_dir() {
-  printf '%s\\n' "\${HEED_HOOK_ENDPOINT_FILE%/*}/spool"
-}
-
-# Escape a string for embedding inside a JSON document (POSIX awk).
-# Encodes backslash, double quote, tab and CR; newlines are re-encoded per record.
-# Other C0 control chars survive as-is — payloads are harness JSON, and v1
-# treats a best-effort escape as acceptable for spool records.
-json_escape() {
-  printf '%s' "$1" | LC_ALL=C awk '
-    NR > 1 { printf "\\\\n" }
-    {
-      gsub(/\\\\/, "\\\\\\\\")
-      gsub(/"/, "\\\\\\"")
-      gsub(/\\t/, "\\\\t")
-      gsub(/\\r/, "\\\\r")
-      printf "%s", $0
-    }'
-}
-
-spool_hook_event() {
-  _body="\${1:-}"
-  [ -n "$_body" ] || return 0
-  _dir="$(heed_spool_dir)"
-  mkdir -p "$_dir" 2>/dev/null || return 0
-  _key="\${HEED_PANE_KEY:-\${HEED_SESSION:-}}"
-  [ -n "$_key" ] || _key="default"
-  _file="$_dir/pane-$_key.jsonl"
-
-  # 7-day TTL: prune stale pane spool files, and the events set aside after a change of sign-in (other-sign-in/), on every write (cheap).
-  find "$_dir" -type f \\( -name 'pane-*.jsonl*' -o -path '*/other-sign-in/*' \\) -mtime "+$HEED_HOOK_SPOOL_TTL_DAYS" -delete 2>/dev/null || :
-
-  # 5 MB cap: once a pane file is over budget, drop further events (never grow unbounded).
-  if [ -f "$_file" ]; then
-    _size="$(wc -c < "$_file" 2>/dev/null || echo 0)"
-    [ "$_size" -lt "$HEED_HOOK_SPOOL_CAP" ] || return 0
-  fi
-
-  _received="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u)"
-  _envelope="{\\"paneKey\\":\\"$(json_escape "\${HEED_PANE_KEY:-\${HEED_SESSION:-}}")\\""
-  _envelope="$_envelope,\\"tabId\\":\\"$(json_escape "\${HEED_TAB_ID:-}")\\""
-  _envelope="$_envelope,\\"worktreeId\\":\\"$(json_escape "\${HEED_WORKTREE_ID:-}")\\""
-  _envelope="$_envelope,\\"launchToken\\":\\"$(json_escape "\${HEED_LAUNCH_TOKEN:-}")\\""
-  _envelope="$_envelope,\\"source\\":\\"$(json_escape "$HEED_HOOK_AGENT")\\""
-  _envelope="$_envelope,\\"receivedAt\\":\\"$(json_escape "$_received")\\""
-  _envelope="$_envelope,\\"id\\":\\"$(json_escape "\${heed_event_id:-}")\\""
-  _envelope="$_envelope,\\"payload\\":\\"$(json_escape "$_body")\\"}"
-
-  printf '%s\\n' "$_envelope" >> "$_file" 2>/dev/null || return 0
-  chmod 600 "$_file" 2>/dev/null || :
-  return 0
-}
-
-# Nothing listens (connection refused): start the listener in the background, at most one try a
-# minute, so steering comes back by itself after a restart. It replays the spooled event at its start.
-heed_start_listener() {
-  [ "\${HEED_LISTENER_AUTOSTART:-1}" != "0" ] || return 0
-  _root="\${HEED_HOOK_ENDPOINT_FILE%/*}"
-  case "$_root" in */.heed) ;; *) return 0 ;; esac
-  _lock="$_root/listener.starting"
-  find "$_lock" -maxdepth 0 -mmin +1 -exec rmdir {} \\; 2>/dev/null || :
-  mkdir "$_lock" 2>/dev/null || return 0
-  (PATH="$PATH:$HEED_HOOK_NODE_DIR" HEED_HOME="\${_root%/.heed}" nohup npx -y heedvane listener start < /dev/null >> "$_root/listener.log" 2>&1 &) 2>/dev/null || :
-  return 0
+# The listener gave no answer: Heedvane's one fallback keeps the event and adds the notice once a session (see the
+# header of src/dispatchers/posix.ts). Its own failure never blocks the agent: the answer is then $heed_fallback.
+heed_unanswered() {
+  # The Node that last installed the hooks, by its PATH link and then itself; node on PATH once both are gone (brew upgrade, nvm uninstall).
+  heed_node=""
+  { while IFS= read -r heed_candidate || [ -n "$heed_candidate" ]; do
+    if [ -x "$heed_candidate" ]; then heed_node="$heed_candidate"; break; fi
+  done < "\${0%/*}/${HOOK_NODE_FILE}"; } 2>/dev/null || :
+  [ -n "$heed_node" ] || heed_node="$(command -v node 2>/dev/null)" || :
+  # The agent's NODE_OPTIONS are its project's (a --require of its own code), not the fallback's.
+  _answer="$(printf '%s' "$payload" | NODE_OPTIONS='' HEED_HOOK_FALLBACK_ANSWER="$heed_fallback" HEED_HOOK_EVENT_ID="\${heed_event_id:-}" "$heed_node" "\${0%/*}/${FALLBACK_FILE}" ${UNANSWERED_FLAG} "$HEED_HOOK_AGENT"${noticeField === undefined ? "" : ` ${noticeField}`} 2>/dev/null)" || :
+  case "$_answer" in
+    "{"*) heed_answer "$_answer" ;;
+  esac
+  heed_answer "$heed_fallback"
 }
 
 # The hook payload arrives on stdin. command -p keeps cat working under a stripped PATH.
@@ -142,36 +94,40 @@ heed_answer() {
 
 [ -n "$payload" ] || heed_answer '{}'
 
-# Port/token come from endpoint.env (HEED_AGENT_HOOK_PORT / HEED_AGENT_HOOK_TOKEN lines).
+# Port/token: from the environment when both are set, else from endpoint.env (HEED_AGENT_HOOK_PORT / HEED_AGENT_HOOK_TOKEN lines).
 # shellcheck disable=SC1090
-if [ -r "$HEED_HOOK_ENDPOINT_FILE" ]; then
+if { [ -z "\${HEED_AGENT_HOOK_PORT:-}" ] || [ -z "\${HEED_AGENT_HOOK_TOKEN:-}" ]; } && [ -r "$HEED_HOOK_ENDPOINT_FILE" ]; then
   . "$HEED_HOOK_ENDPOINT_FILE" 2>/dev/null || :
 fi
 
-# No listener contract (endpoint env, port, token): spool instead, still exit 0.
+# No listener contract (endpoint env, port, token): the fallback, still exit 0.
 if [ -z "\${HEED_AGENT_HOOK_PORT:-}" ] || [ -z "\${HEED_AGENT_HOOK_TOKEN:-}" ]; then
-  spool_hook_event "$payload"
-  heed_answer "$heed_fallback"
+  heed_unanswered
 fi
 
 # A local answer takes milliseconds. Only a session start waits for Heedvane (its one policy fetch).
-heed_max_time=0.8
+heed_max_time=${HOOK_TIMEOUT_MS / 1000}
 case "$payload" in
-  *'"hook_event_name":"SessionStart"'*|*'"hook_event_name": "SessionStart"'*) heed_max_time=2 ;;
+  *'"hook_event_name":"SessionStart"'*|*'"hook_event_name": "SessionStart"'*) heed_max_time=${SESSION_START_TIMEOUT_MS / 1000} ;;
 esac
 
-reply="$(printf '%s' "$payload" | curl -sS --fail -X POST "http://127.0.0.1:\${HEED_AGENT_HOOK_PORT}/hook/${agentId}" \\
-  --connect-timeout 0.5 --max-time "$heed_max_time" --noproxy 127.0.0.1 \\
+reply="$(printf '%s' "$payload" | curl -sS --fail -D - -X POST "http://127.0.0.1:\${HEED_AGENT_HOOK_PORT}/hook/${agentId}" \\
+  --connect-timeout ${HOOK_CONNECT_TIMEOUT_MS / 1000} --max-time "$heed_max_time" --noproxy 127.0.0.1 \\
+  -H "Expect:" \\
   -H "Content-Type: application/json" \\
   -H "X-Heed-Agent-Hook-Token: \${HEED_AGENT_HOOK_TOKEN}" \\
   -H "X-Heed-Hook-Version: \${HEED_HOOK_VERSION}" \\
   -H "X-Heed-Event-Id: \${heed_event_id:-}" \\
-  --data-binary @- 2>/dev/null)" || {
-  heed_curl_exit=$?
-  spool_hook_event "$payload"
-  [ "$heed_curl_exit" -ne 7 ] || heed_start_listener
-  heed_answer "$heed_fallback"
-}
+  --data-binary @- 2>/dev/null)" || heed_unanswered
+
+# Only this machine's listener names the proof from endpoint.env (0.3.4 on); any other answer goes to the fallback, which
+# keeps the event. A port and token pinned in the environment come without the proof line, unless ${PROOF_KEY} is pinned
+# too: the fallback derives it from the token.
+# shortcut: pinned without ${PROOF_KEY}, every hook pays a Node start and the fallback's ${RETRY_AFTER_MS} ms pause before it asks again (sh has no HMAC that keeps the token off argv); derive the proof here if such setups show up.
+reply="$(printf '%s\\n' "$reply" | tr -d '\\r')"
+heed_proof="$(printf '%s\\n' "$reply" | sed -n '/^$/q; s/^[Xx]-[Hh][Ee][Ee][Dd]-[Ll][Ii][Ss][Tt][Ee][Nn][Ee][Rr]: //p')"
+[ -n "\${${PROOF_KEY}:-}" ] && [ "$heed_proof" = "\$${PROOF_KEY}" ] || heed_unanswered
+reply="$(printf '%s\\n' "$reply" | sed '1,/^$/d')"
 
 # The listener's answer is the agent's hook output (skill check, steering, recalled memory).
 case "$reply" in
@@ -184,21 +140,45 @@ esac
 export function agentHooksDir(home) {
     return join(home, ".heed", "agent-hooks");
 }
-/** Write (or update) the dispatcher script for one agent. Idempotent, mode 0700. */
+/** Write (or update) the dispatcher script for one agent, mode 0700, and the fallback it runs beside it. Idempotent. */
 export async function writeDispatcherScript(home, agent, options = {}) {
     validateAgentId(agent);
     const dir = agentHooksDir(home);
     await mkdir(dir, { recursive: true, mode: 0o700 });
-    const target = join(dir, `${agent}-hook.sh`);
-    const content = dispatcherScript(agent, options);
-    const existing = await currentDispatcherScript(target);
-    if (existing === content)
+    await writeWhenChanged(join(dir, `${agent}-hook.sh`), dispatcherScript(agent, options));
+    await Promise.resolve()
+        .then(() => writeWhenChanged(join(dir, FALLBACK_FILE), guardSource()))
+        .catch(() => undefined); // without its fallback a dispatcher still answers, with the plain fallback answer
+}
+/**
+ * Names the Node running this install in `node` beside the dispatchers, for every hook's fallback (the dispatchers' and
+ * Hermes'). It is the PATH entry that links to that Node when there is one: Homebrew's /opt/homebrew/bin/node outlives
+ * `brew upgrade`, the Cellar path it links to does not. Git Bash on Windows runs C:/… paths, so no backslashes.
+ */
+export async function writeHookNode(home, path = process.env["PATH"] ?? "") {
+    const real = realpathOrNull(process.execPath);
+    const linked = path.split(delimiter).map((dir) => join(dir, basename(process.execPath))).find((candidate) => real !== null && realpathOrNull(candidate) === real);
+    // The link first, as it outlives `brew upgrade`; then the Node itself, which outlives a per-shell link (fnm's ends with its shell).
+    const nodes = [...new Set([linked, real ?? process.execPath])].filter((node) => node !== undefined);
+    await mkdir(agentHooksDir(home), { recursive: true, mode: 0o700 });
+    await writeWhenChanged(join(agentHooksDir(home), HOOK_NODE_FILE), nodes.map((node) => `${node.replaceAll("\\", "/")}\n`).join(""));
+}
+function realpathOrNull(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null; // not there: not the Node that runs this
+    }
+}
+async function writeWhenChanged(target, content) {
+    if ((await currentText(target)) === content)
         return; // already current
     await writeFileAtomic(target, content, { mode: 0o700 });
     await chmod(target, 0o700);
 }
-/** The dispatcher script's current text, or null when absent (it will be written below). */
-async function currentDispatcherScript(target) {
+/** The file's current text, or null when absent (it will be written). */
+async function currentText(target) {
     try {
         return await readFile(target, "utf8");
     }

package/dist/doctor.d.ts

@@ -34,4 +34,6 @@ export interface DoctorInput {
     /** Desired-entry lookup injection; defaults to the pure planner. */
     desired?: DesiredEntryLookup;
 }
+/** The oldest Node the CLI runs on, as package.json's `engines` states it: 22.5 has path.matchesGlob, which steering rules with file patterns run on. */
+export declare const NODE_FLOOR = "22.5";
 export declare function runDoctor(input: DoctorInput): Promise<DoctorReport>;

package/dist/doctor.js

@@ -3,18 +3,20 @@
  * remediation}. The desired-entry lookup is injected (defaulting to the
  * pure planner's desiredEntriesFor) so this module never imports apply.ts.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
 import { entryValue, parseDoc, readEntry, valuesEqual } from "./config-doc.js";
 import { loadHeedFileAt } from "./heed-file.js";
-import { desiredEntriesFor, heedvaneConnector, hooksDeferredTo, isClientDetected, legacyMcpEntries } from "./plan.js";
-import { MCP_NEEDS_ORG, connectorEntry } from "./mcp.js";
+import { bridgeNodeDir, connectionOff, desiredEntriesFor, heedvaneConnector, heedvaneMcpEntries, hooksDeferredTo, isClientDetected, legacyMcpEntries, supportsCapability } from "./plan.js";
+import { MCP_NEEDS_ORG, MCP_OFF_METRICS_ONLY, ORG_KEY_ENV, ORG_REMEDIATION, comparableEntry, connectorEntry, keyConnectorEntry } from "./mcp.js";
 import { readInstalledSkillDigest } from "./skill/bundle.js";
 import { HeedStateCorruptError, readState } from "./state.js";
 import { readApprovedSkills } from "./skills/approved.js";
-import { pingListener, readEndpoint } from "./listener/endpoint.js";
+import { HEEDVANE_VERSION, listenerVerdict, probeListener, readEndpoint } from "./listener/endpoint.js";
+import { settingsToRun } from "./listener/serve.js";
 import { errorMessage } from "./guards.js";
+import { HOOK_NODE_FILE } from "./hook-fallback.js";
 const INIT_REMEDIATION = "run npx heedvane init";
 const SETUP_REMEDIATION = "run npx heedvane setup";
 /** Inspect one desired entry on disk; every failure path produces a detail line, never a throw. */
@@ -23,6 +25,11 @@ function entryVerdict(d, home) {
     if (!existsSync(path)) {
         return { aligned: false, present: false, detail: `${d.entryName}: missing (${d.path})` };
     }
+    if (d.containerKey === "") {
+        // Whole-file desired (Hermes' plugin files, Pi's guard extension): compared byte for byte, never parsed as a config.
+        const ok = readFileSync(path, "utf8") === d.entry;
+        return { aligned: ok, present: true, detail: `${d.entryName}: ${ok ? "aligned" : "stale"}` };
+    }
     let doc;
     try {
         doc = parseDoc(readFileSync(path, "utf8"), d.format);
@@ -30,16 +37,11 @@ function entryVerdict(d, home) {
     catch {
         return { aligned: false, present: true, detail: `${d.entryName}: config does not parse` };
     }
-    if (d.containerKey === "") {
-        // Whole-file desired (hermes plugin.yaml).
-        const ok = readFileSync(path, "utf8") === d.entry;
-        return { aligned: ok, present: true, detail: `${d.entryName}: ${ok ? "aligned" : "stale"}` };
-    }
     const current = readEntry(doc, d.containerKey, d.entryName);
     if (current === undefined) {
         return { aligned: false, present: true, detail: `${d.entryName}: missing in ${d.path}` };
     }
-    if (!valuesEqual(current, entryValue(d.containerKey, current, d.entry))) {
+    if (!valuesEqual(comparableEntry(current), comparableEntry(entryValue(d.containerKey, current, d.entry)))) {
         return { aligned: false, present: true, detail: `${d.entryName}: stale in ${d.path}` };
     }
     return { aligned: true, present: true, detail: `${d.entryName}: aligned` };
@@ -62,14 +64,17 @@ function registrationState(desireds, home) {
         return { state: "stale", detail: parts.join("; ") };
     return { state: "aligned", detail: parts.join("; ") };
 }
+/** The oldest Node the CLI runs on, as package.json's `engines` states it: 22.5 has path.matchesGlob, which steering rules with file patterns run on. */
+export const NODE_FLOOR = "22.5";
 function checkNode() {
-    const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-    const ok = major >= 22;
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    const [floorMajor = 0, floorMinor = 0] = NODE_FLOOR.split(".").map(Number);
+    const ok = major > floorMajor || (major === floorMajor && minor >= floorMinor);
     return {
         ok,
         name: "node",
-        detail: `node ${process.versions.node} (${ok ? ">= 22" : "< 22 — heedvane requires Node 22+"})`,
-        remediation: ok ? undefined : "upgrade Node to >= 22 (nvm install 22)",
+        detail: `node ${process.versions.node} (${ok ? `>= ${NODE_FLOOR}` : `< ${NODE_FLOOR} — heedvane requires Node ${NODE_FLOOR} or later`})`,
+        remediation: ok ? undefined : `upgrade Node to ${NODE_FLOOR} or later (nvm install ${floorMajor})`,
     };
 }
 function checkHeedFile(home) {
@@ -117,7 +122,7 @@ function defaultDesiredLookup(home, env, heedFile) {
         const client = supportedClients({ home, platform: process.platform, env }).find((c) => c.id === clientId);
         if (!client)
             return undefined;
-        return desiredEntriesFor(client, capability, { home, env, connector }).map((d) => ({
+        return desiredEntriesFor(client, capability, { home, env, connector, nodeDir: bridgeNodeDir(process.platform), gating: heedFile?.gating.mode }).map((d) => ({
             path: d.path,
             format: d.format,
             containerKey: d.containerKey,
@@ -159,11 +164,11 @@ function heedFileWants(client, capability, ctx) {
 function collectCapabilityStates(client, ctx) {
     const states = [];
     for (const capability of ["hooks", "mcp"]) {
-        const supported = client.capabilities.includes(capability) || (capability === "hooks" && client.id === "hermes" && client.capabilities.includes("plugin-install"));
+        const supported = supportsCapability(client, capability);
         if (!supported || !heedFileWants(client, capability, ctx))
             continue;
         const desireds = ctx.desired(client.id, capability) ?? [];
-        const result = capability === "mcp" ? mcpConnectionState(client, desireds, ctx.home) : hooksState(desireds, ctx.home);
+        const result = capability === "mcp" ? mcpConnectionState(client, desireds, ctx) : hooksState(desireds, ctx.home);
         if (result !== undefined)
             states.push({ capability, result });
     }
@@ -174,14 +179,28 @@ function hooksState(desireds, home) {
     return desireds.length > 0 ? registrationState(desireds, home) : undefined;
 }
 /** Heedvane's MCP connection: stale while an earlier version's entry is left, missing without an organization, else the registration verdict. */
-function mcpConnectionState(client, desireds, home) {
+function mcpConnectionState(client, desireds, { home, env, heedFile }) {
+    if (heedFile !== undefined && connectionOff(heedFile) === "metrics-only") {
+        const left = heedvaneMcpEntries(client);
+        return left === undefined ? undefined : { state: "stale", detail: `${left.names.join(", ")} in ${left.path}: ${MCP_OFF_METRICS_ONLY}; npx -y heedvane connect removes it` };
+    }
     const legacy = legacyMcpEntries(client);
+    if (legacy !== undefined && desireds.length === 0)
+        return { state: "stale", detail: `${legacy.names.join(", ")} in ${legacy.path} is an earlier version's entry; ${MCP_NEEDS_ORG}`, remediation: ORG_REMEDIATION };
     if (legacy !== undefined)
-        return { state: "stale", detail: `${legacy.names.join(", ")} in ${legacy.path} is an earlier version's entry; npx heedvane connect replaces it` };
+        return { state: "stale", detail: `${legacy.names.join(", ")} in ${legacy.path} is an earlier version's entry; npx -y heedvane connect replaces it` };
+    const connector = heedFile === undefined ? undefined : heedvaneConnector(heedFile);
+    const keyForm = connector === undefined ? undefined : keyConnectorEntry(client.id, connector);
     if (desireds.length > 0)
-        return registrationState(desireds, home);
+        return withKeyNote(registrationState(desireds, home), desireds.some((desired) => valuesEqual(desired.entry, keyForm)), env);
     // Agents the connection is not registered in have nothing to check.
-    return connectorEntry(client.id, "") === undefined ? undefined : { state: "missing", detail: MCP_NEEDS_ORG };
+    return connectorEntry(client.id, "") === undefined ? undefined : { state: "missing", detail: MCP_NEEDS_ORG, remediation: ORG_REMEDIATION };
+}
+/** A software factory's connection sends HEEDVANE_ORG_KEY from the agent's environment, so doctor says when its own lacks it. */
+function withKeyNote(result, sendsKey, env) {
+    if (!sendsKey || env[ORG_KEY_ENV]?.trim())
+        return result;
+    return { ...result, detail: `${result.detail}; it sends ${ORG_KEY_ENV}, which is not set here: set it where the agent runs` };
 }
 /** One detected client's registration check (aligned / stale / missing with per-entry detail). */
 function pushRegistrationChecks(checks, client, ctx) {
@@ -205,11 +224,12 @@ function pushRegistrationChecks(checks, client, ctx) {
         return;
     const allAligned = states.every((s) => s.result.state === "aligned");
     const detail = states.map((s) => `${s.capability}: ${s.result.state} (${s.result.detail})`).join("; ");
+    const remedies = new Set(states.filter((s) => s.result.state !== "aligned").map((s) => s.result.remediation ?? SETUP_REMEDIATION));
     checks.push({
         ok: allAligned,
         name: `${client.id} registration`,
         detail,
-        remediation: allAligned ? undefined : SETUP_REMEDIATION,
+        remediation: allAligned ? undefined : [...remedies].join("; "),
     });
 }
 /** The skill-digest verdict against state.json (aligned / stale / missing / unrecorded). */
@@ -266,6 +286,7 @@ export async function runDoctor(input) {
     }
     // 7. Listener reachable — best-effort POST, warn-only, never fails the report.
     checks.push(await checkListener(root));
+    checks.push(checkHookNode(root));
     checks.push(await checkApprovedSkills(root, heedFile));
     const healthy = checks.every((c) => c.ok || c.warnOnly);
     return { healthy, checks, scopedTo: scope ? [...scope] : undefined };
@@ -292,6 +313,42 @@ async function checkApprovedSkills(root, heedFile) {
         return { ...base, ok: false, detail: `${list.skills.length} approved, synced ${list.syncedAt}: revocations since then are not enforced`, remediation: sync };
     return { ...base, detail: `${list.skills.length} approved, synced ${list.syncedAt}` };
 }
+/** The Node every hook's fallback runs with (agent-hooks/node), which `brew upgrade` or `nvm uninstall` can remove. */
+function checkHookNode(root) {
+    const dir = join(root, "agent-hooks");
+    const nodes = existsSync(join(dir, HOOK_NODE_FILE)) ? readFileSync(join(dir, HOOK_NODE_FILE), "utf8").split("\n").filter(Boolean) : [];
+    const base = { name: "hooks' Node", warnOnly: true };
+    const node = nodes.find(isExecutable);
+    if (node !== undefined)
+        return { ...base, ok: true, detail: node };
+    // Hooks installed before the file was written (0.3.3 and earlier) have none.
+    if (nodes.length === 0 && !(existsSync(dir) && readdirSync(dir).some((name) => name.endsWith("-hook.sh"))))
+        return { ...base, ok: true, detail: "no hooks installed" };
+    const missing = nodes.length === 0 ? "not recorded" : `${nodes.join(" and ")} ${nodes.length === 1 ? "is" : "are"} gone`;
+    return { ...base, ok: false, detail: `${missing}, so hooks that cannot reach the listener fall back to node on PATH, if there is one`, remediation: "npx heedvane connect" };
+}
+/** A listener the verdict keeps. One before 0.3.4, kept because no settings parse, cannot prove itself: the hooks keep their events instead. */
+function keptListener(running, at) {
+    if (running.settings !== undefined)
+        return { detail: `reachable on ${at}` };
+    return { ok: false, detail: `an older listener (${running.version || "before 0.3.4"}) runs on ${at}, which the hooks do not use: events spool until heed.yaml parses and a listener of this version starts` };
+}
+/** A newer listener: this npx heedvane is older; the newer one applies the settings when it runs earlier ones. */
+function newerListener(running, current, at) {
+    const older = `this npx heedvane (${HEEDVANE_VERSION}) is older`;
+    if (current !== null && running.settings !== current)
+        return { detail: `a newer listener (${running.version}) runs on ${at} with the earlier settings; ${older}`, remediation: "npx -y heedvane@latest listener restart" };
+    return { detail: `a newer listener (${running.version}) runs on ${at}; ${older}`, remediation: "npx -y heedvane@latest doctor" };
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false; // removed, or not a program
+    }
+}
 async function checkListener(root) {
     const base = { ok: true, name: "listener", detail: "", warnOnly: true };
     let endpoint;
@@ -310,10 +367,21 @@ async function checkListener(root) {
     if (!endpoint.port) {
         return { ...base, detail: "endpoint.env incomplete (no port) — re-run npx heedvane setup" };
     }
-    if (await pingListener(endpoint))
-        return { ...base, detail: `reachable on 127.0.0.1:${endpoint.port}` };
-    return {
-        ...base,
-        detail: `not reachable on 127.0.0.1:${endpoint.port} — ${ENFORCEMENT_OFF}; events will spool (warn-only; never fails the report)`,
-    };
+    const running = await probeListener(endpoint);
+    const at = `127.0.0.1:${endpoint.port}`;
+    // The verdict every command acts on (src/listener/background.ts ensureListener): doctor only reports it.
+    const current = await settingsToRun(root).then((settings) => settings.hash, () => null);
+    switch (listenerVerdict(running, current)) {
+        case "keep":
+            return { ...base, ...keptListener(running, at) };
+        case "start":
+            return { ...base, detail: `not reachable on ${at} — ${ENFORCEMENT_OFF}; events will spool (warn-only; never fails the report)` };
+        case "newer":
+            return { ...base, ok: false, ...newerListener(running, current, at) };
+        case "replace":
+            return { ...base, ok: false, detail: `an older listener (${running?.version || "before 0.3.4"}) runs on ${at}`, remediation: "npx heedvane listener restart" };
+        case "restart":
+            // A hand edit of heed.yaml, or a sign-in no command saw, reaches a running listener only through a restart.
+            return { ...base, ok: false, detail: `runs on ${at} with the settings it started with; heed.yaml or the sign-in changed since`, remediation: "npx heedvane listener restart" };
+    }
 }

package/dist/guard.d.ts

@@ -0,0 +1,73 @@
+export interface ToolCallQuestion {
+    tool: string;
+    input: unknown;
+    id?: string;
+    session?: string;
+    cwd?: string;
+    /** Shows the person a notice, where the agent can (Pi's `ctx.ui.notify`); stderr when not given. */
+    tell?: (notice: string) => void;
+}
+/**
+ * Heedvane's reason to refuse this tool call, or undefined to let it run. It never throws: when the listener cannot
+ * answer (none runs, another program holds its port, or it answers with an error) the event is spooled for it to
+ * replay and the tool runs, as with every agent's hooks.
+ */
+export declare function heedvaneRefusal(call: ToolCallQuestion): Promise<string | undefined>;
+/** An event no listener answered: the agent's id, the hook's JSON text, its event id and its session. */
+interface Unanswered {
+    source: string;
+    payload: string;
+    id: string;
+    session: string;
+}
+/**
+ * Every agent's fallback when the listener gives no answer: keeps the event in the spool for the listener to replay,
+ * starts a listener (on any failure: on Windows a refused loopback connection outlasts the timeout), and says whether
+ * the session is yet to be told that its calls are not checked; its marker is written now. Never throws.
+ */
+export declare function keepUnanswered(root: string, unanswered: Unanswered): boolean;
+/** Pi's core: `new Agent({ beforeToolCall })`, or `agent.beforeToolCall = beforeToolCall`. */
+export declare function beforeToolCall(context: {
+    toolCall: {
+        id: string;
+        name: string;
+    };
+    args: unknown;
+}): Promise<{
+    block: true;
+    reason: string;
+} | undefined>;
+/** Pi Durable: `defineExtension({ name: "heedvane", hooks: [hook(ToolTask, { beforeTool })] })`. Its conversation is the session. */
+export declare function beforeTool(call: {
+    id: string;
+    name: string;
+    arguments: unknown;
+}, api?: {
+    conversationId?: string | number;
+}): Promise<{
+    block: string;
+} | undefined>;
+interface PiToolCallEvent {
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+}
+interface PiContext {
+    cwd?: string;
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+    /** False in print and JSON modes, which have no UI. */
+    hasUI?: boolean;
+    ui?: {
+        notify?: (message: string, type?: "info" | "warning" | "error") => void;
+    };
+}
+/** The Pi coding agent's extension entry point. */
+export default function heedvane(pi: {
+    on(event: "tool_call", handler: (event: PiToolCallEvent, ctx: PiContext) => Promise<{
+        block: true;
+        reason: string;
+    } | undefined>): unknown;
+}): void;
+export {};