@rmyndharis/aimhooman 0.1.8 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
             "name": "aimhooman",
             "source": "./",
             "description": "Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
-            "version": "0.1.8",
+            "version": "0.2.0",
             "license": "MIT",
             "keywords": [
                 "git",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "aimhooman",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "description": "AI works. Hoomans ship. Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "aimhooman",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "description": "AI works. Hoomans ship. Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman maintainers",

package/CHANGELOG.md

@@ -5,6 +5,93 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-07-19
+
+This release works through the findings of the cross-ecosystem field test
+(8 upstream clones, 6 language loops, a local bare remote, and a private
+GitHub sandbox). The headline: `allow` no longer says yes when it means no —
+a path allow on a file whose content holds a secret is refused up front,
+with the working escape hatch named in the same breath.
+
+### Fixed
+
+- Tracked-tree scans (`audit`, `check --tracked`, `init --grandfather-secrets`)
+  no longer die with `spawnSync git EPIPE` on a partial clone of a repository
+  with submodule pins. A gitlink names a commit of another repository, so
+  asking `cat-file` about it triggered a promisor fetch that aborted the
+  whole metadata batch ("not our ref"). Gitlinks now skip the metadata read;
+  their type comes from the mode. Found by the OpenSSL field run, whose 11
+  submodule pins made the grandfather flag seed zero allows.
+- `init --grandfather-secrets` now runs its one-shot tracked scan with the
+  total-byte budget raised to the env cap and the finding budget raised to
+  100,000. The commit-time defaults (64 MiB, 1,000 findings) silently missed
+  fixtures beyond them in exactly the large, fixture-heavy repositories the
+  flag exists for; the per-file budget and an explicit env override still
+  apply.
+- `aimhooman allow <path>` on a file whose content matches a secret rule
+  (e.g. a private key inside an ordinary-looking filename) no longer reports
+  `allowed` while the commit stays blocked. The guard now runs the engine's
+  secret content rules over the file's bytes, refuses the allow, and points
+  at `--scope secret-path`. Files over the scan budget or unreadable skip
+  the check; the commit-time scanner still fails closed on those.
+- The scan-incomplete summary now names what was skipped
+  (`skipped: size-limit=1 file`) instead of `(size-limit=1)`, which read as
+  a one-byte budget rather than a count of files.
+
+### Added
+
+- `aimhooman init --grandfather-secrets`: after a successful init, scan the
+  tracked tree once and write a `--scope secret-path` allow for every path
+  already tracking secret-looking material (test certs, sample keys). New
+  secrets stay blocked; only paths found in that scan are allowed. A failed
+  or incomplete scan warns without failing the init.
+- Provider-token findings name the provider in human output
+  (`A provider access token (GitHub) must not enter Git history.`), so the
+  developer knows which credential to revoke. The token itself stays
+  redacted; the JSON report is unchanged.
+- Secret content rules now carry a remediation line naming the fixture
+  escape hatch: `aimhooman allow <path> --scope secret-path --reason
+  "test fixture"`.
+- The pre-commit hook now names locally-ignored AI artifacts once per set
+  change (`3 AI artifact(s) present locally are kept out of commits: ...`).
+  The prevention layer keeps them out of `git status`, which also kept their
+  exclusion silent: a `git add .` never told the developer the chat log did
+  not make the commit. The worktree walk is pathspec-pruned to the managed
+  exclude patterns, so it costs ~15ms; informational only, it never changes
+  an exit code.
+- The reference-transaction veto now notes that the rejected commit object
+  remains in the local object store — collected by `git gc --prune=now` when
+  nothing else references it — so a secret payload is not mistaken for gone.
+
+### Changed
+
+- Repeated findings of the same rule print the remediation once, then
+  `fix: as above for <rule id>`, instead of reprinting an identical fix
+  block for every hit.
+- `init` output now prints `undo: aimhooman uninstall` and notes that known
+  AI artifacts are ignored locally (`git status --ignored` shows them).
+
+### Performance
+
+- `openRepo` resolves the repository in one `git rev-parse` call instead of
+  three; every hook spawn pays this, so it was the cheapest milliseconds on
+  the commit path. The common-dir answer is resolved against the invoking
+  cwd and canonicalized, preserving the previous spelling on symlinked
+  paths (macOS `/tmp`), and a path containing a newline falls back to one
+  flag per call.
+- The reference-transaction dispatcher exits before the Node spawn for a
+  `prepared` transaction that moves neither a branch nor HEAD (ORIG_HEAD,
+  tags, remote-tracking refs). Such payloads carry nothing `refcheck`
+  scans — but the skip first proves the four dispatchers are still
+  installed, so a hook manager wiping them mid-operation is answered with
+  a stop, not silence. An ordinary commit's hook time drops by roughly a
+  third in the field measurement (982ms → 649ms).
+- Installed Git hook shims export `NODE_COMPILE_CACHE` pointing at a
+  per-install directory under the state dir (removed by
+  `uninstall --purge-state`), shaving the module parse/compile cost off
+  each hook spawn. An unwritable cache dir degrades to the old cold start,
+  never to a hook failure.
+
 ## [0.1.8] - 2026-07-18
 
 This release works through the findings of the real-world scenario report

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/github/actions/workflow/status/rmyndharis/aimhooman/test.yml?branch=main&label=CI" alt="CI">
-  <img src="https://img.shields.io/badge/version-v0.1.8-blue" alt="v0.1.8">
+  <img src="https://img.shields.io/badge/version-v0.2.0-blue" alt="v0.2.0">
   <img src="https://img.shields.io/badge/node-%E2%89%A522.8-339933?logo=node.js&logoColor=white" alt="Node 22.8+">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
   <img src="https://img.shields.io/badge/license-MIT-111111" alt="MIT">
@@ -130,6 +130,7 @@ Guard a repository:
 
 ```sh
 aimhooman init        # git hooks + local excludes; normally no worktree files
+aimhooman init --grandfather-secrets # also allow --scope secret-path for every secret already tracked (fixtures); new secrets stay blocked
 aimhooman status
 aimhooman uninstall   # restore hooks/excludes; keep local policy state
 aimhooman uninstall --purge-state # also delete common Git-directory state

package/bin/aimhooman.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { chmodSync, lstatSync, readdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,6 +10,7 @@ import { exitCode, human, jsonReport, visible } from '../src/report.mjs';
 import {
     GitRevisionError,
     gitConfig,
+    ignoredByPatterns,
     introducedCommits,
     openRepo,
     readCommitPath,
@@ -20,10 +22,11 @@ import {
     withIndexFromTree,
 } from '../src/gitx.mjs';
 import { loadConfig, loadOverrides, loadProjectPolicy, normalizeOverrideTarget, saveConfig, saveOverrides } from '../src/state.mjs';
-import { applyExclude, inspectExclude, patternsForRules, removeExclude } from '../src/exclude.mjs';
+import { applyExclude, inspectExclude, managedPatterns, patternsForRules, removeExclude } from '../src/exclude.mjs';
 import { effectiveHooksDir, hookDiagnostics, installHooks, installGlobalHooks, uninstallGlobalHooks, globalHooksDir, installedHooks, remainingDispatchers, uninstallHooks, unrestoredChainedBackups } from '../src/githooks.mjs';
 import { ArgumentError, parseArguments } from '../src/args.mjs';
 import { engineForPolicy, scanGitTarget, scanMessage } from '../src/scan-target.mjs';
+import { DEFAULT_SCAN_LIMITS } from '../src/scan-session.mjs';
 import { resolvePolicy } from '../src/policy-resolver.mjs';
 import { atomicWrite, withLock } from '../src/atomic-write.mjs';
 import { commitParents, resolveCommit } from '../src/history-scan.mjs';
@@ -214,8 +217,11 @@ function emitDiagnostics(diagnostics = []) {
 
 function incompleteMessage(scan) {
     const reasons = scan.stats?.skipped || {};
+    // Each count is how many items were skipped, not the limit that fired:
+    // "(size-limit=1)" read as a one-byte budget. Name the noun so the number
+    // cannot be mistaken for the budget it tripped.
     const skipped = Object.entries(reasons)
-        .map(([reason, count]) => `${reason}=${count}`)
+        .map(([reason, count]) => `${reason}=${count} ${skipCountNoun(reason, count)}`)
         .join(', ');
     // Every other reason is a size or budget the caller can shrink. A pack that
     // will not compile is not, and the warning above already names the file and
@@ -229,7 +235,7 @@ function incompleteMessage(scan) {
         : budgeted
             ? 'reduce the target, or raise AIMHOOMAN_MAX_FILE_BYTES / AIMHOOMAN_MAX_TOTAL_BYTES, and retry'
             : 'reduce the target or limits and retry';
-    let message = `aimhooman: scan incomplete${skipped ? ` (${skipped})` : ''}; ${hint}\n`;
+    let message = `aimhooman: scan incomplete${skipped ? ` (skipped: ${skipped})` : ''}; ${hint}\n`;
     const skippedPaths = scan.stats?.skippedPaths || {};
     const pathLines = [];
     for (const [reason, entries] of Object.entries(skippedPaths)) {
@@ -242,6 +248,17 @@ function incompleteMessage(scan) {
     return message + pathLines.join('');
 }
 
+// Most skip reasons tally files; the three below tally something else, so the
+// noun travels with the reason instead of reading "local-pack-error=1 file".
+function skipCountNoun(reason, count) {
+    const noun = {
+        'finding-limit': 'finding',
+        'local-input-limit': 'input',
+        'local-pack-error': 'pack',
+    }[reason] || 'file';
+    return `${noun}${count === 1 ? '' : 's'}`;
+}
+
 function formatBytes(bytes) {
     if (bytes == null || bytes < 0) return '?';
     if (bytes < 1024) return `${bytes} B`;
@@ -371,6 +388,38 @@ function precommitCleanMatches(repo, treeSha, profile) {
         && marker.profile === profile;
 }
 
+// F-E1: the prevention layer keeps AI artifacts out of `git status`, which
+// also keeps their exclusion silent — a `git add .` never tells the developer
+// the chat log did not make the commit. Name the artifacts once per set
+// change. The worktree walk is pathspec-pruned to the anchored managed
+// patterns (~15ms; a bare ignored-listing costs ~150ms on a large tree), so
+// `**/`-prefixed duplicates are skipped: nested artifacts still get excluded,
+// they just do not get the notice. Informational only — it must never change
+// an exit code, so every failure inside degrades to silence.
+const IGNORED_NOTICE_VERSION = 1;
+function noticeIgnoredArtifacts(repo) {
+    try {
+        const patterns = managedPatterns(repo.excludeFile)
+            .filter((pattern) => !pattern.startsWith('**/'));
+        if (!patterns.length) return;
+        const paths = ignoredByPatterns(repo, patterns).sort();
+        if (!paths.length) return;
+        const hash = createHash('sha256').update(paths.join('\0')).digest('hex');
+        const statePath = join(repo.stateDir, 'ignored-notice.json');
+        let previous = null;
+        try { previous = JSON.parse(readFileSync(statePath, 'utf8')); } catch { /* first run or corrupt state */ }
+        if (previous?.version === IGNORED_NOTICE_VERSION && previous.hash === hash) return;
+        writeFileSync(statePath, JSON.stringify({ version: IGNORED_NOTICE_VERSION, hash }));
+        const shown = paths.slice(0, 5);
+        const more = paths.length - shown.length;
+        process.stderr.write(
+            `aimhooman: ${paths.length} AI artifact(s) present locally are kept out of commits: `
+            + `${shown.map(visible).join(', ')}${more ? `, and ${more} more` : ''} `
+            + "(they stay on disk; 'git status --ignored' lists them; shown once per set change)\n"
+        );
+    } catch { /* informational only */ }
+}
+
 function cmdPrecommit(args) {
     parseNoArguments(args);
     const repo = tryRepo();
@@ -403,6 +452,7 @@ function cmdPrecommit(args) {
         // sha is stable. A missing/stale/mismatched marker makes commit-msg
         // fall back to the full scan, so this is purely an optimization.
         recordPrecommitClean(repo, profile);
+        noticeIgnoredArtifacts(repo);
         return profile === 'strict' && reviews.length ? 11 : 0;
     }
     if (profile === 'strict') {
@@ -479,6 +529,7 @@ function cmdPrecommit(args) {
     // not. The request was to commit the artifact, not to stamp the history with
     // its message and no content.
     if (emptied) return 10;
+    if (scan.complete) noticeIgnoredArtifacts(repo);
     return scan.complete ? 0 : 31;
 }
 
@@ -746,6 +797,15 @@ function cmdRefcheck(args) {
             process.stderr.write(human(scan.findings, tone()));
             if (!scan.complete) process.stderr.write(incompleteMessage(scan));
             process.stderr.write(`aimhooman: proposed commit ${revision} was rejected before refs changed\n`);
+            // The vetoed commit stays in the object store: the ref never
+            // moved, but the bytes — including whatever triggered the block —
+            // are still on disk. Whether gc collects it depends on other refs,
+            // so phrase the cleanup as conditional; rotating an exposed secret
+            // stays the operator's call either way.
+            process.stderr.write(
+                `aimhooman: note: the rejected commit object remains in the local object store; `
+                + "if nothing else references it, 'git gc --prune=now' removes it when you are done inspecting\n"
+            );
             return code;
         }
     }
@@ -840,8 +900,9 @@ function cmdInit(args) {
             profile: { names: ['--profile'], type: 'string', choices: [...PROFILES] },
             global: { names: ['--global'], type: 'boolean' },
             yes: { names: ['--yes'], type: 'boolean' },
+            grandfatherSecrets: { names: ['--grandfather-secrets'], type: 'boolean' },
         },
-        conflicts: [['profile', 'global']],
+        conflicts: [['profile', 'global'], ['grandfatherSecrets', 'global']],
         maxPositionals: 0,
     });
     if (rejectUnsupportedGit()) return 20;
@@ -926,7 +987,7 @@ function cmdInit(args) {
         console.error('aimhooman: not a git repository');
         return 30;
     }
-    return withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
+    const code = withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
         let projectPolicy;
         try {
             projectPolicy = loadProjectPolicy(repo.root);
@@ -1014,11 +1075,77 @@ function cmdInit(args) {
         console.log(`aimhooman: initialised (profile: ${profile})`);
         console.log(`  state:    ${repo.stateDir}`);
         console.log(`  excludes: ${repo.excludeFile}`);
+        console.log(`  note:     known AI artifacts are now ignored locally; see them with 'git status --ignored'`);
         if (rep.installed.length) console.log(`  hooks:    ${rep.installed.join(', ')}`);
         if (rep.chained.length) console.log(`  chained:  ${rep.chained.join(', ')} (existing hooks preserved)`);
         for (const warning of rep.warnings) console.log(`  warning:  ${warning}`);
+        console.log('  undo:     aimhooman uninstall');
         return 0;
     }, LIFECYCLE_LOCK_OPTIONS);
+    if (code === 0 && options.grandfatherSecrets) grandfatherTrackedSecrets(repo);
+    return code;
+}
+
+// --grandfather-secrets: a repository that already tracks secret-looking
+// fixtures (test certs, sample keys) would see every commit touching one
+// blocked, and allowing each path by hand does not scale. After a successful
+// init, scan the tracked tree once and write a --scope secret-path allow for
+// every path with a secret finding. The posture for NEW files is unchanged —
+// only paths found in this scan get an allow, so a secret added after init is
+// still blocked. A failed or incomplete scan never fails the init itself: the
+// guard is already active by then, so the gap is reported as a warning.
+function grandfatherTrackedSecrets(repo) {
+    let scan;
+    try {
+        // Commit-time budgets exist for latency, but a grandfather scan that
+        // stops at the default 64 MiB total or 1,000 findings silently misses
+        // fixtures in exactly the large, fixture-heavy repositories it exists
+        // for (OpenSSL tracks ~200 MiB and its 279 key files produce more
+        // than a thousand PEM findings). This is a one-shot, operator-invoked
+        // scan of the operator's own repository, so the defaults here are the
+        // same cap an env raise could reach plus a generous finding budget;
+        // the per-file budget and an explicit env override still apply.
+        scan = scanGitTarget(repo, {
+            kind: 'tracked',
+            limits: { maxTotalBytes: MAX_SCAN_LIMIT_BYTES, maxFindings: 100_000, ...scanLimits() },
+        });
+    } catch (error) {
+        console.error(`aimhooman: warning: grandfather scan failed (${error.message}); no pre-existing secret paths were allowed`);
+        return;
+    }
+    if (!scan.complete) {
+        console.error('aimhooman: warning: tracked scan was incomplete, so the grandfathered set may be partial; allow the remaining paths with --scope secret-path');
+    }
+    const paths = [...new Set(scan.findings
+        .filter((finding) => finding.category === 'secret' && finding.path)
+        .map((finding) => finding.path))].sort();
+    if (!paths.length) {
+        console.log('aimhooman: no tracked secret findings to grandfather');
+        return;
+    }
+    const { engine } = newEngineWithDiagnostics('clean', repo.stateDir);
+    const added = withLock(join(repo.stateDir, 'overrides.json.lock'), () => {
+        const ov = loadOverrides(repo.stateDir);
+        let count = 0;
+        for (const path of paths) {
+            const entry = {
+                target: path,
+                scope: 'secret-path',
+                reason: 'pre-existing tracked fixture (grandfathered at init)',
+                actor: gitConfig(repo.root, 'user.email'),
+                at: new Date().toISOString(),
+            };
+            const sameAllow = (candidate) => (
+                candidate.target === path && effectiveOverrideScope(candidate, engine) === 'secret-path'
+            );
+            if (ov.allow.some(sameAllow)) continue;
+            ov.allow = upsert(ov.allow, entry, sameAllow);
+            count += 1;
+        }
+        saveOverrides(repo.stateDir, ov);
+        return count;
+    });
+    console.log(`aimhooman: grandfathered ${added} tracked secret path(s) with --scope secret-path allows; new files with secrets are still blocked`);
 }
 
 function cmdStatus(args) {
@@ -1131,6 +1258,25 @@ function cmdExplain(args) {
     return 0;
 }
 
+// The content half of the secret-allow guard in cmdOverride: run the engine's
+// own secret-category content rules over the target's bytes. Files over the
+// scanner's per-file budget, unreadable paths, and non-regular files skip it —
+// this guard is a UX safety net against an allow that would report success yet
+// leave the block in place, and the commit-time scanner still fails closed on
+// whatever was not checked here.
+function fileContentMatchesSecret(engine, repo, target) {
+    let content;
+    try {
+        const file = join(repo.root, target);
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.size > DEFAULT_SCAN_LIMITS.maxFileBytes) return false;
+        content = readFileSync(file, 'utf8');
+    } catch {
+        return false;
+    }
+    return engine.checkContent(target, content, { categories: ['secret'] }).length > 0;
+}
+
 function cmdOverride(args, allow) {
     const verb = allow ? 'allow' : 'deny';
     const { options, positionals } = parseArguments(args, {
@@ -1162,9 +1308,13 @@ function cmdOverride(args, allow) {
     // allow: only --scope secret-path suppresses secret findings, deliberately,
     // so a local override cannot hide a possible leaked key. Without this check
     // a bare `allow .env.minimal` would report success but leave the block in
-    // place, which reads as a broken allow.
+    // place, which reads as a broken allow. checkPaths only evaluates path
+    // rules, so a content-shaped secret (a private key inside an
+    // ordinary-looking filename) would slip past it; the content half of the
+    // guard closes that hole.
     if (allow && scope !== 'secret-path'
-        && engine.checkPaths([target]).some((finding) => finding.category === 'secret')) {
+        && (engine.checkPaths([target]).some((finding) => finding.category === 'secret')
+            || fileContentMatchesSecret(engine, repo, target))) {
         throw new ArgumentError(
             `"${target}" matches a secret rule, so a ${scope} allow cannot silence it `
             + '(a local override must not hide a possible leaked key); '
@@ -1874,7 +2024,7 @@ function usage() {
     process.stdout.write(`aimhooman ${VERSION} - AI works. Hoomans ship.
 
 Usage:
-  aimhooman init [--profile clean|strict|compliance]
+  aimhooman init [--profile clean|strict|compliance] [--grandfather-secrets]
   aimhooman init --global --yes
   aimhooman check [--staged] [-m <file>|--message <file>] [--profile ...] [--json]
   aimhooman check --commit <rev> | --range <base>...<head> | --tracked

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "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/secrets.json

@@ -18,7 +18,8 @@
         },
         "reason": "Private-key material must not enter Git history.",
         "remediation": [
-            "Remove the key from the index, rotate it if exposed, and store it outside the repository."
+            "Remove the key from the index, rotate it if exposed, and store it outside the repository.",
+            "If this is an intentional fixture, run: aimhooman allow <path> --scope secret-path --reason \"test fixture\"."
         ]
     },
     {
@@ -40,7 +41,8 @@
         },
         "reason": "A service-account credential must not enter Git history.",
         "remediation": [
-            "Remove the credential from the index, rotate it if exposed, and use the service's secret store."
+            "Remove the credential from the index, rotate it if exposed, and use the service's secret store.",
+            "If this is an intentional fixture, run: aimhooman allow <path> --scope secret-path --reason \"test fixture\"."
         ]
     },
     {
@@ -63,7 +65,8 @@
         },
         "reason": "AWS credential material must not enter Git history.",
         "remediation": [
-            "Remove the credential from the index, rotate it if exposed, and use an AWS credential provider."
+            "Remove the credential from the index, rotate it if exposed, and use an AWS credential provider.",
+            "If this is an intentional fixture, run: aimhooman allow <path> --scope secret-path --reason \"test fixture\"."
         ]
     },
     {
@@ -86,7 +89,8 @@
         },
         "reason": "A provider access token must not enter Git history.",
         "remediation": [
-            "Remove the token from the index, revoke or rotate it, and use the provider's secret store."
+            "Remove the token from the index, revoke or rotate it, and use the provider's secret store.",
+            "If this is an intentional fixture, run: aimhooman allow <path> --scope secret-path --reason \"test fixture\"."
         ]
     }
 ]

