heedvane 0.2.1 → 0.3.4

package/dist/clients/definitions.d.ts

@@ -11,15 +11,16 @@
  * This module imports nothing outside `node:path` — the package must stay
  * standalone-publishable (no intra-monorepo imports, no Effect).
  */
+import type { HookFiles } from "./hook-files.js";
 /** Env passed to resolvers: { home, platform, env } — pure, testable. */
 export type Env = Record<string, string | undefined>;
 /** Config document dialects the package knows how to parse and patch. */
 export type ClientFormat = "json" | "toml" | "jsonc" | "opencode" | "vscode" | "yaml";
-/** Integration channels per client. `plugin-install` = Hermes-style native plugin. */
-export type Capability = "hooks" | "mcp" | "skill" | "plugin-install";
+/** Integration channels per client. Hooks written as whole files (Hermes' plugin, Pi's extension) are `hookFiles`. */
+export type Capability = "hooks" | "mcp" | "skill";
 /** What a config target is written for. Skill bundles install to the universal
  * `~/.agents/skills/` directory and therefore carry no per-client target. */
-export type ConfigPurpose = "hooks" | "mcp" | "plugin";
+export type ConfigPurpose = "hooks" | "mcp";
 /** Platforms whose path semantics the resolver implements. */
 export type Platform = NodeJS.Platform;
 /** Pure resolution context — callers pass fixture/real values explicitly. */
