heedvane 0.0.0-stage → 0.1.0

package/dist/dispatchers/posix.js

@@ -0,0 +1,191 @@
+import { chmod, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { validateAgentId } from "./snippets.js";
+/** The stdout a Claude Code PreToolUse hook prints to deny (src/reply/harness-output.ts owns the shape). */
+const UNCHECKED_SKILL_DENY = JSON.stringify({
+    hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "Skills need the Heedvane listener to check them against your organization's approved list, and it is not answering. Start it with: npx heedvane listener start",
+    },
+});
+export function dispatcherScript(agentId, options = {}) {
+    validateAgentId(agentId);
+    // Only Claude Code's deny shape is verified; other agents keep the fail-open fallback.
+    const denySkills = options.denySkillsWhenUnchecked === true && agentId === "claude";
+    const gating = options.gating ?? "always";
+    return `#!/bin/sh
+# heedvane-agent-hook dispatcher for ${agentId} — generated by heedvane-hook. Do not hand-edit.
+# Rewritten wholesale by \`npx heedvane setup\`; policy updates never touch agent configs.
+# Marker: heedvane-agent-hook-form
+# This hook never fails the agent: every path exits 0 and prints exactly one JSON answer, the
+# listener's when it answers in time, else the fallback below.
+
+set -u
+umask 077
+
+HEED_HOOK_AGENT="${agentId}"
+HEED_HOOK_VERSION=1
+HEED_HOOK_SPOOL_CAP=5242880
+HEED_HOOK_SPOOL_TTL_DAYS=7
+
+[ -n "\${HOME:-}" ] || exit 0
+
+# heed.yaml gating.mode: "pane" runs the hooks only in sessions launched with HEED_SESSION set;
+# "always" runs them in every session. Any other session gets no answer, as if no hook ran.
+HEED_HOOK_GATING="${gating}"
+[ "$HEED_HOOK_GATING" = "always" ] || [ -n "\${HEED_SESSION:-}" ] || exit 0
+
+# endpoint.env (written by init/setup/listener start) sits in the heed root; the spool beside it.
+HEED_HOOK_ENDPOINT_FILE="\${HEED_AGENT_HOOK_ENDPOINT:-\${HEED_AGENT_HOOK_ROOT:-$HOME/.heed}/endpoint.env}"
+
+heed_spool_dir() {
+  printf '%s\\n' "\${HEED_HOOK_ENDPOINT_FILE%/*}/spool"
+}
+
+# Escape a string for embedding inside a JSON document (POSIX awk).
+# Encodes backslash, double quote, tab and CR; newlines are re-encoded per record.
+# Other C0 control chars survive as-is — payloads are harness JSON, and v1
+# treats a best-effort escape as acceptable for spool records.
+json_escape() {
+  printf '%s' "$1" | LC_ALL=C awk '
+    NR > 1 { printf "\\\\n" }
+    {
+      gsub(/\\\\/, "\\\\\\\\")
+      gsub(/"/, "\\\\\\"")
+      gsub(/\\t/, "\\\\t")
+      gsub(/\\r/, "\\\\r")
+      printf "%s", $0
+    }'
+}
+
+spool_hook_event() {
+  _body="\${1:-}"
+  [ -n "$_body" ] || return 0
+  _dir="$(heed_spool_dir)"
+  mkdir -p "$_dir" 2>/dev/null || return 0
+  _key="\${HEED_PANE_KEY:-\${HEED_SESSION:-}}"
+  [ -n "$_key" ] || _key="default"
+  _file="$_dir/pane-$_key.jsonl"
+
+  # 7-day TTL: prune stale pane spool files, and the events set aside after a change of sign-in (other-sign-in/), on every write (cheap).
+  find "$_dir" -type f \\( -name 'pane-*.jsonl*' -o -path '*/other-sign-in/*' \\) -mtime "+$HEED_HOOK_SPOOL_TTL_DAYS" -delete 2>/dev/null || :
+
+  # 5 MB cap: once a pane file is over budget, drop further events (never grow unbounded).
+  if [ -f "$_file" ]; then
+    _size="$(wc -c < "$_file" 2>/dev/null || echo 0)"
+    [ "$_size" -lt "$HEED_HOOK_SPOOL_CAP" ] || return 0
+  fi
+
+  _received="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u)"
+  _envelope="{\\"paneKey\\":\\"$(json_escape "\${HEED_PANE_KEY:-\${HEED_SESSION:-}}")\\""
+  _envelope="$_envelope,\\"tabId\\":\\"$(json_escape "\${HEED_TAB_ID:-}")\\""
+  _envelope="$_envelope,\\"worktreeId\\":\\"$(json_escape "\${HEED_WORKTREE_ID:-}")\\""
+  _envelope="$_envelope,\\"launchToken\\":\\"$(json_escape "\${HEED_LAUNCH_TOKEN:-}")\\""
+  _envelope="$_envelope,\\"source\\":\\"$(json_escape "$HEED_HOOK_AGENT")\\""
+  _envelope="$_envelope,\\"receivedAt\\":\\"$(json_escape "$_received")\\""
+  _envelope="$_envelope,\\"id\\":\\"$(json_escape "\${heed_event_id:-}")\\""
+  _envelope="$_envelope,\\"payload\\":\\"$(json_escape "$_body")\\"}"
+
+  printf '%s\\n' "$_envelope" >> "$_file" 2>/dev/null || return 0
+  chmod 600 "$_file" 2>/dev/null || :
+  return 0
+}
+
+# The hook payload arrives on stdin. command -p keeps cat working under a stripped PATH.
+payload="$(command -p cat 2>/dev/null || cat)"
+
+# One id per event, sent live and kept in the spool, so Heedvane can drop the copy when a slow
+# listener already forwarded an event this script then spooled.
+heed_event_id="$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen 2>/dev/null || od -An -N16 -tx1 /dev/urandom 2>/dev/null | tr -d ' \\n')"
+heed_event_id="$(printf '%s' "$heed_event_id" | tr -cd 'A-Za-z0-9-' | cut -c1-64)"
+
+# What the agent gets when the listener cannot answer: {} lets it continue.
+heed_fallback='{}'
+${denySkills ? `case "$payload" in
+  *'"PreToolUse"'*) case "$payload" in
+    *'"tool_name":"Skill"'*|*'"tool_name": "Skill"'*|*'SKILL.md"'*) heed_fallback='${UNCHECKED_SKILL_DENY.replaceAll("'", "'\\''")}' ;;
+  esac ;;
+esac` : "# Skills are not denied without the listener (heedvane.skills.whenUnknown: allow)."}
+${agentId === "claude" ? `# The organization's instructions, pre-rendered by the listener at its last policy sync, are injected
+# even when it cannot answer.
+case "$payload" in
+  *'"hook_event_name":"SessionStart"'*|*'"hook_event_name": "SessionStart"'*) heed_instructions="SessionStart" ;;
+  *'"hook_event_name":"UserPromptSubmit"'*|*'"hook_event_name": "UserPromptSubmit"'*) heed_instructions="UserPromptSubmit" ;;
+  *) heed_instructions="" ;;
+esac
+heed_instructions_file="\${HEED_HOOK_ENDPOINT_FILE%/*}/steering/instructions-\${heed_instructions}.json"
+if [ -n "$heed_instructions" ] && [ -r "$heed_instructions_file" ]; then
+  heed_fallback="$(cat "$heed_instructions_file" 2>/dev/null || printf '{}')"
+fi` : ""}
+
+heed_answer() {
+  printf '%s\\n' "$1"
+  exit 0
+}
+
+[ -n "$payload" ] || heed_answer '{}'
+
+# Port/token come from endpoint.env (HEED_AGENT_HOOK_PORT / HEED_AGENT_HOOK_TOKEN lines).
+# shellcheck disable=SC1090
+if [ -r "$HEED_HOOK_ENDPOINT_FILE" ]; then
+  . "$HEED_HOOK_ENDPOINT_FILE" 2>/dev/null || :
+fi
+
+# No listener contract (endpoint env, port, token): spool instead, still exit 0.
+if [ -z "\${HEED_AGENT_HOOK_PORT:-}" ] || [ -z "\${HEED_AGENT_HOOK_TOKEN:-}" ]; then
+  spool_hook_event "$payload"
+  heed_answer "$heed_fallback"
+fi
+
+# A local answer takes milliseconds. Only a session start waits for Heedvane (its one policy fetch).
+heed_max_time=0.8
+case "$payload" in
+  *'"hook_event_name":"SessionStart"'*|*'"hook_event_name": "SessionStart"'*) heed_max_time=2 ;;
+esac
+
+reply="$(printf '%s' "$payload" | curl -sS --fail -X POST "http://127.0.0.1:\${HEED_AGENT_HOOK_PORT}/hook/${agentId}" \\
+  --connect-timeout 0.5 --max-time "$heed_max_time" --noproxy 127.0.0.1 \\
+  -H "Content-Type: application/json" \\
+  -H "X-Heed-Agent-Hook-Token: \${HEED_AGENT_HOOK_TOKEN}" \\
+  -H "X-Heed-Hook-Version: \${HEED_HOOK_VERSION}" \\
+  -H "X-Heed-Event-Id: \${heed_event_id:-}" \\
+  --data-binary @- 2>/dev/null)" || {
+  spool_hook_event "$payload"
+  heed_answer "$heed_fallback"
+}
+
+# The listener's answer is the agent's hook output (skill check, steering, recalled memory).
+case "$reply" in
+  "{"*) heed_answer "$reply" ;;
+  *) heed_answer "$heed_fallback" ;;
+esac
+`;
+}
+/** The on-disk dispatcher directory under the heed root. */
+export function agentHooksDir(home) {
+    return join(home, ".heed", "agent-hooks");
+}
+/** Write (or update) the dispatcher script for one agent. Idempotent, mode 0700. */
+export async function writeDispatcherScript(home, agent, options = {}) {
+    validateAgentId(agent);
+    const dir = agentHooksDir(home);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const target = join(dir, `${agent}-hook.sh`);
+    const content = dispatcherScript(agent, options);
+    const existing = await currentDispatcherScript(target);
+    if (existing === content)
+        return; // already current
+    await writeFileAtomic(target, content, { mode: 0o700 });
+    await chmod(target, 0o700);
+}
+/** The dispatcher script's current text, or null when absent (it will be written below). */
+async function currentDispatcherScript(target) {
+    try {
+        return await readFile(target, "utf8");
+    }
+    catch {
+        return null; // absent — write below
+    }
+}