package/src/exclude.mjs

@@ -74,6 +74,20 @@ export function inspectExclude(file, patterns) {
     return { installed: true, current: missing.length === 0 && actual.size === patterns.length, missing };
 }
 
+// managedPatterns returns the pattern lines currently inside the managed
+// block, or [] when the file or block is absent. Read-only.
+export function managedPatterns(file) {
+    const existing = readExclude(file, null);
+    if (existing === null) return [];
+    const range = managedRange(existing);
+    if (!range) return [];
+    return existing
+        .slice(range.start + BEGIN.length, range.end)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('#') && !line.startsWith('!'));
+}
+
 function stripBlock(s) {
     const range = managedRange(s);
     if (!range) return s;

package/src/githooks.mjs

@@ -651,6 +651,12 @@ function hookScript(name, cmd, cliPath, chainedPath) {
     const shellPathValue = hookPathForShell(pathValue);
     const nodeMetadata = Buffer.from(nodePath, 'utf8').toString('base64url');
     const pathMetadata = Buffer.from(pathValue, 'utf8').toString('base64url');
+    // chainedPath is <stateDir>/chained/<name> for a repository install and
+    // <globalHooksDir>/chained/<name> for a global one, so its grandparent is
+    // always per-install state. The compile cache lives there rather than in a
+    // shared or temp location: no other repository can pollute it, and
+    // `uninstall --purge-state` removes it along with the rest of the state.
+    const compileCacheDir = join(dirname(dirname(String(chainedPath))), 'compile-cache');
     const captureTree = name === 'commit-msg'
         ? `AIMHOOMAN_COMMIT_TREE=$(PATH="$AIMHOOMAN_PATH" git write-tree) || {
   echo "aimhooman: cannot snapshot the would-be commit tree" >&2
@@ -690,10 +696,31 @@ function hookScript(name, cmd, cliPath, chainedPath) {
     // committed/aborted fire only after refs are locked in, and refcheck can do
     // nothing but return 0 for them (see cmdRefcheck). Short-circuit in the shell
     // so an ordinary commit no longer pays a Node cold start for the committed
-    // phase. Placed after the chained-hook call, so a chained hook still sees
-    // every phase.
+    // phase. The prepared filter goes further: a transaction that moves neither
+    // a branch nor HEAD (ORIG_HEAD, tags, remote-tracking refs) carries nothing
+    // refcheck scans, so it never spawns at all — but only after proving the
+    // guard is still there to skip. A hook manager that wipes the dispatchers
+    // during a branch-free operation (tag, fetch, stash) would otherwise go
+    // unnoticed, because after a full wipe no later hook exists to raise the
+    // alarm. Presence is exactly what a deletion removes; content integrity
+    // keeps running on every branch transaction via refcheck. Both sit after
+    // the chained-hook call, so a chained hook still sees every phase.
     const phaseShortCircuit = name === 'reference-transaction'
-        ? 'case "$1" in committed|aborted) exit 0 ;; esac\n'
+        ? `case "$1" in committed|aborted) exit 0 ;; esac
+case "$1" in prepared)
+  case "$AIMHOOMAN_REF_UPDATES" in
+    *refs/heads/*|*" HEAD"*) ;;
+    *)
+      for AIMHOOMAN_GUARD in pre-commit pre-merge-commit commit-msg reference-transaction; do
+        [ -x "$(dirname "$0")/$AIMHOOMAN_GUARD" ] || {
+          echo "aimhooman: required Git guards changed while reference-transaction was running; $AIMHOOMAN_GUARD is unavailable. The operation was stopped; run 'aimhooman init' and retry." >&2
+          exit 20
+        }
+      done
+      exit 0 ;;
+  esac ;;
+esac
+`
         : '';
     const template = `#!/bin/sh -p
 ${MARKER} (${name})
@@ -706,6 +733,7 @@ ${MARKER} (${name})
 AIMHOOMAN_CLI=${shq(resolvedCliPath)}
 AIMHOOMAN_NODE=${shq(nodePath)}
 AIMHOOMAN_PATH=${shq(shellPathValue)}
+AIMHOOMAN_COMPILE_CACHE=${shq(compileCacheDir)}
 ${captureTree}${captureTransaction}run_aimhooman() {
   if [ ! -f "$AIMHOOMAN_CLI" ]; then
     echo "aimhooman: guard unavailable (aimhooman CLI is missing); allowing this operation without protection. Reinstall aimhooman or remove the managed hooks." >&2
@@ -731,8 +759,15 @@ ${captureTree}${captureTransaction}run_aimhooman() {
     unset BASH_ENV ENV CDPATH
     PATH=$AIMHOOMAN_PATH
     AIMHOOMAN_ACTIVE_HOOK=${shq(name)}
+    # A V8 compile cache shared by every hook spawn of this installation shaves
+    # the module parse/compile cost off each Node start. Node creates the
+    # directory when it can and silently disables the cache when it cannot, so
+    # an unwritable state directory degrades to the old cold start, never to a
+    # hook failure.
+    NODE_COMPILE_CACHE=$AIMHOOMAN_COMPILE_CACHE
     export PATH
     export AIMHOOMAN_ACTIVE_HOOK
+    export NODE_COMPILE_CACHE
     "$AIMHOOMAN_NODE" "$AIMHOOMAN_CLI" "$@"
   )
 }

package/src/gitx.mjs

@@ -12,7 +12,7 @@ import {
     rmSync,
     symlinkSync,
 } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 
 export class GitRevisionError extends Error {
@@ -99,7 +99,23 @@ function objectMetadata(repo, oids) {
 }
 
 function enrichEntries(repo, entries) {
-    const metadata = objectMetadata(repo, entries.map((entry) => entry.oid));
+    const metadata = objectMetadata(
+        repo,
+        entries.filter((entry) => entry.mode !== '160000').map((entry) => entry.oid),
+    );
+    // Gitlinks (mode 160000) pin a commit of another repository. Enrich them
+    // from the local object store when the pin happens to be there, but never
+    // let the read fail the scan: in a partial clone asking cat-file about a
+    // pin that is not local triggers a promisor fetch that aborts the whole
+    // batch ("not our ref"), surfacing as an EPIPE. A failed read leaves the
+    // mode-derived type in place with no size.
+    try {
+        const gitlinks = objectMetadata(
+            repo,
+            entries.filter((entry) => entry.mode === '160000').map((entry) => entry.oid),
+        );
+        for (const [oid, object] of gitlinks) metadata.set(oid, object);
+    } catch { /* best effort — see above */ }
     return entries.map((entry) => {
         const object = metadata.get(entry.oid) || { type: null, size: null };
         return {
@@ -146,10 +162,45 @@ function diffEntries(repo, args, renameThreshold = null) {
 
 // openRepo resolves the repository containing cwd. Throws if not a repo.
 export function openRepo(cwd = process.cwd()) {
-    const root = gitStr(['rev-parse', '--show-toplevel'], cwd);
-    const gitDir = gitStr(['rev-parse', '--absolute-git-dir'], root);
-    let commonDir = gitStr(['rev-parse', '--git-common-dir'], root);
-    if (!isAbsolute(commonDir)) commonDir = join(root, commonDir);
+    // One rev-parse invocation, not three: this runs inside every Git hook
+    // spawn, and each git subprocess costs ~13ms of the commit-time budget.
+    // The flags print in request order, one value per line.
+    const lines = gitStr(
+        ['rev-parse', '--show-toplevel', '--absolute-git-dir', '--git-common-dir'],
+        cwd,
+    ).split('\n');
+    if (lines.length !== 3) {
+        // A newline inside the repository path breaks the multi-flag output
+        // into extra lines; one flag per call is immune to that.
+        const root = gitStr(['rev-parse', '--show-toplevel'], cwd);
+        const gitDir = gitStr(['rev-parse', '--absolute-git-dir'], root);
+        let commonDir = gitStr(['rev-parse', '--git-common-dir'], root);
+        if (!isAbsolute(commonDir)) commonDir = join(root, commonDir);
+        return {
+            root,
+            gitDir,
+            commonDir,
+            stateDir: join(commonDir, 'aimhooman'),
+            excludeFile: join(commonDir, 'info', 'exclude'),
+        };
+    }
+    const [root, gitDir, commonRaw] = lines;
+    // Only --git-common-dir comes back relative, and it is relative to the cwd
+    // the command ran in, never to the toplevel. Anchor the plain-'.git' case
+    // (a main worktree from any cwd spelling) on git's own canonical root —
+    // the same spelling the three-call version produced — instead of
+    // realpath'ing through the cwd: git lengthens 8.3 names on Windows and
+    // resolves symlinked cwds on macOS, and matching it keeps one spelling
+    // per repository. Anything else (a subdir's ../.git, an uncommon layout)
+    // resolves against the invoking cwd, which is the same directory.
+    let commonDir;
+    if (isAbsolute(commonRaw)) {
+        commonDir = commonRaw;
+    } else if (commonRaw === '.git') {
+        commonDir = join(root, commonRaw);
+    } else {
+        commonDir = resolve(cwd, commonRaw);
+    }
     return {
         root,
         gitDir,
@@ -177,6 +228,17 @@ export function stagedPaths(repo) {
     ], repo.root));
 }
 
+// ignoredByPatterns lists untracked, ignored paths under the given pathspecs.
+// Passing pathspecs keeps git's directory pruning effective: a bare
+// `ls-files --others --ignored` walks the whole worktree and costs ~150ms on
+// a large one, while anchored pathspecs answer in ~15ms.
+export function ignoredByPatterns(repo, pathspecs) {
+    if (!pathspecs.length) return [];
+    return nulStrings(gitBuf([
+        'ls-files', '--others', '--ignored', '--exclude-standard', '-z', '--', ...pathspecs,
+    ], 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

package/src/report.mjs

@@ -7,6 +7,33 @@
 // for the rest. The JSON report (aimhooman review / --json) is never capped.
 const HUMAN_FINDING_CAP = 20;
 
+// UT-06: prefix -> provider for secret.provider-token findings. The rule packs
+// every provider into one pattern set (rules/secrets.json), so the provider
+// name is recovered from the raw matched line at report time — before the
+// redaction below runs. Only the label is ever rendered, never the token.
+// Mirrors the rule's patterns; keep the rule's alternation order.
+const TOKEN_PROVIDERS = [
+    ['ghp_', 'GitHub'], ['gho_', 'GitHub'], ['ghu_', 'GitHub'], ['ghs_', 'GitHub'],
+    ['ghr_', 'GitHub'], ['github_pat_', 'GitHub'],
+    ['glpat-', 'GitLab'],
+    ['npm_', 'npm'],
+    ['xoxb-', 'Slack'], ['xoxp-', 'Slack'], ['xoxa-', 'Slack'], ['xoxr-', 'Slack'], ['xoxs-', 'Slack'],
+    ['sk-ant-', 'Anthropic'],
+    ['sk-proj-', 'OpenAI'],
+    ['AIza', 'Google'],
+    ['sk_live_', 'Stripe'], ['rk_live_', 'Stripe'],
+    ['hf_', 'Hugging Face'],
+    ['SG.', 'SendGrid'],
+];
+
+function tokenProvider(text) {
+    if (!text) return undefined;
+    for (const [prefix, provider] of TOKEN_PROVIDERS) {
+        if (text.includes(prefix)) return provider;
+    }
+    return undefined;
+}
+
 export function human(findings, tone) {
     if (!findings.length) return '';
     let out = tone === 'professional' ? '\n' : '\nnot very hooman.\n\n';
@@ -21,6 +48,7 @@ export function human(findings, tone) {
     // while bounding stderr for repeated-rule scans.
     const shown = findings.slice(0, HUMAN_FINDING_CAP);
     const hidden = findings.length - shown.length;
+    const fixesPrinted = new Set();
     for (const f of shown) {
         const loc = f.path
             ? `${visible(f.path)}${f.line ? `:${f.line}` : ''}`
@@ -28,15 +56,30 @@ export function human(findings, tone) {
         const related = (f.matchedRuleIds || []).filter((id) => id !== f.ruleId);
         const identity = related.length ? `${f.ruleId} (+ ${related.join(', ')})` : f.ruleId;
         const commit = f.commit ? ` [commit ${String(f.commit).slice(0, 12)}]` : '';
-        out += `${f.decision.toUpperCase().padEnd(6)} ${identity}${commit}\n       ${loc}\n       ${f.reason}\n`;
+        // UT-06: a provider-token finding used to say only "a provider access
+        // token", leaving the developer to guess which credential to revoke.
+        // Name the provider in the reason; the token itself stays redacted.
+        const provider = f.ruleId === 'secret.provider-token' ? tokenProvider(f.text) : undefined;
+        const reason = provider
+            ? f.reason.replace('provider access token', `provider access token (${provider})`)
+            : f.reason;
+        out += `${f.decision.toUpperCase().padEnd(6)} ${identity}${commit}\n       ${loc}\n       ${reason}\n`;
         if (f.text && f.text.trim()) {
             out += `       > ${isSensitive(f) ? '[redacted]' : visible(f.text.trim())}\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`;
+        // that the previous single-index render dropped silently. UT-08: print a
+        // rule's fix once — a repeated rule (20 hits of the same secret rule)
+        // used to reprint the identical fix block for every finding.
+        const remedies = f.remediation || [];
+        if (remedies.length && fixesPrinted.has(f.ruleId)) {
+            out += `       fix: as above for ${f.ruleId}\n`;
+        } else {
+            if (remedies.length) fixesPrinted.add(f.ruleId);
+            for (const remedy of remedies) {
+                out += `       fix: ${remedy}\n`;
+            }
         }
         out += '\n';
     }