heedvane 0.3.3 → 0.3.4

package/dist/mcp.js

@@ -1,8 +1,8 @@
 /**
  * Heedvane's MCP connection: the one MCP entry the installer registers, named `heedvane`, pointing at
- * the organization's remote server (`<server>/api/mcp/<org>`), in the shapes the dashboard's setup writes
- * (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`). The agent signs in to it in the
- * browser on first use.
+ * the organization's remote server (`<server>/api/mcp/<org>`). Remote entries take the shapes the dashboard's
+ * setup writes (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`); Claude Desktop's mcp-remote bridge
+ * (`bridgeEntry`, with the installing Node's folder) is this CLI's own. The agent signs in in the browser on first use.
  *
  * Identity: uninstall and detection recognize an entry by its name and shape together, never by a name
  * alone: today's connection, the local helper earlier versions registered (`npx -y heedvane mcp`, under any
@@ -10,14 +10,16 @@
  */
 /** The entry's name in every agent's MCP config. */
 export const HEEDVANE_SERVER_NAME = "heedvane";
+/** Why metrics only registers no MCP connection: its tools send questions and repository names to Heedvane. */
+export const MCP_OFF_METRICS_ONLY = "Heedvane's MCP connection: off under Metrics only, since its tools send your questions and repository names to Heedvane";
 /** What to do when no organization is known, so no MCP connection can be registered. */
-export const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx heedvane connect --org <id>";
+export const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx -y heedvane connect --org <id>";
+/** How to add the organization: `setup` cannot, since it compiles heed.yaml as it is. */
+export const ORG_REMEDIATION = "run the connect command from your dashboard's Settings, or npx -y heedvane connect --org <organization id>";
 /** The connection's name before 0.3.0; connect and uninstall remove an entry under it. */
 const EARLIER_CONNECTOR_NAME = "heedvane-findings";
-/** Names development builds of the local helper ran under, matched in its command and arguments. */
-const IDENTITY_MARKERS = ["@heedvane/hooks", "heedvane-hooks"];
-/** The local helper's arguments (its command was always `npx`). */
-const HELPER_ARGS = "-y heedvane mcp";
+/** The packages the local helper ran from: `heedvane` (0.1.0 to 0.2.1 on npm) and the development builds' names. */
+const HELPER_PACKAGES = ["heedvane", "heedvane-hooks", "@heedvane/hooks"];
 /** Uninstall/detection marker for inline dispatcher snippets (hooks configs). */
 export const SNIPPET_MARKER = "heedvane-agent-hook-form";
 /** The connection's URL for an organization, as the dashboard builds it (`buildHeedvaneMcpUrl`). */
@@ -48,33 +50,130 @@ const CONNECTOR_ENTRY = {
     windsurf: (url) => ({ serverUrl: url }),
     // Copilot CLI lists the tools it may call; `*` is every tool.
     copilot_cli: (url) => ({ type: "http", url, tools: ["*"] }),
+    // Pi signs in on the first 401 (`pi mcp login heedvane`) and offers the tools to the model only with `direct` exposure.
+    pi: (url) => ({ url, exposure: "direct" }),
     // Claude Desktop's config file runs only local (stdio) servers, so the mcp-remote bridge carries the connection and
     // its browser sign-in. `@latest` keeps npx off an older cached copy (0.1.15 and earlier had CVE-2025-6514).
     claude_desktop: (url, nodeDir) => bridgeEntry(["-y", "mcp-remote@latest", url], nodeDir),
 };
 /**
- * A local server run by npx. With the installing Node's folder, npx is named by its absolute path and that folder
- * leads the server's PATH: Claude Desktop opened from Finder starts servers with launchd's PATH, which holds no
- * Node from nvm, and npx finds `node` through PATH.
+ * Finds npx when the agent starts the server: the installing Node's folder first, then the newest Node 22 or later
+ * from nvm, then Homebrew's and /usr/local's, so an upgrade that removes the installing folder does not break the entry.
+ * The folder found leads PATH, since npx finds `node` through PATH and Claude Desktop opened from Finder starts servers
+ * with launchd's PATH, which holds no Node from nvm or Homebrew.
  */
