vigiles 2.4.0 → 2.6.0

package/dist/harness-test.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveHarness = exports.loadPlugin = exports.scriptModel = void 0;
+exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.resolveHarness = exports.loadPlugin = exports.scriptModel = void 0;
 exports.parseToolCalls = parseToolCalls;
+exports.parseResultEvent = parseResultEvent;
+exports.parseOutput = parseOutput;
+exports.parseHooks = parseHooks;
+exports.buildClaudeArgs = buildClaudeArgs;
 exports.claudeAvailable = claudeAvailable;
 exports.runHarnessTest = runHarnessTest;
 /**
@@ -28,10 +32,11 @@ exports.runHarnessTest = runHarnessTest;
  * The "steps" are the scripted model turns — their real home is deterministic
  * harness testing, not production enforcement.
  *
- * Note: the simple mock drives the Bash tool and Stop hooks reliably; the
- * Edit/Write tools are gated in headless mode and don't fire via the mock —
- * drive file actions through Bash, or use the real-model eval tier (`eval.ts`)
- * for Edit/Write hooks.
+ * Note: the mock drives Bash and Stop hooks, and — verified on claude 2.1.169 —
+ * the Edit/Write tools too (allowlisted past the permission prompt), so their
+ * PreToolUse/PostToolUse hooks fire in this tier. The events the mock can't
+ * trigger (PreCompact / Notification / SessionEnd / SubagentStop) belong to the
+ * `runHook` unit tier.
  */
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -39,11 +44,16 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const mock_model_js_1 = require("./mock-model.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
+const sandbox_js_1 = require("./sandbox.js");
 var mock_model_js_2 = require("./mock-model.js");
 Object.defineProperty(exports, "scriptModel", { enumerable: true, get: function () { return mock_model_js_2.scriptModel; } });
 var plugin_loader_js_2 = require("./plugin-loader.js");
 Object.defineProperty(exports, "loadPlugin", { enumerable: true, get: function () { return plugin_loader_js_2.loadPlugin; } });
 Object.defineProperty(exports, "resolveHarness", { enumerable: true, get: function () { return plugin_loader_js_2.resolveHarness; } });
+var sandbox_js_2 = require("./sandbox.js");
+Object.defineProperty(exports, "decideSandbox", { enumerable: true, get: function () { return sandbox_js_2.decideSandbox; } });
+Object.defineProperty(exports, "specTrusted", { enumerable: true, get: function () { return sandbox_js_2.specTrusted; } });
+Object.defineProperty(exports, "sandboxAvailable", { enumerable: true, get: function () { return sandbox_js_2.sandboxAvailable; } });
 function contentText(content) {
     if (typeof content === "string")
         return content;
@@ -101,6 +111,92 @@ function parseToolCalls(streamJson) {
         isError: results.get(u.id)?.isError ?? false,
     }));
 }