package/dist/dispatchers/snippets.d.ts

@@ -0,0 +1,6 @@
+/** Compat alias — A's modules import HOOK_SCRIPT_MARKER from this module. */
+export declare const HOOK_SCRIPT_MARKER = "heedvane-agent-hook-form";
+export declare function validateAgentId(agentId: string): string;
+export declare function genericSnippet(agentId: string): string;
+export declare function claudeSnippet(): string;
+export declare function codexSnippet(): string;

package/dist/dispatchers/snippets.js

@@ -0,0 +1,39 @@
+/**
+ * Per-agent inline snippet generators.
+ *
+ * The snippet is the tiny sh one-liner embedded in the agent's native hook config. It must:
+ *  (a) delegate through a two-tier lookup: HEED_AGENT_HOOK_ROOT when set and
+ *      readable, else $HOME/.heed/agent-hooks — so policy updates never rewrite
+ *      agent configs. Which sessions run the hooks (heed.yaml `gating.mode`), the
+ *      port and the token are the dispatcher script's to decide;
+ *  (b) always exit 0. Observability hooks must never block the agent.
+ *
+ * The trailing `# heedvane-agent-hook-form` comment is the uninstall marker:
+ * `npx heedvane uninstall` removes only entries carrying it. The marker is
+ * owned by src/mcp.ts (SNIPPET_MARKER) so uninstall/doctor share one constant.
+ */
+import { SNIPPET_MARKER as marker } from "../mcp.js";
+/** Compat alias — A's modules import HOOK_SCRIPT_MARKER from this module. */
+export const HOOK_SCRIPT_MARKER = marker;
+export function validateAgentId(agentId) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(agentId)) {
+        throw new Error(`invalid agent id: ${JSON.stringify(agentId)}`);
+    }
+    return agentId;
+}
+export function genericSnippet(agentId) {
+    validateAgentId(agentId);
+    return [
+        `d="\${HEED_AGENT_HOOK_ROOT:-$HOME/.heed}/agent-hooks";`,
+        `s="$d/${agentId}-hook.sh";`,
+        `[ -r "$s" ] || s="$HOME/.heed/agent-hooks/${agentId}-hook.sh";`,
+        `[ -r "$s" ] && sh "$s" "$@";`,
+        `exit 0 # ${marker}`,
+    ].join(" ");
+}
+export function claudeSnippet() {
+    return genericSnippet("claude");
+}
+export function codexSnippet() {
+    return genericSnippet("codex");
+}

