@rmyndharis/aimhooman 0.1.6 → 0.1.8

package/docs/design/frictionless-enforcement.md

@@ -55,15 +55,18 @@ enforcement requires local or global hook setup.
 | 2. Agent guard | PreToolUse reports paths and rejects unprovable protected Git mutations | plugin | advisory for paths; fail-closed for boundary bypass |
 | 3. Strict policy | `strict` profile blocks instead of repairing (exit 10) | both | block |
 | 4. Pinned tree | `commit-msg` checks the exact would-be tree and message | git hook | blocks a remaining violation or incomplete scan |
-| 5. Final ref check | prepared `reference-transaction` full-scans every commit introduced to `HEAD` or a branch | git hook | blocks a violation or incomplete scan |
+| 5. Final ref check | prepared `reference-transaction` scans what each commit introduced to `HEAD` or a branch changes (and the message of commits authored locally) | git hook | blocks a violation or incomplete scan |
 
 Default profile `clean` uses layers 0, 1, 2, 4, and 5. Successful repair keeps the
 ordinary path low-friction. The pinned-tree and final-ref scans deliberately stop if
-a block remains, including a pre-existing tracked block that was not part of the
-current diff, or if any scan is incomplete.
+a block remains on a path the commit actually changes, or if any scan is incomplete.
+A file already in history is not re-tried on every later commit: the final ref check
+judges a commit by its change set, so an inherited path no longer blocks unrelated
+work. Use `aimhooman check --tracked` (or scan the PR range in CI) to surface legacy
+secrets without bricking the branch.
 Git 2.54 also emits an earlier `preparing` reference-transaction callback. The
 hook checks dispatcher integrity there without scanning unresolved references,
-then keeps the full-scan veto at `prepared`, after Git has locked them.
+then keeps the scan veto at `prepared`, after Git has locked them.
 
 ### Frictionless agent guard (the everyday commands run)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.1.6",
+    "version": "0.1.8",
     "description": "AI works. Hoomans ship. Keep AI session files, secrets, and attribution out of your commits.",
     "homepage": "https://github.com/rmyndharis/aimhooman#readme",
     "repository": {

package/rules/paths.json

@@ -253,7 +253,7 @@
     },
     {
         "id": "secret.private-key",
-        "version": 2,
+        "version": 3,
         "provider": "generic",
         "category": "secret",
         "confidence": "high",
@@ -274,10 +274,11 @@
             "strict": "block",
             "compliance": "block"
         },
-        "reason": "Private key material must never be committed.",
+        "reason": "A path matching a private-key filename (id_rsa, id_ed25519, *.p12, *.pfx, ...) is blocked by name — content is not inspected. If this is a real key, it must never be committed; if the name is coincidental, rename the file.",
         "remediation": [
             "git restore --staged <path>",
-            "rotate the key if it was ever exposed"
+            "if this is a real key, rotate it if it was ever exposed",
+            "if the name is coincidental (a fixture, a doc), rename the file so it no longer matches a private-key pattern"
         ]
     },
     {
@@ -391,10 +392,22 @@
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "path_case": "insensitive", "paths": [".playwright-mcp/**", "**/.playwright-mcp/**"] },
-        "actions": { "clean": "block", "strict": "block", "compliance": "block" },
+        "match": {
+            "path_case": "insensitive",
+            "paths": [
+                ".playwright-mcp/**",
+                "**/.playwright-mcp/**"
+            ]
+        },
+        "actions": {
+            "clean": "block",
+            "strict": "block",
+            "compliance": "block"
+        },
         "reason": "Playwright MCP session artifacts are local, not repository content.",
-        "remediation": ["git restore --staged <path>"]
+        "remediation": [
+            "git restore --staged <path>"
+        ]
     },
     {
         "id": "remember.state",
@@ -403,10 +416,22 @@
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "path_case": "insensitive", "paths": [".remember/**", "**/.remember/**"] },
-        "actions": { "clean": "block", "strict": "block", "compliance": "block" },
+        "match": {
+            "path_case": "insensitive",
+            "paths": [
+                ".remember/**",
+                "**/.remember/**"
+            ]
+        },
+        "actions": {
+            "clean": "block",
+            "strict": "block",
+            "compliance": "block"
+        },
         "reason": "Remember second-brain data is local, not repository content.",
