@reneturcios/hookcheck 0.1.7 → 0.1.9

package/dist/core.js

@@ -6,7 +6,7 @@
  */
 import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
-export const VERSION = "0.1.7";
+export const VERSION = "0.1.9";
 export const RISKY_RULES = [
     { id: "DECODE-PIPE-SH", pattern: /\bbase64\s+(-d|--decode|-D)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|node|python3?|perl|ruby)\b/, evidence: "decodes a base64 payload and pipes it straight into an interpreter", severe: true, remote: true },
     { id: "CURL-PIPE-SH", pattern: /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|node|python3?|perl|ruby)\b/, evidence: "pipes a network download straight into an interpreter", severe: true, remote: true },
@@ -713,6 +713,17 @@ const CRED_ENV_NAME = /(SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|ACCES
 function detectEnvAccess(cmd, dataRanges) {
     let cred = false;
     let bulk = false;
+    // Bulk form tracking (P-091): the evidence sentence must describe
+    // the form that actually fired. A spread ({**os.environ, ...}), a
+    // dict() or list() copy, or an os.environ.copy() handed on (the
+    // environment inheritance idiom, typically as a subprocess env=) is
+    // bulk access, but it is not a serialization or a dump, and the
+    // v0.1.8 evidence called every bulk form one. bulkInheritanceOnly
+    // is true when every bulk hit is an inheritance or copy form and no
+    // serialization or dump form (JSON.stringify, printenv, a bare env
+    // statement, str(os.environ)) fired.
+    let bulkDump = false;
+    let bulkCopy = false;
     const skipSpans = [
         ...Array.from(cmd.matchAll(/\benv(?:\s+-u\s+[A-Za-z_][A-Za-z0-9_]*)+/g), (m) => ({ start: m.index, end: m.index + m[0].length })),
         ...Array.from(cmd.matchAll(/\[\[?\s+-[nz]\s+"?\$\{?[A-Za-z_][A-Za-z0-9_]*\}?"?\s*\]\]?/g), (m) => ({ start: m.index, end: m.index + m[0].length })),
@@ -739,14 +750,26 @@ function detectEnvAccess(cmd, dataRanges) {
                 cred = true;
         }
     }
-    if (/(JSON\.stringify|Object\.(keys|values|entries|assign)|util\.inspect)\s*\([^)]*(process\.env|os\.environ)/.test(cmd))
+    if (/(JSON\.stringify|Object\.(keys|values|entries|assign)|util\.inspect)\s*\([^)]*(process\.env|os\.environ)/.test(cmd)) {
         bulk = true;
-    if (/\bprintenv\b/.test(cmd) && !inRanges(cmd.search(/\bprintenv\b/), dataRanges))
+        bulkDump = true;
+    }
+    if (/\bprintenv\b/.test(cmd) && !inRanges(cmd.search(/\bprintenv\b/), dataRanges)) {
         bulk = true;
-    if (/(^|[;&|]\s*)env\s*($|[|>;])/m.test(cmd))
+        bulkDump = true;
+    }
+    if (/(^|[;&|]\s*)env\s*($|[|>;])/m.test(cmd)) {
         bulk = true;
-    if (/\b(str|dict|list)\s*\(\s*os\.environ\s*\)/.test(cmd))
+        bulkDump = true;
+    }
+    if (/\bstr\s*\(\s*os\.environ\s*\)/.test(cmd)) {
+        bulk = true;
+        bulkDump = true;
+    }
+    if (/\b(?:dict|list)\s*\(\s*os\.environ\s*\)/.test(cmd)) {
         bulk = true;
+        bulkCopy = true;
+    }
     // Whole os.environ use (P-020): scan every occurrence and judge the
     // operation that follows it, instead of one negative lookahead.
     const envRe = /\bos\.environ\b/g;
@@ -763,14 +786,90 @@ function detectEnvAccess(cmd, dataRanges) {
             continue; // write or removal, not a read
         if (/^\s*\.copy\s*\(/.test(after)) {
             bulk = true;
+            bulkCopy = true;
             continue;
         } // whole copy is a bulk read
         const before = cmd.slice(Math.max(0, em.index - 24), em.index);
         if (/env\s*=\s*$/.test(before))
             continue; // subprocess env inheritance
         bulk = true;
+        // A spread occurrence ({**os.environ, ...}) is the inheritance
+        // idiom in dict form; anything else here is an unqualified whole
+        // environment use, counted with the dump forms for wording.
+        if (/\*\*\s*$/.test(before))
+            bulkCopy = true;
+        else
+            bulkDump = true;
     }
-    return { cred, bulk };
+    return { cred, bulk, bulkInheritanceOnly: bulk && bulkCopy && !bulkDump };
+}
+/**
+ * Text ranges of environment inheritance expressions that are passed
+ * as a subprocess environment (P-091). Two shapes count: a value used
+ * directly as env= or env: (env={**os.environ, ...},
+ * env=os.environ.copy()), and a variable assigned from an inheritance
+ * expression that is itself passed as env= somewhere in the same
+ * text (ENV = {**os.environ, ...}; subprocess.Popen(..., env=ENV)).
+ * The same forms in any other position (a request body, a printed
+ * value) are NOT inheritance ranges: dict(os.environ) handed to
+ * requests.post as data is serialization into a payload and keeps
+ * full exfil weight.
+ */
+function isInheritanceExpr(expr) {
+    const t = expr.trim();
+    if (/^(?:os\.environ|process\.env)$/.test(t))
+        return true;
+    if (/^(?:os\.environ|process\.env)\.copy\(\s*\)$/.test(t))
+        return true;
+    if (/^dict\(\s*(?:os\.environ|process\.env)\s*\)$/.test(t))
+        return true;
+    if (/^Object\.assign\(\s*\{\s*\}\s*,\s*(?:process\.env|os\.environ)\b/.test(t))
+        return true;
+    if (t.startsWith("{") && (/\*\*\s*(?:os\.environ|process\.env)\b/.test(t) || /\.\.\.\s*(?:process\.env|os\.environ)\b/.test(t)))
+        return true;
+    return false;
+}
+function inheritanceRanges(text) {
+    const ranges = [];
+    for (const m of text.matchAll(/\benv\s*[:=]\s*/g)) {
+        const start = m.index + m[0].length;
+        const end = consumeValueExpr(text, start);
+        if (end > start && isInheritanceExpr(text.slice(start, end)))
+            ranges.push({ start, end });
+    }
+    const assignRe = /(?:^|[;\n,])\s*(?:export\s+|const\s+|let\s+|var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=(?![=<>])\s*/g;
+    let m;
+    while ((m = assignRe.exec(text)) !== null) {
+        const rhsStart = m.index + m[0].length;
+        const end = consumeValueExpr(text, rhsStart);
+        if (end <= rhsStart)
+            continue;
+        if (!isInheritanceExpr(text.slice(rhsStart, end)))
+            continue;
+        const name = m[1].replace(/\$/g, "\\$");
+        if (new RegExp(`\\benv\\s*[:=]\\s*(?:${name}\\b|\\{[^}]*\\b${name}\\b)`).test(text)) {
+            ranges.push({ start: rhsStart, end });
+        }
+    }
+    return ranges;
+}
+/**
+ * True when every network destination visible in the text is
+ * loopback and at least one destination is visible at all (P-091).
+ * Destinations are URL hosts plus netcat target hosts. An unknown
+ * destination (a URL held in a variable) is not loopback-only: the
+ * discount applies only when the flow's destinations are provably
+ * all local, the same standard as the P-004 loopback downgrade.
+ */
+function loopbackOnlyDestinations(text) {
+    const hosts = [];
+    for (const m of text.matchAll(/https?:\/\/([^\s"'`\/:?#]+)/g))
+        hosts.push(m[1]);
+    for (const m of text.matchAll(/\b(?:nc|netcat)\s+(?:-\S+\s+)*([A-Za-z0-9._-]+)/g))
+        hosts.push(m[1]);
+    if (hosts.length === 0)
+        return false;
+    return hosts.every((h) => isLoopbackHost(h));
 }
 /**
  * Credential value atoms: text positions where a credential shaped env
@@ -1076,14 +1175,19 @@ function authRanges(text) {
     return ranges;
 }
 /**
- * Variables assigned (transitively) from a credential value expression.
+ * Variables assigned (transitively) from a credential value expression,
+ * mapped to their inheritance purity (P-091): a variable is pure when
+ * every taint source in its assignment chain is an inheritance atom
+ * or another pure variable (ENV = {**os.environ, ...} is pure; a
+ * payload built by serializing that same environment is not, because
+ * the serializing atom in its own right-hand side is impure).
  * References inside authentication positions do not propagate taint
  * (P-061): a headers dict whose only credential use is its
  * Authorization value is an authentication container, not a tainted
  * payload, and passing it to fetch does not become exfil.
  */
 function taintedVars(text, atoms, dataRanges, auth = []) {
-    const tainted = new Set();
+    const tainted = new Map();
     const assignRe = /(?:^|[;\n,])\s*(?:export\s+|const\s+|let\s+|var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=(?![=<>])\s*/g;
     const assigns = [];
     let m;
@@ -1099,17 +1203,18 @@ function taintedVars(text, atoms, dataRanges, auth = []) {
         for (const a of assigns) {
             if (tainted.has(a.name))
                 continue;
-            if (live.some((x) => x.start >= a.rhsStart && x.start < a.rhsEnd)) {
-                tainted.add(a.name);
-                continue;
+            const sources = [];
+            for (const x of live) {
+                if (x.start >= a.rhsStart && x.start < a.rhsEnd)
+                    sources.push(x.pure === true);
             }
             const rhs = text.slice(a.rhsStart, a.rhsEnd);
-            for (const v of tainted) {
-                if (refOutsideRanges(rhs, v, a.rhsStart, [...dataRanges, ...auth])) {
-                    tainted.add(a.name);
-                    break;
-                }
+            for (const [v, vPure] of tainted) {
+                if (refOutsideRanges(rhs, v, a.rhsStart, [...dataRanges, ...auth]))
+                    sources.push(vPure);
             }
+            if (sources.length > 0)
+                tainted.set(a.name, sources.every(Boolean));
         }
     }
     return tainted;
@@ -1143,17 +1248,33 @@ function callSpan(text, openIdx) {
     }
     return { start: openIdx, end: text.length };
 }
+/**
+ * Taint inside one span, with inheritance purity (P-091): pure is
+ * true only when every taint hit in the span is inheritance purity.
+ * A span carrying even one impure hit (a credential shaped read, a
+ * serialization of the whole environment) is an impure flow.
+ */
 function spanHasTaint(text, span, atoms, tainted, dataRanges, auth = []) {
-    if (atoms.some((a) => !a.inData && a.start >= span.start && a.start < span.end))
-        return true;
-    if (tainted.size === 0)
-        return false;
-    const seg = text.slice(span.start, span.end);
-    for (const v of tainted) {
-        if (refOutsideRanges(seg, v, span.start, [...dataRanges, ...auth]))
-            return true;
+    let found = false;
+    let pure = true;
+    for (const a of atoms) {
+        if (!a.inData && a.start >= span.start && a.start < span.end) {
+            found = true;
+            if (a.pure !== true)
+                pure = false;
+        }
+    }
+    if (tainted.size > 0) {
+        const seg = text.slice(span.start, span.end);
+        for (const [v, vPure] of tainted) {
+            if (refOutsideRanges(seg, v, span.start, [...dataRanges, ...auth])) {
+                found = true;
+                if (!vPure)
+                    pure = false;
+            }
+        }
     }
-    return false;
+    return { found, pure };
 }
 /**
  * Exfil value flow (Round 2, P-018). ENV-EXFIL used to fire on mere
@@ -1181,8 +1302,34 @@ function analyzeExfil(text, views, lang) {
     const dataRanges = views.dataRanges;
     const auth = authRanges(text);
     const atoms = findAtoms(text, dataRanges).filter((a) => !inRanges(a.start, auth));
+    // Inheritance purity (P-091): a bulk atom inside an inheritance
+    // expression passed as a subprocess env= is marked pure. Flows are
+    // accumulated with their purity instead of returning at the first
+    // hit: an impure flow fires ENV-EXFIL unconditionally (the v0.1.4
+    // rule), while a flow whose taint is exclusively inheritance purity
+    // fires only when the flow has a non-loopback destination. The
+    // distilled failure was CloudCorpRecords/xod: a test script builds
+    // ENV = {**os.environ, ...}, passes it as env= to the project's own
+    // server and CLI, and every network call is loopback to the server
+    // it just started; the inherited env tainted the subprocess result
+    // variable, whose print next to the loopback urlopen read as exfil.
+    const inhRanges = inheritanceRanges(text);
+    for (const a of atoms) {
+        if (a.kind === "bulk" && inRanges(a.start, inhRanges))
+            a.pure = true;
+    }
     const tainted = taintedVars(text, atoms, dataRanges, auth);
-    const has = (span) => spanHasTaint(text, span, atoms, tainted, dataRanges, auth);
+    let sawPureFlow = false;
+    let sawImpureFlow = false;
+    const note = (r) => {
+        if (!r.found)
+            return;
+        if (r.pure)
+            sawPureFlow = true;
+        else
+            sawImpureFlow = true;
+    };
+    const has = (span) => note(spanHasTaint(text, span, atoms, tainted, dataRanges, auth));
     const callRes = [
         /\bfetch\s*\(/g,
         /\baxios(?:\s*\.\s*(?:post|put|patch|get|request|delete))?\s*\(/g,
@@ -1195,8 +1342,7 @@ function analyzeExfil(text, views, lang) {
     for (const re of callRes) {
         let m;
         while ((m = re.exec(text)) !== null) {
-            if (has(callSpan(text, m.index + m[0].length - 1)))
-                return true;
+            has(callSpan(text, m.index + m[0].length - 1));
         }
     }
     // Fetch positions run on the code view with data blanked (indices
@@ -1215,8 +1361,7 @@ function analyzeExfil(text, views, lang) {
         }
         if (!isFetchStmt)
             continue;
-        if (has(stmt))
-            return true;
+        has(stmt);
     }
     for (const stmt of statements) {
         const stmtText = text.slice(stmt.start, stmt.end);
@@ -1232,8 +1377,7 @@ function analyzeExfil(text, views, lang) {
                 continue;
             for (let e = 0; e < k; e++) {
                 const early = { start: stmt.start + segments[e].start, end: stmt.start + segments[e].end };
-                if (has(early))
-                    return true;
+                has(early);
             }
         }
     }
@@ -1249,27 +1393,35 @@ function analyzeExfil(text, views, lang) {
     if (hasSendConstruct) {
         for (const m of text.matchAll(/(?:^|[;\n|&]\s*)(?:echo|printf)\s+([^\n;|]*)/g)) {
             const span = { start: m.index, end: m.index + m[0].length };
-            if (atoms.some((a) => a.start >= span.start && a.start < span.end))
-                return true;
+            for (const a of atoms) {
+                if (a.start >= span.start && a.start < span.end)
+                    note({ found: true, pure: a.pure === true });
+            }
             const argText = m[1] ?? "";
             const argStart = m.index + m[0].length - argText.length;
-            for (const v of tainted) {
+            for (const [v, vPure] of tainted) {
                 if (lang === "shell" || refOutsideRanges(argText, v, argStart, [...dataRanges, ...auth]))
-                    return true;
+                    note({ found: true, pure: vPure });
             }
         }
         for (const m of text.matchAll(/\b(?:console\.(?:log|info|debug)|print)\s*\(([^)]*)\)/g)) {
             const span = { start: m.index, end: m.index + m[0].length };
-            if (atoms.some((a) => a.start >= span.start && a.start < span.end && (lang === "shell" || !a.inData)))
-                return true;
+            for (const a of atoms) {
+                if (a.start >= span.start && a.start < span.end && (lang === "shell" || !a.inData))
+                    note({ found: true, pure: a.pure === true });
+            }
             const argText = m[1] ?? "";
             const argStart = m.index + m[0].indexOf(argText);
-            for (const v of tainted) {
+            for (const [v, vPure] of tainted) {
                 if (lang === "shell" || refOutsideRanges(argText, v, argStart, [...dataRanges, ...auth]))
-                    return true;
+                    note({ found: true, pure: vPure });
             }
         }
     }
+    if (sawImpureFlow)
+        return true;
+    if (sawPureFlow)
+        return !loopbackOnlyDestinations(text);
     return false;
 }
 function isLoopbackHost(host) {
@@ -1388,7 +1540,12 @@ export function classifyCommand(command, lang = "shell") {
         fired.push({ id: "ENV-ACCESS", evidence: "reads an environment variable whose name is credential shaped (token, secret, password, api key)" });
     }
     if (env.bulk) {
-        fired.push({ id: "ENV-BULK", evidence: "accesses the whole environment at once (serialization, printenv, or env dump)" });
+        fired.push({
+            id: "ENV-BULK",
+            evidence: env.bulkInheritanceOnly
+                ? "accesses the whole environment at once in inheritance or copy form (a spread, dict(), list(), or copy() of the whole environment handed on, for example as a subprocess environment); bulk access, not by itself a serialization or dump"
+                : "accesses the whole environment at once (serialization, printenv, or env dump)",
+        });
     }
     // Exfil is a value flow, not a co-occurrence (P-018): the credential
     // value must reach a send. Token as authentication does not count.
@@ -1684,7 +1841,30 @@ function makeFinding(root, file, source, hook, command, idSuffix, line, baseAbs
     };
     return escalateWithLocalFile(root, base, baseAbs);
 }
+/**
+ * Stat-type guard (P-069). A file the scanner has decided to read is
+ * checked by stat type BEFORE it is opened, and only regular files are
+ * ever opened. Opening a FIFO (named pipe) blocks until a writer
+ * appears, so a pipe planted at a surface path (.github/workflows/
+ * pipe.yml, a package.json, an .mcp.json) hung the scan forever with
+ * no internal timeout to catch it; sockets and device files are the
+ * same hazard. injectcheck already stats before opening; every read
+ * path in hookcheck now goes through readText or readTextWarn, which
+ * enforce the check centrally, and the per surface scanners that stat
+ * first (Claude settings, husky and githooks files, agent dirs, the
+ * one hop follower) keep their own isFile checks as well.
+ */
+function statIsRegularFile(abs) {
+    try {
+        return statSync(abs).isFile();
+    }
+    catch {
+        return null;
+    }
+}
 function readText(abs) {
+    if (statIsRegularFile(abs) === false)
+        return null;
     try {
         return readFileSync(abs, "utf8");
     }
@@ -1701,6 +1881,10 @@ function readText(abs) {
  * presents as a complete all-clear.
  */
 function readTextWarn(abs, rel, warnings) {
+    if (statIsRegularFile(abs) === false) {
+        warnings.push(`Non-regular file skipped: ${rel} is not a regular file (FIFO, socket, or device); it was not opened or inventoried`);
+        return null;
+    }
     try {
         return readFileSync(abs, "utf8");
     }
@@ -1763,21 +1947,65 @@ function scanOnePackageJson(root, rel, findings, warnings) {
     }
 }
 /**
- * Nested package.json discovery (P-032). Install scripts in workspace
- * subpackages (packages/foo, apps/web) run on a root install, so a
- * root-only scan misses exactly the surface a worm would persist in.
- * The walk is bounded so a hostile or giant tree cannot explode the
- * report: directories are visited in sorted order to depth
- * PACKAGE_MAX_DEPTH (the package.json directory depth below the root),
- * node_modules, .git, and dot directories are never entered, symlinked
- * directories are never followed (a symlink loop cannot hang the scan),
- * and at most PACKAGE_MAX_NESTED nested files are inventoried, with the
- * cap reported as a warning when it is hit.
+ * Unified nested discovery (P-032, P-060, P-065). Every surface the
+ * tool inventories at the scan root is also inventoried when it
+ * appears inside a subdirectory: before v0.1.8 only nested package.json
+ * files (P-032) and plugin hooks files (P-060) were recursed, so a
+ * parent scan of a monorepo or workspace silently missed nested
+ * .claude/settings.json, .vscode/tasks.json, workflows, husky and
+ * githooks directories, lefthook and pre-commit configs, and MCP
+ * configs, and a tree holding only nested surfaces scanned CLEAN with
+ * the empty estate note attached (P-065).
+ *
+ * One bounded walk enumerates every project root (each directory at
+ * most NESTED_MAX_DEPTH levels below the scan root, the scan root
+ * itself included) plus the nested package.json and plugin hooks file
+ * lists. Per surface scanners then run once per project root with the
+ * root prefix carried into every finding file path, so findings carry
+ * their real relative paths. The walk is bounded so a hostile or
+ * giant tree cannot explode the report: directories are visited in
+ * sorted order, node_modules, .git, and dot directories are never
+ * entered, symlinked directories are never followed (a symlink loop
+ * cannot hang the scan), and each surface family inventories at most
+ * NESTED_MAX_FILES_PER_SURFACE nested files, with the cap reported as
+ * a warning when it is hit. When directories remain below the depth
+ * bound the walk says so in a warning naming the bound, and it probes
+ * the directories just below the bound (names only, no file reads) so
+ * surfaces sitting there are counted in the warning instead of being
+ * silently dropped.
+ *
+ * The bound itself was raised from 4 to 8 in v0.1.9 (P-072): at depth
+ * 4, realistic monorepo nesting (apps/<team>/<app>, packages grouped
+ * by area, fixture trees) sat below the bound, so a package.json
+ * dropper at depth 5 floored at REVIEW via the probe and a depth 8
+ * chain verdicted CLEAN with only the warning. Depth 8 covers those
+ * layouts; the walk cost stays linear in the number of directories
+ * actually present, and the 2,000 file tree and 5 MB workflow perf
+ * spot checks for v0.1.9 showed no material regression against
+ * v0.1.8. Whatever bound remains keeps the warning and the
+ * never-bare-CLEAN rule when the probe detects surface below it.
  */
-export const PACKAGE_MAX_DEPTH = 4;
-export const PACKAGE_MAX_NESTED = 200;
-function discoverNestedPackageJson(root, warnings) {
-    const found = [];
+export const NESTED_MAX_DEPTH = 8;
+export const NESTED_MAX_FILES_PER_SURFACE = 200;
+export const PACKAGE_MAX_DEPTH = NESTED_MAX_DEPTH;
+export const PACKAGE_MAX_NESTED = NESTED_MAX_FILES_PER_SURFACE;
+export const PLUGIN_HOOKS_MAX_DEPTH = NESTED_MAX_DEPTH;
+export const PLUGIN_HOOKS_MAX_FILES = NESTED_MAX_FILES_PER_SURFACE;
+const SURFACE_FILE_INDICATORS = new Set([
+    "package.json", "lefthook.yml", "lefthook.yaml", ".lefthook.yml", ".lefthook.yaml",
+    ".pre-commit-config.yaml", ".pre-commit-config.yml", ".mcp.json", "mcp.json",
+]);
+const SURFACE_DIR_INDICATORS = new Set([
+    ".claude", "claude", ".vscode", ".github", ".husky", ".githooks",
+    "hooks", ".cursor", ".windsurf", ".codex",
+]);
+function discoverSurfaces(root, warnings) {
+    const projectRoots = [];
+    const packageFiles = [];
+    const pluginSet = new Set();
+    let frontierDirs = 0;
+    let surfacesBelowBound = 0;
+    let probes = 0;
     const skipDirs = new Set(["node_modules", ".git"]);
     const stack = [{ abs: root, rel: "", depth: 0 }];
     while (stack.length > 0) {
@@ -1792,14 +2020,38 @@ function discoverNestedPackageJson(root, warnings) {
             continue;
         }
         entries.sort();
+        projectRoots.push(cur.rel);
         if (cur.depth >= 1 && entries.includes("package.json")) {
-            found.push(cur.rel === "" ? "package.json" : `${cur.rel}/package.json`);
+            packageFiles.push(`${cur.rel}/package.json`);
+        }
+        // Plugin hooks files sit in a hooks directory one level below the
+        // plugin root, so they are spotted from the plugin root listing
+        // (the hooks directory itself can sit at depth bound plus one).
+        if (entries.includes("hooks")) {
+            const hooksAbs = join(cur.abs, "hooks");
+            let lst = null;
+            try {
+                lst = lstatSync(hooksAbs);
+            }
+            catch {
+                lst = null;
+            }
+            if (lst && lst.isDirectory() && !lst.isSymbolicLink()) {
+                let hookEntries = [];
+                try {
+                    hookEntries = readdirSync(hooksAbs);
+                }
+                catch {
+                    hookEntries = [];
+                }
+                for (const name of ["hooks.json", "hooks-cursor.json"]) {
+                    if (hookEntries.includes(name))
+                        pluginSet.add(cur.rel === "" ? `hooks/${name}` : `${cur.rel}/hooks/${name}`);
+                }
+            }
         }
-        if (cur.depth >= PACKAGE_MAX_DEPTH)
-            continue;
-        // Push in reverse so the stack pops in sorted order.
-        for (let i = entries.length - 1; i >= 0; i--) {
-            const name = entries[i];
+        const children = [];
+        for (const name of entries) {
             if (skipDirs.has(name) || name.startsWith("."))
                 continue;
             const childAbs = join(cur.abs, name);
@@ -1812,19 +2064,84 @@ function discoverNestedPackageJson(root, warnings) {
             }
             if (lst.isSymbolicLink() || !lst.isDirectory())
                 continue;
-            stack.push({ abs: childAbs, rel: cur.rel === "" ? name : `${cur.rel}/${name}`, depth: cur.depth + 1 });
+            children.push({ abs: childAbs, rel: cur.rel === "" ? name : `${cur.rel}/${name}`, depth: cur.depth + 1 });
+        }
+        if (cur.depth >= NESTED_MAX_DEPTH) {
+            frontierDirs += children.length;
+            for (const child of children) {
+                if (probes >= 1000)
+                    break;
+                probes++;
+                let sub = [];
+                try {
+                    sub = readdirSync(child.abs);
+                }
+                catch {
+                    continue;
+                }
+                if (sub.some((n) => SURFACE_FILE_INDICATORS.has(n) || SURFACE_DIR_INDICATORS.has(n)))
+                    surfacesBelowBound++;
+            }
+            continue;
         }
+        // Push in reverse so the stack pops in sorted order.
+        for (let i = children.length - 1; i >= 0; i--)
+            stack.push(children[i]);
     }
-    found.sort();
-    if (found.length > PACKAGE_MAX_NESTED) {
-        warnings.push(`Nested package.json inventory capped at ${PACKAGE_MAX_NESTED} files (${found.length} found); the remaining nested package.json files were not inventoried and the scan is partial`);
-        return found.slice(0, PACKAGE_MAX_NESTED);
+    projectRoots.sort((a, b) => (a === b ? 0 : a === "" ? -1 : b === "" ? 1 : a < b ? -1 : 1));
+    packageFiles.sort();
+    return {
+        projectRoots,
+        packageFiles,
+        pluginHookFiles: Array.from(pluginSet).sort(),
+        frontierDirs,
+        surfacesBelowBound,
+        depthBoundHit: frontierDirs > 0,
+    };
+}
+const FAMILY_LABELS = {
+    settings: "Claude settings",
+    tasks: "VS Code tasks",
+    workflows: "workflow",
+    husky: "husky hook",
+    githooks: "githooks hook",
+    lefthook: "lefthook config",
+    "pre-commit": "pre-commit config",
+    mcp: "MCP config",
+    agent: "agent config",
+};
+/**
+ * Claim one surface file for inventory. Returns false when the file
+ * was already inventoried through another discovery path, or when the
+ * nested file cap for its family is already spent (the skip is
+ * counted, and scanHooks warns once per capped family).
+ */
+function claimFile(state, family, rel, isNested) {
+    if (state.inventoried.has(rel))
+        return false;
+    if (isNested) {
+        const found = (state.familyFound.get(family) ?? 0) + 1;
+        state.familyFound.set(family, found);
+        if (found > NESTED_MAX_FILES_PER_SURFACE) {
+            state.familyCapped.set(family, (state.familyCapped.get(family) ?? 0) + 1);
+            state.partial = true;
+            return false;
+        }
     }
-    return found;
+    state.inventoried.add(rel);
+    return true;
 }
-function scanPackageJson(root, findings, warnings) {
+function scanPackageJson(root, findings, warnings, state) {
     scanOnePackageJson(root, "package.json", findings, warnings);
-    for (const rel of discoverNestedPackageJson(root, warnings)) {
+    state.inventoried.add("package.json");
+    let nested = state.disc.packageFiles;
+    if (nested.length > PACKAGE_MAX_NESTED) {
+        warnings.push(`Nested package.json inventory capped at ${PACKAGE_MAX_NESTED} files (${nested.length} found); the remaining nested package.json files were not inventoried and the scan is partial`);
+        state.partial = true;
+        nested = nested.slice(0, PACKAGE_MAX_NESTED);
+    }
+    for (const rel of nested) {
+        state.inventoried.add(rel);
         scanOnePackageJson(root, rel, findings, warnings);
     }
 }
@@ -1850,16 +2167,22 @@ function collectClaudeHooks(node, file, root, findings, prefix, source = "claude
  * the GNU stow layout used by real dotfiles repos (claude/settings.json,
  * no dot), and a settings file nested one level under a config dir
  * (config/.claude/settings.json). A settings path that exists as a
- * directory is reported as a warning, never silently skipped.
+ * directory is reported as a warning, never silently skipped. Since
+ * v0.1.8 (P-065) the candidates are computed per project root, so the
+ * same locations are inventoried in every subdirectory within the
+ * discovery bound; the inventoried set in ScanState keeps a file
+ * reachable by two paths (a parent root one level candidate and its
+ * own project root) counted exactly once.
  */
-function claudeSettingsCandidates(root) {
+function claudeSettingsCandidates(root, prefix) {
+    const base = prefix === "" ? "" : `${prefix}/`;
     const rels = [
-        ".claude/settings.json", ".claude/settings.local.json",
-        "claude/settings.json", "claude/settings.local.json",
+        `${base}.claude/settings.json`, `${base}.claude/settings.local.json`,
+        `${base}claude/settings.json`, `${base}claude/settings.local.json`,
     ];
     let entries = [];
     try {
-        entries = readdirSync(root);
+        entries = readdirSync(join(root, prefix));
     }
     catch {
         entries = [];
@@ -1869,7 +2192,7 @@ function claudeSettingsCandidates(root) {
             continue;
         let st;
         try {
-            st = statSync(join(root, name));
+            st = statSync(join(root, prefix, name));
         }
         catch {
             continue;
@@ -1877,42 +2200,50 @@ function claudeSettingsCandidates(root) {
         if (!st.isDirectory())
             continue;
         for (const f of ["settings.json", "settings.local.json"]) {
-            rels.push(`${name}/.claude/${f}`);
+            rels.push(`${base}${name}/.claude/${f}`);
         }
     }
     return Array.from(new Set(rels));
 }
-function scanClaude(root, findings, warnings) {
-    for (const rel of claudeSettingsCandidates(root)) {
-        const abs = join(root, rel);
-        if (!existsSync(abs))
-            continue;
-        let st;
-        try {
-            st = statSync(abs);
-        }
-        catch {
-            continue;
-        }
-        if (st.isDirectory()) {
-            warnings.push(`${rel} is a directory, not a settings file: any hooks inside it cannot be parsed as Claude settings`);
-            continue;
-        }
-        if (!st.isFile())
-            continue;
-        const data = readJson(root, rel, warnings);
-        if (!data || typeof data !== "object")
-            continue;
-        if (!("hooks" in data)) {
-            warnings.push(`No hooks key in ${rel}`);
-            continue;
-        }
-        const hooks = data.hooks;
-        if (!hooks || typeof hooks !== "object") {
-            warnings.push(`hooks key in ${rel} is not an object: hooks skipped`);
-            continue;
+function scanClaude(root, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        for (const rel of claudeSettingsCandidates(root, prefix)) {
+            const abs = join(root, rel);
+            if (!existsSync(abs))
+                continue;
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (!state.inventoried.has(rel)) {
+                    state.inventoried.add(rel);
+                    warnings.push(`${rel} is a directory, not a settings file: any hooks inside it cannot be parsed as Claude settings`);
+                }
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!claimFile(state, "settings", rel, prefix !== ""))
+                continue;
+            const data = readJson(root, rel, warnings);
+            if (!data || typeof data !== "object")
+                continue;
+            if (!("hooks" in data)) {
+                warnings.push(`No hooks key in ${rel}`);
+                continue;
+            }
+            const hooks = data.hooks;
+            if (!hooks || typeof hooks !== "object") {
+                warnings.push(`hooks key in ${rel} is not an object: hooks skipped`);
+                continue;
+            }
+            collectClaudeHooks(hooks, rel, root, findings, "", "claude-settings", baseAbs);
         }
-        collectClaudeHooks(hooks, rel, root, findings, "");
     }
 }
 /**
@@ -1933,67 +2264,21 @@ function scanClaude(root, findings, warnings) {
  * command object shape under Cursor event names, so it is inventoried
  * the same way.
  *
- * The walk mirrors the nested package.json discipline (P-032): sorted
- * order, node_modules, .git, and dot directories never entered,
- * symlinked directories never followed, and a cap with a warning. The
- * depth bound applies to the plugin root (at most PLUGIN_HOOKS_MAX_DEPTH
- * directories below the scan root); the hooks directory itself sits one
- * level below its plugin root.
+ * Discovery is part of the unified bounded walk (P-065): the file
+ * list comes from discoverSurfaces, with the plugin root at most
+ * PLUGIN_HOOKS_MAX_DEPTH directories below the scan root (the hooks
+ * directory itself sits one level below its plugin root), and the
+ * same cap with a warning applies.
  */
-export const PLUGIN_HOOKS_MAX_DEPTH = 4;
-export const PLUGIN_HOOKS_MAX_FILES = 200;
-function discoverPluginHookFiles(root, warnings) {
-    const found = [];
-    const skipDirs = new Set(["node_modules", ".git"]);
-    const maxHooksDirDepth = PLUGIN_HOOKS_MAX_DEPTH + 1;
-    const stack = [{ abs: root, rel: "", depth: 0 }];
-    while (stack.length > 0) {
-        const cur = stack.pop();
-        let entries = [];
-        try {
-            entries = readdirSync(cur.abs);
-        }
-        catch {
-            if (cur.rel)
-                warnings.push(`Unreadable directory skipped: ${cur.rel} could not be listed; the scan is partial`);
-            continue;
-        }
-        entries.sort();
-        const base = cur.rel === "" ? "" : (cur.rel.split("/").pop() ?? "");
-        if (cur.depth >= 1 && base === "hooks") {
-            for (const name of ["hooks.json", "hooks-cursor.json"]) {
-                if (entries.includes(name))
-                    found.push(cur.rel === "" ? name : `${cur.rel}/${name}`);
-            }
-        }
-        if (cur.depth >= maxHooksDirDepth)
-            continue;
-        for (let i = entries.length - 1; i >= 0; i--) {
-            const name = entries[i];
-            if (skipDirs.has(name) || name.startsWith("."))
-                continue;
-            const childAbs = join(cur.abs, name);
-            let lst;
-            try {
-                lst = lstatSync(childAbs);
-            }
-            catch {
-                continue;
-            }
-            if (lst.isSymbolicLink() || !lst.isDirectory())
-                continue;
-            stack.push({ abs: childAbs, rel: cur.rel === "" ? name : `${cur.rel}/${name}`, depth: cur.depth + 1 });
-        }
-    }
-    found.sort();
-    if (found.length > PLUGIN_HOOKS_MAX_FILES) {
-        warnings.push(`Plugin hooks inventory capped at ${PLUGIN_HOOKS_MAX_FILES} files (${found.length} found); the remaining plugin hook files were not inventoried and the scan is partial`);
-        return found.slice(0, PLUGIN_HOOKS_MAX_FILES);
-    }
-    return found;
-}
-function scanPluginHooks(root, findings, warnings) {
-    for (const rel of discoverPluginHookFiles(root, warnings)) {
+function scanPluginHooks(root, findings, warnings, state) {
+    let files = state.disc.pluginHookFiles;
+    if (files.length > PLUGIN_HOOKS_MAX_FILES) {
+        warnings.push(`Plugin hooks inventory capped at ${PLUGIN_HOOKS_MAX_FILES} files (${files.length} found); the remaining plugin hook files were not inventoried and the scan is partial`);
+        state.partial = true;
+        files = files.slice(0, PLUGIN_HOOKS_MAX_FILES);
+    }
+    for (const rel of files) {
+        state.inventoried.add(rel);
         const data = readJson(root, rel, warnings);
         if (!data || typeof data !== "object" || Array.isArray(data))
             continue;
@@ -2009,129 +2294,48 @@ function scanPluginHooks(root, findings, warnings) {
         collectClaudeHooks(eventsNode, rel, root, findings, "", "claude-plugin", pluginRootAbs);
     }
 }
-function scanVscode(root, findings, warnings) {
-    const rel = ".vscode/tasks.json";
-    if (existsSync(join(root, rel))) {
-        const data = readJson(root, rel, warnings);
-        if (data && data.tasks !== undefined && !Array.isArray(data.tasks)) {
-            warnings.push(`tasks key in ${rel} is not an array: tasks skipped`);
-        }
-        const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
-        tasks.forEach((rawTask, idx) => {
-            // Malformed entries (null, strings, numbers) are skipped, never fatal:
-            // one bad task must not hide every other surface in the repo.
-            if (!rawTask || typeof rawTask !== "object")
-                return;
-            const task = rawTask;
-            const runOptions = (task.runOptions ?? {});
-            const options = (task.options ?? {});
-            const optionsRunOptions = (options.runOptions ?? {});
-            // folderOpen lives in runOptions in the standard schema, but real
-            // world files also nest it under options or put runOn on the task.
-            const runOn = runOptions.runOn ?? optionsRunOptions.runOn ?? task.runOn;
-            const isFolderOpen = runOn === "folderOpen" || (Array.isArray(runOn) && runOn.includes("folderOpen"));
-            const command = typeof task.command === "string" ? task.command : "";
-            const args = Array.isArray(task.args) ? task.args.filter((a) => typeof a === "string").join(" ") : "";
-            const full = [command, args].filter(Boolean).join(" ").trim();
-            if (!full)
-                return;
-            const label = typeof task.label === "string" ? task.label : `task-${idx}`;
-            if (isFolderOpen) {
-                findings.push(makeFinding(root, rel, "vscode-tasks", `folderOpen:${label}`, full, String(idx)));
+function scanVscode(root, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const base = prefix === "" ? "" : `${prefix}/`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        const rel = `${base}.vscode/tasks.json`;
+        if (existsSync(join(root, rel)) && claimFile(state, "tasks", rel, prefix !== "")) {
+            const data = readJson(root, rel, warnings);
+            if (data && data.tasks !== undefined && !Array.isArray(data.tasks)) {
+                warnings.push(`tasks key in ${rel} is not an array: tasks skipped`);
             }
-            else {
-                // Inventory non auto-run tasks at lower weight: still record them so
-                // explain can find them, classified by their command.
-                const f = makeFinding(root, rel, "vscode-tasks", label, full, String(idx));
-                findings.push(f);
-            }
-        });
-    }
-    // MCP config inside .vscode
-    scanMcpFile(root, ".vscode/mcp.json", findings, warnings);
-}
-function scanDirFiles(root, dirRel, source, findings, warnings) {
-    const abs = join(root, dirRel);
-    if (!existsSync(abs))
-        return;
-    let entries = [];
-    try {
-        entries = readdirSync(abs);
-    }
-    catch {
-        warnings.push(`Unreadable directory skipped: ${dirRel} could not be listed; the scan is partial`);
-        return;
-    }
-    for (const name of entries.sort()) {
-        const fileAbs = join(abs, name);
-        let st;
-        try {
-            st = statSync(fileAbs);
-        }
-        catch {
-            continue;
-        }
-        if (!st.isFile())
-            continue;
-        if (name === "_" || name.startsWith("."))
-            continue;
-        const content = readTextWarn(fileAbs, `${dirRel}/${name}`, warnings);
-        if (content === null)
-            continue;
-        const firstMeaningful = content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#") && !l.startsWith("set -")).join(" ");
-        const fileRel = `${dirRel}/${name}`;
-        // Entire file content is the command surface for husky style hooks.
-        // Classify generously deep into the file: a payload hidden behind
-        // padding must still be seen. Display code truncates separately.
-        findings.push(makeFinding(root, fileRel, source, name, content.trim().slice(0, 200000)));
-        void firstMeaningful;
-    }
-}
-function scanLefthook(root, findings, warnings) {
-    for (const rel of ["lefthook.yml", "lefthook.yaml", ".lefthook.yml"]) {
-        if (!existsSync(join(root, rel)))
-            continue;
-        const raw = (readTextWarn(join(root, rel), rel, warnings) ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-        const runRe = /^\s*run:\s*(.+)$/gm;
-        let m;
-        let i = 0;
-        while ((m = runRe.exec(raw)) !== null) {
-            findings.push(makeFinding(root, rel, "lefthook", "run", m[1].trim().replace(/^["']|["']$/g, ""), String(i++)));
-        }
-    }
-}
-function scanPreCommit(root, findings, warnings) {
-    const rel = ".pre-commit-config.yaml";
-    if (!existsSync(join(root, rel)))
-        return;
-    const raw = (readTextWarn(join(root, rel), rel, warnings) ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-    const entryRe = /^\s*entry:\s*(.+)$/gm;
-    let m;
-    let i = 0;
-    while ((m = entryRe.exec(raw)) !== null) {
-        findings.push(makeFinding(root, rel, "pre-commit", "entry", m[1].trim().replace(/^["']|["']$/g, ""), String(i++)));
-    }
-    const repoRe = /^\s*-\s*repo:\s*(https?:\/\/\S+)$/gm;
-    while ((m = repoRe.exec(raw)) !== null) {
-        // A remote hook repo is the standard pre-commit pattern, not a finding
-        // of compromise: the URL alone is inventoried as UNKNOWN so a human can
-        // review the pinned rev. Classifying the bare URL with the command
-        // rules would verdict every normal pre-commit config COMPROMISED.
-        findings.push({
-            id: `${rel}:remote-repo:${i++}`,
-            file: rel,
-            source: "pre-commit",
-            hook: "remote-repo",
-            command: m[1].trim(),
-            classification: "UNKNOWN",
-            rules: [],
-            evidence: "remote pre-commit hook repo (standard pattern): its hooks run locally at commit time; hookcheck cannot verify remote contents, review the pinned rev",
-        });
-    }
-}
-function scanAgentDirs(root, findings, warnings) {
-    for (const [dir, source] of [[".cursor", "cursor"], [".codex", "codex"]]) {
-        const abs = join(root, dir);
+            const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+            tasks.forEach((rawTask, idx) => {
+                // Malformed entries (null, strings, numbers) are skipped, never fatal:
+                // one bad task must not hide every other surface in the repo.
+                if (!rawTask || typeof rawTask !== "object")
+                    return;
+                const task = rawTask;
+                const runOptions = (task.runOptions ?? {});
+                const options = (task.options ?? {});
+                const optionsRunOptions = (options.runOptions ?? {});
+                // folderOpen lives in runOptions in the standard schema, but real
+                // world files also nest it under options or put runOn on the task.
+                const runOn = runOptions.runOn ?? optionsRunOptions.runOn ?? task.runOn;
+                const isFolderOpen = runOn === "folderOpen" || (Array.isArray(runOn) && runOn.includes("folderOpen"));
+                const command = typeof task.command === "string" ? task.command : "";
+                const args = Array.isArray(task.args) ? task.args.filter((a) => typeof a === "string").join(" ") : "";
+                const full = [command, args].filter(Boolean).join(" ").trim();
+                if (!full)
+                    return;
+                const label = typeof task.label === "string" ? task.label : `task-${idx}`;
+                findings.push(makeFinding(root, rel, "vscode-tasks", isFolderOpen ? `folderOpen:${label}` : label, full, String(idx), undefined, baseAbs));
+            });
+        }
+        // MCP config inside .vscode
+        scanMcpFile(root, `${base}.vscode/mcp.json`, findings, warnings, state, baseAbs, prefix !== "");
+    }
+}
+function scanDirFiles(root, dirName, source, family, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const dirRel = prefix === "" ? dirName : `${prefix}/${dirName}`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        const abs = join(root, dirRel);
         if (!existsSync(abs))
             continue;
         let entries = [];
@@ -2139,6 +2343,7 @@ function scanAgentDirs(root, findings, warnings) {
             entries = readdirSync(abs);
         }
         catch {
+            warnings.push(`Unreadable directory skipped: ${dirRel} could not be listed; the scan is partial`);
             continue;
         }
         for (const name of entries.sort()) {
@@ -2152,43 +2357,144 @@ function scanAgentDirs(root, findings, warnings) {
             }
             if (!st.isFile())
                 continue;
-            const rel = `${dir}/${name}`;
-            // mcp.json is an MCP config surface, inventoried exactly once by
-            // the central scanMcpFile pass in scanHooks (P-035). Running it
-            // through the generic command walk here as well counted every
-            // .cursor/mcp.json server twice.
-            if (name === "mcp.json")
+            if (name === "_" || name.startsWith("."))
+                continue;
+            const fileRel = `${dirRel}/${name}`;
+            if (!claimFile(state, family, fileRel, prefix !== ""))
+                continue;
+            const content = readTextWarn(fileAbs, fileRel, warnings);
+            if (content === null)
+                continue;
+            // Entire file content is the command surface for husky style hooks.
+            // Classify generously deep into the file: a payload hidden behind
+            // padding must still be seen. Display code truncates separately.
+            findings.push(makeFinding(root, fileRel, source, name, content.trim().slice(0, 200000), undefined, undefined, baseAbs));
+        }
+    }
+}
+function scanLefthook(root, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const base = prefix === "" ? "" : `${prefix}/`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        for (const name of ["lefthook.yml", "lefthook.yaml", ".lefthook.yml"]) {
+            const rel = `${base}${name}`;
+            if (!existsSync(join(root, rel)))
+                continue;
+            if (!claimFile(state, "lefthook", rel, prefix !== ""))
+                continue;
+            const raw = (readTextWarn(join(root, rel), rel, warnings) ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+            const runRe = /^\s*run:\s*(.+)$/gm;
+            let m;
+            let i = 0;
+            while ((m = runRe.exec(raw)) !== null) {
+                findings.push(makeFinding(root, rel, "lefthook", "run", m[1].trim().replace(/^["']|["']$/g, ""), String(i++), undefined, baseAbs));
+            }
+        }
+    }
+}
+function scanPreCommit(root, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const base = prefix === "" ? "" : `${prefix}/`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        const rel = `${base}.pre-commit-config.yaml`;
+        if (!existsSync(join(root, rel)))
+            continue;
+        if (!claimFile(state, "pre-commit", rel, prefix !== ""))
+            continue;
+        const raw = (readTextWarn(join(root, rel), rel, warnings) ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        const entryRe = /^\s*entry:\s*(.+)$/gm;
+        let m;
+        let i = 0;
+        while ((m = entryRe.exec(raw)) !== null) {
+            findings.push(makeFinding(root, rel, "pre-commit", "entry", m[1].trim().replace(/^["']|["']$/g, ""), String(i++), undefined, baseAbs));
+        }
+        const repoRe = /^\s*-\s*repo:\s*(https?:\/\/\S+)$/gm;
+        while ((m = repoRe.exec(raw)) !== null) {
+            // A remote hook repo is the standard pre-commit pattern, not a finding
+            // of compromise: the URL alone is inventoried as UNKNOWN so a human can
+            // review the pinned rev. Classifying the bare URL with the command
+            // rules would verdict every normal pre-commit config COMPROMISED.
+            findings.push({
+                id: `${rel}:remote-repo:${i++}`,
+                file: rel,
+                source: "pre-commit",
+                hook: "remote-repo",
+                command: m[1].trim(),
+                classification: "UNKNOWN",
+                rules: [],
+                evidence: "remote pre-commit hook repo (standard pattern): its hooks run locally at commit time; hookcheck cannot verify remote contents, review the pinned rev",
+            });
+        }
+    }
+}
+function scanAgentDirs(root, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const base = prefix === "" ? "" : `${prefix}/`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        for (const [dir, source] of [[".cursor", "cursor"], [".codex", "codex"]]) {
+            const abs = join(root, base, dir);
+            if (!existsSync(abs))
+                continue;
+            let entries = [];
+            try {
+                entries = readdirSync(abs);
+            }
+            catch {
                 continue;
-            if (name.endsWith(".json")) {
-                const data = readJson(root, rel, warnings);
-                if (data)
-                    collectGenericCommands(data, rel, root, findings, source);
             }
-            else {
-                const content = readTextWarn(fileAbs, rel, warnings);
-                if (content && content.trim()) {
-                    findings.push(makeFinding(root, rel, source, name, content.trim().slice(0, 200000)));
+            for (const name of entries.sort()) {
+                const fileAbs = join(abs, name);
+                let st;
+                try {
+                    st = statSync(fileAbs);
+                }
+                catch {
+                    continue;
+                }
+                if (!st.isFile())
+                    continue;
+                const rel = `${base}${dir}/${name}`;
+                // mcp.json is an MCP config surface, inventoried exactly once by
+                // the central scanMcpFile pass in scanHooks (P-035). Running it
+                // through the generic command walk here as well counted every
+                // .cursor/mcp.json server twice.
+                if (name === "mcp.json")
+                    continue;
+                if (!claimFile(state, "agent", rel, prefix !== ""))
+                    continue;
+                if (name.endsWith(".json")) {
+                    const data = readJson(root, rel, warnings);
+                    if (data)
+                        collectGenericCommands(data, rel, root, findings, source, "", baseAbs);
+                }
+                else {
+                    const content = readTextWarn(fileAbs, rel, warnings);
+                    if (content && content.trim()) {
+                        findings.push(makeFinding(root, rel, source, name, content.trim().slice(0, 200000), undefined, undefined, baseAbs));
+                    }
                 }
             }
         }
     }
 }
-function collectGenericCommands(node, file, root, findings, source, prefix = "") {
+function collectGenericCommands(node, file, root, findings, source, prefix = "", baseAbs = root) {
     if (!node || typeof node !== "object")
         return;
     const obj = node;
     if (typeof obj.command === "string" && obj.command.trim()) {
         const args = Array.isArray(obj.args) ? obj.args.filter((a) => typeof a === "string").join(" ") : "";
-        findings.push(makeFinding(root, file, source, prefix || "command", [obj.command, args].filter(Boolean).join(" "), String(findings.length)));
+        findings.push(makeFinding(root, file, source, prefix || "command", [obj.command, args].filter(Boolean).join(" "), String(findings.length), undefined, baseAbs));
     }
     for (const [key, value] of Object.entries(obj)) {
         if (value && typeof value === "object")
-            collectGenericCommands(value, file, root, findings, source, prefix ? `${prefix}:${key}` : key);
+            collectGenericCommands(value, file, root, findings, source, prefix ? `${prefix}:${key}` : key, baseAbs);
     }
 }
-function scanMcpFile(root, rel, findings, warnings) {
+function scanMcpFile(root, rel, findings, warnings, state, baseAbs, isNested) {
     if (!existsSync(join(root, rel)))
         return;
+    if (!claimFile(state, "mcp", rel, isNested))
+        return;
     const data = readJson(root, rel, warnings);
     if (!data)
         return;
@@ -2203,9 +2509,9 @@ function scanMcpFile(root, rel, findings, warnings) {
         const args = Array.isArray(c.args) ? c.args.filter((a) => typeof a === "string").join(" ") : "";
         const full = [command, args].filter(Boolean).join(" ").trim();
         if (full)
-            findings.push(makeFinding(root, rel, "mcp-config", `mcp:${name}`, full));
+            findings.push(makeFinding(root, rel, "mcp-config", `mcp:${name}`, full, undefined, undefined, baseAbs));
         if (typeof c.url === "string" && c.url) {
-            findings.push(makeFinding(root, rel, "mcp-config", `mcp:${name}:url`, c.url));
+            findings.push(makeFinding(root, rel, "mcp-config", `mcp:${name}:url`, c.url, undefined, undefined, baseAbs));
         }
     }
 }
@@ -2233,26 +2539,37 @@ function scanMcpFile(root, rel, findings, warnings) {
  * resolved is still inventoried, as the literal alias text at UNKNOWN,
  * so no executable step ever yields zero findings.
  */
-function scanWorkflows(root, findings, warnings) {
-    const dir = ".github/workflows";
-    const abs = join(root, dir);
-    if (!existsSync(abs))
-        return;
-    let entries = [];
-    try {
-        entries = readdirSync(abs);
-    }
-    catch {
-        warnings.push(`Unreadable directory skipped: ${dir} could not be listed; the scan is partial`);
-        return;
-    }
-    for (const name of entries.sort()) {
-        if (!/\.(yml|yaml)$/.test(name))
+function scanWorkflows(root, findings, warnings, state) {
+    for (const prefix of state.disc.projectRoots) {
+        const base = prefix === "" ? "" : `${prefix}/`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        const dir = `${base}.github/workflows`;
+        const abs = join(root, dir);
+        if (!existsSync(abs))
             continue;
-        const rel = `${dir}/${name}`;
+        let entries = [];
+        try {
+            entries = readdirSync(abs);
+        }
+        catch {
+            warnings.push(`Unreadable directory skipped: ${dir} could not be listed; the scan is partial`);
+            continue;
+        }
+        for (const name of entries.sort()) {
+            if (!/\.(yml|yaml)$/.test(name))
+                continue;
+            const rel = `${dir}/${name}`;
+            if (!claimFile(state, "workflows", rel, prefix !== ""))
+                continue;
+            scanOneWorkflow(root, rel, baseAbs, findings, warnings);
+        }
+    }
+}
+function scanOneWorkflow(root, rel, baseAbs, findings, warnings) {
+    {
         const rawFile = readTextWarn(join(root, rel), rel, warnings);
         if (rawFile === null)
-            continue;
+            return;
         const raw = rawFile.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
         const lines = raw.split("\n");
         const indentOf = (l) => l.length - l.trimStart().length;
@@ -2344,14 +2661,14 @@ function scanWorkflows(root, findings, warnings) {
             if (aliasStep) {
                 const name = aliasStep[1];
                 const resolved = scalarAnchors.has(name) || mapAnchors.has(name) ? resolveAlias(`*${name}`) : `*${name}`;
-                findings.push(makeFinding(root, rel, "github-workflow", "run", resolved, String(i++), lineNo));
+                findings.push(makeFinding(root, rel, "github-workflow", "run", resolved, String(i++), lineNo, baseAbs));
                 continue;
             }
             const mergeKey = line.match(/^\s*<<:\s*\*([A-Za-z0-9_-]+)\s*(#.*)?$/);
             if (mergeKey) {
                 const name = mergeKey[1];
                 const resolved = scalarAnchors.has(name) || mapAnchors.has(name) ? resolveAlias(`*${name}`) : `*${name}`;
-                findings.push(makeFinding(root, rel, "github-workflow", "run", resolved, String(i++), lineNo));
+                findings.push(makeFinding(root, rel, "github-workflow", "run", resolved, String(i++), lineNo, baseAbs));
                 continue;
             }
             const m = line.match(/^(\s*)-?\s*run:\s*(.*)$/);
@@ -2374,19 +2691,19 @@ function scanWorkflows(root, findings, warnings) {
             if (blockHeader) {
                 const { body, end } = collectBlock(idx, runIndent);
                 if (body) {
-                    findings.push(makeFinding(root, rel, "github-workflow", "run", body, String(i++), lineNoRun));
+                    findings.push(makeFinding(root, rel, "github-workflow", "run", body, String(i++), lineNoRun, baseAbs));
                 }
                 idx = end - 1;
                 continue;
             }
             if (rest === "")
                 continue;
-            findings.push(makeFinding(root, rel, "github-workflow", "run", rest, String(i++), lineNoRun));
+            findings.push(makeFinding(root, rel, "github-workflow", "run", rest, String(i++), lineNoRun, baseAbs));
         }
     }
 }
-function scanGitHooks(root, findings, warnings) {
-    scanDirFiles(root, ".githooks", "githooks", findings, warnings);
+function scanGitHooks(root, findings, warnings, state) {
+    scanDirFiles(root, ".githooks", "githooks", "githooks", findings, warnings, state);
 }
 /**
  * Empty estate note (P-014, hookcheck half). A scan that inventories
@@ -2423,21 +2740,44 @@ export function scanHooks(root) {
             note: EMPTY_ESTATE_NOTE,
         };
     }
-    scanPackageJson(root, findings, warnings);
-    scanClaude(root, findings, warnings);
-    scanPluginHooks(root, findings, warnings);
-    scanVscode(root, findings, warnings);
-    scanDirFiles(root, ".husky", "husky", findings, warnings);
-    scanLefthook(root, findings, warnings);
-    scanPreCommit(root, findings, warnings);
-    scanAgentDirs(root, findings, warnings);
-    // MCP config surfaces, each inventoried exactly once (P-035).
+    const disc = discoverSurfaces(root, warnings);
+    const state = { disc, inventoried: new Set(), familyFound: new Map(), familyCapped: new Map(), partial: false };
+    scanPackageJson(root, findings, warnings, state);
+    scanClaude(root, findings, warnings, state);
+    scanPluginHooks(root, findings, warnings, state);
+    scanVscode(root, findings, warnings, state);
+    scanDirFiles(root, ".husky", "husky", "husky", findings, warnings, state);
+    scanLefthook(root, findings, warnings, state);
+    scanPreCommit(root, findings, warnings, state);
+    scanAgentDirs(root, findings, warnings, state);
+    // MCP config surfaces, each inventoried exactly once (P-035), at the
+    // scan root and at every nested project root (P-065).
     // .windsurf/mcp.json joined the covered surfaces in v0.1.6 (P-034);
     // .vscode/mcp.json is handled inside scanVscode.
-    for (const rel of [".mcp.json", "mcp.json", ".cursor/mcp.json", ".windsurf/mcp.json", ".codex/mcp.json"])
-        scanMcpFile(root, rel, findings, warnings);
-    scanWorkflows(root, findings, warnings);
-    scanGitHooks(root, findings, warnings);
+    for (const prefix of disc.projectRoots) {
+        const base = prefix === "" ? "" : `${prefix}/`;
+        const baseAbs = prefix === "" ? root : join(root, prefix);
+        for (const name of [".mcp.json", "mcp.json", ".cursor/mcp.json", ".windsurf/mcp.json", ".codex/mcp.json"]) {
+            scanMcpFile(root, `${base}${name}`, findings, warnings, state, baseAbs, prefix !== "");
+        }
+    }
+    scanWorkflows(root, findings, warnings, state);
+    scanGitHooks(root, findings, warnings, state);
+    // Bounded scan honesty (P-065): a scan cut short by the discovery
+    // bounds must say so, naming the bound, instead of presenting as
+    // complete. Surfaces spotted just below the depth bound are counted
+    // in the warning, never silently dropped.
+    if (disc.depthBoundHit) {
+        const below = disc.surfacesBelowBound > 0
+            ? `; at least ${disc.surfacesBelowBound} of the directories just below the bound contain hook surface files or config directories that were not inventoried`
+            : "";
+        warnings.push(`Nested discovery bounded at depth ${NESTED_MAX_DEPTH}: project directories more than ${NESTED_MAX_DEPTH} levels below the scan root were not scanned (${disc.frontierDirs} ${disc.frontierDirs === 1 ? "directory" : "directories"} below the bound not entered${below}); the scan is partial (bounded)`);
+    }
+    for (const [family, capped] of state.familyCapped) {
+        const label = FAMILY_LABELS[family] ?? family;
+        warnings.push(`Nested ${label} inventory capped at ${NESTED_MAX_FILES_PER_SURFACE} files (${state.familyFound.get(family) ?? 0} found); the remaining nested ${label} files were not inventoried and the scan is partial`);
+        void capped;
+    }
     // Dedupe identical ids (agent dir scan may double count mcp.json).
     const seen = new Set();
     const deduped = findings.filter((f) => {
@@ -2453,12 +2793,14 @@ export function scanHooks(root) {
         risky: deduped.filter((f) => f.classification === "RISKY").length,
         unknown: deduped.filter((f) => f.classification === "UNKNOWN").length,
     };
-    // Partial scan floor (P-049): when any inventoried file or directory
-    // could not be read, the scan did not see the whole estate, so a bare
-    // CLEAN is not an honest verdict. Floor at REVIEW; the warnings name
-    // exactly what was missed.
+    // Partial scan floor (P-049, extended by P-065): when any inventoried
+    // file or directory could not be read, when a file cap left surface
+    // files uninventoried, or when hook surfaces were spotted just below
+    // the discovery depth bound, the scan did not see the whole estate,
+    // so a bare CLEAN is not an honest verdict. Floor at REVIEW; the
+    // warnings name exactly what was missed.
     let verdict = computeVerdict(deduped);
-    if (verdict === "CLEAN" && warnings.some((w) => w.startsWith("Unreadable"))) {
+    if (verdict === "CLEAN" && (warnings.some((w) => w.startsWith("Unreadable")) || state.partial || disc.surfacesBelowBound > 0)) {
         verdict = "REVIEW";
     }
     return {