vigiles 27.3.0 → 29.0.0

package/dist/plugin-loader.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPlugin = loadPlugin;
+exports.loadPlugins = loadPlugins;
 exports.danglingRefs = danglingRefs;
 exports.resolveHarness = resolveHarness;
 /**
@@ -37,6 +38,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const toml_1 = require("@iarna/toml");
 const hash_js_1 = require("./core/hash.js");
+const exclude_js_1 = require("./exclude.js");
 const fs_walk_js_1 = require("./fs-walk.js");
 const source_refs_js_1 = require("./core/source-refs.js");
 const surface_scopes_js_1 = require("./core/surface-scopes.js");
@@ -140,13 +142,20 @@ function readHooks(root, layout) {
  * `entryOf` has already cleared would cost a syscall per directory to answer a
  * question that cannot come out differently.
  */
-function readTree(dir, base) {
+function readTree(dir, base, excluded = exclude_js_1.excludesNothing) {
     const out = {};
     for (const entry of (0, node_fs_1.readdirSync)(dir)) {
         const full = (0, node_path_1.join)(dir, entry);
+        // `.vigilesrc.json#exclude`, applied HERE — per entry, inside the recursion —
+        // and not merely at the surface-dir entry point. A vendored tree is usually
+        // excluded at its own root (`bench`, `vendor/corpus`), which is a descendant
+        // of a surface dir, so a check that only guarded the walk's start would let
+        // every one of its files into the file map the whole report is computed from.
+        if (excluded(full))
+            continue;
         const { kind, size } = (0, fs_walk_js_1.entryOf)(full);
         if (kind === "dir")
-            Object.assign(out, readTree(full, base));
+            Object.assign(out, readTree(full, base, excluded));
         // The cap keeps a stray binary out of the in-memory file map, and the size
         // comes from the SAME stat that classified the entry. Asking a second time
         // needed its own `catch` — reachable only if the file vanished between the two
@@ -162,9 +171,21 @@ function readTree(dir, base) {
  * 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.
  */
-function loadPlugin(pluginPath, layout) {
+function loadPlugin(pluginPath, layout, excludes, surfaceRoots) {
     const root = (0, node_path_1.resolve)(pluginPath);
+    const excluded = (0, exclude_js_1.excludedBy)(excludes);
     const hooks = readHooks(root, layout);
     // Expand the plugin-root token to the real absolute path so the actual hook
     // scripts execute — we test the shipped wiring, not a reimplementation.
@@ -174,11 +195,11 @@ function loadPlugin(pluginPath, layout) {
     const files = {};
     const sources = {};
     const instructions = (0, node_path_1.join)(root, layout.instructionFile);
-    if ((0, node_fs_1.existsSync)(instructions)) {
+    if ((0, node_fs_1.existsSync)(instructions) && !excluded(instructions)) {
         files[layout.instructionFile] = (0, node_fs_1.readFileSync)(instructions, "utf-8");
         sources[layout.instructionFile] = instructions;
     }
-    const surfaces = materializeSurfaces(root, layout, files, sources);
+    const surfaces = materializeSurfaces(root, layout, files, sources, excluded, surfaceRoots);
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files,
@@ -186,6 +207,69 @@ function loadPlugin(pluginPath, layout) {
         warnings: pluginWarnings(root, surfaces, resolvedHooks, files, layout),
     };
 }
+/**
+ * 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.
+ */
+function loadPlugins(pluginPath, harnesses, excludes) {
+    const loads = harnesses.map((h) => loadPlugin(pluginPath, h.layout, excludes, h.roots));
+    /* v8 ignore next -- callers always pass >=1; the guard keeps the type honest */
+    if (loads.length <= 1)
+        return loads[0] ?? EMPTY_LOAD;
+    const files = {};
+    const sources = {};
+    const seenOnDisk = new Set();
+    const warnings = [];
+    let settings = {};
+    for (const load of loads) {
+        for (const [key, content] of Object.entries(load.files)) {
+            // A file with no recorded source is one the loader synthesized rather than
+            // read (there are none today); key it by its own key so it still dedupes.
+            const onDisk = load.sources[key] ?? key;
+            if (seenOnDisk.has(onDisk))
+                continue;
+            seenOnDisk.add(onDisk);
+            files[key] = content;
+            sources[key] = onDisk;
+        }
+        for (const w of load.warnings)
+            if (!warnings.includes(w))
+                warnings.push(w);
+        if (settings.hooks === undefined && load.settings.hooks !== undefined)
+            settings = load.settings;
+    }
+    return { settings, files, sources, warnings };
+}
+/** The shape `loadPlugins` returns for an empty harness list. */
+const EMPTY_LOAD = {
+    settings: {},
+    files: {},
+    sources: {},
+    warnings: [],
+};
 /**
  * Materialize every model surface (skills/agents/commands) into `files`, and
  * record each file's real on-disk path in `sources`. Best-effort (headless
@@ -214,8 +298,9 @@ function surfaceHasLoadable(layout, surface, tree) {
         ? keys.some((k) => (0, node_path_1.basename)(k) === "SKILL.md")
         : keys.some((k) => k.endsWith(".md"));
 }
-function materializeSurfaces(root, layout, files, sources) {
+function materializeSurfaces(root, layout, files, sources, excluded = exclude_js_1.excludesNothing, surfaceRoots) {
     const counts = {};
+    const harnessCounts = {};
     const isDir = (p) => (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isDirectory();
     /**
      * One surface dir's tree, or `{}` when there is nothing to read.
@@ -226,7 +311,9 @@ function materializeSurfaces(root, layout, files, sources) {
      * per-entry one and that function says why; a shared skills dir linked in from
      * outside is still read.
      */
-    const surfaceTree = (dir) => isDir(dir) && (0, fs_walk_js_1.walkableRoot)(dir, root) ? readTree(dir, dir) : {};
+    const surfaceTree = (dir) => isDir(dir) && (0, fs_walk_js_1.walkableRoot)(dir, root) && !excluded(dir)
+        ? readTree(dir, dir, excluded)
+        : {};
     /** Every surface tree of one scope, read once, keyed by surface dir. */
     const scopeTrees = (base) => {
         const trees = new Map();
@@ -245,13 +332,24 @@ function materializeSurfaces(root, layout, files, sources) {
     const userTrees = layout.userSurfaceRoot !== undefined
         ? scopeTrees(layout.userSurfaceRoot)
         : new Map();
+    // Declared roots are read HERE, up front and once, for the same reason the two
+    // above are: `surfaceSource` needs to know which of them hold anything before
+    // it can decide the scope list, and re-reading them afterwards would be a
+    // second walk that could disagree with the first.
+    const declaredRoots = (0, surface_scopes_js_1.normalizeSurfaceRoots)(surfaceRoots);
+    const declaredTrees = new Map();
+    for (const base of declaredRoots)
+        declaredTrees.set(base, scopeTrees(base));
     /** Copy one scope's already-read trees into `files`, keyed by that scope. */
     const materializeScope = (scope, trees) => {
         for (const surface of layout.surfaceDirs) {
             const tree = trees.get(surface) ?? {};
             for (const [rel, content] of Object.entries(tree))
                 add((0, surface_scopes_js_1.scopeKey)(scope, surface, rel), content, (0, node_path_1.join)(root, scope.base, surface, rel));
-            counts[surface] = (counts[surface] ?? 0) + Object.keys(tree).length;
+            const n = Object.keys(tree).length;
+            counts[surface] = (counts[surface] ?? 0) + n;
+            if (scope.declared !== true)
+                harnessCounts[surface] = (harnessCounts[surface] ?? 0) + n;
         }
     };
     /**
@@ -288,6 +386,12 @@ function materializeSurfaces(root, layout, files, sources) {
                 add((0, node_path_1.join)(base, dir, rel), content, (0, node_path_1.join)(root, base, dir, rel));
         }
     };
+    /** The already-read trees a scope materializes from — never a second walk. */
+    const treesOf = (scope) => scope.declared === true
+        ? (declaredTrees.get(scope.base) ?? new Map())
+        : scope.base === ""
+            ? rootTrees
+            : userTrees;
     const source = (0, surface_scopes_js_1.surfaceSource)(layout, {
         hasRootSkillFile: (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "SKILL.md")),
         skillName: (0, node_path_1.basename)(root),
@@ -295,6 +399,7 @@ function materializeSurfaces(root, layout, files, sources) {
         isPluginShaped: (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.manifestPath)) ||
             (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.hooksConventionPath)),
         userHasLoadable: hasLoadable(userTrees),
+        declaredRoots,
     });
     switch (source.kind) {
         case "single-skill": {
@@ -303,19 +408,20 @@ function materializeSurfaces(root, layout, files, sources) {
             // No `walkableRoot` here on purpose: `root` is the directory the CALLER
             // named (`vigiles audit <dir>`), not one this walk discovered, and refusing
             // to read the path someone explicitly pointed at is not a containment rule.
-            const tree = readTree(root, root);
+            const tree = readTree(root, root, excluded);
             for (const [rel, content] of Object.entries(tree)) {
                 add((0, node_path_1.join)(layout.materializeRoot, layout.skillDir, source.skillName, rel), content, (0, node_path_1.join)(root, rel));
             }
             counts[layout.skillDir] = Object.keys(tree).length;
-            return { counts, scopes: [] };
+            harnessCounts[layout.skillDir] = counts[layout.skillDir];
+            return { counts, harnessCounts, scopes: [] };
         }
         case "scopes": {
             (0, surface_scopes_js_1.assertDistinctScopeKeys)(source.scopes, layout.name);
             for (const scope of source.scopes)
-                materializeScope(scope, scope.base === "" ? rootTrees : userTrees);
+                materializeScope(scope, treesOf(scope));
             materializeRules();
-            return { counts, scopes: source.scopes };
+            return { counts, harnessCounts, scopes: source.scopes };
         }
         /* v8 ignore next 2 -- exhaustiveness guard, unreachable given SurfaceSource */
         default:
@@ -329,9 +435,9 @@ function materializeSurfaces(root, layout, files, sources) {
  * the eval tier. MCP servers aren't wired by the loader at all. And a plugin
  * that yields neither hooks nor files would otherwise be a silent empty machine.
  */
-function pluginWarnings(root, { counts, scopes }, hooks, files, layout) {
+function pluginWarnings(root, { counts, harnessCounts, scopes }, hooks, files, layout) {
     const warnings = [];
-    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, counts);
+    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, harnessCounts);
     if (multiScope !== undefined)
         warnings.push(multiScope);
     if (counts.agents) {

package/dist/run-hook.js

@@ -189,7 +189,23 @@ function runHookWith(command, input, opts, deps) {
             ran: false,
             conditionReason: verdict.why,
         };
-    const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), opts, deps);
+    // 🔴 A SPAWN DIRECTORY WITH NO DECLARED ROOT MEANS "THIS DIRECTORY IS THE
+    // PROJECT". Without this, a test that says `{ cwd: dir }` and nothing else
+    // inherits whatever `$CLAUDE_PROJECT_DIR` the AMBIENT shell exports, and since
+    // the runtime prefers the env over the payload (see `projectRootOf`), the hook
+    // resolves a root the test never named. Measured 2026-09-19: five rail suites
+    // pass with the variable unset — which is CI, and this container — and fail
+    // when it is set, which is any run inside a live Claude Code session. That is
+    // a one-sided failure, invisible exactly where it would be caught.
+    //
+    // An EXPLICIT value always wins, including the empty string: a test that pins
+    // `CLAUDE_PROJECT_DIR: ""` is saying "no env root, resolve from the payload",
+    // and that case has its own coverage.
+    const rooted = opts.cwd !== undefined &&
+        !Object.prototype.hasOwnProperty.call(opts.env ?? {}, "CLAUDE_PROJECT_DIR")
+        ? { ...opts, env: { ...opts.env, CLAUDE_PROJECT_DIR: opts.cwd } }
+        : opts;
+    const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), rooted, deps);
     const json = parseHookOutput(res.stdout);
     const { blocked, decision, haltsTurn, blockedBy } = decideHook(res.exitCode, json, protocol);
     return {

package/dist/scan-core.d.ts

@@ -37,6 +37,25 @@ export interface SurfaceClassifier {
     readonly isRule: (f: string) => boolean;
 }
 export declare function makeClassifier(layout: PluginLayout): SurfaceClassifier;
+/**
+ * ONE classifier over SEVERAL layouts — a path is a skill if ANY declared
+ * harness would read it as one.
+ *
+ * 🔴 IT EXISTS BECAUSE A MERGED FILE MAP HAS NO SINGLE LAYOUT. A repo declaring
+ * `{"harnesses": {"claude-code": {…}, "codex": {}}}` is read under BOTH layouts
+ * and the two file maps merge into one, at which point classifying with one
+ * layout drops the other's surfaces on the floor — Codex's `prompts/x.md` is not
+ * a Claude Code command, and silently counting it as nothing is the same shape of
+ * bug as reading no surfaces and grading A (100).
+ *
+ * `agentName` answers from the FIRST layout that calls the path an agent, so the
+ * name is always the one the layout that claimed it would give — never a name
+ * derived under a layout that would not have read the file at all.
+ *
+ * A single-layout list behaves byte-identically to {@link makeClassifier}, which
+ * is what lets every existing caller keep passing one layout.
+ */
+export declare function makeUnionClassifier(layouts: readonly PluginLayout[]): SurfaceClassifier;
 /** The plugin-root + materialize-root + dialect context skill scanning needs. */
 export interface SkillScanContext {
     readonly root: string;

package/dist/scan-core.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeClassifier = makeClassifier;
+exports.makeUnionClassifier = makeUnionClassifier;
 exports.remapFindingPaths = remapFindingPaths;
 exports.detectOwnTestSignal = detectOwnTestSignal;
 exports.scanSkills = scanSkills;
@@ -199,6 +200,35 @@ function makeClassifier(layout) {
         agentName: (f) => isAgent(f) ? (0, layout_js_1.agentSurfaceName)(f, layout.agentDir) : null,
     };
 }
+/**
+ * ONE classifier over SEVERAL layouts — a path is a skill if ANY declared
+ * harness would read it as one.
+ *
+ * 🔴 IT EXISTS BECAUSE A MERGED FILE MAP HAS NO SINGLE LAYOUT. A repo declaring
+ * `{"harnesses": {"claude-code": {…}, "codex": {}}}` is read under BOTH layouts
+ * and the two file maps merge into one, at which point classifying with one
+ * layout drops the other's surfaces on the floor — Codex's `prompts/x.md` is not
+ * a Claude Code command, and silently counting it as nothing is the same shape of
+ * bug as reading no surfaces and grading A (100).
+ *
+ * `agentName` answers from the FIRST layout that calls the path an agent, so the
+ * name is always the one the layout that claimed it would give — never a name
+ * derived under a layout that would not have read the file at all.
+ *
+ * A single-layout list behaves byte-identically to {@link makeClassifier}, which
+ * is what lets every existing caller keep passing one layout.
+ */
+function makeUnionClassifier(layouts) {
+    const cs = layouts.map(makeClassifier);
+    const any = (pick) => (f) => cs.some((c) => pick(c)(f));
+    return {
+        isSkill: any((c) => c.isSkill),
+        isAgent: any((c) => c.isAgent),
+        isCommand: any((c) => c.isCommand),
+        isRule: any((c) => c.isRule),
+        agentName: (f) => cs.find((c) => c.isAgent(f))?.agentName(f) ?? null,
+    };
+}
 function skillName(path) {
     return (path
         .replace(/\/SKILL\.md$/, "")

package/dist/scan-files.js

@@ -49,6 +49,8 @@ const mcp_config_js_1 = require("./core/mcp-config.js");
 const agent_plugins_js_1 = require("./core/agent-plugins.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
 const plugin_dir_layout_js_1 = require("./core/plugin-dir-layout.js");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
+const layout_registry_js_1 = require("./layout-registry.js");
 const surface_scopes_js_1 = require("./core/surface-scopes.js");
 const hook_block_ineffective_js_1 = require("./core/hook-block-ineffective.js");
 const hook_matcher_js_1 = require("./core/hook-matcher.js");
@@ -231,6 +233,7 @@ function surfaceHasLoadable(layout, surface, tree) {
 function materializeSurfaces(files, layout, acc, repoName) {
     const { out, sources } = acc;
     const counts = {};
+    const harnessCounts = {};
     const scopeTrees = (base) => {
         const trees = new Map();
         for (const surface of layout.surfaceDirs) {
@@ -255,7 +258,10 @@ function materializeSurfaces(files, layout, acc, repoName) {
             const dirRel = scope.base === "" ? surface : `${scope.base}/${surface}`;
             for (const [rel, content] of Object.entries(tree))
                 add((0, surface_scopes_js_1.scopeKey)(scope, surface, rel), content, (0, posix_path_js_1.join)(exports.BROWSER_ROOT, dirRel, rel));
-            counts[surface] = (counts[surface] ?? 0) + Object.keys(tree).length;
+            const n = Object.keys(tree).length;
+            counts[surface] = (counts[surface] ?? 0) + n;
+            if (scope.declared !== true)
+                harnessCounts[surface] = (harnessCounts[surface] ?? 0) + n;
         }
     };
     const source = (0, surface_scopes_js_1.surfaceSource)(layout, {
@@ -276,13 +282,14 @@ function materializeSurfaces(files, layout, acc, repoName) {
                 add((0, posix_path_js_1.join)(layout.materializeRoot, layout.skillDir, source.skillName, rel), content, (0, posix_path_js_1.join)(exports.BROWSER_ROOT, rel));
             }
             counts[layout.skillDir] = Object.keys(tree).length;
-            return { counts, scopes: [] };
+            harnessCounts[layout.skillDir] = counts[layout.skillDir];
+            return { counts, harnessCounts, scopes: [] };
         }
         case "scopes": {
             (0, surface_scopes_js_1.assertDistinctScopeKeys)(source.scopes, layout.name);
             for (const scope of source.scopes)
                 materializeScope(scope, scope.base === "" ? rootTrees : userTrees);
-            return { counts, scopes: source.scopes };
+            return { counts, harnessCounts, scopes: source.scopes };
         }
     }
 }
@@ -371,9 +378,9 @@ function danglingRefs(files, layout, rootName) {
 // ---------------------------------------------------------------------------
 // Warnings (mirrors plugin-loader.ts pluginWarnings)
 // ---------------------------------------------------------------------------
-function pluginWarnings(files, layout, { counts, scopes }, hooks, materialized, rootName) {
+function pluginWarnings(files, layout, { counts, harnessCounts, scopes }, hooks, materialized, rootName) {
     const warnings = [];
-    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, counts);
+    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, harnessCounts);
     if (multiScope !== undefined)
         warnings.push(multiScope);
     if (counts.agents) {
@@ -550,6 +557,9 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
+        // The browser twin has the WHOLE fetched key set in hand, so discovery needs
+        // no walk here — the pure classifier re-applies the same bounded-root rule.
+        unclaimedSurfaces: (0, surface_discovery_js_1.unclaimedSurfaceFindings)(Object.keys(files), layout_registry_js_1.REGISTERED_LAYOUTS),
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, posix_path_js_1.join)(exports.BROWSER_ROOT, (0, posix_path_js_1.dirname)(lay.manifestPath)), [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: exists, isDirectory: mapIsDirectory(files) }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
         hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0

package/dist/scan.d.ts

@@ -12,6 +12,7 @@
  * stack on top later; this core stays pure so it runs anywhere in CI for free.
  */
 import type { PluginLayout } from "./core/layout.js";
+import type { ExcludeSet } from "./exclude.js";
 import type { HarnessDialect } from "./core/dialect.js";
 import type { ToolIssue } from "./core/tool-contract.js";
 import { type HookEventIssue } from "./core/hook-events.js";
@@ -25,6 +26,7 @@ import type { TrifectaFinding } from "./core/lethal-trifecta.js";
 import type { SkillResourceFinding } from "./core/skill-resources.js";
 import type { SkillFenceFinding } from "./core/skill-missing-fence.js";
 import { type PluginLayoutFinding } from "./core/plugin-dir-layout.js";
+import { type UnclaimedSurfaceFinding } from "./core/surface-discovery.js";
 import type { DelegationTrifectaFinding } from "./core/delegation-trifecta.js";
 import { type HookBlockFinding } from "./core/hook-block-ineffective.js";
 import { type HookMatcherFinding } from "./core/hook-matcher.js";
@@ -283,6 +285,14 @@ export interface ScanReport {
      * and the `plugin-dir-layout` lint rule (one detector, no drift).
      */
     readonly pluginLayoutIssues: readonly PluginLayoutFinding[];
+    /**
+     * Surface directories found by SHAPE in the bounded root set that NO
+     * registered harness claims — a harness sitting somewhere vigiles does not
+     * read, reported instead of silently graded around (#240). Computed by
+     * `core/surface-discovery.ts` from paths alone; shared with the browser twin
+     * (one detector, no drift).
+     */
+    readonly unclaimedSurfaces: readonly UnclaimedSurfaceFinding[];
     /**
      * Lethal trifectas that EMERGE across a delegation edge — a subagent whose
      * effective (own ∪ delegated-to) capability holds all three legs though no
@@ -386,10 +396,63 @@ export interface ScanReport {
         unrestricted: number;
     };
 }
+/**
+ * ONE harness a scan reads the repo under — the resolved form of a
+ * `.vigilesrc.json#harnesses` entry (#240).
+ *
+ * All three parts travel together on purpose. The LAYOUT says where this harness
+ * reads and what a surface is there; the DIALECT says what it understands (and
+ * carries its own instruction budget, in its own unit); the ROOTS are the extra
+ * places this repo's owner says that harness's surfaces also live. Splitting
+ * them is how a root came to be read under a layout nobody chose for it.
+ */
+export interface ScanHarness {
+    readonly layout: PluginLayout;
+    readonly dialect: HarnessDialect;
+    readonly roots: readonly string[];
+}
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect, opts?: {
     sharedDirs?: readonly string[];
     sharedDirsRoot?: string;
+    /**
+     * The repo's `.vigilesrc.json#exclude`, so surface DISCOVERY honours it.
+     *
+     * It rides in `opts` rather than as a fifth positional parameter because ~25
+     * call sites pass the first three and nothing else; a required parameter here
+     * would be twenty-odd mechanical edits for one behavioural change.
+     *
+     * ⚠️ Omitting it is NOT "the repo excludes nothing" — it is "this caller has
+     * no ExcludeSet to give", and the walk then reads everything. Today only
+     * `audit` supplies one; the `lint` rule checkers below still do not (they
+     * share a `(config, silent, adapter, root)` signature through `overBundles`).
+     */
+    excludes?: ExcludeSet;
+    /**
+     * The repo's `.vigilesrc.json#harnesses`, resolved — every declared harness
+     * with its own layout, dialect and roots, IN DECLARATION ORDER.
+     *
+     * 🔴 THE LIST IS READ WHOLE, AND THAT IS THE FIX (#240). The repo is loaded
+     * once per entry, each under its OWN layout, and the file maps merge
+     * (deduplicated by on-disk path, so one tree serving two harnesses is
+     * counted once). Under the flat `harness` array only the first entry's
+     * layout was ever used, so a repo declaring both got its skills OR its
+     * instruction file depending on which name it happened to list first, and no
+     * order gave it both.
+     *
+     * The first entry is the PRIMARY: it supplies the dialect every
+     * dialect-shaped check runs under and the `harness` the report is labelled
+     * with. The INSTRUCTION FILE is the deliberate exception — it comes from the
+     * first declared harness whose instruction file is actually present, because
+     * reporting "no instruction file" for a repo holding the other declared
+     * harness's one is the half of the bug that has nothing to do with skills.
+     *
+     * Rides in `opts` for the same reason `excludes` does: ~25 call sites pass
+     * the first three positionals and nothing else. Omitting it means "this
+     * caller has no declaration to pass" and the scan runs single-harness on the
+     * positional `layout`/`dialect`, exactly as before.
+     */
+    harnesses?: readonly ScanHarness[];
 }): ScanReport;
 /**
  * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static