-        "remediation": ["git restore --staged <path>"]
+        "remediation": [
+            "git restore --staged <path>"
+        ]
     },
     {
         "id": "superpowers.state",
@@ -415,10 +440,22 @@
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "path_case": "insensitive", "paths": [".superpowers/**", "**/.superpowers/**"] },
-        "actions": { "clean": "block", "strict": "block", "compliance": "block" },
+        "match": {
+            "path_case": "insensitive",
+            "paths": [
+                ".superpowers/**",
+                "**/.superpowers/**"
+            ]
+        },
+        "actions": {
+            "clean": "block",
+            "strict": "block",
+            "compliance": "block"
+        },
         "reason": "Superpowers plugin state is local, not repository content.",
-        "remediation": ["git restore --staged <path>"]
+        "remediation": [
+            "git restore --staged <path>"
+        ]
     },
     {
         "id": "agent.state",
@@ -427,9 +464,21 @@
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "path_case": "insensitive", "paths": [".agent/**", "**/.agent/**"] },
-        "actions": { "clean": "block", "strict": "block", "compliance": "block" },
+        "match": {
+            "path_case": "insensitive",
+            "paths": [
+                ".agent/**",
+                "**/.agent/**"
+            ]
+        },
+        "actions": {
+            "clean": "block",
+            "strict": "block",
+            "compliance": "block"
+        },
         "reason": "Generic agent state is local, not repository content.",
-        "remediation": ["git restore --staged <path>"]
+        "remediation": [
+            "git restore --staged <path>"
+        ]
     }
-]
+]

package/rules/secrets.json

@@ -45,14 +45,14 @@
     },
     {
         "id": "secret.aws-key-content",
-        "version": 2,
+        "version": 3,
         "provider": "aws",
         "category": "secret",
         "confidence": "high",
         "kind": "code",
         "match": {
             "content": [
-                "(?i)\\baws_(?:secret_access_key|session_token)\\b\\s*[:=]\\s*[\\\"']?[A-Za-z0-9/+=]{32,}(?![A-Za-z0-9/+=])",
+                "(?i)\\baws_(?:secret_access_key|session_token)\\b\\s*[:=]\\s*[\\\"']?[A-Za-z0-9/+=]{32,}(?<!EXAMPLEKEY)(?![A-Za-z0-9/+=])",
                 "\\b(?:AKIA|ASIA)(?![A-Z0-9]{9}EXAMPLE\\b)[A-Z0-9]{16}\\b"
             ]
         },
@@ -89,4 +89,4 @@
             "Remove the token from the index, revoke or rotate it, and use the provider's secret store."
         ]
     }
-]
+]

package/src/githooks.mjs

