heedvane 0.0.0-stage → 0.2.0

package/dist/memory/private-memory.d.ts

@@ -0,0 +1,12 @@
+import type { Envelope } from "../events/contract.js";
+import { type Verdict } from "../reply/verdict.js";
+export declare function memoryDir(root: string): string;
+/**
+ * The private memories to inject at session start, in at most `room` characters (what the organization's
+ * rules left of the session-start budget, src/reply/harness-output.ts); `allow` with no context when there
+ * are none. What does not fit is cut with a note naming where the rest is; with no room for any, a pointer; with no room for that, nothing.
+ */
+export declare function recall(root: string, request: {
+    envelope: Envelope;
+    repository: string;
+}, room: number): Promise<Verdict>;

package/dist/memory/private-memory.js

@@ -0,0 +1,54 @@
+/**
+ * A developer's private memories stay on their machine: plain Markdown under `<root>/memory/`
+ * (`~/.heed/memory/`), written by the developer or their agent, never sent to Heedvane. At session
+ * start the hook adds them as context, so every agent (not only the one that wrote them) starts with
+ * them:
+ *
+ * - `MEMORY.md`: memories for every repository.
+ * - `<owner>/<name>.md`: memories for one repository (its origin's owner/name).
+ *
+ * Team memory is separate and lives in Heedvane.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ALLOW } from "../reply/verdict.js";
+export function memoryDir(root) {
+    return join(root, "memory");
+}
+/** The memory files for a repository (`owner/name`, or "" outside a git checkout), general first. */
+function memoryFiles(root, repository) {
+    const general = join(memoryDir(root), "MEMORY.md");
+    return repository === "" ? [general] : [general, join(memoryDir(root), ...repository.split("/")) + ".md"];
+}
+/**
+ * The private memories to inject at session start, in at most `room` characters (what the organization's
+ * rules left of the session-start budget, src/reply/harness-output.ts); `allow` with no context when there
+ * are none. What does not fit is cut with a note naming where the rest is; with no room for any, a pointer; with no room for that, nothing.
+ */
+export async function recall(root, request, room) {
+    if (request.envelope.event !== "session_start")
+        return ALLOW;
+    const texts = await Promise.all(memoryFiles(root, request.repository).map(readMemory));
+    const text = texts.filter((t) => t !== "").join("\n\n");
+    if (text === "")
+        return ALLOW;
+    const dir = memoryDir(root);
+    const header = `Your private memories (${dir}):\n\n`;
+    const note = `\n[truncated: the rest is in ${dir}]`;
+    const pointer = `Your private memories are in ${dir}; read them there.`;
+    const fits = header.length + text.length <= room;
+    const keep = room - header.length - note.length;
+    const cutText = keep > 0 ? header + text.slice(0, keep) + note : null;
+    const context = fits ? header + text : (cutText ?? pointer);
+    return context.length <= room ? { decision: "allow", messages: [], context: [context] } : ALLOW;
+}
+async function readMemory(path) {
+    try {
+        return (await readFile(path, "utf8")).trim();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "";
+        throw err;
+    }
+}

package/dist/memory/table-of-contents.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The team memory's table of contents for the session-start block (docs/product/agent-integration/policies.md
+ * "Session start" owns where it sits: after the policies, before the private memories). Folders and titles,
+ * never memory text. It fills at most the room it is given and shrinks in a fixed order: titles first,
+ * starting with the largest folders; then every folder keeps only its count; last, one line with the
+ * total. Every shorter form still says where the rest is.
+ */
+import type { TeamMemoryMap } from "./team-memory.js";
+/** The table of contents in at most `room` characters; "" when not even the total line fits. */
+export declare function renderTableOfContents(map: TeamMemoryMap, repository: string, room: number): string;

package/dist/memory/table-of-contents.js