package/dist/dispatchers/windows.d.ts

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

package/dist/dispatchers/windows.js

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

package/dist/doctor.d.ts

@@ -0,0 +1,37 @@
+import { type Env } from "./clients/definitions.js";
+import { type DocFormat } from "./config-doc.js";
+export type RegistrationState = "aligned" | "stale" | "missing";
+export interface DoctorCheck {
+    ok: boolean;
+    name: string;
+    detail: string;
+    remediation?: string;
+    /** Warn-only checks never fail the report (listener reachability). */
+    warnOnly?: boolean;
+}
+export interface DoctorReport {
+    healthy: boolean;
+    checks: DoctorCheck[];
+    /** Client ids the report was scoped to, when a scope was given. */
+    scopedTo?: string[];
+}
+/** Where the desired entry for a client capability would be written. */
+export interface DesiredEntry {
+    path: string;
+    format: DocFormat;
+    containerKey: string;
+    entryName: string;
+    entry: unknown;
+}
+export type DesiredEntryLookup = (clientId: string, capability: "hooks" | "mcp") => DesiredEntry[] | undefined;
+export interface DoctorInput {
+    home: string;
+    env: Env;
+    /** Restrict checks to these client ids (the --client flag). */
+    clients?: string[];
+    /** Emits the {status, checks, healthy} envelope in cli; kept here for API parity. */
+    json?: boolean;
+    /** Desired-entry lookup injection; defaults to the pure planner. */
+    desired?: DesiredEntryLookup;
+}
+export declare function runDoctor(input: DoctorInput): Promise<DoctorReport>;

