heedvane 0.2.1 → 0.3.4

package/dist/doctor.js

@@ -3,17 +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, hooksDeferredTo, isClientDetected } from "./plan.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. */
@@ -22,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);
@@ -29,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` };
@@ -61,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) {
@@ -109,13 +115,14 @@ void checkState;
 function scopeSet(clients) {
     return clients && clients.length > 0 ? new Set(clients) : null;
 }
-/** The pure-planner desired-entry lookup, resolving each client id against home/env. */
-function defaultDesiredLookup(home, env) {
+/** The pure-planner desired-entry lookup, resolving each client id against home/env and heed.yaml's organization. */
+function defaultDesiredLookup(home, env, heedFile) {
+    const connector = heedFile === undefined ? undefined : heedvaneConnector(heedFile);
     return (clientId, capability) => {
         const client = supportedClients({ home, platform: process.platform, env }).find((c) => c.id === clientId);
         if (!client)
             return undefined;
-        return desiredEntriesFor(client, capability, { home, env }).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,
@@ -157,16 +164,44 @@ 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);
-        if (!desireds || desireds.length === 0)
-            continue;
-        states.push({ capability, result: registrationState(desireds, ctx.home) });
+        const desireds = ctx.desired(client.id, capability) ?? [];
+        const result = capability === "mcp" ? mcpConnectionState(client, desireds, ctx) : hooksState(desireds, ctx.home);
+        if (result !== undefined)
+            states.push({ capability, result });
     }
     return states;
 }
+/** The hooks' registration verdict, when this client has hooks to register. */
+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, 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 -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 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, 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) {
     const detected = isClientDetected(client);
@@ -189,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). */
@@ -233,7 +269,7 @@ export async function runDoctor(input) {
     const root = join(home, ".heed");
     const state = await readStateOrReport(root, checks);
     // 4. Desired-entry lookup: injected, falling back to the pure planner.
-    const desired = input.desired ?? defaultDesiredLookup(home, env);
+    const desired = input.desired ?? defaultDesiredLookup(home, env, heedFile);
     // 5. Per detected client: registration state aligned | stale | missing.
     const scope = scopeSet(input.clients);
     const allClients = supportedClients({ home, platform: process.platform, env });
@@ -250,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 };
@@ -276,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;
@@ -294,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 {};

package/dist/guard.js

@@ -0,0 +1,302 @@
+// heedvane: Heedvane's guard for Pi. It asks the local Heedvane listener before each tool runs, and lets the tool run when it cannot ask.
+//
+// One file serves every Pi:
+// - The Pi coding agent loads it as an extension: `npx -y heedvane connect --agent pi` copies it to
+//   `<Pi's agent folder>/extensions/heedvane.ts`, and `npx -y heedvane uninstall` removes it.
+// - Code built on Pi's core (`@earendil-works/pi-agent-core`): `new Agent({ ..., beforeToolCall })`.
+// - Pi Durable (`@earendil-works/pi-durable`), which does not run on Pi's core: `hook(ToolTask, { beforeTool })`.
+// It imports only Node's own modules and src/hook-fallback.ts, which the copy carries inline, so it runs on its own.
+// It is also every agent's fallback when the listener cannot answer ({@link keepUnanswered}): the dispatchers and
+// Hermes run its copy `fallback.mjs` with UNANSWERED_FLAG. It spools the event for the listener to replay, starts a
+// listener, tells the person once per session that calls are not checked, and lets the tool run.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join, sep } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { parseEnv } from "node:util";
+import { HOOK_TIMEOUT_MS, LISTENER_START, OTHER_SIGN_IN_DIR, PANE_KEY_ENV, listenerProof, PROBE_REFUSAL, PROOF_HEADER, SESSION_START_TIMEOUT_MS, SPOOL_CAP_BYTES, SPOOL_DIR, SPOOL_ENV, SPOOL_FILE_PREFIX, SPOOL_FILE_SUFFIX, SPOOL_TTL_DAYS, START_LOCK, START_LOCK_HOLDER, START_LOCK_MINUTES, RETRY_AFTER_MS, UNANSWERED_FLAG, UNCHECKED_ERROR_NOTICE, UNCHECKED_MARK_PREFIX, UNCHECKED_NOTICE } from "./hook-fallback.js";
+/** heed.yaml `gating.mode`, set in the copy `connect` installs: `pane` asks only in sessions started with HEED_SESSION. Code that imports the guard always asks. */
+const GATING = "always";
+/** Pi's built-in tools under Claude Code's names, the names Heedvane's rules list. */
+const RULE_TOOL_NAMES = { bash: "Bash", read: "Read", edit: "Edit", write: "Write", grep: "Grep", find: "Glob", ls: "LS" };
+const FALLBACK_REASON = "Heedvane's rules refuse this tool call.";
+/**
+ * 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 async function heedvaneRefusal(call) {
+    let asked;
+    try {
+        if (GATING !== "always" && !process.env["HEED_SESSION"])
+            return undefined;
+        asked = { place: listenerPlace(), event: { event: hookEvent(call), id: randomUUID() } };
+        const question = { agent: "pi", body: JSON.stringify(asked.event.event), id: asked.event.id };
+        const answer = await listenerAnswer(asked.place, question).catch((err) => {
+            return askAgain(asked.place, question, err); // its second answer; a refusal of the listener's own is rethrown there
+        });
+        return refusalIn(answer);
+    }
+    catch (err) {
+        if (refusedWith(err) === undefined)
+            keepForTheListener(call, asked, err);
+        else if (noteRefused(asked.place.root, err, { source: "pi", payload: JSON.stringify(asked.event.event), id: asked.event.id, session: asked.event.event.session_id }))
+            tell(call, UNCHECKED_ERROR_NOTICE);
+        return undefined;
+    }
+}
+/** The process's folder; the home folder when it cannot say (its folder was removed). */
+function cwdOrHome() {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return homedir();
+    }
+}
+/** The call as Claude Code's PreToolUse, with Claude Code's tool names. */
+function hookEvent(call) {
+    return {
+        hook_event_name: "PreToolUse",
+        session_id: call.session ?? process.env["HEED_SESSION"] ?? `pi-${process.pid}`,
+        cwd: call.cwd ?? cwdOrHome(),
+        tool_name: RULE_TOOL_NAMES[call.tool] ?? call.tool,
+        tool_input: call.input,
+        tool_use_id: call.id,
+    };
+}
+/**
+ * The port and token from HEED_AGENT_HOOK_PORT and HEED_AGENT_HOOK_TOKEN when both are set, else from the endpoint file:
+ * HEED_AGENT_HOOK_ENDPOINT, else endpoint.env in HEED_AGENT_HOOK_ROOT (which `heedvane run` sets), else in ~/.heed.
+ * An empty variable counts as unset, as in the dispatchers.
+ */
+function listenerPlace() {
+    const endpointFile = process.env["HEED_AGENT_HOOK_ENDPOINT"] || join(process.env["HEED_AGENT_HOOK_ROOT"] || join(homedir(), ".heed"), "endpoint.env");
+    const root = dirname(endpointFile);
+    const fromEnv = { port: process.env["HEED_AGENT_HOOK_PORT"], token: process.env["HEED_AGENT_HOOK_TOKEN"] };
+    if (fromEnv.port && fromEnv.token)
+        return { root, ...fromEnv };
+    try {
+        const values = parseEnv(readFileSync(endpointFile, "utf8"));
+        return { root, port: values["HEED_AGENT_HOOK_PORT"], token: values["HEED_AGENT_HOOK_TOKEN"] };
+    }
+    catch {
+        return { root }; // no endpoint file: nothing to ask, the event is spooled
+    }
+}
+/**
+ * The listener's answer; throws when there is none: no endpoint, nothing listening, another program, or an error
+ * answer. An error answer from a listener that names its settings (0.3.4 on), other than 503 (it is stopping), is its
+ * own answer to this event: the error carries its status as `refused`, and starting another listener would change nothing.
+ */
+async function listenerAnswer(place, { agent, body, id }) {
+    if (!place.port || !place.token)
+        throw new Error("no listener endpoint");
+    const route = `http://127.0.0.1:${place.port}/hook/${agent}`;
+    // Every call, since the port can change hands between calls; a probe on loopback costs well under a millisecond.
+    const probe = await fetch(route, { signal: AbortSignal.timeout(HOOK_TIMEOUT_MS) });
+    const about = (probe.status === 405 ? await probe.json() : {});
+    // Only this machine's listener names the proof of its token; a listener before 0.3.4 names none, and is never asked.
+    // shortcut: proof is static and readable by GET; another OS user can replay it — challenge-response (nonce + HMAC, no token on the wire) right after this PR
+    const proof = await listenerProof(place.token);
+    const proven = (answer) => answer.headers.get(PROOF_HEADER) === proof;
+    if (about.error !== PROBE_REFUSAL || !proven(probe))
+        throw new Error(`another program answers on 127.0.0.1:${place.port}`);
+    const response = await fetch(route, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Heed-Agent-Hook-Token": place.token, "X-Heed-Hook-Version": "1", "X-Heed-Event-Id": id },
+        body,
+        // As long as the dispatcher's own ask: a session start waits for Heedvane's team memory.
+        signal: AbortSignal.timeout(/"hook_event_name": ?"SessionStart"/.test(body) ? SESSION_START_TIMEOUT_MS : HOOK_TIMEOUT_MS),
+    });
+    if (!proven(response))
+        throw new Error(`another program answers on 127.0.0.1:${place.port}`);
+    if (!response.ok)
+        throw Object.assign(new Error(`the listener answered ${response.status}`), { refused: typeof about.settings === "string" && response.status !== 503 ? response.status : undefined });
+    return response.json();
+}
+/** The listener's answer after one pause, unless `failed` was its own error answer: a listener taking over from another binds within milliseconds. */
+async function askAgain(place, question, failed) {
+    if (refusedWith(failed) !== undefined)
+        throw failed;
+    // Nothing to ask without a port and a token (no endpoint.env: heedvane/guard without Heedvane installed), so no pause.
+    if (!place.port || !place.token)
+        throw failed ?? new Error("no listener endpoint");
+    await delay(RETRY_AFTER_MS);
+    return listenerAnswer(place, question);
+}
+/** The status of the listener's own error answer to this event (see {@link listenerAnswer}), or undefined. */
+function refusedWith(err) {
+    const status = err?.refused;
+    return typeof status === "number" ? status : undefined;
+}
+/**
+ * A current listener answered this event with an error: the call runs, the listener's log says so, and this says
+ * whether the session is yet to be told (once, by its own marker). A server error (5xx) may pass, so the event is kept
+ * for the listener to replay; a refused request (4xx) would be refused again.
+ */
+function noteRefused(root, err, unanswered) {
+    // shortcut: the kept event waits for the next listener start to replay it, upgrade if a running listener should drain its spool.
+    if ((refusedWith(err) ?? 0) >= 500)
+        attempt(() => spoolEvent(root, unanswered));
+    attempt(() => appendFileSync(join(root, "listener.log"), `[heedvane] ${String(err)} to a hook; the call ran unchecked\n`, { mode: 0o600 }));
+    return attempt(() => markTold(root, `error-${unanswered.session}`)) === true;
+}
+/** The reason in the listener's `{block: true, reason}`, or undefined when it lets the call run. */
+function refusalIn(answer) {
+    if (typeof answer !== "object" || answer === null || answer.block !== true)
+        return undefined;
+    const reason = answer.reason;
+    return typeof reason === "string" && reason !== "" ? reason : FALLBACK_REASON;
+}
+/**
+ * Pi's call the listener did not answer, kept for it ({@link keepUnanswered}), the session told once. `asked` is
+ * undefined when the guard failed before it could ask: the call is then built again here and the failure logged.
+ * It never throws into Pi.
+ */
+function keepForTheListener(call, asked, err) {
+    const { place, event } = asked ?? { place: { root: join(homedir(), ".heed") }, event: { event: hookEvent(call), id: randomUUID() } };
+    const unanswered = { source: "pi", payload: JSON.stringify(event.event), id: event.id, session: event.event.session_id };
+    if (keepUnanswered(place.root, unanswered))
+        tell(call, UNCHECKED_NOTICE);
+    if (asked === undefined)
+        attempt(() => appendFileSync(join(place.root, "listener.log"), `[heedvane] Pi's guard could not ask the listener (${String(err)}); the call ran unchecked and is spooled\n`, { mode: 0o600 }));
+}
+/** Shows the person `notice` where Pi can (its notice, or stderr); never throws into Pi. */
+function tell(call, notice) {
+    attempt(() => (call.tell ?? ((text) => tellPerson(undefined, text)))(notice));
+}
+/**
+ * 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 function keepUnanswered(root, unanswered) {
+    attempt(() => spoolEvent(root, unanswered));
+    attempt(() => startListener(root));
+    return attempt(() => markTold(root, unanswered.session)) === true;
+}
+/** `step`'s result, or undefined when it throws (a full disk, a read-only home, a start already under way): the tool still runs. */
+function attempt(step) {
+    try {
+        return step();
+    }
+    catch {
+        return undefined; // the fallback's own failure never reaches the agent
+    }
+}
+/** The spool record, in the pane's file, which the listener replays when it starts; spool files past their TTL go first. */
+function spoolEvent(root, { source, payload, id }) {
+    const pane = PANE_KEY_ENV.map((variable) => process.env[variable]).find(Boolean) ?? "";
+    const dir = join(root, SPOOL_DIR);
+    const file = join(dir, `${SPOOL_FILE_PREFIX}${pane || "default"}${SPOOL_FILE_SUFFIX}`);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    attempt(() => pruneSpool(dir)); // a prune that fails (an older Node in Pi, a file another hook just removed) never costs the event
+    if ((statSync(file, { throwIfNoEntry: false })?.size ?? 0) >= SPOOL_CAP_BYTES)
+        return;
+    const fromEnv = Object.fromEntries(Object.entries(SPOOL_ENV).map(([field, variable]) => [field, process.env[variable] ?? ""]));
+    const record = { paneKey: pane, ...fromEnv, source, receivedAt: new Date().toISOString(), id, payload };
+    appendFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+/** Removes spool files, told markers and the events set aside after a change of sign-in that are older than SPOOL_TTL_DAYS. */
+function pruneSpool(dir) {
+    const cutoff = Date.now() - SPOOL_TTL_DAYS * 86_400_000;
+    for (const entry of readdirSync(dir, { recursive: true, withFileTypes: true })) {
+        const path = join(entry.parentPath, entry.name);
+        const pruned = entry.name.startsWith(SPOOL_FILE_PREFIX) || entry.name.startsWith(UNCHECKED_MARK_PREFIX) || path.includes(`${sep}${OTHER_SIGN_IN_DIR}${sep}`);
+        if (entry.isFile() && pruned && statSync(path).mtimeMs < cutoff)
+            rmSync(path, { force: true });
+    }
+}
+/** Writes the session's told marker in the spool folder; false when it was there: the session has been told. */
+function markTold(root, session) {
+    const marker = join(root, SPOOL_DIR, `${UNCHECKED_MARK_PREFIX}${session.replace(/[^A-Za-z0-9_.-]/g, "") || "default"}`);
+    mkdirSync(dirname(marker), { recursive: true, mode: 0o700 });
+    closeSync(openSync(marker, "wx", 0o600)); // throws when the marker is there
+    return true;
+}
+/** LISTENER_START from the heed folder, in the background, at most once a minute; `listener start` decides whether one must start. */
+function startListener(root) {
+    if (process.env["HEED_LISTENER_AUTOSTART"] === "0" || basename(root) !== ".heed")
+        return;
+    const lock = join(root, START_LOCK);
+    const lockAge = Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
+    if (lockAge > START_LOCK_MINUTES * 60_000)
+        rmSync(lock, { recursive: true, force: true });
+    mkdirSync(lock); // throws when another start holds the lock
+    const log = openSync(join(root, "listener.log"), "a", 0o600);
+    try {
+        // From the heed folder: in the agent's project, npx could run a `heedvane` the project's package.json names.
+        // The folder of the Node that runs this is the last place to find npx: an agent started from a desktop app may have none on PATH.
+        const path = `${process.env["PATH"] ?? ""}${delimiter}${dirname(process.execPath)}`;
+        const [command, ...args] = LISTENER_START;
+        // Windows runs npx as npx.cmd, which Node starts only through a shell. Not run on Windows in this package's tests.
+        const child = spawn(command, args, { cwd: root, detached: true, windowsHide: true, shell: process.platform === "win32", stdio: ["ignore", log, log], env: { ...process.env, NODE_OPTIONS: undefined, PATH: path, HEED_HOME: dirname(root) } }); // Node drops undefined variables; the agent's NODE_OPTIONS are its project's
+        child.on("error", () => undefined); // no npx: the next start is a minute away
+        child.unref();
+        writeFileSync(join(lock, START_LOCK_HOLDER), String(child.pid ?? "")); // a command takes the lock over once this start has ended
+    }
+    finally {
+        closeSync(log);
+    }
+}
+/** Pi's core: `new Agent({ beforeToolCall })`, or `agent.beforeToolCall = beforeToolCall`. */
+export async function beforeToolCall(context) {
+    const reason = await heedvaneRefusal({ tool: context.toolCall.name, input: context.args, id: context.toolCall.id });
+    return reason === undefined ? undefined : { block: true, reason };
+}
+/** Pi Durable: `defineExtension({ name: "heedvane", hooks: [hook(ToolTask, { beforeTool })] })`. Its conversation is the session. */
+export async function beforeTool(call, api) {
+    const session = api?.conversationId === undefined ? undefined : `pi-durable-${api.conversationId}`;
+    const reason = await heedvaneRefusal({ tool: call.name, input: call.arguments, id: call.id, session });
+    return reason === undefined ? undefined : { block: reason };
+}
+/** The Pi coding agent's extension entry point. */
+export default function heedvane(pi) {
+    pi.on("tool_call", async (event, ctx) => {
+        const reason = await heedvaneRefusal({ tool: event.toolName, input: event.input, id: event.toolCallId, cwd: ctx?.cwd, session: sessionOf(ctx), tell: (notice) => tellPerson(ctx, notice) });
+        return reason === undefined ? undefined : { block: true, reason };
+    });
+}
+/** Pi's warning notice where it has a UI; on stderr in print and JSON modes, where a pipeline's log shows it. */
+function tellPerson(ctx, notice) {
+    if (ctx?.hasUI === true && ctx.ui?.notify !== undefined)
+        ctx.ui.notify(`Heedvane: ${notice}`, "warning");
+    else
+        process.stderr.write(`heedvane: ${notice}\n`);
+}
+function sessionOf(ctx) {
+    try {
+        return ctx?.sessionManager?.getSessionId?.();
+    }
+    catch {
+        return undefined; // a session manager that cannot say: the process's session stands in
+    }
+}
+/**
+ * `node fallback.mjs --heedvane-unanswered <agent> [notice field]`: the dispatchers' and Hermes' fallback, with the
+ * hook's event on stdin and the answer the hook gives without the listener in HEED_HOOK_FALLBACK_ANSWER. Keeps the
+ * event, and prints that answer with the notice in the agent's notice field the first time in a session.
+ */
+async function answerUnanswered([agent = "", noticeField]) {
+    const fallback = JSON.parse(process.env["HEED_HOOK_FALLBACK_ANSWER"] || "{}");
+    const payload = readFileSync(0, "utf8");
+    const place = listenerPlace();
+    const question = { agent, body: payload, id: process.env["HEED_HOOK_EVENT_ID"] || randomUUID() };
+    // The hook asked once already; a listener taking the port over answers the second time.
+    const answer = await askAgain(place, question, undefined).catch((err) => {
+        const unanswered = { source: agent, payload, id: question.id, session: sessionIn(payload) };
+        const [told, notice] = refusedWith(err) === undefined ? [keepUnanswered(place.root, unanswered), UNCHECKED_NOTICE] : [noteRefused(place.root, err, unanswered), UNCHECKED_ERROR_NOTICE];
+        return told && noticeField ? { [noticeField]: notice, ...fallback } : fallback;
+    });
+    process.stdout.write(`${JSON.stringify(answer)}\n`);
+}
+/** The hook event's session id, or "" when it names none. */
+function sessionIn(payload) {
+    const session = attempt(() => JSON.parse(payload).session_id);
+    return typeof session === "string" ? session : "";
+}
+if (process.argv[2] === UNANSWERED_FLAG)
+    void answerUnanswered(process.argv.slice(3));