vigiles 27.3.0 → 29.0.0

package/dist/hook-runtime.js

@@ -75,8 +75,8 @@ function injectableEventsFor(root) {
  */
 exports.loadHookProgram = load_hook_js_1.loadHook;
 /** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
-async function loadProvider(file) {
-    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+async function loadProvider(file, root = process.cwd()) {
+    const abs = (0, node_path_1.resolve)(root, file);
     const { pathToFileURL } = require("node:url");
     let mod;
     try {
@@ -95,8 +95,8 @@ async function loadProvider(file) {
     return def;
 }
 /** Path of the tamper-evident stamp sidecar for a hook file. */
-function hookStampPath(file) {
-    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
+function hookStampPath(file, root = process.cwd()) {
+    return (0, node_path_1.resolve)(root, ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
 }
 /**
  * Perform the state writes a hook declared, after its output has been emitted.
@@ -104,14 +104,14 @@ function hookStampPath(file) {
  * thrown on) is announced — silence here would be a hook that believes it
  * remembered something.
  */
-function applyHookWrites(file, outcome) {
+function applyHookWrites(file, outcome, root) {
     const { ok, refused } = (0, hook_program_js_1.outcomeWrites)(outcome);
     for (const name of refused) {
         console.error(`vigiles: refused to record ${name} from ${file} — not a valid state key.`);
     }
     for (const w of ok) {
         try {
-            (0, hook_state_store_js_1.writeHookState)(file, w);
+            (0, hook_state_store_js_1.writeHookState)(file, w, { cwd: root });
         }
         catch (e) {
             console.error(`vigiles: could not record ${w.name} from ${file}: ${String(e)}`);
@@ -124,13 +124,13 @@ function applyHookWrites(file, outcome) {
  * that can't resolve yields its default (never throws). The pure registry +
  * decision logic live in core/hook-providers.ts — this only injects the real IO.
  */
-async function gatherHookContext(program, file) {
+async function gatherHookContext(program, file, root) {
     const needs = (0, hook_program_js_1.hookNeeds)(program);
     if (needs.length === 0)
         return {};
     // Only load the registered-provider registry if a provider() ref is declared.
     const hasRef = needs.some((n) => typeof n !== "string" && n.kind === "provider-ref");
-    const registry = hasRef ? await loadProviderRegistry() : {};
+    const registry = hasRef ? await loadProviderRegistry(root) : {};
     const { execSync } = require("node:child_process");
     const { isCI } = require("ci-info");
     return (0, hook_providers_js_1.gatherContext)(needs, {
@@ -138,12 +138,12 @@ async function gatherHookContext(program, file) {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "ignore"],
         }),
-        cwd: process.cwd(),
+        cwd: root,
         platform: process.platform,
         isCI,
         // The namespace is bound HERE, from the hook's own path — core never sees
         // it, so no key a hook can spell reaches another owner's store.
-        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key),
+        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key, root),
         now: Date.now(),
     }, registry);
 }
@@ -152,11 +152,11 @@ async function gatherHookContext(program, file) {
  * for `provider()` ref resolution. A bad/unloadable provider file is skipped (the
  * ref then yields its default ""), never crashes a live session.
  */
-async function loadProviderRegistry() {
+async function loadProviderRegistry(root) {
     const registry = {};
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(root)) {
         try {
-            const def = await loadProvider(file);
+            const def = await loadProvider(file, root);
             registry[def.name] = def;
         }
         catch {
@@ -166,9 +166,9 @@ async function loadProviderRegistry() {
     return registry;
 }
 /** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
-function recordObservation(file, on, would, reason) {
+function recordObservation(file, on, would, reason, root) {
     try {
-        const dir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, ".vigiles");
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
         const line = JSON.stringify({
             ts: new Date().toISOString(),
@@ -189,7 +189,7 @@ function recordObservation(file, on, would, reason) {
  * shadow/rollout path. Harness-neutral — exit 2 / exit 0 are identical on Claude
  * Code and Codex; the record is vigiles-local.
  */
-function emitGate(decision, on, mode, file) {
+function emitGate(decision, on, mode, file, root) {
     const action = (0, hook_program_js_1.gateAction)(decision, mode);
     switch (action.kind) {
         case "block":
@@ -200,7 +200,7 @@ function emitGate(decision, on, mode, file) {
                 mode: "enforce",
                 rule: file,
                 reason: action.reason,
-            });
+            }, root);
             console.error(action.reason);
             process.exit(2);
             return;
@@ -212,7 +212,7 @@ function emitGate(decision, on, mode, file) {
                 mode: "enforce",
                 rule: file,
                 reason: action.reason,
-            });
+            }, root);
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
                     hookEventName: on,
@@ -229,8 +229,8 @@ function emitGate(decision, on, mode, file) {
                 mode: "observe",
                 rule: file,
                 reason: action.reason,
-            });
-            recordObservation(file, on, action.would, action.reason);
+            }, root);
+            recordObservation(file, on, action.would, action.reason, root);
             console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
             return; // exit 0 — observe never blocks
         case "allow":
@@ -247,9 +247,9 @@ function emitGate(decision, on, mode, file) {
  * observed wedge came from a `package.json` the author was not thinking about at
  * the time — it had merge-conflict markers in it, nothing to do with hooks.
  */
-function hookLoadPathFiles(hookFile) {
+function hookLoadPathFiles(hookFile, root) {
     const files = [];
-    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), hookFile));
+    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(root, hookFile));
     for (;;) {
         const pkg = (0, node_path_1.resolve)(dir, "package.json");
         files.push(pkg);
@@ -275,15 +275,15 @@ function hookLoadPathFiles(hookFile) {
             break;
         dir = up;
     }
-    files.push((0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json"));
+    files.push((0, node_path_1.resolve)(root, ".vigilesrc.json"));
     return files;
 }
 /**
  * The conflicted files on this hook's load path, if any — the difference between
  * "your hook is broken" and "your repo is mid-merge and the hook is collateral".
  */
-function conflictedLoadPathFiles(hookFile) {
-    return hookLoadPathFiles(hookFile)
+function conflictedLoadPathFiles(hookFile, root) {
+    return hookLoadPathFiles(hookFile, root)
         .filter((p) => {
         try {
             return ((0, node_fs_1.existsSync)(p) && (0, merge_conflict_js_1.hasMergeConflictMarkers)((0, node_fs_1.readFileSync)(p, "utf-8")));
@@ -292,7 +292,7 @@ function conflictedLoadPathFiles(hookFile) {
             return false; // unreadable is a different problem; don't guess about it
         }
     })
-        .map((p) => (0, node_path_1.relative)(process.cwd(), p) || p);
+        .map((p) => (0, node_path_1.relative)(root, p) || p);
 }
 /**
  * Print the loud stderr banner that accompanies a REPAIR-only pass-through, and
@@ -321,14 +321,15 @@ function announceRepairEscape(file, why) {
  * `.claude/settings.json` to unwire the gate. Observed 2026-08-03.
  */
 function verifyStampOrRefuse(file, event) {
-    const stampPath = hookStampPath(file);
+    const { root } = event;
+    const stampPath = hookStampPath(file, root);
     if (!(0, node_fs_1.existsSync)(stampPath))
         return;
     try {
         const { stamp } = JSON.parse((0, node_fs_1.readFileSync)(stampPath, "utf-8"));
-        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(root, file), "utf-8");
         if (stamp && !(0, hook_program_js_1.verifyHookStamp)(source, stamp)) {
-            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, process.cwd())) {
+            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, root)) {
                 announceRepairEscape(file, "does not match its compiled stamp");
                 return;
             }
@@ -388,21 +389,39 @@ async function runHookProgramCommand(file) {
     catch {
         /* no stdin */
     }
-    let event = {};
+    let payload = {};
     try {
-        event = JSON.parse(raw);
+        payload = JSON.parse(raw);
     }
     catch {
         /* malformed → empty event */
     }
-    // The root repo-relative path prefixes resolve against. `$CLAUDE_PROJECT_DIR`
-    // first (the same root the harness resolved THIS hook's own path against),
-    // then the payload's `cwd`; never `process.cwd()`, which under a git worktree
-    // can be a different checkout. See `projectRootOf`.
-    const projectRoot = (0, hook_program_js_1.projectRootOf)(event, process.env);
+    // 🔴 THE ROOT IS RESOLVED ONCE, HERE, AND RIDES ON THE EVENT. Everything below
+    // reads `event.root`; nothing recomputes it and nothing is handed a root
+    // beside an event it might disagree with. That disagreement is the defect
+    // this shape exists to prevent — the stamp sidecar, the hook's own source,
+    // the state store, the ledger and the provider registry each used to resolve
+    // against `process.cwd()` while the decision layer resolved against the
+    // payload, so under a worktree the tamper check did not misfire, it did not
+    // run at all.
+    //
+    // This is the only `process.cwd()` on the runtime's own execution path, and
+    // it is the documented last resort for a payload that declares no root. The
+    // two others in this file are back-compat defaults on exported helpers
+    // (`loadProvider`, `hookStampPath`) for callers outside the runtime; the
+    // runtime itself always passes a root and never takes them.
+    const event = (0, hook_program_js_1.resolveHookEvent)(payload, process.env, process.cwd());
+    const root = event.root;
+    // ⚠️ THE DECISION LAYER MUST NOT SEE THE FALLBACK, and this is not a detail.
+    // `pathView` treats an undefined root as "I cannot place this path" and errs
+    // toward SILENCE. Handing it `process.cwd()` instead would turn that silence
+    // into confident decisions measured against a directory nobody declared —
+    // quietly widening what gates fire on. IO paths need a usable root; verdicts
+    // need an honest one, and they are not the same question.
+    const declaredRoot = event.rootDeclared ? event.root : undefined;
     let program;
     try {
-        program = await (0, exports.loadHookProgram)(file);
+        program = await (0, exports.loadHookProgram)(file, root);
     }
     catch (err) {
         // A LOAD failure is a fact about the harness, not a verdict about the
@@ -430,7 +449,7 @@ async function runHookProgramCommand(file) {
         //     not go through PreToolUse(Bash)).
         // Everything else stays BLOCKED, and the escapes are whitelists of commands
         // that are WRITES — see `isLoadPathRepairEvent` for why no command is one.
-        const conflicted = conflictedLoadPathFiles(file);
+        const conflicted = conflictedLoadPathFiles(file, root);
         // 🔴 THE THROWN MESSAGE IS THE ONLY THING THAT NAMES THE REAL CAUSE when the
         // merge-conflict heuristic above does not fire. Without it this said just
         // "cannot be loaded" — a diagnosis that sends the reader looking in the wrong
@@ -444,13 +463,13 @@ async function runHookProgramCommand(file) {
                 `may be fine)`
             : `cannot be loaded — ${thrown}`;
         if ((0, hook_program_js_1.isLoadPathRepairEvent)(event, file, {
-            // The root the REST of this runtime already uses: `hookStampPath` and
-            // `verifyStampOrRefuse` read the hook and its sidecar via `process.cwd()`,
-            // so a repair accepted against any other root would name a file the
-            // runtime never reads. The hook's own path cannot supply it (a hook sits
-            // at any depth, and a `.git` probe would be a disk read core does not do).
-            root: process.cwd(),
-            loadPathFiles: hookLoadPathFiles(file),
+            // The root the REST of this runtime already uses — now the PROJECT's,
+            // not the process's. A repair accepted against any other root would name
+            // a file the runtime never reads. The hook's own path cannot supply it (a
+            // hook sits at any depth, and a `.git` probe would be a disk read core
+            // does not do), so it is passed in.
+            root,
+            loadPathFiles: hookLoadPathFiles(file, root),
         })) {
             announceRepairEscape(file, cause);
             return;
@@ -466,7 +485,7 @@ async function runHookProgramCommand(file) {
             `${file}, ${merge_conflict_js_1.HARNESS_CONFIG_FILES.join(", ")} is broken — those writes are ` +
             `allowed even while this refuses, and a Bash gate never gated file tools ` +
             `at all. The hook then loads and the gate decides normally again.\n` +
-            `vigiles: those paths resolve under ${process.cwd()} — plus any ancestor ` +
+            `vigiles: those paths resolve under ${root} — plus any ancestor ` +
             `\`package.json\` Node actually reads, so whatever is named above as the ` +
             `cause is writable. A path in a DIFFERENT checkout is refused: it cannot ` +
             `repair this failure.\n` +
@@ -494,7 +513,7 @@ async function runHookProgramCommand(file) {
     verifyStampOrRefuse(file, event);
     switch ((0, hook_program_js_1.dispatchKind)(program)) {
         case "inject": {
-            const ctx = await gatherHookContext(program, file);
+            const ctx = await gatherHookContext(program, file, root);
             const injection = (0, hook_program_js_1.injectionOf)(program, event, ctx);
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
@@ -508,20 +527,20 @@ async function runHookProgramCommand(file) {
                 kind: "injection",
                 context: injection.context,
                 records: injection.records,
-            });
+            }, root);
             return;
         }
         case "react": {
-            const ctx = await gatherHookContext(program, file);
-            warnIfPathUndecidable(event, projectRoot);
-            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, projectRoot);
+            const ctx = await gatherHookContext(program, file, root);
+            warnIfPathUndecidable(event, declaredRoot);
+            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, declaredRoot);
             // A notice has to REACH someone. stderr at exit 0 goes to the debug log
             // and nothing else (the host's docs are explicit: "Claude never sees it"),
             // and a react always exits 0 because its type has no `deny` — so stderr
             // alone delivered nowhere. Emit the same `additionalContext` shape the
             // shipped refs/eval-lock nudges use, gated on the ACTIVE adapter's
             // `injectableEvents` so this is per-harness fact, not a CC literal.
-            const injectable = injectableEventsFor(projectRoot ?? process.cwd());
+            const injectable = injectableEventsFor(root);
             const delivery = (0, hook_program_js_1.noticeDelivery)(reaction, program.on, injectable);
             if (delivery.kind === "inject") {
                 process.stdout.write(JSON.stringify({
@@ -537,7 +556,7 @@ async function runHookProgramCommand(file) {
             // Removing it would break existing consumers to gain nothing.
             if (reaction.kind === "notice")
                 console.error(reaction.message);
-            applyHookWrites(file, { kind: "reaction", reaction });
+            applyHookWrites(file, { kind: "reaction", reaction }, root);
             if (reaction.kind === "run") {
                 const { spawnSync } = require("node:child_process");
                 const res = spawnSync(reaction.command, {
@@ -549,29 +568,29 @@ async function runHookProgramCommand(file) {
             return;
         }
         case "file-gate": {
-            const ctx = await gatherHookContext(program, file);
-            warnIfPathUndecidable(event, projectRoot);
-            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            const ctx = await gatherHookContext(program, file, root);
+            warnIfPathUndecidable(event, declaredRoot);
+            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, declaredRoot), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "bash-gate": {
-            const ctx = await gatherHookContext(program, file);
-            // The same `projectRoot` the file gates get: without it every
+            const ctx = await gatherHookContext(program, file, root);
+            // The same `declaredRoot` the file gates get: without it every
             // repo-relative prefix in a DENYLIST matcher (`touches`/`writesTo`) is
             // matched by over-blocking alone, and with it an absolute token is placed
             // exactly. Measured bypass this closes: `sed -i s/a/b/ <abs>/paper.tex`
             // exited 0 against a guard that blocked the relative spelling.
-            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx, declaredRoot), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "prompt-gate": {
-            const ctx = await gatherHookContext(program, file);
-            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            const ctx = await gatherHookContext(program, file, root);
+            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "stop-gate": {
-            const ctx = await gatherHookContext(program, file);
-            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            const ctx = await gatherHookContext(program, file, root);
+            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
     }

package/dist/layout-registry.d.ts

@@ -0,0 +1,14 @@
+import type { PluginLayout } from "./core/layout.js";
+/** Every SHIPPED harness layout, in registry order. */
+export declare const REGISTERED_LAYOUTS: readonly PluginLayout[];
+/**
+ * "Is this repo-relative path read by some harness vigiles knows about?" — one
+ * predicate per registered layout, the input to `unclaimedSurfaces`.
+ *
+ * Note it is the layouts of every REGISTERED harness, not of the DETECTED one.
+ * A repo carrying both `.claude/skills` and `.agents/skills` has each half
+ * claimed by a different harness and neither is a finding; a repo whose skills
+ * sit under `.ai/` has them claimed by nobody, and that is the finding (#240).
+ */
+export declare const registeredClaims: ReadonlyArray<(path: string) => boolean>;
+//# sourceMappingURL=layout-registry.d.ts.map

package/dist/layout-registry.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registeredClaims = exports.REGISTERED_LAYOUTS = void 0;
+/**
+ * The registered harnesses' LAYOUTS, as pure data — the claim side of surface
+ * discovery, available where the adapter bundle is not.
+ *
+ * 🔴 WHY THIS IS NOT JUST `ADAPTERS.map(a => a.layout)`. `src/adapter-registry.ts`
+ * imports the full `HarnessAdapter` bundles, and an adapter's `detect(root)` does
+ * real filesystem work — so that module pulls `node:fs` in. `src/scan-files.ts`
+ * is the BROWSER-SAFE twin of the scan ("NO filesystem, NO child_process, NO disk
+ * I/O at all") and needs exactly one thing from the registry: which paths a
+ * shipped harness reads. A `PluginLayout` is a plain object of strings, so this
+ * list is importable from both sides.
+ *
+ * The drift that split lists invite is CHECKED, not hoped for:
+ * `src/layout-registry.test.ts` asserts this list is exactly the layouts the
+ * `ADAPTERS` registry carries, and that every adapter's `claims` agrees with
+ * `layoutClaims` over its own layout — so adding a harness to one registry and
+ * not the other fails a test instead of quietly halving discovery.
+ */
+const layout_js_1 = require("./adapters/claude-code/layout.js");
+const layout_js_2 = require("./adapters/codex/layout.js");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
+/** Every SHIPPED harness layout, in registry order. */
+exports.REGISTERED_LAYOUTS = [
+    layout_js_1.claudeCodeLayout,
+    layout_js_2.codexLayout,
+];
+/**
+ * "Is this repo-relative path read by some harness vigiles knows about?" — one
+ * predicate per registered layout, the input to `unclaimedSurfaces`.
+ *
+ * Note it is the layouts of every REGISTERED harness, not of the DETECTED one.
+ * A repo carrying both `.claude/skills` and `.agents/skills` has each half
+ * claimed by a different harness and neither is a finding; a repo whose skills
+ * sit under `.ai/` has them claimed by nobody, and that is the finding (#240).
+ */
+exports.registeredClaims = exports.REGISTERED_LAYOUTS.map((l) => (path) => (0, surface_discovery_js_1.layoutClaims)(l, path));
+//# sourceMappingURL=layout-registry.js.map

package/dist/load-hook.d.ts

@@ -20,5 +20,5 @@ import { type AnyHook } from "./core/hook-program.js";
  * @throws {HookCompileError} when the file can't be imported, or has no
  * default-exported hook program.
  */
-export declare function loadHook(file: string): Promise<AnyHook>;
+export declare function loadHook(file: string, root?: string): Promise<AnyHook>;
 //# sourceMappingURL=load-hook.d.ts.map

package/dist/load-hook.js

@@ -39,8 +39,8 @@ const hook_program_js_1 = require("./core/hook-program.js");
  * @throws {HookCompileError} when the file can't be imported, or has no
  * default-exported hook program.
  */
-async function loadHook(file) {
-    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+async function loadHook(file, root = process.cwd()) {
+    const abs = (0, node_path_1.resolve)(root, file);
     let mod;
     try {
         mod = (await import((0, node_url_1.pathToFileURL)(abs).href));

package/dist/plugin-loader.d.ts

@@ -1,4 +1,5 @@
 import type { PluginLayout } from "./core/layout.js";
+import type { ExcludeSet } from "./exclude.js";
 export interface LoadedPlugin {
     /** A `.claude/settings.json`-shaped object with hooks resolved. */
     readonly settings: {
@@ -29,8 +30,55 @@ export interface LoadedPlugin {
  * the files (CLAUDE.md + skills + agents + commands) to write into the test
  * sandbox, and `warnings` for surfaces the deterministic tier can't drive. Merge
  * `settings` with any inline settings and spread `files` into the fixture.
+ *
+ * `surfaceRoots` is this function's parameter name for what the repo owner
+ * writes as `.vigilesrc.json#harnesses["<name>"].roots` — extra repo-relative
+ * bases to read `<base>/<surfaceDir>/…` from, for a repo that keeps its skills
+ * somewhere no harness reads by default. The config key is nested UNDER a
+ * harness name precisely so a root cannot be declared without saying whose
+ * layout reads it; this parameter receives one harness's slice of that, which
+ * is why it is still a bare list here. `excludes` still wins over it:
+ * both the per-tree check in {@link materializeSurfaces} and `readTree` drop an
+ * excluded path whatever declared it, so a root that is declared AND excluded is
+ * read exactly as if it had never been declared.
  */
-export declare function loadPlugin(pluginPath: string, layout: PluginLayout): LoadedPlugin;
+export declare function loadPlugin(pluginPath: string, layout: PluginLayout, excludes?: ExcludeSet, surfaceRoots?: readonly string[]): LoadedPlugin;
+/**
+ * ONE declared harness for {@link loadPlugins}: the layout to read the repo
+ * under, and the extra roots declared for THAT harness.
+ */
+export interface HarnessLoad {
+    readonly layout: PluginLayout;
+    readonly roots?: readonly string[];
+}
+/**
+ * Load the repo once PER DECLARED HARNESS and merge the results into one
+ * `LoadedPlugin` (#240).
+ *
+ * 🔴 THE MERGE IS WHY THIS EXISTS, AND THE DEDUPLICATION IS ITS WHOLE CONTRACT.
+ * A repo that declares two harnesses is a repo whose grade must cover both — the
+ * flat `harness` array could not do that, because whichever name sat first
+ * decided the ONE layout everything was read under: measured on a repo with
+ * `AGENTS.md` + `.ai/skills/alpha/SKILL.md`, Claude-Code-first graded the skill
+ * and reported 0 chars of always-loaded instructions, Codex-first read
+ * `AGENTS.md` and reported no skill at all. Neither order produced both halves.
+ *
+ * ⚠️ AND THE OBVIOUS FIX HAS AN OBVIOUS SECOND BUG: a repo honest enough to say
+ * one tree serves both tools would then have that tree read twice and every
+ * skill in it counted twice, so declaring the truth would lower the grade. So the
+ * merge keys on the REAL ON-DISK PATH (`sources`), not on the materialized key:
+ * the first harness to claim a file keeps it, later ones skip it, and the counts
+ * are of files rather than of claims. Keying on the materialized key would not
+ * do — two layouts can reach one file under two different keys (`.ai/.agents`
+ * + `skills` and `.ai` + `.agents/skills` are the same directory), and that is
+ * exactly the case an honest dual declaration produces.
+ *
+ * Settings come from the FIRST harness that yields any, and the file-map merge
+ * is first-wins for the same reason: the primary harness is the one whose
+ * dialect the report is rendered in, so its reading of a shared path is the one
+ * the rest of the report is consistent with.
+ */
+export declare function loadPlugins(pluginPath: string, harnesses: readonly HarnessLoad[], excludes?: ExcludeSet): LoadedPlugin;
 export declare function danglingRefs(root: string, layout: PluginLayout): string[];
 /**
  * Resolve the effective harness for a test/eval (arm): load the plugin if given,