@@ -34,7 +35,7 @@ export interface ResolveContext {
 /** Root a client's directory or detection marker is resolved against. */
 export type ClientPathBase = "home" | "xdg-config" | "platform-config";
 /** Base a writable config target is resolved against. */
-export type PathBase = "client" | "home" | "platform-config";
+export type PathBase = "client" | "home" | "platform-config" | "xdg-config";
 /** One writable config file for a client. */
 export interface ConfigTarget {
     /** Path segments relative to {@link PathBase}. */
@@ -82,6 +83,8 @@ export interface ClientDef {
     readonly hooksVersion?: number;
     /** Another client whose installed hooks this one also runs; when both are managed, only that client's are installed. */
     readonly runsHooksOf?: string;
+    /** Hooks written as whole files Heedvane owns in the client's folder (Hermes' plugin, Pi's extension), not config entries. */
+    readonly hookFiles?: HookFiles;
     /** Additional detection markers (e.g. GUI ADE app-support directory when CLI and GUI share configs). */
     readonly altMarkers?: readonly {
         readonly segments: readonly string[];
@@ -105,6 +108,7 @@ export interface ResolvedClient {
     readonly hookEntries?: HookEntryShape;
     readonly hooksVersion?: number;
     readonly runsHooksOf?: string;
+    readonly hookFiles?: HookFiles;
 }
 /**
  * Resolve every client definition into absolute marker/config paths for the

package/dist/clients/definitions.js

@@ -14,6 +14,8 @@
 import { posix, win32 } from "node:path";
 // Single owner of the canonical taxonomy: src/events/contract.ts.
 import { CANONICAL_EVENTS } from "../events/contract.js";
+import { HERMES_PLUGIN } from "./hermes-plugin.js";
+import { PI_EXTENSION } from "./pi-extension.js";
 /** Harness-neutral canonical taxonomy (v1). Native sets normalize into this.
  *  Single owner: src/events/contract.ts — re-exported here for the table. */
 /** Claude Code's 14 native hook events (verified against its hook contract). */
@@ -155,13 +157,13 @@ const SUPPORTED_CLIENTS = [
                 base: "client",
                 format: "json",
                 purpose: "mcp",
-                limitation: "Warp has no native hook events (hooks unavailable); ~/.warp/.mcp.json is project-level, and user-level MCP requires explicit in-app approval of the import.",
+                limitation: "Warp has no native hook events (hooks unavailable); ~/.warp/.mcp.json is Warp's global MCP file, and a remote server signs in through the browser when it first starts.",
             },
         ],
         capabilities: ["mcp", "skill"],
         events: [],
         mcpServersKey: "mcpServers",
-        limitation: "Warp exposes no native hook events — policies ship via MCP only, and the MCP import needs explicit user approval in Warp.",
+        limitation: "Warp exposes no native hook events, so Heedvane adds only its MCP connection and the skill there.",
     },
     {
         id: "opencode",
@@ -188,10 +190,9 @@ const SUPPORTED_CLIENTS = [
         displayName: "Hermes",
         markerSegments: [".hermes"],
         base: "home",
-        configs: [
-            { segments: ["plugins", "heedvane-hooks"], base: "client", format: "yaml", purpose: "plugin" },
-        ],
-        capabilities: ["plugin-install", "skill"],
+        configs: [],
+        hookFiles: HERMES_PLUGIN,
+        capabilities: ["skill"],
         events: [
             "on_session_start",
             "pre_llm_call",
@@ -205,6 +206,20 @@ const SUPPORTED_CLIENTS = [
         mcpServersKey: "mcpServers",
         notes: "Hermes integrates via a plugin install (~/.hermes/plugins/heedvane-hooks) using its native hook API — not a hooks.json/config.toml write.",
     },
+    {
+        // Pi 1.x (pi.dev): its agent folder holds mcp.json and the extensions it loads; PI_CODING_AGENT_DIR replaces the folder.
+        id: "pi",
+        displayName: "Pi",
+        markerSegments: [".pi", "agent"],
+        base: "home",
+        homeOverrideEnv: "PI_CODING_AGENT_DIR",
+        configs: [{ segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" }],
+        hookFiles: PI_EXTENSION,
+        capabilities: ["mcp", "skill"],
+        events: ["tool_call"],
+        mcpServersKey: "mcpServers",
+        notes: "Pi's hooks are Heedvane's guard (src/guard.ts), installed as the extension extensions/heedvane.ts — not a hooks file.",
+    },
     {
         // --- Snapshot-tested rows (same table, same resolver, no bespoke tests) ---
         id: "qwen-code",
@@ -227,11 +242,12 @@ const SUPPORTED_CLIENTS = [
         homeOverrideEnv: "KIMI_CODE_HOME",
         configs: [
             { segments: ["config.toml"], base: "client", format: "toml", purpose: "hooks" },
-            { segments: ["config.toml"], base: "client", format: "toml", purpose: "mcp" },
+            // MCP servers live in mcp.json (Kimi Code's MCP docs); config.toml is listed with hooks, so cleanup still finds the helper 0.3.0 and earlier wrote there.
+            { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["hooks", "mcp", "skill"],
         events: KIMI_EVENTS,
-        mcpServersKey: "mcp_servers",
+        mcpServersKey: "mcpServers",
     },
     {
         id: "droid",
@@ -253,6 +269,8 @@ const SUPPORTED_CLIENTS = [
         base: "home",
         configs: [
             { segments: [".gemini", "config", "hooks.json"], base: "home", format: "json", purpose: "hooks" },
+            // Antigravity's documented global MCP file; the second is where 0.3.0 and earlier wrote, kept only so cleanup and uninstall reach it.
+            { segments: [".gemini", "config", "mcp_config.json"], base: "home", format: "json", purpose: "mcp" },
             { segments: ["mcp_config.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["hooks", "mcp", "skill"],
@@ -266,6 +284,8 @@ const SUPPORTED_CLIENTS = [
         base: "home",
         homeOverrideEnv: "COPILOT_HOME",
         configs: [
+            // Copilot CLI's documented MCP file; the second is where 0.3.0 and earlier wrote, kept only so cleanup and uninstall reach it.
+            { segments: ["mcp-config.json"], base: "client", format: "json", purpose: "mcp" },
             { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["mcp", "skill"],
@@ -276,8 +296,12 @@ const SUPPORTED_CLIENTS = [
         id: "windsurf",
         displayName: "Windsurf",
         markerSegments: [".codeium", "windsurf"],
+        // Devin Desktop's folder: $XDG_CONFIG_HOME/devin, %APPDATA%\devin on Windows.
+        altMarkers: [{ segments: ["devin"], base: "xdg-config" }],
         base: "home",
         configs: [
+            // The file Windsurf's docs (now Devin Desktop's) name; the second is where 0.3.1 and earlier wrote, kept only so cleanup and uninstall reach it.
+            { segments: ["devin", "mcp_config.json"], base: "xdg-config", format: "json", purpose: "mcp" },
             { segments: ["mcp_config.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["mcp"],
@@ -324,14 +348,20 @@ function platformConfigDir(def, ctx, p) {
     switch (ctx.platform) {
         case "darwin":
             return p.join(ctx.home, "Library", "Application Support", appName);
-        case "win32": {
-            const appData = ctx.env["APPDATA"] ?? p.join(ctx.home, "AppData", "Roaming");
-            return p.join(absoluteOrHome(appData, ctx, p), appName);
-        }
+        case "win32":
+            return p.join(appDataRoot(ctx, p), appName);
         default:
             return p.join(xdgConfigRoot(ctx, p), appName);
     }
 }
+/** The `xdg-config` base for a marker or a config file: the XDG root, %APPDATA% on Windows (Devin Desktop's folder for Windsurf). */
+function configRoot(ctx, p) {
+    return ctx.platform === "win32" ? appDataRoot(ctx, p) : xdgConfigRoot(ctx, p);
+}
+/** %APPDATA%, else the default roaming folder under the home. */
+function appDataRoot(ctx, p) {
+    return absoluteOrHome(ctx.env["APPDATA"] ?? p.join(ctx.home, "AppData", "Roaming"), ctx, p);
+}
 /** Treat a relative env override as home-relative so resolution never throws. */
 function absoluteOrHome(value, ctx, p) {
     return p.isAbsolute(value) ? value : p.join(ctx.home, value);
@@ -346,6 +376,7 @@ function clientDir(def, ctx, p) {
             return p.join(ctx.home, ...def.markerSegments);
         }
         case "xdg-config":
+            // A client's own folder keeps the XDG root on Windows too (OpenCode's ~/.config/opencode); a marker or a config file under this base uses `configRoot`.
             return p.join(xdgConfigRoot(ctx, p), ...def.markerSegments);
         case "platform-config":
             return p.join(platformConfigDir(def, ctx, p), ...def.markerSegments);
@@ -357,7 +388,7 @@ function resolveMarkerBase(target, ctx, p) {
         case "home":
             return p.join(ctx.home, ...segments);
         case "xdg-config":
-            return p.join(xdgConfigRoot(ctx, p), ...segments);
+            return p.join(configRoot(ctx, p), ...segments);
         case "platform-config":
             return p.join(platformConfigDir(def, ctx, p), ...segments);
     }
@@ -388,6 +419,9 @@ function resolveConfigTarget(def, target, resolve) {
         case "platform-config":
             path = p.join(platformConfigDir(def, ctx, p), ...target.segments);
             break;
+        case "xdg-config":
+            path = p.join(configRoot(ctx, p), ...target.segments);
+            break;
     }
     return target.limitation === undefined
         ? { path, format: target.format, purpose: target.purpose }
@@ -423,5 +457,6 @@ export function supportedClients(ctx) {
         ...(def.hookEntries === undefined ? {} : { hookEntries: def.hookEntries }),
         ...(def.hooksVersion === undefined ? {} : { hooksVersion: def.hooksVersion }),
         ...(def.runsHooksOf === undefined ? {} : { runsHooksOf: def.runsHooksOf }),
+        ...(def.hookFiles === undefined ? {} : { hookFiles: def.hookFiles }),
     }));
 }

package/dist/clients/hermes-plugin.d.ts

@@ -1,4 +1,4 @@
-import type { HeedGatingConfig } from "../heed-file.js";
+import type { GatingMode, HookFiles } from "./hook-files.js";
 /**
  * The hooks this plugin registers with the Hermes host. `pre_tool_call` and `pre_llm_call` are directive
  * hooks: Hermes acts on what they return. `on_session_end` fires once per turn despite its name;
@@ -9,25 +9,10 @@ export type HermesPluginFile = {
     relativePath: string;
     content: string;
 };
-export type HermesPluginInstallStatus = "installed" | "skipped" | "unchanged";
-/** heed.yaml `gating.mode`, baked into the plugin at setup as the POSIX dispatcher gets it. */
-type GatingMode = HeedGatingConfig["mode"];
-/** The two files that make up the Hermes plugin, ready to install. */
+/** The files that make up the Hermes plugin, ready to install. */
 export declare function hermesPluginFiles(gating?: GatingMode): HermesPluginFile[];
-/** Does `<home>/.hermes/plugins/heedvane-hooks/plugin.yaml` declare our plugin? Uninstall removes only then. */
-export declare function hermesPluginOwned(home: string): Promise<boolean>;
 /**
- * Install the Hermes plugin into `<home>/.hermes/plugins/heedvane-hooks/`.
- *
- * - "skipped"  — a foreign plugin owns the target directory. Whether Hermes is installed at all
- *                is the planner's decision (detected, or named with `--agent`).
- * - "unchanged" — the dir is heed-owned and every file already matches.
- * - "installed" — files were written (fresh install or update).
- *
- * A heed-owned directory is one whose plugin.yaml exists and contains
- * `name: heedvane-hooks`. Differing heed-owned files are backed up to
- * `<file>.heedvane.backup` before being replaced. Foreign plugin.yaml files
- * are never overwritten.
+ * Hermes' hooks: the plugin `<Hermes folder>/plugins/heedvane-hooks`, Heedvane's when its plugin.yaml declares
+ * `name: heedvane-hooks`. A folder without that manifest is another plugin's, never overwritten or removed.
  */
-export declare function installHermesPlugin(home: string, gating?: GatingMode): Promise<HermesPluginInstallStatus>;
-export {};
+export declare const HERMES_PLUGIN: HookFiles;

package/dist/clients/hermes-plugin.js

@@ -1,6 +1,8 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { FALLBACK_FILE, FALLBACK_TIMEOUT_MS, HOOK_NODE_FILE, HOOK_TIMEOUT_MS, PROOF_HEADER, PROOF_MESSAGE, UNANSWERED_FLAG } from "../hook-fallback.js";
+import { guardSource } from "./pi-extension.js";
 const HERMES_PLUGIN_NAME = "heedvane-hooks";
 /**
  * The hooks this plugin registers with the Hermes host. `pre_tool_call` and `pre_llm_call` are directive
@@ -32,26 +34,39 @@ Reports coding-agent lifecycle events to the local heedvane listener
 The listener's answer goes back to the host: a tool block on pre_tool_call,
 turn context on pre_llm_call. Best-effort by contract: a slow, absent, or
 misconfigured listener must never block the host or raise into it, so any
-failure answers None and the host carries on.
+failure answers None and the host carries on. When the listener gives no
+answer, Heedvane's one fallback (fallback.mjs beside this file, the other
+agents' hooks' own, run with the Node that last installed the hooks, or node on
+PATH once that one is gone) keeps the event for the listener to replay and
+starts a listener.
 Configuration comes from the HEED_AGENT_HOOK_PORT / HEED_AGENT_HOOK_TOKEN
-env vars, falling back to the user's ~/.heed/endpoint.env (KEY=VALUE lines).
+env vars, falling back to endpoint.env (KEY=VALUE lines) where the dispatchers
+find it.
 Which sessions report follows heed.yaml gating.mode, baked in at setup: with
 "pane" only sessions launched with HEED_SESSION set, with "always" every one.
 """
 
+import hashlib
+import hmac
 import json
 import os
+import shutil
+import subprocess
 import urllib.error
 import urllib.request
+import uuid
 
 # The hooks registered with the host via register(ctx).
 EVENTS = (
 ${HERMES_EVENTS.map((event) => `    "${event}",\n`).join("")})
 
-REQUEST_TIMEOUT_S = 0.75
+REQUEST_TIMEOUT_S = ${HOOK_TIMEOUT_MS / 1000}
 
 GATING = "${gating}"
 
+FALLBACK = os.path.join(os.path.dirname(os.path.abspath(__file__)), "${FALLBACK_FILE}")
+FALLBACK_TIMEOUT_S = ${FALLBACK_TIMEOUT_MS / 1000}
+
 
 def _endpoint_from_env():
     port = os.environ.get("HEED_AGENT_HOOK_PORT")
@@ -61,9 +76,19 @@ def _endpoint_from_env():
     return None
 
 
+def _heed_root():
+    """The heed folder as the dispatchers find it: HEED_AGENT_HOOK_ROOT (which \`heedvane run\` sets), else ~/.heed."""
+    return os.environ.get("HEED_AGENT_HOOK_ROOT") or os.path.join(os.path.expanduser("~"), ".heed")
+
+
+def _endpoint_file():
+    """endpoint.env as the dispatchers find it: HEED_AGENT_HOOK_ENDPOINT, else in the heed folder."""
+    return os.environ.get("HEED_AGENT_HOOK_ENDPOINT") or os.path.join(_heed_root(), "endpoint.env")
+
+
 def _endpoint_from_home_file():
-    """Parse ~/.heed/endpoint.env (KEY=VALUE lines, mode 0600)."""
-    path = os.path.join(os.path.expanduser("~"), ".heed", "endpoint.env")
+    """Parse endpoint.env (KEY=VALUE lines, mode 0600)."""
+    path = _endpoint_file()
     try:
         with open(path, "r", encoding="utf-8") as handle:
             lines = handle.read().splitlines()
@@ -98,15 +123,19 @@ def _post_to_listener(hook_event_name, cwd, payload):
     Best-effort: never raises."""
     if GATING != "always" and not os.environ.get("HEED_SESSION"):
         return None
-    endpoint = _resolve_endpoint()
-    if endpoint is None:
-        return None
-    port, token = endpoint
     # Flat like every other harness: the host's fields (tool_name, tool_input, ...) at the top level.
     event = dict(payload)
     event["hook_event_name"] = hook_event_name
     event["cwd"] = cwd
     body = json.dumps(event, default=str).encode("utf-8")
+    # Sent live and kept with the event, so Heedvane drops a replayed copy of one the listener did receive.
+    event_id = uuid.uuid4().hex
+    endpoint = _resolve_endpoint()
+    if endpoint is None:
+        return _keep_unanswered(body, event_id)
+    port, token = endpoint
+    # The proof of the token (src/hook-fallback.ts listenerProof), also for a port and token pinned in the environment.
+    proof = hmac.new(token.encode("utf-8"), ${JSON.stringify(PROOF_MESSAGE)}.encode("utf-8"), hashlib.sha256).hexdigest()[:32]
     request = urllib.request.Request(
         "http://127.0.0.1:" + str(port) + "/hook/hermes",
         data=body,
@@ -114,17 +143,57 @@ def _post_to_listener(hook_event_name, cwd, payload):
             "Content-Type": "application/json",
             "X-Heed-Agent-Hook-Token": token,
             "X-Heed-Hook-Version": "1",
+            "X-Heed-Event-Id": event_id,
         },
         method="POST",
     )
     try:
         with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_S) as response:
+            # Only this machine's listener names the proof from endpoint.env (0.3.4 on); any other answer goes to the
+            # fallback, which tells an older listener from another program by its probe.
+            if response.headers.get("${PROOF_HEADER}") != proof:
+                return _keep_unanswered(body, event_id)
             return json.loads(response.read().decode("utf-8"))
-    except (OSError, urllib.error.URLError, ValueError):
+    except (OSError, urllib.error.URLError, ValueError) as error:
         # OSError covers socket errors/timeouts (URLError subclasses it);
         # ValueError covers a malformed port or URL and an answer that is not
-        # JSON. Silent by design: a hook must never raise into the host.
-        return None
+        # JSON. Silent by design: a hook must never raise into the host. Any of
+        # them is no answer: on Windows a refused connection times out.
+        return _keep_unanswered(body, event_id)
+
+
+def _node():
+    """The Node that last installed the hooks, as the dispatchers find it (agent-hooks/node in
+    the heed folder: its PATH link, then itself); node on PATH once both are gone."""
+    try:
+        with open(os.path.join(_heed_root(), "agent-hooks", "${HOOK_NODE_FILE}"), "r", encoding="utf-8") as handle:
+            nodes = handle.read().splitlines()
+    except OSError:
+        nodes = []
+    return next((node for node in nodes if node and os.access(node, os.X_OK)), None) or shutil.which("node")
+
+
+def _keep_unanswered(body, event_id):
+    """The listener gave no answer: the fallback asks it once more (one taking
+    the port over answers then), else keeps the event for it to replay and
+    starts a listener. The listener's answer, or None. Its own failure never
+    reaches the host."""
+    # The agent's NODE_OPTIONS are its project's (a --require of its own code), not the fallback's.
+    env = {key: value for key, value in os.environ.items() if key != "NODE_OPTIONS"}
+    try:
+        ran = subprocess.run(
+            [_node() or "node", FALLBACK, "${UNANSWERED_FLAG}", "hermes"],
+            input=body,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            env=dict(env, HEED_HOOK_EVENT_ID=event_id),
+            timeout=FALLBACK_TIMEOUT_S,
+            # No console window on Windows when Hermes runs without one.
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+        return json.loads(ran.stdout.decode("utf-8") or "{}") or None
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return None  # no Node, it ran out of time, or it printed no answer: the host carries on
 
 
 def _extract(payload):
@@ -168,32 +237,14 @@ def register(ctx):
     for event in EVENTS:
         ctx.register_hook(event, _make_hook(event))
 `;
-/** The two files that make up the Hermes plugin, ready to install. */
+/** The files that make up the Hermes plugin, ready to install. */
 export function hermesPluginFiles(gating = "always") {
     return [
         { relativePath: "plugin.yaml", content: PLUGIN_YAML },
         { relativePath: "__init__.py", content: pluginInitPy(gating) },
+        { relativePath: FALLBACK_FILE, content: guardSource() },
     ];
 }
-async function pathExists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function readFileOrNull(path) {
-    try {
-        return await readFile(path, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return null;
-        throw err;
-    }
-}
 function isHeedOwned(pluginYaml) {
     try {
         const manifest = parseYaml(pluginYaml);
@@ -203,45 +254,20 @@ function isHeedOwned(pluginYaml) {
         return false; // unparseable manifest — not provably ours
     }
 }
-/** Does `<home>/.hermes/plugins/heedvane-hooks/plugin.yaml` declare our plugin? Uninstall removes only then. */
-export async function hermesPluginOwned(home) {
-    const manifest = await readFileOrNull(join(home, ".hermes", "plugins", HERMES_PLUGIN_NAME, "plugin.yaml"));
-    return manifest !== null && isHeedOwned(manifest);
-}
 /**
- * Install the Hermes plugin into `<home>/.hermes/plugins/heedvane-hooks/`.
- *
- * - "skipped"  — a foreign plugin owns the target directory. Whether Hermes is installed at all
- *                is the planner's decision (detected, or named with `--agent`).
- * - "unchanged" — the dir is heed-owned and every file already matches.
- * - "installed" — files were written (fresh install or update).
- *
- * A heed-owned directory is one whose plugin.yaml exists and contains
- * `name: heedvane-hooks`. Differing heed-owned files are backed up to
- * `<file>.heedvane.backup` before being replaced. Foreign plugin.yaml files
- * are never overwritten.
+ * Hermes' hooks: the plugin `<Hermes folder>/plugins/heedvane-hooks`, Heedvane's when its plugin.yaml declares
+ * `name: heedvane-hooks`. A folder without that manifest is another plugin's, never overwritten or removed.
  */
-export async function installHermesPlugin(home, gating = "always") {
-    const pluginDir = join(home, ".hermes", "plugins", HERMES_PLUGIN_NAME);
-    if (await pathExists(pluginDir)) {
-        const marker = await readFileOrNull(join(pluginDir, "plugin.yaml"));
-        if (marker === null || !isHeedOwned(marker)) {
-            return "skipped"; // foreign plugin owns this directory — never overwrite
+export const HERMES_PLUGIN = {
+    name: "hermes plugin",
+    path: (agentFolder) => join(agentFolder, "plugins", HERMES_PLUGIN_NAME),
+    files: hermesPluginFiles,
+    owned: (dir) => {
+        try {
+            return isHeedOwned(readFileSync(join(dir, "plugin.yaml"), "utf8"));
         }
-    }
-    let changed = false;
-    await mkdir(pluginDir, { recursive: true });
-    for (const file of hermesPluginFiles(gating)) {
-        const target = join(pluginDir, file.relativePath);
-        const current = await readFileOrNull(target);
-        if (current === file.content)
-            continue;
-        if (current !== null) {
-            // Heed-owned but drifted: keep the old bytes for operator recovery.
-            await writeFile(`${target}.heedvane.backup`, current, "utf8");
+        catch {
+            return false; // no manifest: not provably ours
         }
-        await writeFile(target, file.content, "utf8");
-        changed = true;
-    }
-    return changed ? "installed" : "unchanged";
-}
+    },
+};

package/dist/clients/hook-files.d.ts

@@ -0,0 +1,22 @@
+import type { HeedGatingConfig } from "../heed-file.js";
+export type GatingMode = HeedGatingConfig["mode"];
+export interface HookFiles {
+    /** What uninstall reports it as. */
+    readonly name: string;
+    /** Where the files go, in the agent's folder. */
+    path(agentFolder: string): string;
+    /** The files, by path relative to {@link path} ("" for the path itself), with heed.yaml's gating set in them. */
+    files(gating: GatingMode): Array<{
+        relativePath: string;
+        content: string;
+    }>;
+    /** Whether Heedvane wrote what is at the path: only then is it replaced or removed. */
+    owned(path: string): boolean;
+}
+/**
+ * Writes the files, unless something Heedvane did not write holds the path ("skipped"). A file of Heedvane's that
+ * differs (edited by hand, or an earlier version's) is kept as `<file>.heedvane.backup` before it is replaced.
+ */
+export declare function installHookFiles(hookFiles: HookFiles, path: string, gating?: GatingMode): Promise<"installed" | "unchanged" | "skipped">;
+/** Removes the path when Heedvane wrote it; leaves anything else. */
+export declare function removeHookFiles(hookFiles: HookFiles, path: string): Promise<"removed" | "skipped" | "absent">;

package/dist/clients/hook-files.js

@@ -0,0 +1,39 @@
+/**
+ * Hooks an agent gets as whole files Heedvane owns, Hermes' plugin or Pi's extension, instead of entries in its config.
+ * The agent's definition names its {@link HookFiles} (definitions.ts `hookFiles`), and plan, apply, uninstall and doctor
+ * read only that. The files sit at one path: a folder of them (Hermes), or the file itself (Pi).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+/**
+ * Writes the files, unless something Heedvane did not write holds the path ("skipped"). A file of Heedvane's that
+ * differs (edited by hand, or an earlier version's) is kept as `<file>.heedvane.backup` before it is replaced.
+ */
+export async function installHookFiles(hookFiles, path, gating = "always") {
+    if (existsSync(path) && !hookFiles.owned(path))
+        return "skipped";
+    let changed = false;
+    for (const file of hookFiles.files(gating)) {
+        const target = join(path, file.relativePath);
+        const current = existsSync(target) ? readFileSync(target, "utf8") : null;
+        if (current === file.content)
+            continue;
+        if (current !== null)
+            await writeFileAtomic(`${target}.heedvane.backup`, current);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFileAtomic(target, file.content);
+        changed = true;
+    }
+    return changed ? "installed" : "unchanged";
+}
+/** Removes the path when Heedvane wrote it; leaves anything else. */
+export async function removeHookFiles(hookFiles, path) {
+    if (!existsSync(path))
+        return "absent";
+    if (!hookFiles.owned(path))
+        return "skipped";
+    await rm(path, { recursive: true, force: true });
+    return "removed";
+}

package/dist/clients/pi-extension.d.ts

@@ -0,0 +1,9 @@
+import type { GatingMode, HookFiles } from "./hook-files.js";
+/**
+ * The guard as one plain JavaScript file, with heed.yaml's gating set: Pi's extension, and every agent's fallback
+ * (`fallback.mjs`, which the dispatchers and Hermes run with Node). It is the compiled guard, or its source with the
+ * types stripped when Heedvane runs from source.
+ */
+export declare function guardSource(gating?: GatingMode): string;
+/** Pi's hooks: Heedvane's guard as the extension `<Pi's agent folder>/extensions/heedvane.ts`, Heedvane's when it begins with the guard's mark. */
+export declare const PI_EXTENSION: HookFiles;

package/dist/clients/pi-extension.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+// A namespace import: Node 22.0 to 22.12 have no stripTypeScriptTypes, and naming it in an import fails the whole CLI at load.
+import * as nodeModule from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** How the guard (src/guard.ts) begins: a file in Pi's extensions folder that begins so is Heedvane's. */
+const OWNER_MARK = "// heedvane: Heedvane's guard for Pi.";
+/** The guard's gating line (typed in its source, plain once compiled), which the installed copy sets from heed.yaml. */
+const GATING_LINE = /^const GATING(?:: string)? = "always";$/m;
+/** The guard's one import of Heedvane's own code, which the copy carries inline: Pi loads the file on its own. */
+const FALLBACK_IMPORT = /^import \{[^}]*\} from "\.\/hook-fallback\.js";$/m;
+/**
+ * The guard as one plain JavaScript file, with heed.yaml's gating set: Pi's extension, and every agent's fallback
+ * (`fallback.mjs`, which the dispatchers and Hermes run with Node). It is the compiled guard, or its source with the
+ * types stripped when Heedvane runs from source.
+ */
+export function guardSource(gating = "always") {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const compiled = existsSync(join(here, "..", "guard.js"));
+    const source = (name) => readFileSync(join(here, "..", `${name}.${compiled ? "js" : "ts"}`), "utf8");
+    const guard = source("guard");
+    if (!guard.startsWith(OWNER_MARK) || !GATING_LINE.test(guard) || !FALLBACK_IMPORT.test(guard))
+        throw new Error("the Pi guard lost its owner mark, its gating line or its fallback import");
+    // Replacer functions: the inlined text has `$` signs that a replacement string would read as patterns.
+    const whole = guard.replace(FALLBACK_IMPORT, () => source("hook-fallback")).replace(GATING_LINE, () => `const GATING = ${JSON.stringify(gating)};`);
+    return compiled ? whole : nodeModule.stripTypeScriptTypes(whole);
+}
+/** Pi's hooks: Heedvane's guard as the extension `<Pi's agent folder>/extensions/heedvane.ts`, Heedvane's when it begins with the guard's mark. */
+export const PI_EXTENSION = {
+    name: "pi extension",
+    path: (agentFolder) => join(agentFolder, "extensions", "heedvane.ts"),
+    files: (gating) => [{ relativePath: "", content: guardSource(gating) }],
+    owned: (path) => {
+        try {
+            return readFileSync(path, "utf8").startsWith(OWNER_MARK);
+        }
+        catch {
+            return false; // unreadable: nothing provably ours
+        }
+    },
+};