@@ -0,0 +1,80 @@
+/** A title is cut here. */
+const TITLE_CHARACTERS = 100;
+const quoted = (folder) => `"${folder}"`;
+/** Cuts on whole characters (never inside a surrogate pair) and says so with an ellipsis. */
+function shortTitle(title) {
+    const characters = Array.from(title);
+    return characters.length <= TITLE_CHARACTERS ? title : `${characters.slice(0, TITLE_CHARACTERS - 1).join("")}…`;
+}
+function entryLine(entry) {
+    const commit = entry.validatedCommitSha === null ? "" : ` at ${entry.validatedCommitSha.slice(0, 7)}`;
+    return `  [${entry.id}] ${shortTitle(entry.title)} · confirmed ${entry.validatedAt.slice(0, 10)}${commit}`;
+}
+function summary(map, repository) {
+    const { live, expired, retired } = map.counts;
+    const gone = [expired > 0 ? `${expired} expired` : "", retired > 0 ? `${retired} retired` : ""].filter((part) => part !== "").join(", ");
+    return `Team memory for ${repository}: ${live} memories in ${map.folders.length} folders${gone === "" ? "" : ` (${gone}: see the team memory page)`}.`;
+}
+const HOW_TO = [
+    'Open a folder: list_team_memory "<folder>" (or: npx heedvane memory list "<folder>"). Read one: get_team_memory <id> (npx heedvane memory show <id>).',
+    'Search: search_team_memory "<question>", optionally inside one folder (npx heedvane memory search "<question>").',
+];
+/** Entries by folder, in the order Heedvane gave them, as the lines they print. */
+function entryLinesByFolder(map) {
+    const byFolder = new Map();
+    for (const entry of map.entries) {
+        const lines = byFolder.get(entry.folder) ?? [];
+        lines.push(entryLine(entry));
+        byFolder.set(entry.folder, lines);
+    }
+    return byFolder;
+}
+/** Every folder with at most `cap` of its entry lines, and a line naming the rest. */
+function withTitles(table, cap) {
+    const { header, map, byFolder } = table;
+    const lines = [...header];
+    for (const { folder, count } of map.folders) {
+        const shown = (byFolder.get(folder) ?? []).slice(0, cap);
+        lines.push(`${folder} (${count})`, ...shown);
+        if (shown.length < count)
+            lines.push(`  ... ${count - shown.length} more: list_team_memory ${quoted(folder)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * The most entries per folder that fit in `room`, or 0 when not even one does. A table never gets shorter
+ * when a folder shows one more title, so the answer is found by halving; no cap above `room` divided by the
+ * shortest entry line can fit, so the search starts there.
+ */
+function largestCapThatFits(room, byFolder, render) {
+    const lines = [...byFolder.values()].flat();
+    const shortest = lines.reduce((least, line) => Math.min(least, line.length), Infinity);
+    let high = Math.min(Math.max(0, ...[...byFolder.values()].map((folder) => folder.length)), Math.floor(room / shortest));
+    let low = 0;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (render(middle).length <= room)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low;
+}
+/** The table of contents in at most `room` characters; "" when not even the total line fits. */
+export function renderTableOfContents(map, repository, room) {
+    if (map.counts.live === 0) {
+        const empty = `Team memory for ${repository} has no memories yet.`;
+        return empty.length <= room ? empty : "";
+    }
+    const byFolder = entryLinesByFolder(map);
+    const header = [summary(map, repository), ...HOW_TO];
+    const table = { header, map, byFolder };
+    const cap = largestCapThatFits(room, byFolder, (candidate) => withTitles(table, candidate));
+    if (cap >= 1)
+        return withTitles(table, cap);
+    const counts = [...header, ...map.folders.map(({ folder, count }) => `${folder} (${count})`)].join("\n");
+    if (counts.length <= room)
+        return counts;
+    const total = `${summary(map, repository).replace(/ \(.*\)\.$/, ".")} List them: list_team_memory (npx heedvane memory list).`;
+    return total.length <= room ? total : "";
+}

package/dist/memory/team-memory.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Heedvane's team memory from this machine (docs/engineering/openviking-foundation.md "Team memory",
+ * the hooks client's routes): `POST /api/agent/memory/<action>` with the checkout's `gitOrigin`. The
+ * session-start table of contents (src/memory/table-of-contents.ts) and `npx heedvane memory ...` read
+ * the same routes. A folder is Heedvane's canonical name (one or two segments, raw UTF-8); this client
+ * hands names back exactly as the routes gave them.
+ */
+import { type Backend } from "../backend/client.js";
+export type TeamMemoryAction = "map" | "list" | "search" | "get";
+/** One live, unexpired memory as the map and a list show it: never its text. */
+export interface TeamMemoryEntry {
+    id: string;
+    title: string;
+    folder: string;
+    createdAt: string;
+    validatedAt: string;
+    commitSha: string | null;
+    validatedCommitSha: string | null;
+}
+/** Every live, unexpired memory of a repository, most recently confirmed first, and its folders in name order (`_general` last). */
+export interface TeamMemoryMap {
+    repositoryId: string;
+    generatedAt: string;
+    entries: TeamMemoryEntry[];
+    folders: Array<{
+        folder: string;
+        count: number;
+    }>;
+    counts: {
+        live: number;
+        expired: number;
+        retired: number;
+    };
+}
+/** The outcome of asking for a route: Heedvane's JSON, or why there is none. */
+export type TeamMemoryAnswer = {
+    state: "answered";
+    json: Record<string, unknown>;
+} | {
+    state: "unavailable";
+    status: number | null;
+    error: string;
+};
+export declare function askTeamMemory(backend: Backend, ask: {
+    action: TeamMemoryAction;
+    body: Record<string, unknown>;
+    timeoutMs?: number;
+}): Promise<TeamMemoryAnswer>;
+/** What the session start learned of the repository's team memory: its map, none to show (no plan, repository not connected), or an unanswered ask. */
+export type TeamMemoryStart = {
+    state: "map";
+    map: TeamMemoryMap;
+} | {
+    state: "none";
+} | {
+    state: "unavailable";
+    error: string;
+};
+/** The map of the repository at `gitOrigin`. A refusal that is about this checkout (a plan without team memory, a repository Heedvane does not know) is "none", not a failure. */
+export declare function fetchTeamMemoryMap(backend: Backend, gitOrigin: string): Promise<TeamMemoryStart>;

package/dist/memory/team-memory.js

@@ -0,0 +1,54 @@
+/**
+ * Heedvane's team memory from this machine (docs/engineering/openviking-foundation.md "Team memory",
+ * the hooks client's routes): `POST /api/agent/memory/<action>` with the checkout's `gitOrigin`. The
+ * session-start table of contents (src/memory/table-of-contents.ts) and `npx heedvane memory ...` read
+ * the same routes. A folder is Heedvane's canonical name (one or two segments, raw UTF-8); this client
+ * hands names back exactly as the routes gave them.
+ */
+import { callHeedvane } from "../backend/client.js";
+import { isRecord } from "../guards.js";
+/** How long the session start waits for the map; the one wait on Heedvane besides the policy fetch, run beside it. */
+const TEAM_MEMORY_MAP_TIMEOUT_MS = 1_000;
+const TEAM_MEMORY_TIMEOUT_MS = 15_000;
+export async function askTeamMemory(backend, ask) {
+    const { action, body, timeoutMs = TEAM_MEMORY_TIMEOUT_MS } = ask;
+    const answer = await callHeedvane(backend, { method: "POST", path: `/api/agent/memory/${action}`, body, timeoutMs });
+    if (answer === null)
+        return { state: "unavailable", status: null, error: "Heedvane did not answer" };
+    if (answer.status === 200 && isRecord(answer.json))
+        return { state: "answered", json: answer.json };
+    const error = isRecord(answer.json) && typeof answer.json["error"] === "string" ? answer.json["error"] : `status ${answer.status}`;
+    return { state: "unavailable", status: answer.status, error };
+}
+/** The `map` route's answer; null when it is not one. */
+function teamMemoryMap(json) {
+    const { repositoryId, generatedAt, entries, folders, counts } = json;
+    if (typeof repositoryId !== "string" || typeof generatedAt !== "string" || !Array.isArray(entries) || !Array.isArray(folders) || !isRecord(counts))
+        return null;
+    const { live, expired, retired } = counts;
+    if (typeof live !== "number" || typeof expired !== "number" || typeof retired !== "number")
+        return null;
+    return {
+        repositoryId,
+        generatedAt,
+        entries: entries.flatMap((entry) => teamMemoryEntry(entry) ?? []),
+        folders: folders.flatMap((folder) => (isRecord(folder) && typeof folder["folder"] === "string" && typeof folder["count"] === "number" ? [{ folder: folder["folder"], count: folder["count"] }] : [])),
+        counts: { live, expired, retired },
+    };
+}
+function teamMemoryEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const { id, title, folder, createdAt, validatedAt, commitSha, validatedCommitSha } = value;
+    if (typeof id !== "string" || typeof title !== "string" || typeof folder !== "string" || typeof createdAt !== "string" || typeof validatedAt !== "string")
+        return null;
+    return { id, title, folder, createdAt, validatedAt, commitSha: typeof commitSha === "string" ? commitSha : null, validatedCommitSha: typeof validatedCommitSha === "string" ? validatedCommitSha : null };
+}
+/** The map of the repository at `gitOrigin`. A refusal that is about this checkout (a plan without team memory, a repository Heedvane does not know) is "none", not a failure. */
+export async function fetchTeamMemoryMap(backend, gitOrigin) {
+    const answer = await askTeamMemory(backend, { action: "map", body: { gitOrigin }, timeoutMs: TEAM_MEMORY_MAP_TIMEOUT_MS });
+    if (answer.state === "unavailable")
+        return answer.status !== null && answer.status < 500 ? { state: "none" } : { state: "unavailable", error: answer.error };
+    const map = teamMemoryMap(answer.json);
+    return map === null ? { state: "unavailable", error: "the map answer is not one" } : { state: "map", map };
+}

package/dist/plan.d.ts

@@ -0,0 +1,77 @@
+import { type Capability, type Env, type ResolvedClient } from "./clients/definitions.js";
+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";
+export interface PlannedAction {
+    clientId: string;
+    kind: ActionKind;
+    operation: Operation;
+    path: string;
+    backupPath?: string;
+    reason?: string;
+}
+export interface PlanInput {
+    home: string;
+    platform: string;
+    env: Env;
+    heedFile: HeedFile;
+    /** Agents named with `--agent`: installed even when not detected on this machine. */
+    forced?: readonly string[];
+    /** Desired skill digest; defaults to the canonical bundled content. */
+    skillDigest?: string;
+}
+/** Our MCP stdio registration entry (unscoped package per the plan's decision). */
+export declare function mcpEntry(): {
+    command: string;
+    args: string[];
+};
+interface Desired {
+    path: string;
+    format: DocFormat;
+    containerKey: string;
+    entryName: string;
+    entry: unknown;
+}
+/** A client's primary hooks config target, resolved. */
+export declare function hooksTarget(client: ResolvedClient): {
+    path: string;
+    format: DocFormat;
+} | undefined;
+/** Where a client's files live: the object form of the per-client path parameters. */
+export interface ClientContext {
+    home: string;
+    env: Env;
+}
+/**
+ * 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.
+ */
+export declare function desiredEntriesFor(client: ResolvedClient, capability: Capability, context: ClientContext & {
+    gating?: HeedGatingConfig["mode"];
+}): Desired[];
+/**
+ * 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
+ * both skip on it.
+ */
+export declare function hooksDeferredTo(client: ResolvedClient, context: ClientContext & AgentScope): ResolvedClient | undefined;
+/** Whether the client's hooks file already holds our hook on any of its events. */
+export declare function ourHooksOnDisk(client: ResolvedClient): boolean;
+/** Which agents a run manages: heed.yaml's `agents`, plus the ones named with `--agent`. */
+interface AgentScope {
+    heedFile: HeedFile;
+    forced?: ReadonlySet<string>;
+}
+/** 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 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.
+ */
+export declare function planActions(input: PlanInput): PlannedAction[];
+/** Count of distinct agents that would receive a write for a kind. */
+export declare function wouldInstallCount(actions: PlannedAction[], kind: "hooks" | "mcp" | "skill"): number;
+export {};

package/dist/plan.js

@@ -0,0 +1,288 @@
+/**
+ * The PURE planner: heed.yaml + machine detection → PlannedAction[].
+ *
+ * Zero side effects — read-only fs for detection/inspection only. This is
+ * what makes --dry-run trivially trustworthy: the same function feeds the
+ * --dry-run printout and the apply step.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { supportedClients, } from "./clients/definitions.js";
+import { hermesPluginFiles } from "./clients/hermes-plugin.js";
+import { entryValue, isOurHookGroup, parseDoc, readEntry, TOP_LEVEL, valuesEqual } from "./config-doc.js";
+import { genericSnippet } from "./dispatchers/snippets.js";
+import { MCP_ENTRY_ARGS, desiredServer } from "./mcp.js";
+import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
+import { errorMessage } from "./guards.js";
+/** Our MCP stdio registration entry (unscoped package per the plan's decision). */
+export function mcpEntry() {
+    return { command: "npx", args: [...MCP_ENTRY_ARGS] };
+}
+/** A client's primary hooks config target, resolved. */
+export function hooksTarget(client) {
+    const target = client.configs.find((t) => t.purpose === "hooks") ?? client.configs[0];
+    return target && target.format !== "yaml" ? { path: target.path, format: target.format } : undefined;
+}
+/** A client's MCP config target, resolved. */
+function mcpTarget(client) {
+    const target = client.configs.find((t) => t.purpose === "mcp");
+    return target && target.format !== "yaml" ? { path: target.path, format: target.format } : undefined;
+}
+/**
+ * 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.
+ */
+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);
+        }
+        // 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);
+        if (!target)
+            return targets;
+        const entry = [hookEntry(client)];
+        if (client.hooksVersion !== undefined) {
+            targets.push({ path: target.path, format: target.format, containerKey: TOP_LEVEL, entryName: "version", entry: client.hooksVersion });
+        }
+        for (const event of client.events) {
+            targets.push({ path: target.path, format: target.format, containerKey: "hooks", entryName: event, entry });
+        }
+        return targets;
+    }
+    if (capability === "mcp") {
+        const target = mcpTarget(client);
+        if (!target)
+            return targets;
+        // Codex (TOML) carries an explicit generous startup timeout for npx cold starts.
+        targets.push({ path: target.path, format: target.format, containerKey: client.mcpServersKey, entryName: "heedvane", entry: desiredServer(client.id) });
+        return targets;
+    }
+    return targets; // skill has no per-client config entry
+}
+/** Our one hook for an event, in the shape the client's hooks file holds it. */
+function hookEntry(client) {
+    const command = genericSnippet(client.id);
+    return client.hookEntries === "flat"
+        ? { command }
+        : { matcher: "", hooks: [{ type: "command", command }] };
+}
+/**
+ * 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
+ * both skip on it.
+ */
+export function hooksDeferredTo(client, context) {
+    const runs = client.runsHooksOf;
+    if (runs === undefined || !context.heedFile.install.hooks)
+        return undefined;
+    const other = supportedClients({ home: context.home, platform: process.platform, env: context.env }).find((c) => c.id === runs);
+    return other !== undefined && (installsClient(other, context) || ourHooksOnDisk(other)) ? other : undefined;
+}
+/** Whether the client's hooks file already holds our hook on any of its events. */
+export function ourHooksOnDisk(client) {
+    const target = hooksTarget(client);
+    if (target === undefined || !existsSync(target.path))
+        return false;
+    try {
+        const doc = parseDoc(readFileSync(target.path, "utf8"), target.format);
+        return client.events.some((event) => {
+            const groups = readEntry(doc, "hooks", event);
+            return Array.isArray(groups) && groups.some(isOurHookGroup);
+        });
+    }
+    catch {
+        return false; // a file that does not parse shows no hook of ours; that client's own row reports it
+    }
+}
+/** Whether a client is detected on this machine via its primary marker or any altMarkerPaths (e.g. GUI ADEs). */
+export function isClientDetected(client) {
+    return existsSync(client.markerPath) || (client.altMarkerPaths?.some((p) => existsSync(p)) ?? false);
+}
+/** Whether a run installs this client: named with `--agent`, or detected and in heed.yaml's `agents` (every one under `auto`). */
+function installsClient(client, scope) {
+    if (scope.forced?.has(client.id) === true)
+        return true;
+    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
+        containerKey: "",
+        entryName: f.relativePath,
+        entry: f.content,
+    }));
+}
+/** Read-only inspection: what operation would satisfy the desired entry at its path? */
+function inspect(d) {
+    const { path, format, containerKey, entryName, entry: desired } = 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.
+    if (containerKey === "") {
+        return readFileSync(path, "utf8") === desired ? { operation: "unchanged", path } : { operation: "update", path, backupPath };
+    }
+    let doc;
+    try {
+        doc = parseDoc(readFileSync(path, "utf8"), format);
+    }
+    catch (err) {
+        return {
+            operation: "update",
+            path,
+            backupPath: `${path}.heedvane.backup`,
+            reason: `existing config does not parse (${errorMessage(err)}) — apply will refuse and report remediation`,
+        };
+    }
+    const current = readEntry(doc, containerKey, entryName);
+    if (current === undefined)
+        return { operation: "create", path, backupPath };
+    if (!valuesEqual(current, entryValue(containerKey, current, desired)))
+        return { operation: "update", path, backupPath };
+    return { operation: "unchanged", path };
+}
+function inspectMcp(client, home, env) {
+    const desireds = desiredEntriesFor(client, "mcp", { home, env });
+    // A client with multiple MCP targets (codex hooks.json + config.toml) is
+    // only "aligned" when every target is; the action reports the worst path.
+    let worst = { operation: "unchanged" };
+    for (const d of desireds) {
+        const r = inspect(d);
+        if (r.operation === "create")
+            return r;
+        if (r.operation === "update")
+            worst = r;
+    }
+    return worst.path ? worst : { ...worst, path: desireds[0].path };
+}
+function inspectSkill(home, client, desiredDigest) {
+    // One shared install dir; the action is reported per managed client so
+    // the plan is honest about per-agent scope.
+    const dir = join(home, ".agents", "skills", "heedvane-hooks");
+    const skillMd = join(dir, "SKILL.md");
+    if (!existsSync(skillMd))
+        return { operation: "create", path: skillMd };
+    const files = canonicalSkillFiles();
+    let same = true;
+    for (const f of files) {
+        const p = join(dir, f.relativePath);
+        if (!existsSync(p) || readFileSync(p, "utf8") !== f.content) {
+            same = false;
+            break;
+        }
+    }
+    void desiredDigest;
+    void client;
+    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");
+}
+function skipAction(client, reason, path) {
+    return { clientId: client.id, kind: "skip", operation: "skip", path: path ?? client.markerPath, reason };
+}
+/** Worst per-target inspection for the hooks capability: first create wins, else the latest update. */
+function worstHooksResult(desireds) {
+    let worst = { operation: "unchanged" };
+    for (const d of desireds) {
+        const r = inspect(d);
+        if (r.operation === "create") {
+            return { operation: "create", path: d.path, backupPath: r.backupPath };
+        }
+        if (r.operation === "update")
+            worst = { ...r, path: r.path ?? d.path };
+    }
+    return worst;
+}
+function noHooksSkip(client) {
+    return skipAction(client, `${client.id}: no native hooks — policies arrive via MCP`, client.configs[0]?.path ?? client.markerPath);
+}
+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);
+}
+/** One client × one capability → its planned action, or null when nothing to plan. */
+function planCapability(client, capability, ctx) {
+    if (!ctx.heedFile.install[capability])
+        return null;
+    if (!supportsCapability(client, capability))
+        return capability === "hooks" ? noHooksSkip(client) : null;
+    const deferredTo = capability === "hooks" ? hooksDeferredTo(client, ctx) : undefined;
+    if (deferredTo !== undefined)
+        return deferredHooksSkip(client, deferredTo);
+    if (capability === "skill") {
+        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 });
+    if (desireds.length === 0)
+        return null;
+    if (capability === "mcp") {
+        const r = inspectMcp(client, ctx.home, ctx.env);
+        const primary = desireds[0];
+        return {
+            clientId: client.id,
+            kind: "mcp",
+            operation: r.operation,
+            path: r.path ?? primary.path,
+            backupPath: r.backupPath,
+            reason: r.reason,
+        };
+    }
+    // hooks (including the hermes whole-file plugin shape)
+    const primary = desireds[0];
+    const worst = worstHooksResult(desireds);
+    return {
+        clientId: client.id,
+        kind: "hooks",
+        operation: worst.operation,
+        path: worst.path ?? primary.path,
+        backupPath: worst.backupPath,
+        reason: worst.reason,
+    };
+}
+/**
+ * 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.
+ */
+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 };
+    for (const client of supportedClients({ home, platform: platform, env })) {
+        if (!installsClient(client, ctx)) {
+            // Listed in heed.yaml but not on this machine.
+            if (heedFile.agents !== "auto" && heedFile.agents.includes(client.id)) {
+                actions.push(skipAction(client, `${client.id}: not detected — skip or force with --agent ${client.id}`));
+            }
+            continue;
+        }
+        for (const capability of ["hooks", "mcp", "skill"]) {
+            const action = planCapability(client, capability, ctx);
+            if (action !== null)
+                actions.push(action);
+        }
+    }
+    return actions;
+}
+/** 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"))
+        .map((a) => a.clientId)).size;
+}