+const BRIDGE_LAUNCHER = [
+    'installed="$1"; shift',
+    'newest=""; newest_rank=0',
+    'for bin in "$HOME"/.nvm/versions/node/v*/bin; do',
+    '  version="${bin%/bin}"; version="${version##*/v}"; major="${version%%.*}"; rest="${version#*.}"; minor="${rest%%.*}"; patch="${rest#*.}"',
+    '  case "$major$minor$patch" in ""|*[!0-9]*) continue ;; esac',
+    "  rank=$((major * 1000000 + minor * 1000 + patch))",
+    '  if [ "$major" -ge 22 ] && [ "$rank" -gt "$newest_rank" ] && [ -x "$bin/npx" ]; then newest="$bin"; newest_rank="$rank"; fi',
+    "done",
+    'for dir in "$installed" "$newest" /opt/homebrew/bin /usr/local/bin; do',
+    '  if [ -n "$dir" ] && [ -x "$dir/npx" ]; then PATH="$dir:/usr/bin:/bin:/usr/sbin:/sbin" exec "$dir/npx" "$@"; fi',
+    "done",
+    'echo "heedvane: no npx found for Heedvane\'s MCP connection; install Node.js 22 or later" >&2',
+    "exit 127",
+].join("\n");
+const BRIDGE_NAME = "heedvane-bridge";
+/** A local server run by npx: through {@link BRIDGE_LAUNCHER} given the installing Node's folder, else the bare npx (Windows). */
 function bridgeEntry(args, nodeDir) {
     if (nodeDir === undefined)
         return { command: "npx", args };
-    return { command: `${nodeDir}/npx`, args, env: { PATH: [nodeDir, "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(":") } };
+    return { command: "/bin/sh", args: ["-c", BRIDGE_LAUNCHER, BRIDGE_NAME, nodeDir, ...args] };
+}
+/**
+ * The entry as drift checks compare it: a bridge's installing-Node folder is left out, since the launcher finds a Node
+ * without it, and connect run from another Node is no change to the connection.
+ */
+export function comparableEntry(entry) {
+    if (entry === null || typeof entry !== "object")
+        return entry;
+    const { command, args } = entry;
+    if (command !== "/bin/sh" || !Array.isArray(args) || args[0] !== "-c" || args[2] !== BRIDGE_NAME)
+        return entry;
+    return { ...entry, args: [...args.slice(0, 3), ...args.slice(4)] };
 }
 /** The fields agents name a remote server's URL with. */
 const URL_FIELDS = ["url", "httpUrl", "serverUrl"];
+/** The variable a software factory holds its organization API key in; the dashboard's factory commands use it. */
+export const ORG_KEY_ENV = "HEEDVANE_ORG_KEY";
+/**
+ * A software factory's connection: the agent sends the organization key from HEEDVANE_ORG_KEY as `Authorization: Bearer`
+ * through its own documented way to read a variable, so the key is never written to a file and no browser sign-in is
+ * needed. VS Code, Warp, Antigravity and Claude Desktop document none, so they keep the browser sign-in.
+ */
+const KEY_CONNECTOR_ENTRY = {
+    // Claude Code, Gemini CLI, Qwen Code, Droid, Copilot CLI and Pi expand ${VAR} in header values.
+    claude: (url) => ({ type: "http", url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    gemini: (url) => ({ httpUrl: url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    "qwen-code": (url) => ({ httpUrl: url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    droid: (url) => ({ type: "http", url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    copilot_cli: (url) => ({ type: "http", url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` }, tools: ["*"] }),
+    pi: (url) => ({ url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` }, exposure: "direct" }),
+    // Codex and Kimi Code name the variable that holds the bearer token.
+    codex: (url) => ({ url, bearer_token_env_var: ORG_KEY_ENV }),
+    kimi: (url) => ({ url, bearerTokenEnvVar: ORG_KEY_ENV }),
+    // Cursor and Windsurf (Devin Desktop) read ${env:VAR}; OpenCode reads {env:VAR} and needs its own OAuth off.
+    cursor: (url) => ({ url, headers: { Authorization: `Bearer \${env:${ORG_KEY_ENV}}` } }),
+    windsurf: (url) => ({ serverUrl: url, headers: { Authorization: `Bearer \${env:${ORG_KEY_ENV}}` } }),
+    opencode: (url) => ({ type: "remote", url, enabled: true, oauth: false, headers: { Authorization: `Bearer {env:${ORG_KEY_ENV}}` } }),
+};
+/** The software-factory connection entry for this agent; undefined where it keeps the browser sign-in. */
+export function keyConnectorEntry(clientId, url) {
+    return KEY_CONNECTOR_ENTRY[clientId]?.(url);
+}
 /** The connection entry for this agent, or undefined when the installer does not register it there. `nodeDir` (POSIX only) is the installing Node's folder, for an entry that runs a local bridge. */
 export function connectorEntry(clientId, url, nodeDir) {
     return CONNECTOR_ENTRY[clientId]?.(url, nodeDir);
 }
-/** Does this entry point at a Heedvane MCP URL, under any agent's name for the field or as a bridge's argument? */
-function hasConnectorUrl(entry) {
+/**
+ * The server and organization of a Heedvane MCP URL exactly as {@link connectorUrl} builds it: http(s)
+ * `<server>/api/mcp/<organization>`, where a server under a base path keeps that path, with no credentials, query or
+ * fragment. A user's own URL whose path merely contains `/api/mcp/` is none.
+ */
+function parsedConnectorUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        const path = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+        const segments = path.split("/");
+        const encodedOrg = segments.pop();
+        if (!encodedOrg || segments.pop() !== "mcp" || segments.pop() !== "api")
+            return undefined;
+        const written = new URL(url);
+        written.pathname = path;
+        const server = `${url.origin}${segments.join("/")}`;
+        const org = decodeURIComponent(encodedOrg);
+        return new URL(connectorUrl(server, org)).href === written.href ? { server, org } : undefined;
+    }
+    catch {
+        return undefined; // not a URL, or an organization that does not decode: not one connectorUrl builds
+    }
+}
+/** The organization an entry's Heedvane MCP URL names at `server`, if it points there. */
+export function connectorOrganization(entry, server) {
+    for (const value of entryUrls(entry)) {
+        const parsed = parsedConnectorUrl(value);
+        if (parsed !== undefined && new URL(connectorUrl(parsed.server, parsed.org)).href === new URL(connectorUrl(server, parsed.org)).href)
+            return parsed.org;
+    }
+    return undefined;
+}
+/** The strings an entry names a server URL with: any agent's URL field, or a bridge's arguments. */
+export function entryUrls(entry) {
     if (entry === null || typeof entry !== "object")
-        return false;
+        return [];
     const e = entry;
     const args = Array.isArray(e.args) ? e.args : [];
-    return [...URL_FIELDS.map((field) => e[field]), ...args].some((url) => typeof url === "string" && url.includes("/api/mcp/"));
+    return [...URL_FIELDS.map((field) => e[field]), ...args].filter((value) => typeof value === "string");
+}
+/** Does this entry point at a Heedvane MCP URL, under any agent's name for the field or as a bridge's argument? */
+function hasConnectorUrl(entry) {
+    return entryUrls(entry).some((url) => parsedConnectorUrl(url) !== undefined);
 }
 /** Is this today's connection entry? Its name and a Heedvane MCP URL both have to match. */
 export function isConnectorEntry(name, entry) {
@@ -84,6 +183,10 @@ export function isConnectorEntry(name, entry) {
 export function isLegacyEntry(name, entry) {
     return hasHelperCommand(entry) || (name === EARLIER_CONNECTOR_NAME && hasConnectorUrl(entry));
 }
+/** Does this entry run the local helper an earlier version registered, under any name? */
+export function isHelperEntry(_name, entry) {
+    return hasHelperCommand(entry);
+}
 /** Is this server entry Heedvane's, today's or an earlier version's? Used by uninstall, detection and doctor. */
 export function isHeedvaneEntry(name, entry) {
     return isConnectorEntry(name, entry) || isLegacyEntry(name, entry);
@@ -102,13 +205,12 @@ export function mcpEntryNames(doc, containerKeys, match) {
     }
     return names;
 }
-/** Does this entry's command/args run the local helper (today's package name or a development build's)? */
+/** Does this entry run the local helper, exactly as earlier versions wrote it: `npx -y <helper package> mcp`? */
 function hasHelperCommand(entry) {
     if (entry === null || typeof entry !== "object")
         return false;
-    const e = entry;
-    const command = typeof e.command === "string" ? e.command : "";
-    const args = Array.isArray(e.args) ? e.args.filter((a) => typeof a === "string") : [];
-    const haystack = [command, ...args].join(" ");
-    return haystack.includes(HELPER_ARGS) || IDENTITY_MARKERS.some((m) => haystack.includes(m));
+    const { command, args } = entry;
+    if (command !== "npx" || !Array.isArray(args) || args.length !== 3)
+        return false;
+    return args[0] === "-y" && HELPER_PACKAGES.includes(String(args[1])) && args[2] === "mcp";
 }

package/dist/plan.d.ts

@@ -2,7 +2,8 @@ import { type Capability, type Env, type ResolvedClient } from "./clients/defini
 import { type DocFormat } from "./config-doc.js";
 import type { HeedFile, HeedGatingConfig } from "./heed-file.js";
 export type ActionKind = "hooks" | "mcp" | "skill" | "skip";
-export type Operation = "create" | "update" | "unchanged" | "skip";
+/** `remove`: the action only removes entries ({@link mcpLeftovers}); the plan shows it as removed. */
+export type Operation = "create" | "update" | "unchanged" | "skip" | "remove";
 export interface PlannedAction {
     clientId: string;
     kind: ActionKind;
@@ -39,29 +40,49 @@ export interface ClientContext {
     env: Env;
     /** Heedvane's MCP connection URL (`connect --org`), registered where the agent takes it. */
     connector?: string;
+    /** The folder whose npx runs a local MCP bridge (`bridgeNodeDir`); without it, the bare `npx`. */
+    nodeDir?: string;
 }
 /**
  * Desired write targets per client × capability. This is the desired-state
  * compiler heed.yaml → concrete files; doctor reuses it via a callback so
- * it never needs apply.ts. `env` is accepted for API stability — the client's
- * config paths arrive already resolved against it.
+ * it never needs apply.ts. The client's config paths arrive already resolved
+ * against `env`; its HEEDVANE_ORG_KEY picks the software-factory MCP connection.
  */
 export declare function desiredEntriesFor(client: ResolvedClient, capability: Capability, context: ClientContext & {
     gating?: HeedGatingConfig["mode"];
 }): Desired[];
-/** The folder of the Node running this install: the hook dispatcher records it, and a local MCP bridge runs its npx. */
-export declare function installingNodeDir(): string;
-/** Heedvane's MCP connection URL for the organization heed.yaml names; none without one. */
+/** The folder whose npx runs a local MCP bridge on `platform`; none on Windows, which keeps the bare `npx` its docs show (a `.cmd` path cannot be started without a shell). */
+export declare function bridgeNodeDir(platform: string): string | undefined;
+/**
+ * Why heed.yaml registers no MCP connection, the one owner of that decision: metrics only, whose promise the
+ * connection's tools would break (they send questions and repository names), or no organization. None when it does.
+ */
+export declare function connectionOff(heedFile: HeedFile): "metrics-only" | "no-organization" | undefined;
+/** Heedvane's MCP connection URL for the organization heed.yaml names, unless {@link connectionOff} says there is none. */
 export declare function heedvaneConnector(heedFile: HeedFile): string | undefined;
+/** What to tell a person who asked for the MCP connection but gets none, and why; nothing when it is registered. */
+export declare function connectionNote(heedFile: HeedFile): string | undefined;
+/** The organization an earlier version's connection (`heedvane-findings`) names at `server`, so connect can replace it without --org. */
+export declare function legacyOrganization(clients: readonly ResolvedClient[], server: string): string | undefined;
 /** The MCP containers a client's configs can hold our entries in (Codex's TOML and OpenCode's `mcp` beside the usual key). */
 export declare function mcpContainers(client: ResolvedClient): string[];
 /** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
 export declare function parseClientDoc(path: string, format: DocFormat): Record<string, unknown> | null;
+/** True when the client's MCP config holds Heedvane's connection, not only a user's entry that shares its name. */
+export declare function hasOwnConnection(client: ResolvedClient): boolean;
+/** Whether Heedvane's connection in this client's MCP config is in the key form (mcp.ts `keyConnectorEntry`), for whatever server and organization it names. */
+export declare function sendsOrgKey(client: ResolvedClient): boolean;
 /** The first config of this client still holding an MCP entry an earlier version wrote, and those entries' names. */
 export declare function legacyMcpEntries(client: ResolvedClient): {
     path: string;
     names: string[];
 } | undefined;
+/** The first config of this client holding any Heedvane MCP entry, today's or an earlier version's, and their names. */
+export declare function heedvaneMcpEntries(client: ResolvedClient): {
+    path: string;
+    names: string[];
+} | undefined;
 /**
  * The client whose hooks this one already runs, when that client's hooks are installed too, by this run or
  * an earlier one: installing both would run every event twice, recorded under two agents. Plan and doctor
@@ -77,6 +98,14 @@ interface AgentScope {
 }
 /** Whether a client is detected on this machine via its primary marker or any altMarkerPaths (e.g. GUI ADEs). */
 export declare function isClientDetected(client: ResolvedClient): boolean;
+/** The client's native capability, or hooks written as whole files (definitions.ts `hookFiles`). */
+export declare function supportsCapability(client: ResolvedClient, capability: "hooks" | "mcp" | "skill"): boolean;
+/**
+ * The MCP entries connect removes: under metrics only every Heedvane entry, today's too; without an organization the
+ * local helper, which has no tools any more (a connection under its earlier name still works, and nothing would replace
+ * it); otherwise everything an earlier version registered.
+ */
+export declare function mcpLeftovers(heedFile: HeedFile): (name: string, entry: unknown) => boolean;
 /**
  * The planner. For each client a run installs (installsClient), emit one action per enabled
  * capability the client supports — or an honest skip with a reason it doesn't.

package/dist/plan.js

@@ -6,12 +6,12 @@
  * --dry-run printout and the apply step.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { supportedClients, } from "./clients/definitions.js";
-import { hermesPluginFiles } from "./clients/hermes-plugin.js";
+import { signsInWithOrgKey } from "./backend/credentials.js";
 import { entryValue, isOurHookGroup, parseDoc, readEntry, TOP_LEVEL, valuesEqual } from "./config-doc.js";
 import { genericSnippet } from "./dispatchers/snippets.js";
-import { HEEDVANE_SERVER_NAME, connectorEntry, connectorUrl, isLegacyEntry, mcpEntryNames } from "./mcp.js";
+import { HEEDVANE_SERVER_NAME, MCP_NEEDS_ORG, MCP_OFF_METRICS_ONLY, ORG_KEY_ENV, comparableEntry, connectorEntry, connectorOrganization, connectorUrl, entryUrls, isConnectorEntry, isHeedvaneEntry, isHelperEntry, isLegacyEntry, keyConnectorEntry, mcpEntryNames } from "./mcp.js";
 import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
 import { errorMessage } from "./guards.js";
 /** A client's primary hooks config target, resolved. */
@@ -27,18 +27,14 @@ function mcpTarget(client) {
 /**
  * Desired write targets per client × capability. This is the desired-state
  * compiler heed.yaml → concrete files; doctor reuses it via a callback so
- * it never needs apply.ts. `env` is accepted for API stability — the client's
- * config paths arrive already resolved against it.
+ * it never needs apply.ts. The client's config paths arrive already resolved
+ * against `env`; its HEEDVANE_ORG_KEY picks the software-factory MCP connection.
  */
 export function desiredEntriesFor(client, capability, context) {
-    const home = context.home;
-    void context.env;
     const targets = [];
     if (capability === "hooks") {
-        if (client.id === "hermes") {
-            // Hermes gets a native plugin, not a hooks.json entry.
-            return hermesDesiredFiles(home, context.gating);
-        }
+        if (client.hookFiles !== undefined)
+            return hookFilesDesired(client, client.hookFiles, context.gating);
         // Real harness shape: the `hooks` container is keyed by event name, and
         // we patch per-event so a user's own hook entries are never clobbered.
         const target = hooksTarget(client);
@@ -55,21 +51,66 @@ export function desiredEntriesFor(client, capability, context) {
     }
     if (capability === "mcp") {
         const target = mcpTarget(client);
-        // Windows keeps the bare `npx` its docs show: a `.cmd` path cannot be started without a shell.
-        const entry = context.connector === undefined ? undefined : connectorEntry(client.id, context.connector, process.platform === "win32" ? undefined : installingNodeDir());
+        const entry = context.connector === undefined ? undefined : connectionEntry(client.id, { ...context, connector: context.connector });
         if (target !== undefined && entry !== undefined)
             targets.push({ path: target.path, format: target.format, containerKey: client.mcpServersKey, entryName: HEEDVANE_SERVER_NAME, entry });
         return targets;
     }
     return targets; // skill has no per-client config entry
 }
+/**
+ * On a software factory (HEEDVANE_ORG_KEY set, or an organization key saved with `auth org`), the entry that sends the
+ * key from HEEDVANE_ORG_KEY; else the one that signs in in the browser. The saved key counts too, so connect, auth org
+ * and doctor agree in whatever order and environment they run.
+ */
+function connectionEntry(clientId, context) {
+    const isFactory = Boolean(context.env[ORG_KEY_ENV]?.trim()) || signsInWithOrgKey(join(context.home, ".heed"));
+    const factory = isFactory ? keyConnectorEntry(clientId, context.connector) : undefined;
+    return factory ?? connectorEntry(clientId, context.connector, context.nodeDir);
+}
 /** The folder of the Node running this install: the hook dispatcher records it, and a local MCP bridge runs its npx. */
-export function installingNodeDir() {
+function installingNodeDir() {
     return dirname(process.execPath);
 }
-/** Heedvane's MCP connection URL for the organization heed.yaml names; none without one. */
+/** The folder whose npx runs a local MCP bridge on `platform`; none on Windows, which keeps the bare `npx` its docs show (a `.cmd` path cannot be started without a shell). */
+export function bridgeNodeDir(platform) {
+    return platform === "win32" ? undefined : installingNodeDir();
+}
+/**
+ * Why heed.yaml registers no MCP connection, the one owner of that decision: metrics only, whose promise the
+ * connection's tools would break (they send questions and repository names), or no organization. None when it does.
+ */
+export function connectionOff(heedFile) {
+    if (heedFile.heedvane.dataMode === "metrics-only")
+        return "metrics-only";
+    return heedFile.heedvane.org === undefined ? "no-organization" : undefined;
+}
+/** Heedvane's MCP connection URL for the organization heed.yaml names, unless {@link connectionOff} says there is none. */
 export function heedvaneConnector(heedFile) {
-    return heedFile.heedvane.org === undefined ? undefined : connectorUrl(heedFile.heedvane.url, heedFile.heedvane.org);
+    const { url, org } = heedFile.heedvane;
+    return org === undefined || connectionOff(heedFile) !== undefined ? undefined : connectorUrl(url, org);
+}
+/** What to tell a person who asked for the MCP connection but gets none, and why; nothing when it is registered. */
+export function connectionNote(heedFile) {
+    const off = heedFile.install.mcp ? connectionOff(heedFile) : undefined;
+    if (off === undefined)
+        return undefined;
+    return off === "metrics-only" ? MCP_OFF_METRICS_ONLY : MCP_NEEDS_ORG;
+}
+/** The organization an earlier version's connection (`heedvane-findings`) names at `server`, so connect can replace it without --org. */
+export function legacyOrganization(clients, server) {
+    for (const client of clients) {
+        for (const target of client.configs) {
+            const doc = target.format === "yaml" ? null : parseClientDoc(target.path, target.format);
+            for (const qualified of doc === null ? [] : mcpEntryNames(doc, mcpContainers(client), isLegacyEntry)) {
+                const [container, name] = qualified.split("::");
+                const org = connectorOrganization(doc[container][name], server);
+                if (org !== undefined)
+                    return org;
+            }
+        }
+    }
+    return undefined;
 }
 /** The MCP containers a client's configs can hold our entries in (Codex's TOML and OpenCode's `mcp` beside the usual key). */
 export function mcpContainers(client) {
@@ -84,11 +125,35 @@ export function parseClientDoc(path, format) {
         return null; // absent or unparseable — nothing marker-verified to remove
     }
 }
+/** True when the client's MCP config holds Heedvane's connection, not only a user's entry that shares its name. */
+export function hasOwnConnection(client) {
+    const target = mcpTarget(client);
+    const doc = target === undefined ? null : parseClientDoc(target.path, target.format);
+    return doc !== null && mcpEntryNames(doc, mcpContainers(client), isConnectorEntry).length > 0;
+}
+/** Whether Heedvane's connection in this client's MCP config is in the key form (mcp.ts `keyConnectorEntry`), for whatever server and organization it names. */
+export function sendsOrgKey(client) {
+    const target = mcpTarget(client);
+    const doc = target === undefined ? null : parseClientDoc(target.path, target.format);
+    return doc !== null && mcpEntryNames(doc, mcpContainers(client), isConnectorEntry).some((qualified) => {
+        const [container, name] = qualified.split("::");
+        const entry = doc[container][name];
+        return entryUrls(entry).some((url) => valuesEqual(entry, keyConnectorEntry(client.id, url)));
+    });
+}
 /** The first config of this client still holding an MCP entry an earlier version wrote, and those entries' names. */
 export function legacyMcpEntries(client) {
+    return mcpEntriesMatching(client, isLegacyEntry);
+}
+/** The first config of this client holding any Heedvane MCP entry, today's or an earlier version's, and their names. */
+export function heedvaneMcpEntries(client) {
+    return mcpEntriesMatching(client, isHeedvaneEntry);
+}
+/** The first config of this client holding MCP entries `match` accepts, and their names. */
+function mcpEntriesMatching(client, match) {
     for (const target of client.configs) {
         const doc = target.format === "yaml" ? null : parseClientDoc(target.path, target.format);
-        const names = doc === null ? [] : mcpEntryNames(doc, mcpContainers(client), isLegacyEntry).map((qualified) => qualified.split("::")[1]);
+        const names = doc === null ? [] : mcpEntryNames(doc, mcpContainers(client), match).map((qualified) => qualified.split("::")[1]);
         if (names.length > 0)
             return { path: target.path, names };
     }
@@ -140,14 +205,15 @@ function installsClient(client, scope) {
     const { agents } = scope.heedFile;
     return isClientDetected(client) && (agents === "auto" || agents.includes(client.id));
 }
-function hermesDesiredFiles(home, gating) {
-    // Hermes gets a native plugin (kind: standalone) instead of hooks.json.
-    return hermesPluginFiles(gating).map((f) => ({
-        path: join(home, ".hermes", "plugins", "heedvane-hooks", f.relativePath),
-        format: "json", // plugin.yaml is written verbatim, not patched
+/** The whole files a client's hooks are (Hermes' plugin, Pi's extension): written verbatim, not patched into a config. */
+function hookFilesDesired(client, hookFiles, gating) {
+    const path = hookFiles.path(client.markerPath);
+    return hookFiles.files(gating ?? "always").map((file) => ({
+        path: join(path, file.relativePath),
+        format: "json",
         containerKey: "",
-        entryName: f.relativePath,
-        entry: f.content,
+        entryName: file.relativePath === "" ? basename(path) : file.relativePath,
+        entry: file.content,
     }));
 }
 /** Read-only inspection: what operation would satisfy the desired entry at its path? */
@@ -156,7 +222,7 @@ function inspect(d) {
     if (!existsSync(path))
         return { operation: "create", path };
     const backupPath = `${path}.heedvane.backup`;
-    // Whole-file desired entries (hermes plugin files) compare byte-wise; they are not configs to parse.
+    // Whole-file desired entries (definitions.ts `hookFiles`) compare byte-wise; they are not configs to parse.
     if (containerKey === "") {
         return readFileSync(path, "utf8") === desired ? { operation: "unchanged", path } : { operation: "update", path, backupPath };
     }
@@ -175,7 +241,7 @@ function inspect(d) {
     const current = readEntry(doc, containerKey, entryName);
     if (current === undefined)
         return { operation: "create", path, backupPath };
-    if (!valuesEqual(current, entryValue(containerKey, current, desired)))
+    if (!valuesEqual(comparableEntry(current), comparableEntry(entryValue(containerKey, current, desired))))
         return { operation: "update", path, backupPath };
     return { operation: "unchanged", path };
 }
@@ -213,11 +279,9 @@ function inspectSkill(home, client, desiredDigest) {
     const backupPath = join(dir, "SKILL.md.heedvane.backup");
     return same ? { operation: "unchanged", path: skillMd } : { operation: "update", path: skillMd, backupPath };
 }
-/** Hooks ride the client's native capability, or hermes' plugin-install channel. */
-function supportsCapability(client, capability) {
-    if (client.capabilities.includes(capability))
-        return true;
-    return capability === "hooks" && client.id === "hermes" && client.capabilities.includes("plugin-install");
+/** The client's native capability, or hooks written as whole files (definitions.ts `hookFiles`). */
+export function supportsCapability(client, capability) {
+    return client.capabilities.includes(capability) || (capability === "hooks" && client.hookFiles !== undefined);
 }
 function skipAction(client, reason, path) {
     return { clientId: client.id, kind: "skip", operation: "skip", path: path ?? client.markerPath, reason };
@@ -241,10 +305,24 @@ function noHooksSkip(client) {
 function deferredHooksSkip(client, deferredTo) {
     return skipAction(client, `${client.id}: runs ${deferredTo.displayName}'s hooks, which are installed — a second install would run each event twice`, client.configs[0]?.path);
 }
-/** The MCP action: write the connection where it is wanted, and remove what an earlier version registered either way. */
-function planMcp(client, desireds) {
-    const legacy = legacyMcpEntries(client);
-    const removal = legacy === undefined ? undefined : { operation: "update", path: legacy.path, backupPath: `${legacy.path}.heedvane.backup`, reason: `replaces ${legacy.names.join(", ")}, which an earlier version registered` };
+/**
+ * The MCP entries connect removes: under metrics only every Heedvane entry, today's too; without an organization the
+ * local helper, which has no tools any more (a connection under its earlier name still works, and nothing would replace
+ * it); otherwise everything an earlier version registered.
+ */
+export function mcpLeftovers(heedFile) {
+    const off = connectionOff(heedFile);
+    if (off === "metrics-only")
+        return isHeedvaneEntry;
+    if (off === "no-organization")
+        return isHelperEntry;
+    return isLegacyEntry;
+}
+/** The MCP action: write the connection where it is wanted, and remove the {@link mcpLeftovers} either way. */
+function planMcp(client, desireds, heedFile) {
+    const off = connectionOff(heedFile);
+    const leftover = mcpEntriesMatching(client, mcpLeftovers(heedFile));
+    const removal = leftover === undefined ? undefined : { operation: "remove", path: leftover.path, backupPath: `${leftover.path}.heedvane.backup`, reason: leftoverReason(leftover.names, off) };
     if (desireds.length === 0)
         return removal === undefined ? null : { clientId: client.id, kind: "mcp", ...removal };
     const r = inspectMcp(desireds);
@@ -252,6 +330,13 @@ function planMcp(client, desireds) {
         return { clientId: client.id, kind: "mcp", ...removal };
     return { clientId: client.id, kind: "mcp", operation: r.operation, path: r.path ?? desireds[0].path, backupPath: r.backupPath, reason: r.reason };
 }
+function leftoverReason(names, off) {
+    if (off === "metrics-only")
+        return `removes ${names.join(", ")}: ${MCP_OFF_METRICS_ONLY}`;
+    if (off === "no-organization")
+        return `removes ${names.join(", ")}, the local helper an earlier version registered; ${MCP_NEEDS_ORG}`;
+    return `replaces ${names.join(", ")}, which an earlier version registered`;
+}
 /** One client × one capability → its planned action, or null when nothing to plan. */
 function planCapability(client, capability, ctx) {
     if (!ctx.heedFile.install[capability])
@@ -265,12 +350,12 @@ function planCapability(client, capability, ctx) {
         const r = inspectSkill(ctx.home, client, ctx.desiredSkillDigest);
         return { clientId: client.id, kind: "skill", operation: r.operation, path: r.path ?? join(ctx.home, ".agents", "skills", "heedvane-hooks", "SKILL.md"), backupPath: r.backupPath };
     }
-    const desireds = desiredEntriesFor(client, capability, { home: ctx.home, env: ctx.env, gating: ctx.heedFile.gating.mode, connector: heedvaneConnector(ctx.heedFile) });
+    const desireds = desiredEntriesFor(client, capability, { home: ctx.home, env: ctx.env, gating: ctx.heedFile.gating.mode, connector: heedvaneConnector(ctx.heedFile), nodeDir: ctx.nodeDir });
     if (capability === "mcp")
-        return planMcp(client, desireds);
+        return planMcp(client, desireds, ctx.heedFile);
     if (desireds.length === 0)
         return null;
-    // hooks (including the hermes whole-file plugin shape)
+    // hooks (including whole hook files)
     const primary = desireds[0];
     const worst = worstHooksResult(desireds);
     return {
@@ -290,7 +375,7 @@ export function planActions(input) {
     const { home, platform, env, heedFile } = input;
     const actions = [];
     const desiredSkillDigest = input.skillDigest ?? skillDigest(canonicalSkillFiles());
-    const ctx = { home, env, heedFile, forced: new Set(input.forced), desiredSkillDigest };
+    const ctx = { home, env, heedFile, forced: new Set(input.forced), desiredSkillDigest, nodeDir: bridgeNodeDir(platform) };
     for (const client of supportedClients({ home, platform: platform, env })) {
         if (!installsClient(client, ctx)) {
             // Listed in heed.yaml but not on this machine.
@@ -310,6 +395,6 @@ export function planActions(input) {
 /** Count of distinct agents that would receive a write for a kind. */
 export function wouldInstallCount(actions, kind) {
     return new Set(actions
-        .filter((a) => a.kind === kind && (a.operation === "create" || a.operation === "update"))
+        .filter((a) => a.kind === kind && (a.operation === "create" || a.operation === "update" || a.operation === "remove"))
         .map((a) => a.clientId)).size;
 }

package/dist/render.js

@@ -8,7 +8,7 @@ import { connectorEntry } from "./mcp.js";
 /** What Heedvane installs into an agent, e.g. "hooks + MCP + skill". */
 export function capabilitySummary(client) {
     const parts = [];
-    if (client.capabilities.includes("hooks"))
+    if (client.capabilities.includes("hooks") || client.hookFiles !== undefined)
         parts.push("hooks");
     // Heedvane's MCP connection goes only into agents with a remote-server shape (not Claude Desktop).
     if (client.capabilities.includes("mcp") && connectorEntry(client.id, "") !== undefined)
@@ -37,6 +37,7 @@ const VERB = {
     create: "added",
     update: "updated",
     unchanged: "already current",
+    remove: "removed",
     skip: "skipped",
 };
 function kindLabel(kind) {

package/dist/reply/harness-output.d.ts

@@ -42,9 +42,18 @@ export type HarnessOutput = Record<string, never> | {
 } | {
     action: "block";
     message: string;
+} | {
+    block: true;
+    reason: string;
 } | {
     context: string;
 };
+/**
+ * The top-level output field each agent shows the person without steering (checked 2026-10-20): Claude Code's, Codex's
+ * (learn.chatgpt.com/docs/hooks) and Gemini CLI's (geminicli.com/docs/hooks/reference) `systemMessage`. Cursor shows
+ * `user_message` only with a denial, and Hermes' plugin hooks have no such field, so they have none here.
+ */
+export declare const USER_NOTICE_FIELD: Readonly<Record<string, string>>;
 /** The events a stop block or halt applies to. */
 export declare const STOP_EVENTS: ReadonlySet<string>;
 /**