package/dist/doctor.js

@@ -0,0 +1,316 @@
+/**
+ * Scoped, versioned doctor. Every check carries {ok, name, detail,
+ * remediation}. The desired-entry lookup is injected (defaulting to the
+ * pure planner's desiredEntriesFor) so this module never imports apply.ts.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { supportedClients } from "./clients/definitions.js";
+import { entryValue, parseDoc, readEntry, valuesEqual } from "./config-doc.js";
+import { loadHeedFileAt } from "./heed-file.js";
+import { desiredEntriesFor, hooksDeferredTo, isClientDetected } from "./plan.js";
+import { readInstalledSkillDigest } from "./skill/bundle.js";
+import { HeedStateCorruptError, readState } from "./state.js";
+import { readApprovedSkills } from "./skills/approved.js";
+import { readEndpoint } from "./listener/endpoint.js";
+import { errorMessage } from "./guards.js";
+const INIT_REMEDIATION = "run npx heedvane init";
+const SETUP_REMEDIATION = "run npx heedvane setup";
+/** Inspect one desired entry on disk; every failure path produces a detail line, never a throw. */
+function entryVerdict(d, home) {
+    const path = d.path.startsWith("~") ? join(home, d.path.slice(1)) : d.path;
+    if (!existsSync(path)) {
+        return { aligned: false, present: false, detail: `${d.entryName}: missing (${d.path})` };
+    }
+    let doc;
+    try {
+        doc = parseDoc(readFileSync(path, "utf8"), d.format);
+    }
+    catch {
+        return { aligned: false, present: true, detail: `${d.entryName}: config does not parse` };
+    }
+    if (d.containerKey === "") {
+        // Whole-file desired (hermes plugin.yaml).
+        const ok = readFileSync(path, "utf8") === d.entry;
+        return { aligned: ok, present: true, detail: `${d.entryName}: ${ok ? "aligned" : "stale"}` };
+    }
+    const current = readEntry(doc, d.containerKey, d.entryName);
+    if (current === undefined) {
+        return { aligned: false, present: true, detail: `${d.entryName}: missing in ${d.path}` };
+    }
+    if (!valuesEqual(current, entryValue(d.containerKey, current, d.entry))) {
+        return { aligned: false, present: true, detail: `${d.entryName}: stale in ${d.path}` };
+    }
+    return { aligned: true, present: true, detail: `${d.entryName}: aligned` };
+}
+function registrationState(desireds, home) {
+    let sawAny = false;
+    let allAligned = true;
+    const parts = [];
+    for (const d of desireds) {
+        const verdict = entryVerdict(d, home);
+        if (verdict.present)
+            sawAny = true;
+        if (!verdict.aligned)
+            allAligned = false;
+        parts.push(verdict.detail);
+    }
+    if (!sawAny && !allAligned)
+        return { state: "missing", detail: parts.join("; ") || "no heedvane entry found" };
+    if (!allAligned)
+        return { state: "stale", detail: parts.join("; ") };
+    return { state: "aligned", detail: parts.join("; ") };
+}
+function checkNode() {
+    const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    const ok = major >= 22;
+    return {
+        ok,
+        name: "node",
+        detail: `node ${process.versions.node} (${ok ? ">= 22" : "< 22 — heedvane requires Node 22+"})`,
+        remediation: ok ? undefined : "upgrade Node to >= 22 (nvm install 22)",
+    };
+}
+function checkHeedFile(home) {
+    const path = join(home, ".heed", "heed.yaml");
+    if (!existsSync(path)) {
+        return {
+            check: { ok: false, name: "heed.yaml", detail: `missing at ${path}`, remediation: INIT_REMEDIATION },
+        };
+    }
+    try {
+        const parsed = loadHeedFileAt(path);
+        if (parsed.schemaVersion !== "v1") {
+            return {
+                check: { ok: false, name: "heed.yaml", detail: `unsupported schemaVersion ${parsed.schemaVersion}`, remediation: INIT_REMEDIATION },
+            };
+        }
+        return {
+            check: { ok: true, name: "heed.yaml", detail: `parses, schemaVersion ${parsed.schemaVersion}, agents: ${parsed.agents === "auto" ? "auto" : parsed.agents.join(", ")}` },
+            heedFile: parsed,
+        };
+    }
+    catch (err) {
+        return {
+            check: {
+                ok: false,
+                name: "heed.yaml",
+                detail: `does not parse: ${errorMessage(err)}`,
+                remediation: INIT_REMEDIATION,
+            },
+        };
+    }
+}
+function checkState() {
+    // state.json surfaces via readState in runDoctor; kept for doc parity.
+}
+void checkState;
+/** The client ids the report is scoped to, or null for all clients. */
+function scopeSet(clients) {
+    return clients && clients.length > 0 ? new Set(clients) : null;
+}
+/** The pure-planner desired-entry lookup, resolving each client id against home/env. */
+function defaultDesiredLookup(home, env) {
+    return (clientId, capability) => {
+        const client = supportedClients({ home, platform: process.platform, env }).find((c) => c.id === clientId);
+        if (!client)
+            return undefined;
+        return desiredEntriesFor(client, capability, { home, env }).map((d) => ({
+            path: d.path,
+            format: d.format,
+            containerKey: d.containerKey,
+            entryName: d.entryName,
+            entry: d.entry,
+        }));
+    };
+}
+/** Read state.json, pushing a remediation-carrying check when it exists but is corrupt. */
+async function readStateOrReport(root, checks) {
+    try {
+        return await readState(root);
+    }
+    catch (err) {
+        if (!(err instanceof HeedStateCorruptError))
+            throw err;
+        checks.push({
+            ok: false,
+            name: "state.json",
+            detail: `corrupt: ${err.message}`,
+            remediation: `delete ${join(root, "state.json")} and ${SETUP_REMEDIATION}`,
+        });
+        return null;
+    }
+}
+/** Does heed.yaml (when present) have setup configure this capability for this client? */
+function heedFileWants(client, capability, ctx) {
+    const heedFile = ctx.heedFile;
+    if (heedFile === undefined)
+        return true;
+    if (heedFile.agents !== "auto" && !heedFile.agents.includes(client.id))
+        return false;
+    if (!heedFile.install[capability])
+        return false;
+    // Setup skips hooks another installed client already runs here (Cursor runs Claude Code's).
+    return capability !== "hooks" || hooksDeferredTo(client, { home: ctx.home, env: ctx.env, heedFile }) === undefined;
+}
+/** Registration verdicts for the capabilities this client should have configured. */
+function collectCapabilityStates(client, ctx) {
+    const states = [];
+    for (const capability of ["hooks", "mcp"]) {
+        const supported = client.capabilities.includes(capability) || (capability === "hooks" && client.id === "hermes" && client.capabilities.includes("plugin-install"));
+        if (!supported || !heedFileWants(client, capability, ctx))
+            continue;
+        const desireds = ctx.desired(client.id, capability);
+        if (!desireds || desireds.length === 0)
+            continue;
+        states.push({ capability, result: registrationState(desireds, ctx.home) });
+    }
+    return states;
+}
+/** One detected client's registration check (aligned / stale / missing with per-entry detail). */
+function pushRegistrationChecks(checks, client, ctx) {
+    const detected = isClientDetected(client);
+    if (!detected) {
+        // Under `agents: auto`, an undetected client is normal — no check.
+        // Only fail when the user explicitly listed this client in heed.yaml.
+        const explicitlyListed = ctx.heedFile && ctx.heedFile.agents !== "auto" && ctx.heedFile.agents.includes(client.id);
+        if (!explicitlyListed)
+            return;
+        checks.push({
+            ok: false,
+            name: `${client.id} registration`,
+            detail: `${client.displayName} not detected (no ${client.markerPath})`,
+            remediation: `install ${client.displayName} or remove ${client.id} from heed.yaml agents`,
+        });
+        return;
+    }
+    const states = collectCapabilityStates(client, ctx);
+    if (states.length === 0)
+        return;
+    const allAligned = states.every((s) => s.result.state === "aligned");
+    const detail = states.map((s) => `${s.capability}: ${s.result.state} (${s.result.detail})`).join("; ");
+    checks.push({
+        ok: allAligned,
+        name: `${client.id} registration`,
+        detail,
+        remediation: allAligned ? undefined : SETUP_REMEDIATION,
+    });
+}
+/** The skill-digest verdict against state.json (aligned / stale / missing / unrecorded). */
+function skillDigestCheck(skillsRoot, state, installedDigest) {
+    const name = "skill digest";
+    if (state === null) {
+        return installedDigest !== null
+            ? { ok: false, name, detail: "installed but state.json has no record", remediation: SETUP_REMEDIATION }
+            : { ok: false, name, detail: "skill missing and no state.json", remediation: INIT_REMEDIATION };
+    }
+    const expected = state.skill?.digest;
+    if (expected === undefined) {
+        return { ok: false, name, detail: "state.json records no skill install", remediation: SETUP_REMEDIATION };
+    }
+    if (installedDigest === null) {
+        return { ok: false, name, detail: `skill not installed at ${join(skillsRoot, "heedvane-hooks")}`, remediation: SETUP_REMEDIATION };
+    }
+    if (installedDigest === expected) {
+        return { ok: true, name, detail: `matches state.json (${expected.slice(0, 12)}…)` };
+    }
+    return {
+        ok: false,
+        name,
+        detail: `stale: installed ${installedDigest.slice(0, 12)}…, state.json ${expected.slice(0, 12)}…`,
+        remediation: SETUP_REMEDIATION,
+    };
+}
+export async function runDoctor(input) {
+    const { home, env } = input;
+    const checks = [];
+    // 1. Node version.
+    checks.push(checkNode());
+    // 2. heed.yaml exists + parses (schemaVersion v1).
+    const { check: heedCheck, heedFile } = checkHeedFile(home);
+    checks.push(heedCheck);
+    // 3. state.json (corrupt → remediation).
+    const root = join(home, ".heed");
+    const state = await readStateOrReport(root, checks);
+    // 4. Desired-entry lookup: injected, falling back to the pure planner.
+    const desired = input.desired ?? defaultDesiredLookup(home, env);
+    // 5. Per detected client: registration state aligned | stale | missing.
+    const scope = scopeSet(input.clients);
+    const allClients = supportedClients({ home, platform: process.platform, env });
+    const clients = allClients.filter((c) => (scope ? scope.has(c.id) : true));
+    const regCtx = { home, env, heedFile, desired };
+    for (const client of clients) {
+        pushRegistrationChecks(checks, client, regCtx);
+    }
+    // 6. Skill digest vs state.json (aligned / stale / missing), unless heed.yaml opts out of the skill.
+    if (heedFile?.install.skill !== false) {
+        const skillsRoot = join(home, ".agents", "skills");
+        const installedDigest = await readInstalledSkillDigest(skillsRoot);
+        checks.push(skillDigestCheck(skillsRoot, state, installedDigest));
+    }
+    // 7. Listener reachable — best-effort POST, warn-only, never fails the report.
+    checks.push(await checkListener(root));
+    checks.push(await checkApprovedSkills(root, heedFile));
+    const healthy = checks.every((c) => c.ok || c.warnOnly);
+    return { healthy, checks, scopedTo: scope ? [...scope] : undefined };
+}
+const ENFORCEMENT_OFF = "skill checks, steering and memory are off until it runs (skills follow heedvane.skills.whenUnknown)";
+/** A synced approved list older than this is reported, not ignored: revocations reach this machine only on sync. */
+const APPROVED_LIST_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Warn-only: is there an approved-skills list for the skill check to enforce, and is it recent? */
+async function checkApprovedSkills(root, heedFile) {
+    const base = { ok: true, name: "approved skills", detail: "", warnOnly: true };
+    const skills = heedFile?.heedvane.skills;
+    if (skills?.enforce === false)
+        return { ...base, detail: "not enforced (heedvane.skills.enforce: false)" };
+    const list = await readApprovedSkills(root);
+    const sync = "run npx heedvane skills sync";
+    if (list === null) {
+        const detail = skills?.whenUnknown === "deny"
+            ? "no list synced — every skill is denied (heedvane.skills.whenUnknown: deny)"
+            : "SKILLS ARE NOT ENFORCED: no list synced, so every skill is allowed unchecked (heedvane.skills.whenUnknown: allow)";
+        return { ...base, ok: false, detail, remediation: `${sync} (a failed sync printed why)` };
+    }
+    const age = Date.now() - Date.parse(list.syncedAt);
+    if (age > APPROVED_LIST_STALE_MS)
+        return { ...base, ok: false, detail: `${list.skills.length} approved, synced ${list.syncedAt}: revocations since then are not enforced`, remediation: sync };
+    return { ...base, detail: `${list.skills.length} approved, synced ${list.syncedAt}` };
+}
+async function checkListener(root) {
+    const base = { ok: true, name: "listener", detail: "", warnOnly: true };
+    let endpoint;
+    try {
+        endpoint = await readEndpoint(root);
+    }
+    catch {
+        return { ...base, detail: "endpoint.env unreadable — listener not configured (opt-in in v1)" };
+    }
+    if (!endpoint) {
+        return {
+            ...base,
+            detail: `not running — ${ENFORCEMENT_OFF}; hook events spool to ~/.heed/spool until a listener starts (npx heedvane listener start)`,
+        };
+    }
+    if (!endpoint.port) {
+        return { ...base, detail: "endpoint.env incomplete (no port) — re-run npx heedvane setup" };
+    }
+    try {
+        const res = await fetch(`http://127.0.0.1:${endpoint.port}/hook/claude`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(endpoint.token ? { "x-heed-agent-hook-token": endpoint.token } : {}) },
+            body: JSON.stringify({ v: 1, event: "doctor_probe", agent: "claude", receivedAt: new Date().toISOString() }),
+            signal: AbortSignal.timeout(750),
+        });
+        if (res.ok || res.status === 400 || res.status === 401) {
+            // Reachable is the point; auth/payload validation is the server's business.
+            return { ...base, detail: `reachable on 127.0.0.1:${endpoint.port}` };
+        }
+        return { ...base, detail: `responded ${res.status} on 127.0.0.1:${endpoint.port} (reachable)` };
+    }
+    catch {
+        return {
+            ...base,
+            detail: `not reachable on 127.0.0.1:${endpoint.port} — ${ENFORCEMENT_OFF}; events will spool (warn-only; never fails the report)`,
+        };
+    }
+}