heedvane 0.2.1 → 0.3.4

package/dist/uninstall.js

@@ -4,21 +4,21 @@
  * byte-identical. heed.yaml is NEVER touched (the user's file) unless
  * --purge-config is passed, and even then it is deleted, not rewritten.
  */
-import { existsSync, readFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
-import { hermesPluginOwned } from "./clients/hermes-plugin.js";
+import { removeHookFiles } from "./clients/hook-files.js";
 import { applyEntry } from "./apply.js";
-import { isOurHookGroup, parseDoc } from "./config-doc.js";
-import { isHeedvaneEntry } from "./mcp.js";
-import { hooksTarget, isClientDetected } from "./plan.js";
+import { isOurHookGroup } from "./config-doc.js";
+import { isHeedvaneEntry, isLegacyEntry, mcpEntryNames } from "./mcp.js";
+import { hooksTarget, isClientDetected, mcpContainers, parseClientDoc } from "./plan.js";
 import { skillInstallDir } from "./skill/bundle.js";
 import { statePath } from "./state.js";
 import { unlinkOptional } from "./best-effort.js";
-import { pingListener, readEndpoint } from "./listener/endpoint.js";
-import { SHUTDOWN_ROUTE } from "./listener/server.js";
-import { setTimeout as delay } from "node:timers/promises";
+import { endpointPath, pingListener, readEndpoint } from "./listener/endpoint.js";
+import { errorMessage } from "./guards.js";
+import { stopRunningListener } from "./listener/background.js";
+import { FALLBACK_FILE, HOOK_NODE_FILE } from "./hook-fallback.js";
 /** Hook events carrying one of our groups, with the user's own groups that must survive. */
 function ourHookEvents(doc) {
     const hooks = doc["hooks"];
@@ -28,28 +28,6 @@ function ourHookEvents(doc) {
         .filter(([, groups]) => Array.isArray(groups) && groups.some(isOurHookGroup))
         .map(([event, groups]) => ({ event, theirs: groups.filter((group) => !isOurHookGroup(group)) }));
 }
-function ourMcpEntryNames(doc, containerKeys) {
-    const names = [];
-    for (const key of containerKeys) {
-        const c = doc[key];
-        if (c === null || typeof c !== "object" || Array.isArray(c))
-            continue;
-        for (const [k, v] of Object.entries(c)) {
-            if (isHeedvaneEntry(k, v))
-                names.push(`${key}::${k}`);
-        }
-    }
-    return names;
-}
-/** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
-function parseClientDoc(path, format) {
-    try {
-        return parseDoc(readFileSync(path, "utf8"), format).value;
-    }
-    catch {
-        return null; // absent or unparseable — nothing marker-verified to remove
-    }
-}
 /**
  * Remove our hook groups from every event of one parsed config except those in `keep`, leaving the
  * user's own groups. Setup passes the events it installs, so a key an earlier version wrote under a
@@ -81,19 +59,40 @@ export async function removeDeferredHookGroups(client) {
     const doc = parseClientDoc(target.path, target.format);
     return doc === null ? [] : removeOurHookGroups(client, target, { doc, keep: new Set() });
 }
+/** Remove the MCP entries `match` accepts from one parsed config; one item per removal. */
+async function removeMcpEntries(client, target, scope) {
+    const items = [];
+    for (const qualified of mcpEntryNames(scope.doc, mcpContainers(client), scope.match)) {
+        const [containerKey, entryName] = qualified.split("::");
+        const res = await applyEntry(target, { containerKey, remove: entryName });
+        items.push({ clientId: client.id, name: `MCP ${entryName}`, path: target.path, status: res.status === "update" ? "removed" : "failed", detail: res.reason });
+    }
+    return items;
+}
+/**
+ * Setup's half for MCP: the entries an earlier version registered (the local helper, the connection's earlier name),
+ * removed from every config; under metrics only (`match` = isHeedvaneEntry), today's connection too.
+ */
+export async function removeLegacyMcpEntries(client, match = isLegacyEntry) {
+    const items = [];
+    for (const target of client.configs) {
+        if (target.format === "yaml")
+            continue;
+        const doc = parseClientDoc(target.path, target.format);
+        if (doc !== null)
+            items.push(...(await removeMcpEntries(client, { path: target.path, format: target.format }, { doc, match })));
+    }
+    return items;
+}
 /** Remove every marker-verified entry of one config file; one item per removal. */
 async function removeMarkedEntries(client, target, doc) {
     // Both kinds can live in the same file (claude settings.json carries
     // hooks AND mcpServers) — remove ours from every container.
     const items = await removeOurHookGroups(client, target, { doc, keep: new Set() });
-    for (const qualified of ourMcpEntryNames(doc, [client.mcpServersKey, "mcp_servers", "mcp"])) {
-        const [containerKey, entryName] = qualified.split("::");
-        const res = await applyEntry(target, { containerKey, remove: entryName });
-        items.push({ clientId: client.id, name: `MCP ${entryName}`, path: target.path, status: res.status === "update" ? "removed" : "failed", detail: res.reason });
-    }
+    items.push(...(await removeMcpEntries(client, target, { doc, match: isHeedvaneEntry })));
     return items;
 }
-/** One non-hermes client's config files: parse each and remove our marked entries. */
+/** One client's config files: parse each and remove our marked entries. */
 async function uninstallClientConfigs(client, items) {
     for (const target of client.configs) {
         if (target.format === "yaml")
@@ -116,12 +115,9 @@ export async function uninstall(input) {
             if (!existsMarker(client))
                 continue;
         }
-        if (client.id !== "hermes") {
-            await uninstallClientConfigs(client, items);
-        }
-        else {
-            items.push(await uninstallHermesPlugin(home));
-        }
+        await uninstallClientConfigs(client, items);
+        if (client.hookFiles !== undefined)
+            items.push(await uninstallHookFiles(client, client.hookFiles));
         // Agent-hook dispatcher scripts owned by this client.
         const script = join(home, ".heed", "agent-hooks", `${client.id}-hook.sh`);
         await unlinkOptional(script);
@@ -130,19 +126,16 @@ export async function uninstall(input) {
     items.push(...(await removeSharedFiles(home, scope !== null)));
     if (input.purgeConfig) {
         await unlinkOptional(join(home, ".heed", "heed.yaml"));
+        await unlinkOptional(join(home, ".heed", "heed.yaml.last-good")); // the listener's copy of it
         items.push({ clientId: "*", name: "heed.yaml (purged)", path: join(home, ".heed", "heed.yaml"), status: "removed" });
     }
     return items;
 }
-/** The Hermes plugin dir, removed only when its plugin.yaml declares our plugin. */
-async function uninstallHermesPlugin(home) {
-    const pluginDir = join(home, ".hermes", "plugins", "heedvane-hooks");
-    const item = { clientId: "hermes", name: "hermes plugin", path: pluginDir };
-    if (await hermesPluginOwned(home)) {
-        await rm(pluginDir, { recursive: true, force: true });
-        return { ...item, status: "removed" };
-    }
-    return existsSync(pluginDir) ? { ...item, status: "skipped", detail: "not ours — left untouched" } : { ...item, status: "absent" };
+/** Hooks written as whole files (Hermes' plugin, Pi's extension), removed only when Heedvane wrote them. */
+async function uninstallHookFiles(client, hookFiles) {
+    const path = hookFiles.path(client.markerPath);
+    const status = await removeHookFiles(hookFiles, path);
+    return { clientId: client.id, name: hookFiles.name, path, status, ...(status === "skipped" ? { detail: "not ours — left untouched" } : {}) };
 }
 /** The skill bundle and state.json every agent shares: a scoped uninstall keeps them. */
 async function removeSharedFiles(home, scoped) {
@@ -152,33 +145,41 @@ async function removeSharedFiles(home, scoped) {
     }
     await rm(skillDir, { recursive: true, force: true });
     await unlinkOptional(statePath(join(home, ".heed")));
+    await unlinkOptional(join(home, ".heed", "agent-hooks", FALLBACK_FILE)); // every dispatcher's, beside their scripts
+    await unlinkOptional(join(home, ".heed", "agent-hooks", HOOK_NODE_FILE));
     return [
         await stopListener(join(home, ".heed")),
         { clientId: "*", name: "skill bundle", path: skillDir, status: "removed" },
         { clientId: "*", name: "state.json", path: statePath(join(home, ".heed")), status: "removed" },
     ];
 }
-/** How long uninstall waits for the listener to stop answering after asking it to stop. */
-const STOP_WAIT_MS = 3_000;
-const STOP_POLL_MS = 100;
-/** The background listener answers hooks that are gone now: ask it to stop (POST /shutdown) and wait until it has. */
-async function stopListener(root) {
-    const endpoint = await readEndpoint(root).catch(() => null);
-    const item = { clientId: "*", name: "listener", path: `127.0.0.1:${endpoint?.port ?? 0}` };
-    if (endpoint === null || !(await pingListener(endpoint)))
-        return { ...item, status: "absent" };
-    const asked = await fetch(`http://127.0.0.1:${endpoint.port}${SHUTDOWN_ROUTE}`, {
-        method: "POST",
-        headers: { "x-heed-agent-hook-token": endpoint.token },
-        signal: AbortSignal.timeout(STOP_WAIT_MS),
-    }).catch(() => null);
-    for (let waited = 0; waited < STOP_WAIT_MS; waited += STOP_POLL_MS) {
-        if (!(await pingListener(endpoint)))
-            return { ...item, status: "removed" };
-        await delay(STOP_POLL_MS);
+/** Uninstall asks the background listener to stop (POST /shutdown) and waits until it has. */
+export async function stopListener(root) {
+    const unknownPort = (reason) => ({
+        clientId: "*",
+        name: "listener",
+        path: endpointPath(root),
+        status: "failed",
+        detail: `${reason}, so a listener still running cannot be asked to stop; it stops at logout or restart. Delete the file to clear this`,
+    });
+    let endpoint;
+    try {
+        endpoint = await readEndpoint(root);
+    }
+    catch (err) {
+        return unknownPort(`cannot read it (${errorMessage(err)})`);
     }
-    // A listener from 0.2.0 or earlier has no stop route (404); it ends at logout or restart.
-    const detail = asked?.status === 404 ? "an older listener is still running; it stops at logout or restart" : "the listener did not stop; it stops at logout or restart";
+    if (endpoint?.port === 0)
+        return unknownPort("it names no port");
+    if (endpoint === null)
+        return { clientId: "*", name: "listener", path: endpointPath(root), status: "absent" };
+    const item = { clientId: "*", name: "listener", path: `127.0.0.1:${endpoint.port}` };
+    if (!(await pingListener(endpoint)))
+        return { ...item, status: "absent" };
+    const stopped = await stopRunningListener(endpoint);
+    if (stopped === "stopped")
+        return { ...item, status: "removed" };
+    const detail = stopped === "no stop route" ? "an older listener is still running; it stops at logout or restart" : "the listener did not stop; it stops at logout or restart";
     return { ...item, status: "failed", detail };
 }
 function existsMarker(client) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heedvane",
-  "version": "0.2.1",
+  "version": "0.3.4",
   "description": "Heedvane for coding agents: one command installs steering, guardrails, team memory and skill checks into Claude Code, Codex, Cursor, Gemini CLI and more.",
   "private": false,
   "type": "module",
@@ -8,15 +8,22 @@
     "heedvane": "dist/cli.js",
     "heedvane-hook": "dist/cli.js"
   },
+  "exports": {
+    "./guard": {
+      "types": "./dist/guard.d.ts",
+      "default": "./dist/guard.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "skills"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.5"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --import ./tests/register-ts-resolver.mjs --test \"tests/**/*.test.ts\"",
+    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --import ./tests/register-ts-resolver.mjs --import ./tests/temp-cleanup.mjs --test \"tests/**/*.test.ts\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
     "build": "tsc -p tsconfig.json",

package/skills/heedvane-hooks/SKILL.md

@@ -7,13 +7,13 @@ description: Use when a user asks about heedvane hooks status, events, or how th
 
 ## Overview
 
-Heedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:
+Heedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes, Pi) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:
 
 1. **Hook contract** — a harness-neutral event taxonomy (`pre_tool_use`, `post_tool_use`, …), one JSON envelope, one normalizer. See `references/events.md`.
-2. **Per-agent adapters** — native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); MCP registration as the universal fallback (Warp has no native hooks — policy arrives via MCP); an honest skip where neither exists.
-3. **Setup mechanism** — `heedvane-hook` CLI: `init` / `setup` / `doctor` / `uninstall` with backup → atomic write → read-back verify. Human intent lives in `~/.heed/heed.yaml`; machine state in `~/.heed/state.json`.
+2. **Per-agent adapters** — native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); Heedvane's MCP connection in every agent (Claude Desktop through the mcp-remote bridge); an honest skip where an agent has no hooks (Warp).
+3. **Setup mechanism** — `npx heedvane`: `connect` / `setup` / `doctor` / `uninstall` with backup → atomic write → read-back verify. Human intent lives in `~/.heed/heed.yaml`; machine state in `~/.heed/state.json`.
 
-Which sessions run the hooks follows `heed.yaml` `gating.mode`: with `always` (the default) every session is governed, with `pane` only sessions launched with `HEED_SESSION` set. The dispatcher script (for Hermes, its plugin) decides, from the mode `setup` bakes into it, and always exits 0. Observability never blocks the agent.
+Which sessions run the hooks follows `heed.yaml` `gating.mode`: with `always` (the default) every session is governed, with `pane` only sessions launched with `HEED_SESSION` set. The dispatcher script (for Hermes, its plugin; for Pi, Heedvane's guard extension) decides, from the mode `setup` bakes into it, and always exits 0. Observability never blocks the agent.
 
 ## When to Use
 
@@ -73,7 +73,7 @@ Backend failures never block the agent: without Heedvane's answer, the locally c
 
 - **Do not rewrite `~/.claude/settings.json` (or any agent config) manually while hooks are installed.** Hand edits fight the compiler; the next `setup` will either back up your change or report the file invalid. Edit `heed.yaml` instead.
 - **Spool files are diagnostics, not policy.** When the listener is unreachable, hook payloads spool to `~/.heed/spool/` (5 MB cap, 7-day TTL) so nothing is lost — but spool presence is not enforcement, and clearing it loses observability history only.
-- Warp gets policies **via MCP only** — that is the designed happy path, not an error to fix.
+- Warp has no native hooks, so Heedvane adds only its MCP connection and the skill there — that is expected, not an error to fix.
 - If `doctor` reports `invalid` on a config, the file does not parse; heedvane never overwrites malformed configs. Fix or move the file aside yourself, then re-run.
 - Re-running `setup` after no changes reports "already current" — idempotence is a feature, not a stalled run.
 
@@ -84,4 +84,4 @@ Backend failures never block the agent: without Heedvane's answer, the locally c
 - [ ] `~/.heed/state.json` skill digest matches the installed skill
 - [ ] A new agent session (launched with `HEED_SESSION` set, or any session with `gating.mode: always`) produces events in the listener log or `~/.heed/spool/`
 - [ ] Backups exist: `<config>.heedvane.backup` next to every patched config
-- [ ] `/heedvane-status` in a fresh agent session reports the same agents as `doctor`
+- [ ] `npx heedvane status` reports state.json ok and the listener's endpoint

package/skills/heedvane-hooks/references/events.md

@@ -57,12 +57,15 @@ fields are truncated at ingest, never dropped.
 | `notification` | `Notification` | `Notification` | — | — |
 | `pre_compact` | `PreCompact` | `PreCompress` | — | — |
 
+Pi's guard (the extension `connect` installs, or `heedvane/guard` in code built on Pi) sends only
+`pre_tool_use`, as Claude Code's `PreToolUse` with Claude Code's tool names.
+
 Hermes' `on_session_end` fires once per turn despite its name, so it passes
 through as `unknown_event`, as does `post_approval_response`. Cursor's session
 is its `conversation_id`.
 
-Warp emits no native events at all — it has no hooks. Policy for Warp
-arrives via MCP tool calls; nothing in this table applies to it.
+Warp emits no native events at all — it has no hooks, so nothing in this
+table applies to it.
 
 Payload keys per source keep their harness names inside `payload` (e.g.
 Claude's `tool_input`, Codex's `tool_input`) after normalization of the

package/dist/dispatchers/windows.d.ts

@@ -1,15 +0,0 @@
-import type { DispatcherOptions } from "./posix.js";
-/**
- * Windows .cmd launcher (best-effort tier — the plan marks Windows untested until
- * CI covers it). It:
- *   1. in heed.yaml's default `gating.mode: pane`, no-ops unless HEED_SESSION is set; with
- *      `always`, runs in every session (the POSIX dispatcher decides the same way);
- *   2. resolves the shared POSIX dispatcher via the two-tier lookup
- *      (HEED_AGENT_HOOK_ROOT → %HOME% → %USERPROFILE%);
- *   3. prefers running that dispatcher through any POSIX shell on PATH (Git for
- *      Windows / MSYS2 / BusyBox) — hook stdin passes through, so spooling still
- *      works with the listener down;
- *   4. otherwise posts via curl.exe with the same headers as the POSIX dispatcher and prints
- *      the listener's answer (nothing, which lets the agent continue, when it fails).
- */
-export declare function windowsLauncher(agentId: string, options?: Pick<DispatcherOptions, "gating">): string;

package/dist/dispatchers/windows.js

@@ -1,50 +0,0 @@
-import { validateAgentId } from "./snippets.js";
-/**
- * Windows .cmd launcher (best-effort tier — the plan marks Windows untested until
- * CI covers it). It:
- *   1. in heed.yaml's default `gating.mode: pane`, no-ops unless HEED_SESSION is set; with
- *      `always`, runs in every session (the POSIX dispatcher decides the same way);
- *   2. resolves the shared POSIX dispatcher via the two-tier lookup
- *      (HEED_AGENT_HOOK_ROOT → %HOME% → %USERPROFILE%);
- *   3. prefers running that dispatcher through any POSIX shell on PATH (Git for
- *      Windows / MSYS2 / BusyBox) — hook stdin passes through, so spooling still
- *      works with the listener down;
- *   4. otherwise posts via curl.exe with the same headers as the POSIX dispatcher and prints
- *      the listener's answer (nothing, which lets the agent continue, when it fails).
- */
-export function windowsLauncher(agentId, options = {}) {
-    validateAgentId(agentId);
-    const gate = (options.gating ?? "always") === "always" ? "rem heed.yaml gating.mode: always, so every session runs the hooks." : "if not defined HEED_SESSION exit /b 0";
-    return `@echo off
-setlocal EnableExtensions
-rem heedvane-agent-hook launcher for ${agentId} — generated by heedvane-hook. Do not hand-edit.
-rem Marker: heedvane-agent-hook-form
-rem Every path exits 0. The listener's answer (steering, skill check) is printed as the hook output.
-
-${gate}
-
-set "HEED_HOOK_SCRIPT="
-if defined HEED_AGENT_HOOK_ROOT if exist "%HEED_AGENT_HOOK_ROOT%\\agent-hooks\\${agentId}-hook.sh" set "HEED_HOOK_SCRIPT=%HEED_AGENT_HOOK_ROOT%\\agent-hooks\\${agentId}-hook.sh"
-if not defined HEED_HOOK_SCRIPT if defined HOME if exist "%HOME%\\.heed\\agent-hooks\\${agentId}-hook.sh" set "HEED_HOOK_SCRIPT=%HOME%\\.heed\\agent-hooks\\${agentId}-hook.sh"
-if not defined HEED_HOOK_SCRIPT if defined USERPROFILE if exist "%USERPROFILE%\\.heed\\agent-hooks\\${agentId}-hook.sh" set "HEED_HOOK_SCRIPT=%USERPROFILE%\\.heed\\agent-hooks\\${agentId}-hook.sh"
-if not defined HEED_HOOK_SCRIPT exit /b 0
-
-rem Preferred: the shared POSIX dispatcher via any available POSIX shell.
-rem Hook stdin passes through to the script, which spools when the listener is down.
-where sh >nul 2>&1
-if %errorlevel%==0 (
-  sh "%HEED_HOOK_SCRIPT%"
-  exit /b 0
-)
-
-rem No POSIX shell: post via curl.exe with the same headers as the POSIX dispatcher.
-if not defined HEED_AGENT_HOOK_PORT exit /b 0
-if not defined HEED_AGENT_HOOK_TOKEN exit /b 0
-
-set "HEED_HOOK_INPUT=%TEMP%\\heed-hook-%RANDOM%-%RANDOM%.json"
-more > "%HEED_HOOK_INPUT%" 2>nul
-curl.exe -s --fail -X POST "http://127.0.0.1:%HEED_AGENT_HOOK_PORT%/hook/${agentId}" --connect-timeout 0.5 --max-time 1.5 --noproxy 127.0.0.1 -H "Content-Type: application/json" -H "X-Heed-Agent-Hook-Token: %HEED_AGENT_HOOK_TOKEN%" -H "X-Heed-Hook-Version: 1" --data-binary "@%HEED_HOOK_INPUT%"
-del "%HEED_HOOK_INPUT%" >nul 2>&1
-exit /b 0
-`;
-}

package/dist/mcp-server.d.ts

@@ -1,9 +0,0 @@
-export interface McpIo {
-    write: (line: string) => void;
-    log: (line: string) => void;
-}
-export declare function statusText(): Promise<string>;
-/** Entry point for the `mcp` subcommand. */
-export declare function runMcpStdio(io: Pick<McpIo, "write"> & {
-    log?: (line: string) => void;
-}): void;

package/dist/mcp-server.js

@@ -1,187 +0,0 @@
-/**
- * `npx heedvane mcp` — the MCP stdio server stub the installers register.
- * v1 exposes two tools (status, doctor) over line-delimited JSON-RPC.
- */
-import { createInterface } from "node:readline";
-import { runDoctor } from "./doctor.js";
-import { cmdMemory } from "./commands/memory.js";
-const MCP_SERVER_INFO = { name: "heedvane-hooks", version: "0.1.0" };
-const TOOLS = [
-    {
-        name: "heedvane_status",
-        description: "Report the live heedvane hook installation state for this machine (agents, skill, listener).",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "heedvane_doctor",
-        description: "Run the scoped heedvane doctor and return its checks with remediations.",
-        inputSchema: {
-            type: "object",
-            properties: { clients: { type: "array", items: { type: "string" } } },
-        },
-    },
-    {
-        name: "heedvane_memory_list",
-        description: "List team memory folders and entries for the current repository.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                folder: { type: "string", description: "Optional folder name to filter by." },
-                cwd: { type: "string", description: "Optional repository checkout path." },
-            },
-        },
-    },
-    {
-        name: "heedvane_memory_show",
-        description: "Read the full markdown content of a team memory entry by id.",
-        inputSchema: {
-            type: "object",
-            required: ["id"],
-            properties: {
-                id: { type: "string", description: "The team memory id." },
-                cwd: { type: "string", description: "Optional repository checkout path." },
-            },
-        },
-    },
-    {
-        name: "heedvane_memory_search",
-        description: "Semantically search team memory for the current repository.",
-        inputSchema: {
-            type: "object",
-            required: ["query"],
-            properties: {
-                query: { type: "string", description: "The question or search query." },
-                folder: { type: "string", description: "Optional folder name to restrict search." },
-                cwd: { type: "string", description: "Optional repository checkout path." },
-            },
-        },
-    },
-];
-/** Run a team memory command and return its collected lines. */
-async function runMemoryTool(words, flags, cwd) {
-    const lines = [];
-    await cmdMemory({
-        home: process.env.HEED_HOME ?? homeDir(),
-        out: (line) => lines.push(line),
-        words,
-        flag: (name) => flags[name],
-        cwd: typeof cwd === "string" && cwd.trim() !== "" ? cwd : process.cwd(),
-    });
-    return lines.join("\n");
-}
-function handleMemoryToolCall(name, args, reply) {
-    if (name === "heedvane_memory_list") {
-        const folder = typeof args.folder === "string" && args.folder.trim() !== "" ? [args.folder.trim()] : [];
-        void runMemoryTool(["list", ...folder], {}, args.cwd).then((text) => reply(textContent(text)));
-        return true;
-    }
-    if (name === "heedvane_memory_show") {
-        const id = typeof args.id === "string" ? args.id.trim() : "";
-        void runMemoryTool(["show", ...(id ? [id] : [])], {}, args.cwd).then((text) => reply(textContent(text)));
-        return true;
-    }
-    if (name === "heedvane_memory_search") {
-        const query = typeof args.query === "string" ? args.query.trim() : "";
-        const folder = typeof args.folder === "string" && args.folder.trim() !== "" ? args.folder.trim() : undefined;
-        void runMemoryTool(["search", ...(query ? [query] : [])], { "--folder": folder }, args.cwd).then((text) => reply(textContent(text)));
-        return true;
-    }
-    return false;
-}
-/** The tools/call branch: reply with the tool's text content, or a unknown-tool error. */
-function handleToolCall(msg, reply, fail) {
-    const name = msg.params?.name;
-    const args = msg.params?.arguments ?? {};
-    if (name === "heedvane_status") {
-        void statusText().then((text) => reply(textContent(text)));
-        return;
-    }
-    if (name === "heedvane_doctor") {
-        const clients = args.clients;
-        const input = { home: process.env.HEED_HOME ?? homeDir(), env: process.env };
-        if (Array.isArray(clients))
-            input.clients = clients.map(String);
-        void runDoctor(input).then((report) => reply(textContent(JSON.stringify(report, null, 2))));
-        return;
-    }
-    if (handleMemoryToolCall(name, args, reply))
-        return;
-    fail(-32602, `unknown tool: ${String(name)}`);
-}
-function handleRpc(msg, io) {
-    const { method, id } = msg;
-    if (!method || id === undefined)
-        return; // notification: ignore silently
-    const reply = (result) => io.write(JSON.stringify({ jsonrpc: "2.0", id, result }));
-    const fail = (code, message) => io.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
-    switch (method) {
-        case "initialize":
-            reply({ protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: MCP_SERVER_INFO });
-            return;
-        case "tools/list":
-            reply({ tools: TOOLS });
-            return;
-        case "tools/call":
-            handleToolCall(msg, reply, fail);
-            return;
-        default:
-            fail(-32601, `method not supported: ${method}`);
-    }
-}
-function textContent(text) {
-    return { content: [{ type: "text", text }] };
-}
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { HeedStateCorruptError, readState } from "./state.js";
-import { readEndpoint } from "./listener/endpoint.js";
-function homeDir() {
-    return homedir();
-}
-export async function statusText() {
-    const home = process.env.HEED_HOME ?? homeDir();
-    const root = join(home, ".heed");
-    const lines = [`heedvane hooks status (home: ${home})`];
-    try {
-        const state = await readState(root);
-        if (state !== null) {
-            const skill = state.skill?.digest.slice(0, 12) ?? "not installed";
-            lines.push(`  state.json: ok (protocol v${state.protocolVersion}, skill ${skill})`);
-        }
-        else {
-            lines.push("  state.json: absent (run npx heedvane init)");
-        }
-    }
-    catch (error) {
-        if (!(error instanceof HeedStateCorruptError))
-            throw error;
-        lines.push(`  state.json: ${error.message}`);
-    }
-    const endpoint = await readEndpoint(root);
-    lines.push(`  listener: ${endpoint ? `endpoint.env present (port ${endpoint.port})` : "not configured — events spool to ~/.heed/spool"}`);
-    lines.push("  next: npx heedvane doctor for scoped checks");
-    return lines.join("\n");
-}
-/** One stdin line → one RPC dispatch. A blank or unparseable line never crashes the host's transport. */
-function dispatchLine(line, io) {
-    const trimmed = line.trim();
-    if (trimmed === "")
-        return;
-    try {
-        handleRpc(JSON.parse(trimmed), io);
-    }
-    catch {
-        return; // unparseable line: ignore (never crash the host's transport)
-    }
-}
-/** Entry point for the `mcp` subcommand. */
-export function runMcpStdio(io) {
-    const log = io.log ?? (() => { });
-    const rl = createInterface({ input: process.stdin });
-    rl.on("line", (line) => {
-        dispatchLine(line, { write: io.write, log });
-    });
-    rl.on("close", () => {
-        log("heedvane mcp: stdin closed");
-    });
-}