@reneturcios/hookcheck 0.1.13 → 0.1.15

package/README.md

@@ -31,7 +31,7 @@ Every surface above is discovered by one bounded recursive walk, not only at the
 Classification per hook:
 
 - **SAFE**: matches known safe dev patterns such as test, lint, build, typecheck, husky, or lint-staged, and matches no risky rule.
-- **RISKY**: matches at least one risky rule: network fetch, curl piped to an interpreter, base64 decode piped to an interpreter, credential store paths or credential files (matched on content and paths, never on a script filename that merely contains the word credentials), credential shaped environment names (token, secret, password, api key) or bulk environment access, base64 decoding or eval style obfuscation, inline code execution, or a remote URL. Ordinary single named environment reads (NODE_ENV, HOME, RUNNER_DEBUG) are not flagged. Neither are operations that are not reads: `env -u NAME` unsets a variable, `os.environ.setdefault(...)` writes one key with a default, and a `[ -n "$NAME" ]` test checks existence. A hook whose target is a shell script is classified by that script's contents, not by the fact that it is a shell script. Comments are stripped before classification, so a docs URL inside a comment is not a fetch, and a fetch whose every URL is loopback (a localhost health check) is not treated as network behavior. In script files (JavaScript, Python), the contents of string and regex literals are data, not behavior: a defensive guard whose pattern list quotes `eval(` or `curl | sh` performs neither, and hookcheck does not classify it as an attacker. Literals handed to exec style calls (`execSync("...")`, `os.system("...")`) are code by construction and are still matched. Two rules are about value flow, not co-occurrence: ENV-EXFIL fires only when a credential value demonstrably flows into an outbound send (a request payload, a query string, a pipe into a network tool, or printed output next to a send), and CRED-EXFIL when credential store contents are piped or posted straight into a network send. Environment inheritance is not a send: when the only environment movement is inheritance or bulk access passed as a subprocess environment (env=os.environ, a {**os.environ, ...} spread, dict(os.environ), os.environ.copy(), and their JavaScript forms), ENV-EXFIL additionally requires a non-loopback destination in the flow, so a test harness that starts its own server on 127.0.0.1 and hands it the inherited environment does not verdict as exfiltration; the same forms serialized into a payload, or paired with a remote destination, still fire. The ENV-BULK evidence names the form it saw: inheritance and copy forms are described as bulk access in inheritance or copy form, not as a serialization or dump. A token used as authentication (an Authorization header, the userinfo of a push URL to the repo's own host, a `--token` flag) is authentication, not exfiltration, and never fires either rule. Authentication positions are recognized by shape, not only by the Authorization spelling: any curl `-H` header argument whatever its name, any dict or object entry whose key is an authentication header name (Authorization, `x-api-key`, `*-api-key`, `*-auth-token`, and friends) in a one hop script file, and any header shaped entry inside a headers construction (a dict assigned to a headers variable, a `headers=` argument, a headers property of a request options object) all count as authentication positions. Further authentication positions are recognized by the same shape principle: a curl `-u` or `--user` basic auth pair, the value configured for a git `http.extraheader` key (an Authorization header value however it was built), an `::add-mask::` registration (printing a value there is the masking idiom itself), and destination positions in the URL of a send itself: a credential that is an entire URL path segment, the whole URL, or the URL origin (capability URLs are credentials by design: a build hook URL, a preview token in the path, a token query parameter), the value of an authentication named query parameter (`token`, `api_key`, `access_token`, `auth`, `secret`, `signature`, `key`), a bare reference in the curl URL operand position, and the destination first argument of a fetch style call. The body test decides: a credential presented in one of those positions with no credential or bulk data in the body is authentication, while the same credential in a body, in a data named query parameter, in a partial URL path segment, or in printed output still counts as exfiltration, and a capability URL shape plus credential data in the body still fires. Taint does not pass through a locally defined helper function's return value unless the helper itself returns tainted data (its body is analyzed as part of the same text), a printed length or count of a value (`len(x)`, `x.length`, `${#NAME}`) is metadata rather than a disclosure of the value, and a name occurrence that is an object key, a property name, an assignment target, or a parameter declaration is a binding, not a reference to the variable of that name. A shell variable assigned in the same text from a value containing no credential atom (a token named response variable bound to a literal file path, used as a curl `--output` sink), or bound via a command substitution whose only credential atoms sit in destination positions (an HTTP status code variable), is not itself a credential value. Fetch detection requires command position: curl or wget counts as a network fetch only when it is the invoked command (the head of a statement or pipeline segment, after sudo or env wrappers, or the head of a command string handed to an interpreter), never when the word merely names a package in an install line (`pacman -S curl`, `apt-get install curl`). In script files the remote URL rule follows the same data view as the other behavior rules: a URL that appears only inside a string literal or a comment (an error message, a documentation link, an API base constant) is data, while a URL handed to a network call (fetch, requests, http.get, urlopen, axios, sendBeacon) is a fetch target and still fires. Inline code execution (DOWNLOAD-EXEC) fires only when the evaluated content itself carries a download or remote reference; constant inline code such as a `node -e` version comparison downloads nothing and is not flagged.
+- **RISKY**: matches at least one risky rule: network fetch, curl piped to an interpreter, base64 decode piped to an interpreter, credential store paths or credential files (matched on content and paths, never on a script filename that merely contains the word credentials), credential shaped environment names (token, secret, password, api key) or bulk environment access, base64 decoding or eval style obfuscation, inline code execution, or a remote URL. Ordinary single named environment reads (NODE_ENV, HOME, RUNNER_DEBUG) are not flagged. Neither are operations that are not reads: `env -u NAME` unsets a variable, `os.environ.setdefault(...)` writes one key with a default, and a `[ -n "$NAME" ]` test checks existence. A hook whose target is a shell script is classified by that script's contents, not by the fact that it is a shell script. Comments are stripped before classification, so a docs URL inside a comment is not a fetch, and a fetch whose every URL is loopback (a localhost health check) is not treated as network behavior. In script files (JavaScript, Python), the contents of string and regex literals are data, not behavior: a defensive guard whose pattern list quotes `eval(` or `curl | sh` performs neither, and hookcheck does not classify it as an attacker. Literals handed to exec style calls (`execSync("...")`, `os.system("...")`) are code by construction and are still matched. Two rules are about value flow, not co-occurrence: ENV-EXFIL fires only when a credential value demonstrably flows into an outbound send (a request payload, a query string, a pipe into a network tool, or printed output next to a send), and CRED-EXFIL when credential store contents are piped or posted straight into a network send. Environment inheritance is not a send: when the only environment movement is inheritance or bulk access passed as a subprocess environment (env=os.environ, a {**os.environ, ...} spread, dict(os.environ), os.environ.copy(), and their JavaScript forms), ENV-EXFIL additionally requires a non-loopback destination in the flow, so a test harness that starts its own server on 127.0.0.1 and hands it the inherited environment does not verdict as exfiltration; the same forms serialized into a payload, or paired with a remote destination, still fire. The ENV-BULK evidence names the form it saw: inheritance and copy forms are described as bulk access in inheritance or copy form, not as a serialization or dump. A token used as authentication (an Authorization header, the userinfo of a push URL to the repo's own host, a `--token` flag) is authentication, not exfiltration, and never fires either rule. Authentication positions are recognized by shape, not only by the Authorization spelling: any curl `-H` header argument whatever its name, any dict or object entry whose key is an authentication header name (Authorization, `x-api-key`, `*-api-key`, `*-auth-token`, and friends) in a one hop script file, and any header shaped entry inside a headers construction (a dict assigned to a headers variable, a `headers=` argument, a headers property of a request options object) all count as authentication positions. Further authentication positions are recognized by the same shape principle: a curl `-u` or `--user` basic auth pair, the value configured for a git `http.extraheader` key (an Authorization header value however it was built), an `::add-mask::` registration (printing a value there is the masking idiom itself), a credential hand-off position (the value configured for a git `credential.helper` key, including the body of a shell function the helper value names: git reads the helper's echoed username and password lines as its authentication protocol, so that echo is presentation, not disclosure; the same family covers a `core.askPass` value, a `GIT_ASKPASS` or `SSH_ASKPASS` assignment, input piped into a `git credential` invocation, and a heredoc feeding one), and destination positions in the URL of a send itself: a credential that is an entire URL path segment, the whole URL, or the URL origin (capability URLs are credentials by design: a build hook URL, a preview token in the path, a token query parameter), the value of an authentication named query parameter (`token`, `api_key`, `access_token`, `auth`, `secret`, `signature`, `key`), a bare reference in the curl URL operand position, and the destination first argument of a fetch style call. The body test decides: a credential presented in one of those positions with no credential or bulk data in the body is authentication, while the same credential in a body, in a data named query parameter, in a partial URL path segment, or in printed output still counts as exfiltration, and a capability URL shape plus credential data in the body still fires. Taint does not pass through a locally defined helper function's return value unless the helper itself returns tainted data (its body is analyzed as part of the same text), a printed length or count of a value (`len(x)`, `x.length`, `${#NAME}`) is metadata rather than a disclosure of the value, and a name occurrence that is an object key, a property name, an assignment target, or a parameter declaration is a binding, not a reference to the variable of that name. A shell variable assigned in the same text from a value containing no credential atom (a token named response variable bound to a literal file path, used as a curl `--output` sink), or bound via a command substitution whose only credential atoms sit in destination positions (an HTTP status code variable), is not itself a credential value. Fetch detection requires command position: curl or wget counts as a network fetch only when it is the invoked command (the head of a statement or pipeline segment, after sudo or env wrappers, or the head of a command string handed to an interpreter), never when the word merely names a package in an install line (`pacman -S curl`, `apt-get install curl`). In script files the remote URL rule follows the same data view as the other behavior rules: a URL that appears only inside a string literal or a comment (an error message, a documentation link, an API base constant) is data, while a URL handed to a network call (fetch, requests, http.get, urlopen, axios, sendBeacon) is a fetch target and still fires. Inline code execution (DOWNLOAD-EXEC) fires only when the evaluated content itself carries a download or remote reference; constant inline code such as a `node -e` version comparison downloads nothing and is not flagged.
 - **UNKNOWN**: matches neither safe nor risky patterns. A local script name alone is UNKNOWN until a human reads it. When a hook runs a local file such as `node setup.mjs`, hookcheck reads that file and escalates the finding if the file itself matches risky rules. The same one hop following applies to direct script execution (`./setup.sh`), `node --require ./setup.mjs`, and package.json script chains (`postinstall: npm run other-script`). If the referenced file itself spawns a further local script, the chain runs past the one hop limit: the finding is floored at UNKNOWN, never SAFE, and the evidence names the second hop file, so the verdict lands at REVIEW for a hand read.
 
 Verdict rules:
@@ -56,7 +56,8 @@ Honest boundaries, pinned by tests in test/hardening.test.ts:
 - Classification reads up to 200,000 characters of a hook file or a referenced local file. Beyond that depth a payload can hide; the cap exists so a hostile file cannot make the scan unbounded.
 - GitHub workflow run steps in block scalars (`run: |`, `run: >`, and chomping variants) are parsed and classified like one line commands. Plain multi-line scalars without a block header are not joined, and reusable workflow internals are not resolved. YAML anchors, aliases, and merge keys on run steps are resolved when the anchor is defined in the same file; anchors applied to other step fields, and anchors defined in other files, are not resolved. Workflow files with CRLF line endings are parsed exactly like their LF equivalents.
 - Nested discovery is one bounded walk covering every inventoried surface: package.json files, `.claude/settings.json` and `settings.local.json` (including the stow layout `claude/settings.json`), plugin `hooks/hooks.json` and `hooks/hooks-cursor.json` files, `.vscode/tasks.json`, `.github/workflows/*.yml` and `*.yaml`, `.husky/` and `.githooks/` hook files, lefthook configs (`lefthook.yml`, `lefthook.yaml`, `.lefthook.yml`), `.pre-commit-config.yaml`, `.cursor/` and `.codex/` config files, and MCP configs (`.mcp.json`, `mcp.json`, `.cursor/mcp.json`, `.windsurf/mcp.json`, `.codex/mcp.json`, and `.vscode/mcp.json`). A surface is in scope when its project directory sits at most 8 levels below the scan root (the plugin hooks directory itself sits one level below its plugin root), visited in sorted order. Each surface family inventories at most 200 nested files; the scan root files always count. node_modules, .git, dot directories, and symlinked directories are never entered, so surfaces deeper than the depth bound, or anywhere under node_modules, are not scanned. Non-regular files (FIFOs, sockets, device files) are never opened: every file the scanner reads is checked by stat type first and a non-regular file is skipped with a warning naming it, because opening a FIFO blocks until a writer appears and would hang the scan. The bound is never silent: when the walk hits the depth bound with more tree remaining, the report carries a warning naming the depth bound and counts the directories just below the bound that contain hook surface files or config directories; when a family hits the file cap, a warning names the cap and the count found. A scan cut short by either bound, by the cap, or by unreadable files is partial, says so in its warnings, and never verdicts a bare CLEAN when surfaces are known to have been missed. Only the object command form of the plugin schema is inventoried; a hook entry written as a bare string instead of a command object is outside the documented schema and is not inventoried.
-- A file or directory the scanner sets out to inventory but cannot read (for example a workflow file at mode 000) is never skipped silently: the report carries a warning naming it, and the verdict is floored at REVIEW while any part of the estate is unread, so a partial scan never presents as a complete all-clear.
+- A file or directory the scanner sets out to inventory but cannot read (for example a workflow file at mode 000) is never skipped silently: the report carries a warning naming it, and the verdict is floored at REVIEW while any part of the estate is unread, so a partial scan never presents as a complete all-clear. The same holds for surfaces skipped under the no-follow policy: a symlinked directory is never entered, and since v0.1.15 the skip produces one warning per directory naming the link and the reason (a dangling or looping symlink at a surface path warns the same way), and a scan that skipped a surface floors at REVIEW.
+- Repeated identical SAFE findings are aggregated (v0.1.15): when the same SAFE finding (same file, source, hook, command, rules, and evidence) repeats at least 3 times, the report carries one aggregate record with a count and the first and last lines instead of one record per occurrence, and an aggregation note in the JSON and the human output states how many findings were collapsed. RISKY and UNKNOWN findings are never aggregated. The verdict is computed on the full inventory before aggregation, so verdicts and exit codes do not change; a 5 MB workflow of about 92,000 identical benign steps reports 1 aggregate record and about 1 KB of JSON instead of 91,980 records and 35 MB.
 - Custom git hook directories set through core.hooksPath are not scanned: hookcheck inventories the standard `.githooks/` directory and `.husky/`, but it does not parse git config or a committed `.gitconfig` to discover a custom core.hooksPath directory. Hooks kept only in a custom hooksPath directory are outside the inventory; audit them by scanning a tree where they sit in a standard location.
 - Agent config coverage boundaries: `.gemini/settings.json` is not scanned yet. Template configs (for example `templates/settings.json.template`) are not scanned: they are inert until copied into place, at which point the copied file is scanned under its real name.
 - UNKNOWN is the dominant classification on large real repos (measured at roughly 80 percent of findings on langfuse and cli/cli in Round 1 validation). The classifications are inventory, not suspicion: a REVIEW verdict on a large estate means the auto-exec surface is mapped and needs human triage, and the per finding evidence says exactly what each hook runs. More workflow step patterns will be classified over time; until then hookcheck does not guess.

package/dist/core.d.ts

@@ -1,6 +1,6 @@
 import { relative } from "node:path";
 import type { Classification, HookFinding, ScanReport, Verdict } from "./types.js";
-export declare const VERSION = "0.1.13";
+export declare const VERSION = "0.1.15";
 interface RuleDef {
     id: string;
     pattern: RegExp;
@@ -118,6 +118,31 @@ export interface Discovery {
     /** True when the depth bound left directories unentered. */
     depthBoundHit: boolean;
 }
+/**
+ * SAFE finding aggregation (P-070). A single 5 MB workflow of about
+ * 92,000 repeated benign steps produced one finding record per step
+ * on 0.1.14: 91,980 findings, 35,390,354 bytes of JSON, 23.7 seconds
+ * of wall time on the published binary, nearly all of it inventory
+ * noise (every finding the same SAFE step). Repetition at that scale
+ * is one fact, not 92,000: when at least AGGREGATE_MIN identical
+ * SAFE findings (same file, source, hook, command, rules, and
+ * evidence) repeat, they collapse into a single aggregate record
+ * that keeps the first finding's id and line and carries count (the
+ * number folded in) and lastLine (the last folded line). Groups of
+ * two stay individual: a pair is ordinary inventory, not mass
+ * repetition.
+ *
+ * Only SAFE findings are ever aggregated. A RISKY or UNKNOWN finding
+ * is a per-occurrence fact (its line is where a human must look),
+ * and collapsing one could hide the one occurrence that matters.
+ * The verdict is computed on the full inventory BEFORE aggregation,
+ * so verdicts and exit codes are unchanged by the collapse; counts
+ * in the report describe the reported records, and the aggregation
+ * object preserves the pre-aggregation total and states the
+ * collapse in words, in JSON and in the human renderer. The
+ * collapse is never silent.
+ */
+export declare const AGGREGATE_MIN = 3;
 /**
  * Empty estate note (P-014, hookcheck half). A scan that inventories
  * nothing must say so next to the verdict, in JSON as well as in the

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.13";
+export const VERSION = "0.1.15";
 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 },
@@ -1675,6 +1675,106 @@ function authRanges(text) {
     for (const m of text.matchAll(/\bauth\s*=\s*\(/g)) {
         ranges.push({ start: m.index, end: consumeBalanced(text, m.index + m[0].length - 1) });
     }
+    // Credential hand-off positions (P-111). A credential.helper
+    // definition is the credential protocol of the tool performing the
+    // send: git invokes the helper and reads username and password
+    // lines from its stdout, so a token echoed inside a credential
+    // helper is presented as authentication, exactly like a header or
+    // a -u pair. The v0.1.11 auth model scrubbed headers, -u pairs,
+    // extraheader, and URL userinfo, but saw the helper's echoed
+    // password as print disclosure next to a send, which fired
+    // ENV-EXFIL on All-Hands-AI/OpenHands (the Publish live E2E media
+    // step, whose push token is used only inside such a helper). The
+    // same protocol family covers core.askPass values, askpass
+    // environment assignments, input piped or heredoc-fed into a
+    // git credential invocation, and the body of a shell function a
+    // credential.helper value names. Only the hand-off span itself is
+    // scrubbed: the same token echoed to a log, or posted by a curl
+    // statement elsewhere in the step, keeps full exfil weight.
+    const configValueAfter = (from) => {
+        let i = from;
+        while (i < text.length && /\s/.test(text[i]))
+            i++;
+        if (text[i] === "=" || text[i] === ":") {
+            i++;
+            while (i < text.length && /\s/.test(text[i]))
+                i++;
+        }
+        if (i >= text.length)
+            return null;
+        if (text[i] === "'" || text[i] === '"' || text[i] === "`") {
+            const end = consumeLiteral(text, i);
+            return end > i ? { start: i, end } : null;
+        }
+        let end = i;
+        while (end < text.length && !/[\s;"']/.test(text[end]))
+            end++;
+        return end > i ? { start: i, end } : null;
+    };
+    const helperNames = [];
+    for (const m of text.matchAll(/\bcredential\.helper\b/gi)) {
+        const v = configValueAfter(m.index + m[0].length);
+        if (!v)
+            continue;
+        ranges.push(v);
+        const rawVal = text.slice(v.start, v.end).replace(/^['"`]/, "").replace(/^!/, "");
+        const tok = rawVal.split(/\s+/)[0] ?? "";
+        if (/^[A-Za-z_][A-Za-z0-9_-]*$/.test(tok))
+            helperNames.push(tok);
+    }
+    for (const m of text.matchAll(/\bcore\.askpass\b/gi)) {
+        const v = configValueAfter(m.index + m[0].length);
+        if (v)
+            ranges.push(v);
+    }
+    for (const m of text.matchAll(/\b(?:GIT_ASKPASS|SSH_ASKPASS|SUDO_ASKPASS)\s*=\s*/g)) {
+        const v = configValueAfter(m.index + m[0].length);
+        if (v)
+            ranges.push(v);
+    }
+    // A shell function a credential.helper value names by bare word:
+    // its body is the helper program, so its echoed password lines are
+    // protocol output. Builtin helper names (cache, store, manager)
+    // simply have no definition in the text and match nothing.
+    for (const name of helperNames) {
+        const fnRe = new RegExp(`(?:^|[\\n;])\\s*(?:function\\s+)?${name}\\s*(?:\\(\\s*\\))?\\s*\\{`, "g");
+        let fm;
+        while ((fm = fnRe.exec(text)) !== null) {
+            const brace = fm.index + fm[0].length - 1;
+            const end = consumeBalanced(text, brace);
+            if (end > fm.index)
+                ranges.push({ start: fm.index, end });
+        }
+    }
+    // Input handed to a git credential invocation: every earlier
+    // segment of a pipeline whose later segment runs git credential
+    // is protocol input (protocol, host, username, password lines),
+    // not a disclosure to a log.
+    for (const stmt of splitShell(text, ["\n", ";", "&&", "||"])) {
+        const stmtText = text.slice(stmt.start, stmt.end);
+        const segs = splitShell(stmtText, ["|"]);
+        if (segs.length < 2)
+            continue;
+        for (let k = 1; k < segs.length; k++) {
+            const segText = stmtText.slice(segs[k].start, segs[k].end);
+            if (!/^\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:sudo\s+)?git\s+credential\b/.test(segText))
+                continue;
+            for (let e = 0; e < k; e++) {
+                ranges.push({ start: stmt.start + segs[e].start, end: stmt.start + segs[e].end });
+            }
+        }
+    }
+    // A heredoc feeding git credential is protocol input as well:
+    // the body up to the delimiter line is read by git as credential
+    // fields, never printed to a log.
+    for (const m of text.matchAll(/\bgit\s+credential\b[^\n]*<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/g)) {
+        const bodyStart = m.index + m[0].length;
+        const rest = text.slice(bodyStart);
+        const endMatch = rest.match(new RegExp(`\\n[ \\t]*${m[1]}\\b`));
+        if (endMatch && (endMatch.index ?? 0) > 0) {
+            ranges.push({ start: bodyStart, end: bodyStart + (endMatch.index ?? 0) });
+        }
+    }
     // Dict and object entries: authentication header keys anywhere, and
     // any header-shaped key inside a headers construction.
     const entryRe = /(?:^|[{,;\n])\s*(?:(["'])([A-Za-z][A-Za-z0-9_-]*)\1|([A-Za-z][A-Za-z0-9_-]*))\s*:\s*/g;
@@ -3111,6 +3211,7 @@ function discoverSurfaces(root, warnings) {
             if (skipDirs.has(name) || name.startsWith("."))
                 continue;
             const childAbs = join(cur.abs, name);
+            const childRel = cur.rel === "" ? name : `${cur.rel}/${name}`;
             let lst;
             try {
                 lst = lstatSync(childAbs);
@@ -3118,9 +3219,34 @@ function discoverSurfaces(root, warnings) {
             catch {
                 continue;
             }
-            if (lst.isSymbolicLink() || !lst.isDirectory())
+            if (lst.isSymbolicLink()) {
+                // No-follow policy (P-074): a symlinked directory is never
+                // entered, but the skip is no longer silent. One warning per
+                // skipped directory names the path and the reason, when the
+                // link resolves to a directory (the container shape that can
+                // hold hook surfaces) or when a surface-shaped name cannot
+                // be resolved at all. A link to a regular file is not a
+                // directory container and is judged by the surface scanners
+                // at its own path, so it earns no warning here.
+                let targetIsDir = false;
+                let unresolved = false;
+                try {
+                    targetIsDir = statSync(childAbs).isDirectory();
+                }
+                catch {
+                    unresolved = true;
+                }
+                if (targetIsDir) {
+                    warnings.push(`Symlinked directory skipped: ${childRel} is a symbolic link to a directory; symlinked directories are not followed, so any hook surfaces inside it were not inventoried`);
+                }
+                else if (unresolved && SURFACE_DIR_INDICATORS.has(name)) {
+                    warnings.push(`Symlinked directory skipped: ${childRel} is a symbolic link that could not be resolved; it was not inventoried`);
+                }
+                continue;
+            }
+            if (!lst.isDirectory())
                 continue;
-            children.push({ abs: childAbs, rel: cur.rel === "" ? name : `${cur.rel}/${name}`, depth: cur.depth + 1 });
+            children.push({ abs: childAbs, rel: childRel, depth: cur.depth + 1 });
         }
         if (cur.depth >= NESTED_MAX_DEPTH) {
             frontierDirs += children.length;
@@ -3266,13 +3392,29 @@ function scanClaude(root, findings, warnings, state) {
         const baseAbs = prefix === "" ? root : join(root, prefix);
         for (const rel of claudeSettingsCandidates(root, prefix)) {
             const abs = join(root, rel);
-            if (!existsSync(abs))
+            // lstat first (P-074): a candidate that is absent is the normal
+            // case and stays silent, but a candidate that EXISTS in some
+            // form and cannot be examined (a symlink loop, a dangling
+            // link, an unreadable parent directory) was skipped silently
+            // before v0.1.15; it now warns by name, once per path.
+            let lst;
+            try {
+                lst = lstatSync(abs);
+            }
+            catch {
                 continue;
+            }
+            void lst;
             let st;
             try {
                 st = statSync(abs);
             }
-            catch {
+            catch (err) {
+                if (!state.inventoried.has(rel)) {
+                    state.inventoried.add(rel);
+                    const code = err?.code ?? "error";
+                    warnings.push(`Unreadable surface skipped: ${rel} could not be examined (${code}); it was not inventoried`);
+                }
                 continue;
             }
             if (st.isDirectory()) {
@@ -3282,8 +3424,13 @@ function scanClaude(root, findings, warnings, state) {
                 }
                 continue;
             }
-            if (!st.isFile())
+            if (!st.isFile()) {
+                if (!state.inventoried.has(rel)) {
+                    state.inventoried.add(rel);
+                    warnings.push(`Non-regular surface skipped: ${rel} is not a regular file; it was not inventoried`);
+                }
                 continue;
+            }
             if (!claimFile(state, "settings", rel, prefix !== ""))
                 continue;
             const data = readJson(root, rel, warnings);
@@ -3404,18 +3551,23 @@ function scanDirFiles(root, dirName, source, family, findings, warnings, state)
         }
         for (const name of entries.sort()) {
             const fileAbs = join(abs, name);
+            const fileRel = `${dirRel}/${name}`;
+            // An entry the directory listing proved exists but stat cannot
+            // examine (a dangling symlink, a symlink loop) was skipped
+            // silently before v0.1.15 (P-074); it now warns by name.
             let st;
             try {
                 st = statSync(fileAbs);
             }
-            catch {
+            catch (err) {
+                const code = err?.code ?? "error";
+                warnings.push(`Unreadable surface skipped: ${fileRel} could not be examined (${code}); it was not inventoried`);
                 continue;
             }
             if (!st.isFile())
                 continue;
             if (name === "_" || name.startsWith("."))
                 continue;
-            const fileRel = `${dirRel}/${name}`;
             if (!claimFile(state, family, fileRel, prefix !== ""))
                 continue;
             const content = readTextWarn(fileAbs, fileRel, warnings);
@@ -3496,20 +3648,23 @@ function scanAgentDirs(root, findings, warnings, state) {
                 entries = readdirSync(abs);
             }
             catch {
+                warnings.push(`Unreadable directory skipped: ${base}${dir} could not be listed; the scan is partial`);
                 continue;
             }
             for (const name of entries.sort()) {
                 const fileAbs = join(abs, name);
+                const rel = `${base}${dir}/${name}`;
                 let st;
                 try {
                     st = statSync(fileAbs);
                 }
-                catch {
+                catch (err) {
+                    const code = err?.code ?? "error";
+                    warnings.push(`Unreadable surface skipped: ${rel} could not be examined (${code}); it was not inventoried`);
                     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
@@ -3627,7 +3782,15 @@ function scanOneWorkflow(root, rel, baseAbs, findings, warnings) {
         if (rawFile === null)
             return;
         const raw = rawFile.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-        const lines = raw.split("\n");
+        // Trailing whitespace is not YAML content (P-075): a line that
+        // differs from its twin only by trailing spaces must parse
+        // identically. Before v0.1.15 a map anchor line carrying only
+        // trailing whitespace after the anchor name matched the scalar
+        // anchor pattern with a whitespace "value", so the mapping
+        // anchor never registered, its definition run line was
+        // inventoried as a live step, and alias and merge-key steps
+        // resolved to an empty command at UNKNOWN.
+        const lines = raw.split("\n").map((l) => l.replace(/[ \t]+$/, ""));
         const indentOf = (l) => l.length - l.trimStart().length;
         const unquote = (s) => {
             const t = s.trim();
@@ -3675,7 +3838,7 @@ function scanOneWorkflow(root, rel, baseAbs, findings, warnings) {
         };
         for (let idx = 0; idx < lines.length; idx++) {
             const line = lines[idx];
-            const scalarM = line.match(/^(\s*)(?:-\s*)?([A-Za-z0-9_-]+):\s*&([A-Za-z0-9_-]+)\s+(.+?)\s*$/);
+            const scalarM = line.match(/^(\s*)(?:-\s*)?([A-Za-z0-9_-]+):\s*&([A-Za-z0-9_-]+)\s+(\S.*?)\s*$/);
             if (scalarM && scalarM[2] !== "run") {
                 scalarAnchors.set(scalarM[3], unquote(scalarM[4]));
                 continue;
@@ -3743,6 +3906,11 @@ function scanOneWorkflow(root, rel, baseAbs, findings, warnings) {
             else if (/^\*[A-Za-z0-9_-]+$/.test(rest)) {
                 rest = resolveAlias(rest);
             }
+            // A plain quoted scalar is the same command as its unquoted
+            // form (P-076): run: "echo single-line" is echo single-line.
+            // Strip one pair of surrounding quotes before classification
+            // and storage, so both forms produce the identical finding.
+            rest = unquote(rest);
             const blockHeader = rest.match(/^([|>])([+-]?)\s*(#.*)?$/);
             if (blockHeader) {
                 const { body, end } = collectBlock(idx, runIndent);
@@ -3761,6 +3929,79 @@ function scanOneWorkflow(root, rel, baseAbs, findings, warnings) {
 function scanGitHooks(root, findings, warnings, state) {
     scanDirFiles(root, ".githooks", "githooks", "githooks", findings, warnings, state);
 }
+/**
+ * SAFE finding aggregation (P-070). A single 5 MB workflow of about
+ * 92,000 repeated benign steps produced one finding record per step
+ * on 0.1.14: 91,980 findings, 35,390,354 bytes of JSON, 23.7 seconds
+ * of wall time on the published binary, nearly all of it inventory
+ * noise (every finding the same SAFE step). Repetition at that scale
+ * is one fact, not 92,000: when at least AGGREGATE_MIN identical
+ * SAFE findings (same file, source, hook, command, rules, and
+ * evidence) repeat, they collapse into a single aggregate record
+ * that keeps the first finding's id and line and carries count (the
+ * number folded in) and lastLine (the last folded line). Groups of
+ * two stay individual: a pair is ordinary inventory, not mass
+ * repetition.
+ *
+ * Only SAFE findings are ever aggregated. A RISKY or UNKNOWN finding
+ * is a per-occurrence fact (its line is where a human must look),
+ * and collapsing one could hide the one occurrence that matters.
+ * The verdict is computed on the full inventory BEFORE aggregation,
+ * so verdicts and exit codes are unchanged by the collapse; counts
+ * in the report describe the reported records, and the aggregation
+ * object preserves the pre-aggregation total and states the
+ * collapse in words, in JSON and in the human renderer. The
+ * collapse is never silent.
+ */
+export const AGGREGATE_MIN = 3;
+function aggregateSafeFindings(findings) {
+    const keyOf = (f) => [f.file, f.source, f.hook, f.command, f.classification, f.rules.join(","), f.evidence].join("\u0001");
+    const groups = new Map();
+    findings.forEach((f, i) => {
+        if (f.classification !== "SAFE")
+            return;
+        const key = keyOf(f);
+        const arr = groups.get(key) ?? [];
+        arr.push(i);
+        groups.set(key, arr);
+    });
+    let aggregateRecords = 0;
+    let collapsedFindings = 0;
+    const out = [];
+    findings.forEach((f, i) => {
+        if (f.classification !== "SAFE") {
+            out.push(f);
+            return;
+        }
+        const idxs = groups.get(keyOf(f));
+        if (idxs.length < AGGREGATE_MIN) {
+            out.push(f);
+            return;
+        }
+        if (idxs[0] !== i)
+            return; // folded into the group's first record
+        aggregateRecords++;
+        collapsedFindings += idxs.length - 1;
+        const last = findings[idxs[idxs.length - 1]];
+        out.push({
+            ...f,
+            count: idxs.length,
+            ...(last.line !== undefined && f.line !== undefined && last.line !== f.line ? { lastLine: last.line } : {}),
+        });
+    });
+    if (aggregateRecords === 0)
+        return { findings: out };
+    const folded = collapsedFindings + aggregateRecords;
+    return {
+        findings: out,
+        aggregation: {
+            findingsBeforeAggregation: findings.length,
+            aggregateRecords,
+            collapsedFindings,
+            note: `${folded} identical SAFE findings were collapsed into ${aggregateRecords} counted aggregate record(s); ${collapsedFindings} finding record(s) were folded away. Only SAFE findings are aggregated; RISKY and UNKNOWN findings are always reported individually. The verdict was computed on the full inventory of ${findings.length} findings before aggregation, so the verdict and exit codes are unchanged.`,
+        },
+    };
+}
 /**
  * Empty estate note (P-014, hookcheck half). A scan that inventories
  * nothing must say so next to the verdict, in JSON as well as in the
@@ -3843,27 +4084,34 @@ export function scanHooks(root) {
         seen.add(key);
         return true;
     });
-    const counts = {
-        total: deduped.length,
-        safe: deduped.filter((f) => f.classification === "SAFE").length,
-        risky: deduped.filter((f) => f.classification === "RISKY").length,
-        unknown: deduped.filter((f) => f.classification === "UNKNOWN").length,
-    };
-    // 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.
+    // The verdict is computed on the full inventory, before any
+    // aggregation (P-070): collapsing repeated SAFE records for
+    // presentation must never move a verdict or an exit code.
     let verdict = computeVerdict(deduped);
-    if (verdict === "CLEAN" && (warnings.some((w) => w.startsWith("Unreadable")) || state.partial || disc.surfacesBelowBound > 0)) {
+    // Partial scan floor (P-049, extended by P-065 and P-074): when any
+    // inventoried file or directory could not be read, when a file cap
+    // left surface files uninventoried, when hook surfaces were
+    // spotted just below the discovery depth bound, or when a
+    // symlinked directory was skipped under the no-follow policy, 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.
+    if (verdict === "CLEAN" && (warnings.some((w) => w.startsWith("Unreadable") || w.startsWith("Symlinked directory skipped")) || state.partial || disc.surfacesBelowBound > 0)) {
         verdict = "REVIEW";
     }
+    const { findings: reported, aggregation } = aggregateSafeFindings(deduped);
+    const counts = {
+        total: reported.length,
+        safe: reported.filter((f) => f.classification === "SAFE").length,
+        risky: reported.filter((f) => f.classification === "RISKY").length,
+        unknown: reported.filter((f) => f.classification === "UNKNOWN").length,
+    };
     return {
         path: root,
         verdict,
-        findings: deduped,
+        findings: reported,
         counts,
+        ...(aggregation ? { aggregation } : {}),
         warnings,
         scannedAt: new Date().toISOString(),
         ...(counts.total === 0 ? { note: EMPTY_ESTATE_NOTE } : {}),
@@ -3892,10 +4140,14 @@ export function renderReport(report) {
     const lines = [];
     lines.push(`hookcheck ${report.path}: ${report.verdict}`);
     lines.push(`  ${report.counts.total} hook(s): ${report.counts.safe} SAFE, ${report.counts.risky} RISKY, ${report.counts.unknown} UNKNOWN`);
+    if (report.aggregation)
+        lines.push(`  aggregation: ${report.aggregation.note}`);
     if (report.note)
         lines.push(`  note: ${report.note}`);
     for (const f of report.findings) {
-        lines.push(`  [${f.classification}] ${f.id} (${f.source}${f.line !== undefined ? `, line ${f.line}` : ""})`);
+        const linePart = f.line !== undefined ? (f.lastLine !== undefined ? `, lines ${f.line}-${f.lastLine}` : `, line ${f.line}`) : "";
+        const countPart = f.count !== undefined ? `, count ${f.count}` : "";
+        lines.push(`  [${f.classification}] ${f.id} (${f.source}${linePart}${countPart})`);
         lines.push(`      command: ${f.command.slice(0, 200)}`);
         if (f.rules.length)
             lines.push(`      rules: ${f.rules.join(", ")}`);