@@ -43,14 +43,25 @@ function hooksDir(repo) {
     // Inside the worktree is not the same as ours. A hooks directory Git tracks
     // (husky, the vanilla .githooks pattern) is repository content: a dispatcher
     // written there stages this machine's absolute CLI, Node, and PATH for
-    // everyone who clones.
-    const tracked = inside && trackedPath(repo, dir);
+    // everyone who clones. An UNTRACKED hooks directory inside the worktree
+    // (a freshly created `.husky` before the first commit, a team-local
+    // `.team-hooks`) is repository content in waiting: the next `git add`
+    // stages it, carrying the same machine-local paths into history. Treat both
+    // as repository content so neither receives a dispatcher — UNLESS the team
+    // has explicitly excluded the path (.gitignore or .git/info/exclude), which
+    // is the opt-in that says "this hooks dir stays local". A hooks path inside
+    // `.git/` (the default, or a custom one) is local Git plumbing and is safe
+    // to install into regardless.
+    const worktreeContent = inside && !insideGitDir(repo, dir) && !gitIgnored(repo, dir);
+    const trackedByGit = inside && trackedPath(repo, dir);
+    const tracked = trackedByGit || worktreeContent;
     const repositoryOwned = inside && !tracked;
     const shared = !repositoryOwned || resolve(dir) === resolve(globalHooksDir());
     if (shared) {
         const where = scope ? `${scope} scope` : 'a non-local scope';
         let reason = where;
-        if (tracked) reason = `${where}, tracked by this repository`;
+        if (trackedByGit) reason = `${where}, tracked by this repository`;
+        else if (worktreeContent) reason = `${where}, inside the worktree so Git will track it on the next add (add it to .gitignore or .git/info/exclude to manage it locally)`;
         else if (localScope && !inside) reason = `${where}, outside this repository`;
         return {
             dir,
@@ -106,10 +117,34 @@ function trackedPath(repo, path) {
     }
 }
 
+// gitIgnored reports whether Git would ignore path (via .gitignore,
+// .git/info/exclude, or core.excludesfile). This is the opt-in that lets a team
+// keep a worktree hooks dir local: an excluded path will not be staged by the
+// next `git add`, so a dispatcher written there cannot leak machine-local
+// absolute paths into history. Used to decide whether a worktree hooksPath is
+// repository content in waiting (refuse) or intentionally local (install). A
+// Git that cannot answer counts as NOT ignored, so we fail closed and refuse
+// (the safer side for a leak that writes machine paths into shared history).
+function gitIgnored(repo, path) {
+    try {
+        execFileSync(
+            'git',
+            ['check-ignore', '--quiet', '--', String(path)],
+            { cwd: repo.root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS },
+        );
+        // git check-ignore exits 0 when the path IS ignored, 1 when it is not.
+        return true;
+    } catch (error) {
+        // Non-zero exit means "not ignored" (exit 1) or "git failed". Either way,
+        // treat as not-ignored so the worktree-content guard stays on.
+        return false;
+    }
+}
+
 function canonicalPath(path) {
     let current = resolve(path);
     const tail = [];
-    for (;;) {
+    for (; ;) {
         try {
             return resolve(realpathSync(current), ...tail);
         } catch (error) {
@@ -631,9 +666,19 @@ function hookScript(name, cmd, cliPath, chainedPath) {
 ) || exit $?
 `
         : '';
+    // The chained predecessor is sourced in a subshell, not exec'd. Git runs the
+    // dispatcher with $0 set to the original hook path (the dispatcher replaced
+    // it in place), and a subshell inherits $0, so sourcing lets the predecessor
+    // see the original $0 and resolve $(dirname "$0") to its real directory —
+    // the pattern husky and vanilla .githooks hooks use to find sibling scripts.
+    // Exec'ing "$CHAINED" would set the predecessor's $0 to the backup path and
+    // break that resolution. Sourcing runs the predecessor in this dispatcher's
+    // shell (/bin/sh -p), so its shebang is honoured only for sh-compatible
+    // scripts; bash-only predecessors are out of scope. exit inside the
+    // predecessor exits the subshell and propagates via || exit $?.
     const chainedInvocation = name === 'reference-transaction'
-        ? `  printf '%s\\n' "$AIMHOOMAN_REF_UPDATES" | "$CHAINED" "$@" || exit $?`
-        : `  "$CHAINED" "$@" || exit $?`;
+        ? `  printf '%s\\n' "$AIMHOOMAN_REF_UPDATES" | ( . "$CHAINED" ) || exit $?`
+        : `  ( . "$CHAINED" ) || exit $?`;
     const aimCommand = name === 'commit-msg'
         ? 'commitmsg "$1" --tree "$AIMHOOMAN_COMMIT_TREE"'
         : name === 'reference-transaction'

package/src/gitx.mjs

@@ -177,6 +177,16 @@ export function stagedPaths(repo) {
     ], repo.root));
 }
 
+// stagedTreeSha writes the index to a tree object and returns its SHA, the same
+// value `git write-tree` produces in the commit-msg dispatcher. Used by the
+// pre-commit/commit-msg marker dedup (W5): pre-commit records this sha when it
+// scans clean, and commit-msg skips its duplicate tree scan when the sha still
+// matches. The index is unchanged between the two hooks in a normal commit, so
+// the sha is stable; any staging mutation invalidates it automatically.
+export function stagedTreeSha(repo) {
+    return gitStr(['write-tree'], repo.root);
+}
+
 // Unmerged index entries have only stages 1-3 and are omitted by the ordinary
 // cached diff. Expose their paths so callers cannot mistake a conflicted index
 // for a complete, clean staged snapshot.

package/src/hook.mjs

@@ -443,6 +443,20 @@ function hookPreToolUse(input) {
             : '--no-verify or shell indirection bypasses the pre-commit guard';
     const unmodelledPrefixReason =
         'aimhooman cannot verify the final staged snapshot or Git hooks after an earlier unmodelled command; run that command separately, then retry the commit.';
+    // A pipeline whose sink can execute code (a shell, an interpreter fed on
+    // stdin) can hide a commit or run arbitrary commands, and there is no argv
+    // to read a --no-verify out of. The earlier message reused the commit text
+    // above, which told a developer to "retry the commit" for a command that
+    // was not a commit at all — this names the real shape instead. The message
+    // is conditional on whether a pipe is actually present: opaque syntax
+    // without a pipe (a subshell, a brace group, command substitution) should
+    // not tell the developer to "drop the `| bash` segment" on a command that
+    // has no `|`.
+    const opaquePipelineReason = commit
+        ? unmodelledPrefixReason
+        : hasUnquotedPipe(executorCommand)
+            ? 'aimhooman cannot prove this pipeline is read-only: a shell or code-executing segment can hide a commit or run arbitrary commands. Drop that segment (for example the `| bash`) and run the pieces separately.'
+            : 'aimhooman cannot prove this command is read-only: it uses shell syntax (a subshell, command substitution, script-feed redirect, background job, or brace group) that can hide a commit or run arbitrary commands. Run the pieces separately.';
     const blocks = [];
     // potentialCommit treats a command as leading to a commit. uncertainShell
     // was too broad: it flagged any pipe, so a benign read-only pipeline
@@ -522,7 +536,7 @@ function hookPreToolUse(input) {
         if (profile !== 'strict' && potentialCommit && prefixHookBypass) {
             return emitDecision(
                 'deny',
-                unmodelledPrefixReason,
+                opaquePipelineReason,
             );
         }
         // Nothing found and nothing to object to, so emit nothing and leave the
@@ -552,7 +566,7 @@ function hookPreToolUse(input) {
     if (profile !== 'strict' && potentialCommit && prefixHookBypass) {
         return emitDecision(
             'deny',
-            unmodelledPrefixReason,
+            opaquePipelineReason,
         );
     }
     const guarded = repo && !bypassed && installedHooks(repo).includes('pre-commit');
@@ -861,6 +875,41 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                     environmentRisk,
                     'git',
                 );
+                // A passthrough prefix (time, timeout, nice, ...) execs the inner
+                // command with the same argv in the same place, so it cannot
+                // inject a flag or hide a --no-verify the way eval/sudo/bash -c
+                // can. Re-parse the inner command from its `git` token so the
+                // commit is judged exactly as if the prefix were not there
+                // (--no-verify still denied, a clean commit still allowed). The
+                // carve-out only applies when nothing else injects risk;
+                // otherwise the wrapper falls back to the closed uncertain path.
+                const passthroughExecutable = PASSTHROUGH_PREFIX_EXECUTORS.has(shellExecutable(g0))
+                    && environmentRisk.length === 0
+                    && !targetEnvironmentRisk
+                    && !indirectTargetEnvironmentRisk
+                    && !commandTargetUncertain
+                    && !indirect.targetUncertain
+                    && !indirect.pathDialectUncertain
+                    && !commandPathDialectUncertain
+                    && !unwrapped.uncertain
+                    ? shellExecutable(g0)
+                    : null;
+                if (passthroughExecutable) {
+                    const gitIndex = toks.findIndex((token, index) => (
+                        index > 0 && isGitExecutable(token.replace(/^\(+/, '').replace(/\)+$/, ''))
+                    ));
+                    if (gitIndex > 0) {
+                        const inner = parseGit(toks.slice(gitIndex).join(' '), unwrapped.cwd);
+                        commit ||= inner.commit;
+                        noVerify ||= inner.noVerify;
+                        bypassHooks ||= inner.bypassHooks;
+                        uncertainShell ||= inner.uncertainShell;
+                        addPaths.push(...inner.addPaths);
+                        commands.push(...inner.commands);
+                        sawAdd ||= inner.addPaths.length > 0;
+                        continue;
+                    }
+                }
                 commit = true;
                 uncertainShell = true;
                 commands.push({
@@ -883,7 +932,8 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                         || indirect.pathDialectUncertain,
                 });
             }
-            if (!READ_ONLY_SHELL_COMMANDS.has(basename(g0))) {
+            if (!READ_ONLY_SHELL_COMMANDS.has(basename(g0))
+                && !PASSTHROUGH_PREFIX_EXECUTORS.has(shellExecutable(g0))) {
                 prefixIndexMutationRisk ||= commandMayReplaceIndex(toks, unit.text);
                 prefixHooksRisk ||= commandMayTouchHooks(toks, unit.text);
                 prefixRisk = true;
@@ -1917,7 +1967,18 @@ function hasUncertainShellSyntax(command) {
             quote = char;
             continue;
         }
-        if (char === '`' || char === '(' || char === ')' || char === '{' || char === '}' || char === '<' || char === '>') return true;
+        // `{`/`}` are ambiguous: brace expansion (`{a,b}`, `{owner}`, `x.{js,ts}`)
+        // is argument-level and cannot hide a commit or feed code into a pipe
+        // sink, while a brace group (`{ list; }`) is control flow and can. Brace
+        // expansion touches the surrounding word (no separator before the `{`, no
+        // space/`;` after it); a brace-group `{` stands as its own token. PowerShell
+        // `{ }` script blocks are handled separately via the non-POSIX executor
+        // path, so this POSIX distinction never loosens that.
+        if (char === '{' || char === '}') {
+            if (isBraceGroupToken(command, i)) return true;
+            continue;
+        }
+        if (char === '`' || char === '(' || char === ')' || char === '<' || char === '>') return true;
         if (char === '|' && command[i + 1] !== '|') return true;
         if (char === '&' && command[i + 1] !== '&' && command[i - 1] !== '&') return true;
     }
@@ -1927,6 +1988,57 @@ function hasUncertainShellSyntax(command) {
     });
 }
 
+// BRACE_GROUP_LEAD chars may appear immediately before a brace-group token.
+// `:` is included so `cmd: { ... }` is handled, though it is not POSIX shell.
+const BRACE_GROUP_LEAD = new Set(['', ' ', '\t', '\n', ';', '&', '|', '(', ')']);
+// BRACE_GROUP_OPEN_TRAIL chars may follow a `{` that opens a brace group: the
+// reserved word `{` must be followed by whitespace, `;`, or end of string.
+const BRACE_GROUP_OPEN_TRAIL = new Set([' ', '\t', '\n', ';', '']);
+// BRACE_GROUP_CLOSE_LEAD chars precede a `}` that closes a brace group: the
+// closer must follow `;` or whitespace (the end of the group body).
+const BRACE_GROUP_CLOSE_LEAD = new Set([' ', '\t', '\n', ';', '']);
+
+// isBraceGroupToken reports whether `{`/`}` at position i in command is a
+// POSIX brace-group token (reserved-word `{` or its closer `}`) rather than a
+// brace-expansion character. Brace expansion `{a,b}` / `{owner}` / `x.{js,ts}`
+// is argument-level and cannot feed code into a pipe sink or run a subcommand,
+// so it must not make a command "opaque". A brace group `{ list; }` is
+// control flow and can, so it stays opaque. PowerShell script blocks are
+// handled by the non-POSIX executor path, not here.
+function isBraceGroupToken(command, i) {
+    const char = command[i];
+    const prev = command[i - 1] ?? '';
+    const next = command[i + 1] ?? '';
+    if (char === '{') {
+        if (!BRACE_GROUP_LEAD.has(prev)) return false;
+        if (!BRACE_GROUP_OPEN_TRAIL.has(next)) return false;
+        return true;
+    }
+    // `}` closer: must follow `;` or whitespace.
+    return BRACE_GROUP_CLOSE_LEAD.has(prev);
+}
+
+// hasUnquotedPipe reports whether command contains a pipe `|` that is not
+// `||`, outside of any quote. Used to decide whether the opaque-pipeline deny
+// message should mention a pipe at all — the original message always named
+// `| bash` even for commands with no pipe.
+function hasUnquotedPipe(command) {
+    let quote = '';
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        if (escaped) { escaped = false; continue; }
+        if (char === '\\' && quote !== "'") { escaped = true; continue; }
+        if (quote) {
+            if (char === quote) quote = '';
+            continue;
+        }
+        if (char === "'" || char === '"') { quote = char; continue; }
+        if (char === '|' && command[i + 1] !== '|') return true;
+    }
+    return false;
+}
+
 function shellUnits(s) {
     const out = [];
     let segment = '';
@@ -2102,7 +2214,14 @@ function containsOpaquePipeLexeme(command) {
             continue;
         }
         if (char === "'" || char === '"') { quote = char; continue; }
-        if (char === '`' || char === '(' || char === ')' || char === '{' || char === '}') return true;
+        // Brace expansion (`{a,b}`, `{owner}`) is not opaque: it only expands to
+        // arguments for the same command and cannot feed code into a pipe sink.
+        // Brace groups (`{ list; }`) are opaque. See isBraceGroupToken.
+        if (char === '{' || char === '}') {
+            if (isBraceGroupToken(command, i)) return true;
+            continue;
+        }
+        if (char === '`' || char === '(' || char === ')') return true;
         if (char === '$' && (next === '(' || next === '{')) return true;
         if (char === '<' || char === ';') return true;
         if (char === '&' && next !== '&' && prev !== '&' && prev !== '>' && prev !== '<') return true;
@@ -2687,6 +2806,19 @@ const UNCERTAIN_TARGET_INDIRECT_EXECUTORS = new Set([
     'systemd-run', 'unshare', 'watch', 'wsl', 'xargs',
 ]);
 
+// Passthrough prefixes exec the inner command verbatim: the same argv, the same
+// cwd, the same target. `time`, `timeout`, `nice`, `ionice` and friends only
+// measure or schedule — they cannot inject a flag, rewrite the command line, or
+// hide a --no-verify the way eval/sudo/bash -c can. An indirect commit seen
+// through one of these is therefore treated as direct, so `time git commit` is
+// judged like `git commit` instead of being refused as opaque indirection. The
+// carve-out only applies when nothing else is risky (no environment override,
+// no uncertain target); otherwise the wrapper falls back to the closed path.
+const PASSTHROUGH_PREFIX_EXECUTORS = new Set([
+    'time', 'timeout', 'nice', 'ionice', 'chrt', 'taskset', 'numactl',
+    'stdbuf', 'setsid', 'nohup', 'prlimit', 'faketime',
+]);
+
 function indirectCommitInvocation(words, initialCwd) {
     if (!words.length) return false;
     const executable = shellExecutable(words[0]);

package/src/report.mjs

@@ -1,5 +1,12 @@
 // Human-facing and JSON reporting for aimhooman findings.
 
+// HUMAN_FINDING_CAP bounds the per-invocation stderr output. A scan that fires
+// many findings of the same rule (a vendored OpenSSL corpus can produce 99) used
+// to emit hundreds of near-identical lines with no truncation marker. The cap
+// prints the first HUMAN_FINDING_CAP finding blocks, then a single summary line
+// for the rest. The JSON report (aimhooman review / --json) is never capped.
+const HUMAN_FINDING_CAP = 20;
+
 export function human(findings, tone) {
     if (!findings.length) return '';
     let out = tone === 'professional' ? '\n' : '\nnot very hooman.\n\n';
@@ -8,6 +15,13 @@ export function human(findings, tone) {
     for (const f of findings) {
         if (f.decision === 'block') block += 1;
         else if (f.decision === 'review') review += 1;
+    }
+    // Render findings in order up to the cap, then collapse the rest into one
+    // summary line. Keeps the first findings fully visible (the actionable ones)
+    // while bounding stderr for repeated-rule scans.
+    const shown = findings.slice(0, HUMAN_FINDING_CAP);
+    const hidden = findings.length - shown.length;
+    for (const f of shown) {
         const loc = f.path
             ? `${visible(f.path)}${f.line ? `:${f.line}` : ''}`
             : (f.line ? `commit message line ${f.line}` : '');
@@ -18,10 +32,21 @@ export function human(findings, tone) {
         if (f.text && f.text.trim()) {
             out += `       > ${isSensitive(f) ? '[redacted]' : visible(f.text.trim())}\n`;
         }
-        if (f.remediation?.length) out += `       fix: ${f.remediation[0]}\n`;
+        // Render the whole remediation array, not just the first entry. Several
+        // rules carry a second line (e.g. "rotate the key if it was ever exposed")
+        // that the previous single-index render dropped silently.
+        for (const remedy of (f.remediation || [])) {
+            out += `       fix: ${remedy}\n`;
+        }
         out += '\n';
     }
-    out += `${findings.length} findings: ${block} block, ${review} review\n`;
+    if (hidden > 0) {
+        out += `… and ${hidden} more ${hidden === 1 ? 'finding' : 'findings'} (run 'aimhooman review' for the full list)\n\n`;
+    }
+    const findingWord = findings.length === 1 ? 'finding' : 'findings';
+    const blockWord = block === 1 ? 'block' : 'blocks';
+    const reviewWord = review === 1 ? 'review' : 'reviews';
+    out += `${findings.length} ${findingWord}: ${block} ${blockWord}, ${review} ${reviewWord}\n`;
     return out;
 }
 

package/src/scan-session.mjs

@@ -86,6 +86,11 @@ export function scanEntries(repo, engine, entries, options = {}) {
     stats.objects_read = batch.objects.size;
     for (const failure of batch.failures) increment(stats.skipped, failure.reason);
 
+    // Precompute changed-line ranges for all text candidates in ONE batched
+    // diff per (commit, parent) pair (W4 + perf). A missing path key means
+    // "scan the whole blob" (staged/snapshot/root entries, or a diff failure).
+    const lineRanges = collectLineRanges(repo, candidates);
+
     const findings = [];
     for (const entry of candidates) {
         const blob = batch.objects.get(entry.oid);
@@ -110,7 +115,9 @@ export function scanEntries(repo, engine, entries, options = {}) {
             });
         } else {
             stats.files_scanned += 1;
-            matched = engine.checkContent(entry.path, blob.toString('utf8'));
+            const ranges = lineRanges.get(entry.path);
+            matched = engine.checkContent(entry.path, blob.toString('utf8'),
+                ranges && ranges.length ? { lineRanges: ranges } : {});
         }
         stats.findings_total += matched.length;
         for (const finding of matched) {
@@ -236,3 +243,72 @@ function isBinary(buffer) {
     for (let index = 0; index < length; index++) if (buffer[index] === 0) return true;
     return false;
 }
+
+// collectLineRanges builds a Map<path, ranges[]> for all entries whose content
+// scan can be narrowed to changed hunks (W4, bug 12d-F1). It batches the work
+// into ONE `git diff --unified=0` per (commit, parent) pair rather than one diff
+// per file — a commit touching 50 files would otherwise pay ~650ms of per-file
+// git subprocess startup. Entries are grouped by their first parent; a normal
+// commit (single parent) is a single diff call covering every file.
+//
+// Entries without commit/parents (tracked snapshots, staged views, root
+// commits) are omitted from the map; the caller treats a missing key as "scan
+// the whole blob" — the safe side for a secret scanner is to scan MORE, not
+// less, so a failure to compute hunks falls back to the pre-W4 behaviour.
+function collectLineRanges(repo, entries) {
+    // Group text-candidate entries by their first parent to batch the diffs.
+    // Key by `${commit}\0${parent}` so a merge with multiple parents produces
+    // one diff per distinct (commit, parent) pair.
+    const groups = new Map();
+    for (const entry of entries) {
+        if (entry.type === 'blob' && !entry.commit) continue; // staged/snapshot: no diff
+        const parent = entry.parents?.[0];
+        if (!entry.commit || !parent) continue; // root commit or no parent: whole-blob
+        const key = `${entry.commit}\0${parent}`;
+        if (!groups.has(key)) groups.set(key, { commit: entry.commit, parent });
+    }
+    const byPath = new Map();
+    for (const { commit, parent } of groups.values()) {
+        let output;
+        try {
+            output = execFileSync('git', [
+                '-c', 'core.quotePath=false',
+                'diff', '--unified=0', '--no-color', '--no-prefix',
+                parent, commit,
+            ], {
+                cwd: repo.root,
+                env: gitEnvironment(),
+                encoding: 'utf8',
+                timeout: GIT_TIMEOUT_MS,
+                maxBuffer: 16 * 1024 * 1024,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        } catch {
+            continue; // diff failed → those paths stay absent → whole-blob scan
+        }
+        // Parse the multi-file diff: track the current file from the `+++ path`
+        // line, and attribute each `@@` hunk header to it. core.quotePath=false
+        // keeps spaces and non-ASCII paths literal so they match entry.path (which
+        // comes from git diff --raw -z, also unquoted). Paths containing newlines
+        // are not handled, but they fall back to a whole-blob scan (safe).
+        let currentPath = null;
+        for (const line of output.split('\n')) {
+            // With --no-prefix the +++ line is `+++ path` (no b/ prefix).
+            const plusMatch = /^\+\+\+ (.+)$/.exec(line);
+            if (plusMatch) {
+                currentPath = plusMatch[1] === '/dev/null' ? null : plusMatch[1];
+                continue;
+            }
+            const match = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+            if (!match || !currentPath) continue;
+            const start = Number(match[1]);
+            const count = match[2] === undefined ? 1 : Number(match[2]);
+            if (start === 0 || count === 0) continue; // pure deletion, no new content
+            const range = { start, end: start + count - 1 };
+            const existing = byPath.get(currentPath);
+            if (existing) existing.push(range);
+            else byPath.set(currentPath, [range]);
+        }
+    }
+    return byPath;
+}