+/**
+ * The terminal `result` event — present in BOTH `--output-format` shapes (a
+ * `{type:"result", …}` line in stream-json, the single object in `json`), or
+ * null. The seam for the final answer + turn count without parsing twice.
+ */
+function parseResultEvent(stdout) {
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (evt.type === "result")
+            return evt;
+    }
+    return null;
+}
+/** The agent's final answer text from a transcript / result object, or "". */
+function parseOutput(stdout) {
+    const result = parseResultEvent(stdout)?.result;
+    return typeof result === "string" ? result : "";
+}
+/**
+ * The hooks that fired, recorded from the CLI's `hook_response` stream events
+ * (`--output-format stream-json`). Each carries the hook name/event, its exit
+ * code, and whether it blocked — the honest record vs. inferring from marker
+ * files. Returns [] for the non-stream `json` output (no per-hook events).
+ */
+function toHookFire(evt) {
+    const exitCode = typeof evt.exit_code === "number" ? evt.exit_code : undefined;
+    return {
+        name: typeof evt.hook_name === "string" ? evt.hook_name : "",
+        event: typeof evt.hook_event === "string" ? evt.hook_event : "",
+        exitCode,
+        blocked: evt.outcome === "error" || (exitCode !== undefined && exitCode !== 0),
+        output: typeof evt.output === "string" ? evt.output : "",
+    };
+}
+function parseHooks(stdout) {
+    const hooks = [];
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (evt.type === "system" && evt.subtype === "hook_response") {
+            hooks.push(toHookFire(evt));
+        }
+    }
+    return hooks;
+}
+/**
+ * The `claude` CLI argv for a harness run (shared by the direct and sandboxed
+ * paths). `ANTHROPIC_BASE_URL` is set by the caller's environment / wrapper, not
+ * here. Pure, so the arg shape is unit-tested.
+ */
+function buildClaudeArgs(spec, hasSettings) {
+    const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
+    return [
+        "-p",
+        spec.prompt ?? "go",
+        ...(spec.transcript
+            ? ["--output-format", "stream-json", "--verbose"]
+            : ["--output-format", "json"]),
+        "--model",
+        "claude-sonnet-4-5",
+        ...(spec.pluginDir !== undefined
+            ? ["--plugin-dir", (0, node_path_1.resolve)(spec.pluginDir)]
+            : []),
+        ...(hasSettings ? ["--settings", "settings.json"] : []),
+        "--allowedTools",
+        ...tools,
+    ];
+}
+/* v8 ignore start -- spawns the real claude CLI + filesystem; exercised by the
+   claude-backed suite, excluded from the deterministic coverage gate (the parse
+   helpers above carry the testable logic). */
 /** Whether the `claude` CLI is available — harness tests need it. */
 function claudeAvailable() {
     try {
@@ -150,8 +246,20 @@ function spawnClaude(args, cwd, baseUrl, timeoutMs) {
 /**
  * Run the real `claude` CLI against a scripted mock model, with the given
  * fixture and settings (hooks). Deterministic — same script, same result.
+ *
+ * Safe by default: an external `plugin` / `pluginDir` brings in untrusted
+ * third-party hooks and is confined under bubblewrap (`spec.sandbox`, default
+ * `"auto"`); if no sandbox is available the run REFUSES rather than executing
+ * unconfined. See `src/sandbox.ts`.
  */
 async function runHarnessTest(spec) {
+    const decision = (0, sandbox_js_1.decideSandbox)({
+        trusted: (0, sandbox_js_1.specTrusted)(spec),
+        mode: spec.sandbox ?? "auto",
+        available: (0, sandbox_js_1.sandboxAvailable)(),
+    });
+    if (decision.action === "throw")
+        throw new Error(decision.reason);
     const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
     const { files, settings } = (0, plugin_loader_js_1.resolveHarness)({
         plugin: spec.plugin,
@@ -159,43 +267,45 @@ async function runHarnessTest(spec) {
         files: spec.files,
     });
     writeFixture(cwd, files, settings);
+    const args = buildClaudeArgs(spec, settings !== undefined);
+    const timeoutMs = spec.timeoutMs ?? 60000;
+    const build = (out, turns, modelRequests) => ({
+        exitCode: out.code,
+        stdout: out.stdout,
+        stderr: out.stderr ?? "",
+        cwd,
+        turns,
+        toolCalls: parseToolCalls(out.stdout),
+        hooks: parseHooks(out.stdout),
+        output: parseOutput(out.stdout),
+        modelRequests,
+        file: (p) => {
+            const f = (0, node_path_1.resolve)(cwd, p);
+            return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
+        },
+        cleanup: () => {
+            (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
+        },
+    });
+    // Confined path: the mock is co-launched inside the sandbox's netns.
+    if (decision.action === "sandbox") {
+        const out = await (0, sandbox_js_1.runSandboxed)({
+            cwd,
+            claudeArgs: args,
+            script: spec.model,
+            timeoutMs,
+        });
+        return build(out, out.requests.length, out.requests);
+    }
+    // Direct path: mock runs in this process; claude reaches it over localhost.
     const mock = await (0, mock_model_js_1.startMock)(spec.model);
     try {
-        const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
-        const args = [
-            "-p",
-            spec.prompt ?? "go",
-            ...(spec.transcript
-                ? ["--output-format", "stream-json", "--verbose"]
-                : ["--output-format", "json"]),
-            "--model",
-            "claude-sonnet-4-5",
-            ...(spec.pluginDir !== undefined
-                ? ["--plugin-dir", (0, node_path_1.resolve)(spec.pluginDir)]
-                : []),
-            ...(settings !== undefined ? ["--settings", "settings.json"] : []),
-            "--allowedTools",
-            ...tools,
-        ];
-        const out = await spawnClaude(args, cwd, mock.url, spec.timeoutMs ?? 60000);
-        return {
-            exitCode: out.code,
-            stdout: out.stdout,
-            stderr: out.stderr,
-            cwd,
-            turns: mock.count,
-            toolCalls: parseToolCalls(out.stdout),
-            file: (p) => {
-                const f = (0, node_path_1.resolve)(cwd, p);
-                return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
-            },
-            cleanup: () => {
-                (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
-            },
-        };
+        const out = await spawnClaude(args, cwd, mock.url, timeoutMs);
+        return build(out, mock.count, [...mock.requests]);
     }
     finally {
         mock.close();
     }
 }
+/* v8 ignore stop */
 //# sourceMappingURL=harness-test.js.map

package/dist/judge.js

@@ -36,6 +36,7 @@ function firstJsonObject(s) {
         return null;
     }
 }
+/* v8 ignore start -- spawns the real claude CLI; parseJudgeOutput holds the logic */
 /** Grade `output` against `rubric` with a model. Synchronous (for `measure`). */
 function judge(opts) {
     const threshold = opts.threshold ?? 0.5;
@@ -65,6 +66,7 @@ function judge(opts) {
     }
     return parseJudgeOutput(res.stdout ?? "", threshold);
 }
+/* v8 ignore stop */
 /**
  * Parse a verdict out of the grader's stdout — pure, so the parsing is testable
  * without a model. Handles `claude --output-format json` (text wrapped in a

package/dist/linters.d.ts

@@ -24,6 +24,12 @@ export interface DetectedLinter {
 }
 /** @internal */ export declare function extractLinterName(enforcedBy: string): string;
 /** @internal */ export declare function extractRuleName(enforcedBy: string): string | null;
+/**
+ * Levenshtein distance for short-string typo detection. Rule names are
+ * short so edit distance is more appropriate than NCD (which is tuned
+ * for longer texts).
+ */
+export declare function editDistance(a: string, b: string): number;
 /** @internal */ export declare function clearCedarCache(): void;
 /**
  * Check a single linter rule reference (e.g., "eslint/no-console").

package/dist/linters.js

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractLinterName = extractLinterName;
 exports.extractRuleName = extractRuleName;
+exports.editDistance = editDistance;
 exports.clearCedarCache = clearCedarCache;
 exports.checkLinterRule = checkLinterRule;
 const node_fs_1 = require("node:fs");

package/dist/linting.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
+ * files. Re-exports the spec builders/types and the compiler under one
+ * concern-named import. The granular paths (`vigiles/spec`, `vigiles/compile`)
+ * keep working; this just groups them so the import name matches the pillar.
+ */
+export * from "./spec.js";
+export * from "./compile.js";
+//# sourceMappingURL=linting.d.ts.map

package/dist/linting.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
+ * files. Re-exports the spec builders/types and the compiler under one
+ * concern-named import. The granular paths (`vigiles/spec`, `vigiles/compile`)
+ * keep working; this just groups them so the import name matches the pillar.
+ */
+__exportStar(require("./spec.js"), exports);
+__exportStar(require("./compile.js"), exports);
+//# sourceMappingURL=linting.js.map

package/dist/mock-entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mock-entry.d.ts.map

package/dist/mock-entry.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * vigiles — the in-sandbox mock entry.
+ *
+ * Run as a subprocess INSIDE the bubblewrap network namespace (see
+ * `src/sandbox.ts`), so the scripted mock lives on the sandbox's isolated
+ * loopback — reachable by the confined `claude`, unreachable from outside.
+ * Reads the model script from a file, streams each captured request to an ndjson
+ * file the parent reads back (for `trace.modelRequests`), and writes its chosen
+ * port so the wrapper can point `ANTHROPIC_BASE_URL` at it.
+ *
+ *   node mock-entry.js <scriptFile> <requestsFile> <portFile>
+ *
+ * Not unit-tested directly (it's a daemon driven only through a live sandbox);
+ * exercised end-to-end by the bwrap-backed integration test.
+ */
+const node_fs_1 = require("node:fs");
+const mock_model_js_1 = require("./mock-model.js");
+void (async () => {
+    const [scriptFile, requestsFile, portFile] = process.argv.slice(2);
+    if (!scriptFile || !requestsFile || !portFile) {
+        process.stderr.write("mock-entry: scriptFile requestsFile portFile\n");
+        process.exit(2);
+    }
+    const turns = JSON.parse((0, node_fs_1.readFileSync)(scriptFile, "utf-8"));
+    const handle = await (0, mock_model_js_1.startMock)(turns, {
+        onRequest: (req) => {
+            (0, node_fs_1.appendFileSync)(requestsFile, JSON.stringify(req) + "\n");
+        },
+    });
+    // Signal readiness last: the wrapper waits for a non-empty port file.
+    (0, node_fs_1.writeFileSync)(portFile, new URL(handle.url).port);
+    // Stay alive until the wrapper kills us once `claude` has finished.
+})();
+//# sourceMappingURL=mock-entry.js.map

package/dist/mock-model.d.ts

@@ -14,12 +14,38 @@ export interface TurnInfo {
     readonly stream: boolean;
     readonly hasToolResult: boolean;
 }
+/**
+ * One `/v1/messages` request the mock received, flattened to text for
+ * assertions. This is the seam that lets a harness test prove what reached the
+ * model — a SessionStart hook's injected `additionalContext`, or a slash
+ * command's expansion — not just that a hook fired.
+ */
+export interface ModelRequest {
+    /** The system prompt, flattened to text (string or text-block array). */
+    readonly system: string;
+    /** The conversation messages, each flattened to `{ role, text }`. */
+    readonly messages: readonly {
+        readonly role: string;
+        readonly text: string;
+    }[];
+}
 export interface MockHandle {
     readonly url: string;
     close(): void;
     /** Number of model turns served so far. */
     readonly count: number;
+    /** Every `/v1/messages` request the mock received, in order. */
+    readonly requests: readonly ModelRequest[];
 }
+/**
+ * Extract a {@link ModelRequest} from a request body — the `system` prompt and
+ * `messages`, each flattened to text. Pure and exported so the capture logic is
+ * testable without the HTTP server.
+ */
+export declare function extractRequest(body: {
+    system?: unknown;
+    messages?: unknown;
+}): ModelRequest;
 /**
  * Start the scripted mock on a free port. Each `/v1/messages` POST consumes the
  * next turn (the last turn repeats if the client asks for more). Resolves to a
@@ -27,5 +53,8 @@ export interface MockHandle {
  */
 export declare function startMock(script: readonly ModelTurn[], opts?: {
     onTurn?: (info: TurnInfo) => void;
+    /** Called with each `/v1/messages` request as it arrives — used by the
+     * in-sandbox mock entry to stream requests to a file for the parent. */
+    onRequest?: (req: ModelRequest) => void;
 }): Promise<MockHandle>;
 //# sourceMappingURL=mock-model.d.ts.map

package/dist/mock-model.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scriptModel = scriptModel;
+exports.extractRequest = extractRequest;
 exports.startMock = startMock;
 /**
  * vigiles — a scripted, deterministic Anthropic Messages API mock.
@@ -127,6 +128,38 @@ function jsonTurn(res, turn, model) {
         usage: { input_tokens: 10, output_tokens: 5 },
     }));
 }
+/** Flatten Anthropic content (string, or an array of text/other blocks) to text. */
+function flattenContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((b) => {
+        if (typeof b === "string")
+            return b;
+        const t = b.text;
+        return typeof t === "string" ? t : "";
+    })
+        .join("");
+}
+/**
+ * Extract a {@link ModelRequest} from a request body — the `system` prompt and
+ * `messages`, each flattened to text. Pure and exported so the capture logic is
+ * testable without the HTTP server.
+ */
+function extractRequest(body) {
+    const messages = Array.isArray(body.messages)
+        ? body.messages.map((m) => {
+            const msg = m;
+            return {
+                role: typeof msg.role === "string" ? msg.role : "",
+                text: flattenContent(msg.content),
+            };
+        })
+        : [];
+    return { system: flattenContent(body.system), messages };
+}
 /**
  * Start the scripted mock on a free port. Each `/v1/messages` POST consumes the
  * next turn (the last turn repeats if the client asks for more). Resolves to a
@@ -134,6 +167,7 @@ function jsonTurn(res, turn, model) {
  */
 function startMock(script, opts = {}) {
     let i = 0;
+    const requests = [];
     const server = node_http_1.default.createServer((req, res) => {
         let body = "";
         req.on("data", (c) => (body += c));
@@ -158,6 +192,9 @@ function startMock(script, opts = {}) {
                 res.end(JSON.stringify({ input_tokens: 10 }));
                 return;
             }
+            const request = extractRequest(reqBody);
+            requests.push(request);
+            opts.onRequest?.(request);
             const last = JSON.stringify(reqBody.messages?.at(-1)?.content ?? "");
             opts.onTurn?.({
                 n: i,
@@ -182,6 +219,9 @@ function startMock(script, opts = {}) {
                 get count() {
                     return i;
                 },
+                get requests() {
+                    return requests;
+                },
             });
         });
     });

package/dist/plugin-loader.js

@@ -26,16 +26,19 @@ exports.resolveHarness = resolveHarness;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
-/** Read and return the `.hooks` field of a JSON file, or undefined on any error. */
-function readHooksFile(path) {
+/** Parse a JSON file, or null on any error (missing / malformed). */
+function safeReadJson(path) {
     try {
-        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"))
-            .hooks;
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
     }
     catch {
-        return undefined;
+        return null;
     }
 }
+/** Read and return the `.hooks` field of a JSON file, or undefined on any error. */
+function readHooksFile(path) {
+    return safeReadJson(path)?.hooks;
+}
 /**
  * Read the hooks block, handling the real-world plugin layouts:
  *   1. inline `hooks` object in .claude-plugin/plugin.json,
@@ -44,9 +47,10 @@ function readHooksFile(path) {
  *   4. a plain repo's `.claude/settings.json`.
  */
 function readHooks(root) {
-    const manifestPath = (0, node_path_1.join)(root, ".claude-plugin", "plugin.json");
-    if ((0, node_fs_1.existsSync)(manifestPath)) {
-        const m = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
+    // A malformed plugin.json must not crash the loader — fall through to the
+    // other layouts (safeReadJson returns null on a parse error).
+    const m = safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"));
+    if (m) {
         if (typeof m.hooks === "string")
             return readHooksFile((0, node_path_1.join)(root, m.hooks));
         if (m.hooks !== undefined)
@@ -134,6 +138,12 @@ function pluginWarnings(root, counts, hooks, files) {
     if (hasMcp(root)) {
         warnings.push(`plugin declares MCP server(s) (mcpServers / .mcp.json) — the loader does not wire MCP; bring the server up yourself if your test needs it.`);
     }
+    const dangling = danglingRefs(root);
+    if (dangling.length) {
+        const shown = dangling.slice(0, 5).join(", ");
+        const more = dangling.length > 5 ? `, … (+${String(dangling.length - 5)})` : "";
+        warnings.push(`plugin references ${String(dangling.length)} intra-plugin file(s) that don't exist (broken path / partial vendor): ${shown}${more}`);
+    }
     if (!hooks && Object.keys(files).length === 0) {
         warnings.push(`nothing was loaded (no hooks, CLAUDE.md, skills, agents, or commands) — the deterministic harness would run an effectively empty machine.`);
     }
@@ -143,16 +153,40 @@ function pluginWarnings(root, counts, hooks, files) {
 function hasMcp(root) {
     if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, ".mcp.json")))
         return true;
-    const manifestPath = (0, node_path_1.join)(root, ".claude-plugin", "plugin.json");
-    if (!(0, node_fs_1.existsSync)(manifestPath))
-        return false;
-    try {
-        const m = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
-        return m.mcpServers !== undefined;
-    }
-    catch {
-        return false;
+    return (safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"))?.mcpServers !==
+        undefined);
+}
+// A plugin-relative path reference to a file under a standard surface dir, with a
+// known extension — e.g. a hook script that `cat`s `skills/using-superpowers/SKILL.md`.
+const INTRA_REF_RE = /(?:skills|hooks|commands|agents)\/[A-Za-z0-9._/-]+\.(?:md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json)/g;
+/**
+ * Intra-plugin file references that don't resolve — the partial-vendor / broken-
+ * path class (e.g. obra/superpowers' `SessionStart` reads
+ * `skills/using-superpowers/SKILL.md`, which a sliced vendor snapshot omits). We
+ * scan the plugin's own text files under the surface dirs (hooks scripts
+ * included — those aren't materialized into `files`) for root-relative path refs
+ * and report the ones missing on disk. A static check that would have caught a
+ * bug the dogfood hit twice. Best-effort: a warning, not an error.
+ */
+function danglingRefs(root) {
+    const missing = new Set();
+    const seen = new Set();
+    for (const surface of ["hooks", "skills", "agents", "commands"]) {
+        const dir = (0, node_path_1.join)(root, surface);
+        if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
+            continue;
+        for (const content of Object.values(readTree(dir, root))) {
+            for (const m of content.matchAll(INTRA_REF_RE)) {
+                const ref = m[0];
+                if (seen.has(ref))
+                    continue;
+                seen.add(ref);
+                if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, ref)))
+                    missing.add(ref);
+            }
+        }
     }
+    return [...missing];
 }
 /**
  * Merge a loaded plugin's settings with inline settings. Inline wins; when both