vigiles 27.3.0 → 29.0.0

package/dist/cli-main.js

@@ -34,6 +34,7 @@ const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scan_js_1 = require("./scan.js");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const dialect_drift_js_1 = require("./dialect-drift.js");
 const skill_reachability_js_1 = require("./skill-reachability.js");
@@ -553,7 +554,7 @@ async function compile(specPaths, config, excludes, opts = {}) {
     // dialect pick and the mirror from it — no re-parsing, no cwd-sniffing in the
     // helpers. A loud notice (never a silent guess) on a multi-harness or
     // ambiguous-detection pick.
-    const declaredHarnesses = (0, adapter_registry_js_1.normalizeHarnessList)(config.harness);
+    const declaredHarnesses = (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses);
     const selection = (0, adapter_registry_js_1.resolveHarnessSelection)({
         root: process.cwd(),
         flag: opts.harnessFlag,
@@ -1466,7 +1467,7 @@ async function runLint(restArgs, flags, excludes, config) {
     const lintSelection = (0, adapter_registry_js_1.resolveHarnessSelection)({
         root: scanRoot,
         flag: harnessFlag,
-        configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
+        configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config?.harnesses),
     });
     const adapter = lintSelection.adapter;
     // 🔴 WHICH ROOTS GET SCORED, and saying so either way (#185).
@@ -3363,7 +3364,7 @@ async function setup(args) {
     // Detect project. An existing `.vigilesrc.json` `harness` (from a prior init /
     // a hand-authored config) wins over auto-detection (dogfood I3).
     const detected = detectProject();
-    const harnesses = resolveHarnesses(parsed, detected, (0, validate_js_1.loadConfig)().harness);
+    const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses));
     printDetection(detected, harnesses);
     // Files actually written, accumulated for an honest commit hint.
     const written = [];
@@ -3436,15 +3437,15 @@ async function setup(args) {
         console.log("\nℹ Ran the standard setup. Already have a harness, or not a JS/Python repo, and want only the CI integrity gate (nothing installed)? Re-run `npx vigiles init --ci-only`.");
     }
 }
-/** Canonical, de-duplicated harness list → a config value (string when one). */
-function harnessConfigValue(harnesses) {
-    const canon = [...new Set(harnesses.map(adapter_registry_js_1.normalizeHarnessName))];
-    return canon.length === 1 ? canon[0] : canon;
+/** Canonical, de-duplicated harness names — the keys `harnesses` gets. */
+function harnessConfigKeys(harnesses) {
+    return [...new Set(harnesses.map(adapter_registry_js_1.normalizeHarnessName))];
 }
 /**
  * Merge the resolved harness(es) (and strict rule severities) into
- * `.vigilesrc.json` without clobbering existing keys — an existing `harness`
- * stays, a missing one is added, a malformed file is left untouched.
+ * `.vigilesrc.json` without clobbering existing keys — an existing
+ * `harnesses` block stays, a missing one is added, a malformed file is left
+ * untouched.
  */
 function writeProjectConfig(opts) {
     const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
@@ -3459,7 +3460,7 @@ function writeProjectConfig(opts) {
         }
     }
     const merged = (0, setup_plan_js_1.mergeProjectConfig)(existing, {
-        harness: harnessConfigValue(opts.harnesses),
+        harnesses: harnessConfigKeys(opts.harnesses),
         strict: opts.strict,
         reportOnly: opts.reportOnly,
         lint: opts.lint,
@@ -3524,7 +3525,7 @@ function harnessLayoutFor(root, config, flag) {
         return (0, adapter_registry_js_1.resolveHarnessSelection)({
             root,
             flag,
-            configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
+            configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config?.harnesses),
         }).adapter.layout;
     }
     catch {
@@ -4391,7 +4392,7 @@ function flagValue(args, name) {
  * Resolve the adapter for a COMMAND, honouring the full precedence: `--harness=`
  * flag → `.vigilesrc.json` `harness` → auto-detect (dogfood A/I3). This is the
  * ONE resolution path a command may use — resolving via the raw auto-detect
- * alone silently ignores config.harness, which is the exact bug this closes.
+ * alone silently ignores `.vigilesrc.json#harnesses`, which is the exact bug this closes.
  * A dogfood test (src/cli-harness-resolution.test.ts) asserts cli.ts routes all
  * command harness resolution through here, so a future command can't regress.
  */
@@ -4399,7 +4400,7 @@ function resolveCommandHarness(dir, harnessFlag) {
     return (0, adapter_registry_js_1.resolveHarnessSelection)({
         root: dir,
         flag: harnessFlag,
-        configHarness: (0, adapter_registry_js_1.normalizeHarnessList)((0, validate_js_1.loadConfig)().harness),
+        configHarness: (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses),
     });
 }
 async function handleMeasure(restArgs, args) {
@@ -5252,6 +5253,45 @@ function annotateLintForGitHub(report, flags) {
         ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
     }
 }
+/**
+ * The project root a `hook-runtime` rail acts on — NEVER `process.cwd()` first.
+ *
+ * These rails are a SECOND execution path, wired by hand into a hooks config
+ * (`npx vigiles hook-runtime <kind>`), and every one of them used to ask
+ * `process.cwd()` where the project was. The hook process has no stable cwd: a
+ * git worktree, or a session that has `cd`-ed into a subdirectory, stands
+ * somewhere the project's files are not, and then the state store writes its
+ * marker beside the wrong repo and `.vigiles/*.json` is simply not found. The
+ * failure is SILENT in the permissive direction — no gates loaded reads exactly
+ * like a project that declared none.
+ *
+ * Same order the compiled runtime uses (`projectRootOf`, core/hook-program.ts):
+ * `$CLAUDE_PROJECT_DIR` first — the harness resolved the hook's own path against
+ * it — then the event's own `cwd`, which Claude Code puts in every hook payload.
+ * `process.cwd()` stays as the documented LAST resort, for the rails a human or
+ * the model invokes as a plain command with no event and no env to go on.
+ *
+ * Pass the parsed event wherever stdin was already read; the handlers that take
+ * only an argument pass nothing and get the env answer.
+ */
+function runtimeRoot(event = {}) {
+    return (0, hook_program_js_1.projectRootOf)(event, process.env) ?? process.cwd();
+}
+/**
+ * The hook payload as a root SOURCE — `{}` when stdin was absent or malformed,
+ * which {@link runtimeRoot} reads as "this event offers no root" and falls
+ * through. Deliberately separate from each handler's own parse: a rail that
+ * cannot understand its event still knows where the project is, and a rail that
+ * only wants `tool_name` should not have to widen its own type to say so.
+ */
+function eventRoot(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Run a compiled skill's deterministic gate ladder: execute each step gate in
  * order (short-circuiting on the first failure), then the result gate. This is
@@ -5264,7 +5304,8 @@ function runSkillCommand(target) {
         console.error("Usage: vigiles hook-runtime run-skill <SKILL.md>");
         process.exit(2);
     }
-    const path = (0, node_path_1.resolve)(process.cwd(), target);
+    const root = runtimeRoot();
+    const path = (0, node_path_1.resolve)(root, target);
     if (!(0, node_fs_1.existsSync)(path)) {
         console.error(`Not found: ${target}`);
         process.exit(2);
@@ -5275,7 +5316,7 @@ function runSkillCommand(target) {
         return;
     }
     console.log(`Running gate ladder for ${target}:\n`);
-    const report = (0, skill_runtime_js_1.runSkillGates)(gates, process.cwd());
+    const report = (0, skill_runtime_js_1.runSkillGates)(gates, root);
     for (const r of report.results) {
         const label = r.at === "result" ? "result" : `step ${String(r.at)}`;
         console.log(`  ${r.ok ? "✓" : "✗"} ${label} — ${(0, skill_runtime_js_1.gateLabel)(r.gate)}`);
@@ -5303,11 +5344,12 @@ function runSkillCommand(target) {
  * feeds the message back to the model; exit 0 allows it and clears the marker.
  */
 function skillHookCommand() {
-    const decision = (0, skill_runtime_js_1.evaluateStopHook)(process.cwd());
+    const root = runtimeRoot();
+    const decision = (0, skill_runtime_js_1.evaluateStopHook)(root);
     if (decision.allow) {
         if (decision.message)
             console.log(decision.message);
-        (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+        (0, skill_runtime_js_1.clearActiveSkill)(root);
         return;
     }
     console.error(decision.message);
@@ -5319,12 +5361,20 @@ function skillStartCommand(target) {
         console.error("Usage: vigiles hook-runtime skill-start <SKILL.md>");
         process.exit(2);
     }
-    (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    const root = runtimeRoot();
+    (0, skill_runtime_js_1.setActiveSkill)(root, target);
     // Record the fire in the flight recorder: the skill NAME is the parent dir of
     // its SKILL.md (skills/<name>/SKILL.md), falling back to the raw target.
     const parts = target.replace(/\\/g, "/").split("/").filter(Boolean);
     const name = parts.length >= 2 ? parts[parts.length - 2] : (parts[0] ?? target);
-    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true });
+    // The SAME root the decision above used. `appendObservation` defaults to
+    // `process.cwd()`, which is correct as a library default and wrong here: a
+    // hook does not run with a stable cwd, so the decision would land in the
+    // project while its record landed beside whatever directory the process
+    // happened to stand in. A ledger split across two directories is not untidy,
+    // it is wrong in a way that reads as normal — the file in the project looks
+    // complete, and nobody notices a flight recorder that is short.
+    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true }, root);
     console.log(`Active skill: ${target}`);
 }
 /**
@@ -5357,7 +5407,7 @@ function skillToolHookCommand() {
     }
     if (!tool)
         return;
-    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(process.cwd(), tool, command);
+    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(runtimeRoot(eventRoot(raw)), tool, command);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -5393,7 +5443,7 @@ function agentHookCommand() {
     catch {
         /* malformed input → no tool, allow */
     }
-    const cwd = process.cwd();
+    const cwd = runtimeRoot(eventRoot(raw));
     // EXPERIMENTAL (parked P3 — do NOT auto-wire). The spawn/SubagentStop bracketing
     // is now nesting-safe: a depth-aware STACK (push on dispatch, POP on SubagentStop)
     // closes the contract-escape the flat single-slot model allowed under CC v2.1.172
@@ -5425,13 +5475,15 @@ function agentHookCommand() {
         return;
     const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(cwd, tool, command);
     if (!decision.allow) {
+        // Same root as the decision — see `skillStartCommand` for why the default
+        // is wrong on a hook rail.
         (0, observe_js_1.appendObservation)({
             kind: "agent",
             name: (0, agent_runtime_js_1.readActiveAgent)(cwd) ?? "unknown",
             tool,
             allowed: false,
             reason: decision.message,
-        });
+        }, cwd);
         console.error(decision.message);
         process.exit(2);
     }
@@ -5476,7 +5528,7 @@ function guardHookCommand() {
     catch {
         /* no stdin */
     }
-    const { decision } = (0, guards_js_1.runGuardHook)(process.cwd(), raw);
+    const { decision } = (0, guards_js_1.runGuardHook)(runtimeRoot(eventRoot(raw)), raw);
     if (!decision.allow) {
         console.error(decision.reason ?? "Blocked by a vigiles guard.");
         process.exit(2);
@@ -5488,7 +5540,7 @@ function agentStartCommand(target) {
         console.error("Usage: vigiles hook-runtime agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_1.pushActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_1.pushActiveAgent)(runtimeRoot(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
@@ -5512,7 +5564,7 @@ async function handleHookRuntime(kind, restArgs) {
             agentStartCommand(restArgs[0]);
             return;
         case "agent-done":
-            (0, agent_runtime_js_1.popActiveAgent)(process.cwd());
+            (0, agent_runtime_js_1.popActiveAgent)(runtimeRoot());
             return;
         case "skill":
             skillHookCommand();
@@ -5524,7 +5576,7 @@ async function handleHookRuntime(kind, restArgs) {
             skillStartCommand(restArgs[0]);
             return;
         case "skill-done":
-            (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+            (0, skill_runtime_js_1.clearActiveSkill)(runtimeRoot());
             return;
         case "run-skill":
             runSkillCommand(restArgs[0]);
@@ -5545,11 +5597,11 @@ async function handleHookRuntime(kind, restArgs) {
             evalLockNudgeHookCommand();
             return;
         case "effect-enter":
-            (0, effect_region_js_1.setEffectActive)(process.cwd());
+            (0, effect_region_js_1.setEffectActive)(runtimeRoot());
             console.log("Effect boundary entered.");
             return;
         case "effect-exit":
-            (0, effect_region_js_1.clearEffectActive)(process.cwd());
+            (0, effect_region_js_1.clearEffectActive)(runtimeRoot());
             return;
         default:
             console.error(`vigiles hook-runtime: unknown runtime entrypoint "${kind ?? ""}". ` +
@@ -5580,7 +5632,8 @@ function actionHookCommand() {
     catch {
         /* malformed input → no event, allow */
     }
-    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(process.cwd()), process.cwd());
+    const root = runtimeRoot(eventRoot(raw));
+    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(root), root);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -5624,7 +5677,7 @@ function evalLockNudgeHookCommand() {
     }
     if (!file)
         return;
-    const cwd = process.cwd();
+    const cwd = runtimeRoot(eventRoot(raw));
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     // 🔴 THE SAME CONFIG `vigiles lint` READS. This used to pass `basePath` alone,
     // so a repo that had switched `untested-skill` off, or pointed `include` at
@@ -5638,7 +5691,11 @@ function evalLockNudgeHookCommand() {
     // second gate saying the same thing is a branch no test can distinguish from
     // its absence (measured — the mutation passed), i.e. the dead-fragment class
     // this same change removed from the runner table.
-    const config = (0, validate_js_1.loadConfig)();
+    // `onInvalid: "warn"` — a HOOK RAIL. This is a fresh process inside somebody's
+    // editing session, and a malformed `.vigilesrc.json` must not turn a JSON typo
+    // into a failed edit: the nudge not firing is the cheaper failure. The verbs
+    // throw on the same config; what is CHECKED is identical.
+    const config = (0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" });
     const { options } = untestedRules(config);
     // 🔴 THE SAME LAYOUT `vigiles lint` RESOLVES, for the same reason as the config
     // above. This used to pass `basePath` alone, so the detector fell back to the
@@ -5701,10 +5758,13 @@ function refsHookCommand() {
     }
     if (!file || !isInstructionFile(file))
         return;
-    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)().rules["unmarked-refs"]);
+    // Root first: the config read below is anchored on it, and reading the config
+    // from the process's directory is how a disabled rule comes back to life.
+    const cwd = runtimeRoot(eventRoot(raw));
+    // A hook rail — see `evalLockNudgeHookCommand` for why it warns, not throws.
+    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" }).rules["unmarked-refs"]);
     if (severity === false)
         return;
-    const cwd = process.cwd();
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     let markdown;
     try {
@@ -5787,7 +5847,14 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // emitter never produced it. Measured 2026-09-10 in a consumer repo: after a compile,
         // one `cd` into a subdirectory made a PreToolUse gate fail to load, and a gate that
         // cannot load must block — the repo seized, every command refused including the repair.
-        gateCommand: `npx vigiles hook-runtime run-program ${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)}`,
+        //
+        // 🔴 AND LAUNCHED LOCALLY, NOT THROUGH `npx` — 193 ms against 2545 ms on a warm
+        // cache, thirteen times, on every tool call. The trailing `|| exit N` is what the
+        // shell does when that binary cannot start at all, and N is decided by the hook's
+        // ROLE: see `hookRuntimeRef` and `hookRuntimeMissingExit` for both measurements
+        // and for why a gate and a nudge must answer differently.
+        gateCommand: `${(0, hook_install_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens)} hook-runtime run-program ` +
+            `${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)} || exit ${(0, hook_install_js_1.hookRuntimeMissingExit)((0, hook_program_js_1.dispatchKind)(program))}`,
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settingsFormat: adapter.layout.settingsFormat,
@@ -5869,7 +5936,7 @@ async function installHookFile(file, adapter, registeredProviders = []) {
  * harness-neutral, so when a repo targets both harnesses the SAME hook is merged
  * into `.claude/settings.json` AND `.codex/config.toml` (each in its native
  * format, with per-harness warnings) — never just the first. The harness set is
- * resolved from the `--harness=` flag, else `config.harness`, else auto-detect.
+ * resolved from the `--harness=` flag, else `.vigilesrc.json#harnesses`, else auto-detect.
  * Returns false if any hook failed to compile for any harness.
  */
 async function installHooks(hookFiles, harnessFlag, configHarness) {
@@ -6389,7 +6456,8 @@ async function main() {
             if (specs.length > 0)
                 valid =
                     (await compile(specs, config, excludes, { harnessFlag })) && valid;
-            valid = (await installHooks(hooks, harnessFlag, config.harness)) && valid;
+            valid =
+                (await installHooks(hooks, harnessFlag, (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses))) && valid;
             // Keep an existing whole-harness registry in sync (cheap, opt-in) so the
             // user never hand-runs `generate-harness`. Skipped when no harness.gen.ts.
             if (specs.length > 0)
@@ -6517,19 +6585,74 @@ async function main() {
                 const harnessFlag = harnessFlagFrom(args);
                 // Honor the SAME precedence as lint/compile (dogfood A): --harness= flag,
                 // else the `.vigilesrc.json` `harness` key, else auto-detect. Previously
-                // audit auto-detected and IGNORED config.harness, so a repo that
-                // config-declares `"harness": "codex"` but carries a CLAUDE.md was still
+                // audit auto-detected and IGNORED the declared harnesses, so a repo
+                // that config-declares `"harnesses": {"codex": {}}` but carries a CLAUDE.md was still
                 // scanned as Claude Code. `resolveHarnessSelection` also carries the
                 // ambiguity/multi-target `notice` so the warning stays consistent.
                 const selection = (0, adapter_registry_js_1.resolveHarnessSelection)({
                     root,
                     flag: harnessFlag,
-                    configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config.harness),
+                    configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses),
                 });
                 const adapter = selection.adapter;
+                // EVERY declared harness, each with the roots declared under it — the
+                // list the scan reads WHOLE. The flag still wins (an explicit override
+                // is singular, and the user typed it), and a repo with no declaration
+                // scans under the one detected adapter exactly as before.
+                //
+                // The PRIMARY is `adapter`, so the report is still labelled and
+                // dialect-checked by one harness; the list is what stops the OTHER
+                // declared harness's skills and instruction file from being invisible.
+                const scanHarnesses = harnessFlag === undefined || harnessFlag === ""
+                    ? (0, adapter_registry_js_1.resolveDeclaredHarnesses)(root, config.harnesses)
+                        .map((d) => ({
+                        layout: d.adapter.layout,
+                        dialect: d.adapter.dialect,
+                        roots: d.roots,
+                    }))
+                        // The primary first, whatever order the object was written in:
+                        // `resolveHarnessSelection` already decided which harness this
+                        // report is FOR, and the scan's first entry is the one that
+                        // supplies the dialect. Two different answers to "which is
+                        // primary" is the bug this change exists to remove.
+                        .sort((a, b) => a.layout.name === adapter.layout.name
+                        ? -1
+                        : b.layout.name === adapter.layout.name
+                            ? 1
+                            : 0)
+                    : [];
+                // A declared root under a harness that reads no surface there is
+                // REFUSED, not ignored. It is the one silent state the nested shape
+                // would otherwise keep: the line changes nothing, and saying nothing is
+                // the tool agreeing with a belief that is false.
+                const badRoots = (0, surface_discovery_js_1.unresolvedDeclaredRoots)(scanHarnesses.map((h) => ({
+                    harness: h.layout.name,
+                    layout: h.layout,
+                    roots: h.roots,
+                })), (rel) => {
+                    const abs = (0, node_path_1.resolve)(root, rel);
+                    return ((0, node_fs_1.lstatSync)(abs, { throwIfNoEntry: false })?.isDirectory() === true);
+                });
+                if (badRoots.length > 0) {
+                    for (const msg of badRoots)
+                        console.error(`✗ ${msg}`);
+                    process.exitCode = 2;
+                    return;
+                }
                 const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
                     sharedDirs: config.sharedDirs,
                     sharedDirsRoot: sharedDirsRootFor(targets[0]),
+                    // `.vigilesrc.json#exclude` reaches surface DISCOVERY, not just the
+                    // instruction file. Measured 2026-09-21 before this line existed: a repo
+                    // with `{"exclude": [".claude"]}` and one skill at `.claude/skills/demo`
+                    // still printed `Skills (1): ✓ demo` and docked Safety to 90 for it — the
+                    // grade was computed over a tree the user had told the tool to ignore.
+                    excludes,
+                    // The repo owner's answer to "N skills no harness reads": these are
+                    // mine, grade them — each root under the harness whose layout reads
+                    // it, so no array order decides which half of the repo is seen.
+                    // `exclude` still wins over it; the walk drops an excluded path first.
+                    harnesses: scanHarnesses,
                 });
                 if (!json) {
                     console.log(`Detected harness: ${adapter.name}`);

package/dist/core/adapter.d.ts

@@ -84,7 +84,28 @@ export interface HarnessAdapter {
      * one seam the runner dispatches through). Carried on the bundle so the runner
      * never imports a sibling adapter to find it.
      */
-    readonly harnessTestDriver?: HarnessTestDriver;
+    /**
+     * 🔴 A THUNK, NOT THE DRIVER, and the indirection is the whole point. A driver
+     * lives in `harness-test.ts`, which imports the conformance suite, which
+     * imports the compiler, which imports the cross-language symbol index, which
+     * loads a NATIVE binary. Holding the driver eagerly meant every consumer of an
+     * adapter paid for all of it — including the hook runtime, which reads only
+     * `dialect` and `hookProtocol` and never runs a harness test at all.
+     *
+     * Measured 2026-09-19, `require("./adapter-registry.js")`:
+     *
+     *     eager:  107 modules, 7 ast-grep, 1 native .node
+     *
+     * ...on a path whose actual work takes about a millisecond. Calling the thunk
+     * is what loads the driver, so the test tier pays and the runtime does not.
+     *
+     * ASYNC because a dynamic `import()` is the only form that defers in BOTH
+     * environments this code runs in: the CJS `dist/` build (where TypeScript
+     * lowers it to a deferred `require`) and vitest loading the TS sources
+     * directly, where a synchronous `require` of a sibling `.ts` does not resolve
+     * at all — measured, not assumed.
+     */
+    readonly harnessTestDriver?: () => Promise<HarnessTestDriver>;
     /**
      * How strongly a repo at `root` looks like it targets this harness — the CLI
      * uses it to auto-detect which adapter to use (the library selects by import).
@@ -94,5 +115,28 @@ export interface HarnessAdapter {
      * `AGENTS.md` that many harnesses share) regardless of registration order.
      */
     detect(root: string): number;
+    /**
+     * Is this repo-relative path one THIS harness reads — "is it mine?"
+     *
+     * 🔴 THE POINT OF THIS METHOD IS WHAT IT CANNOT DO. It takes a path and
+     * returns a boolean: no root, no filesystem, no enumeration. An adapter can
+     * therefore LABEL a surface the domain already found and nothing else —
+     * **registering a new adapter cannot make vigiles read more in anyone's
+     * repository.** The rejected alternative was each adapter DECLARING roots for
+     * the audit to walk, which inverts that: shipping a Cursor adapter would start
+     * reading `.cursor/rules` in every user's repo, and a surface no adapter
+     * declared would stay invisible. Discovery is the domain's job
+     * (`core/surface-discovery.ts`); a claim is an adapter's. See
+     * `research/audit-harness-dx.md` §9.
+     *
+     * The consequence the audit reports: a surface NO registered adapter claims is
+     * a FINDING, not silence — measured on a real repo whose 37 skills under
+     * `.ai/` graded A (100/100) precisely because nothing read them (#240).
+     *
+     * Every shipped adapter implements this as `layoutClaims(<its layout>, path)`,
+     * so a layout that moves takes its claim with it and the two cannot drift.
+     * Override it only for a location the `PluginLayout` fields cannot express.
+     */
+    claims(path: string): boolean;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/dist/core/compile.js

@@ -172,13 +172,23 @@ function validateSymbolRef(file, name, basePath) {
             path: file,
         };
     }
-    if ((0, symbols_js_1.langForFile)(file) === null) {
+    const support = (0, symbols_js_1.langForFile)(file);
+    if (support.kind === "unsupported") {
         return {
             type: "stale-ref",
             message: `Unsupported language for symbol check: "${file}"`,
             path: file,
         };
     }
+    if (support.kind === "grammar-missing") {
+        // The language is parseable by this tool; the optional grammar is absent in THIS install.
+        // Distinct wording on purpose — see the union's docblock in core/symbols.ts.
+        return {
+            type: "stale-ref",
+            message: `Symbol not checked: the ${support.id} grammar is not installed (npm i -D ${support.pkg})`,
+            path: file,
+        };
+    }
     if (!(0, symbols_js_1.fileDefinesSymbol)(full, name)) {
         return {
             type: "stale-ref",