feat(discovery): version-aware cache filtering + --exclude-cache flag (v5.9 B3a) [skip-docs]

Stale ~/.claude/plugins/cache versions polluted token-hotspots ranking and
inflated CNF duplicate-hook findings with config that loads on zero turns.
installPaths point INTO the cache, so a blunt "skip all of plugins/cache"
would drop ACTIVE plugins — the filter is therefore version-aware: it reads
the adjacent installed_plugins.json, keeps active version dirs, drops only
stale ones (and exposes them via discovery.staleCacheVersions for B3b).

- file-discovery: cacheVersionKey() + applyCacheFilter() (active vs stale via
  installed_plugins.json; HOME-independent, derives the manifest from the cache
  path); discoverConfigFiles/Multi gain { excludeCache } + staleCacheVersions.
  Absent/unparseable manifest -> no filtering (never silently drop live config).
- token-hotspots-cli + scan-orchestrator: --exclude-cache (default ON for these
  live-cost scans) / --no-exclude-cache restores the full walk.
- Tests: cacheVersionKey unit cases; stale-dropped/active-kept/no-manifest
  discovery cases; CNF-drop proof (soft-spot verified, not assumed:
  include=1 -> exclude=0 duplicate-hook findings).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scanners/scan-orchestrator.mjs

@@ -80,6 +80,7 @@ const SCANNERS = [
  * @param {boolean} [opts.fullMachine=false] - Scan all known locations across the machine
  * @param {boolean} [opts.suppress=true] - Apply suppressions from .config-audit-ignore
  * @param {boolean} [opts.filterFixtures=true] - Exclude findings from test/example paths
+ * @param {boolean} [opts.excludeCache=true] - Drop stale ~/.claude/plugins/cache versions so findings reflect live config (B3)
  * @returns {Promise<object>} Full envelope with all results
  */
 // Exported for testing
@@ -89,14 +90,19 @@ export async function runAllScanners(targetPath, opts = {}) {
   const start = Date.now();
   const resolvedPath = resolve(targetPath);
 
+  // Default ON: stale cached plugin versions otherwise inflate token hotspots
+  // and CNF duplicate-hook findings with config that loads on zero turns. (B3)
+  const excludeCache = opts.excludeCache !== false;
+
   // Shared file discovery — scanners reuse this
   let discovery;
   if (opts.fullMachine) {
     const roots = await discoverFullMachinePaths();
-    discovery = await discoverConfigFilesMulti(roots);
+    discovery = await discoverConfigFilesMulti(roots, { excludeCache });
   } else {
     discovery = await discoverConfigFiles(resolvedPath, {
       includeGlobal: opts.includeGlobal || false,
+      excludeCache,
     });
   }
 
@@ -216,6 +222,8 @@ async function main() {
       // handled below
     } else if (args[i] === '--include-fixtures') {
       // handled below
+    } else if (args[i] === '--exclude-cache' || args[i] === '--no-exclude-cache') {
+      // handled below
     } else if (args[i] === '--json') {
       // handled below — explicit machine-readable mode (bypass humanizer)
     } else if (args[i] === '--raw') {
@@ -229,6 +237,7 @@ async function main() {
   const fullMachine = args.includes('--full-machine');
   const suppress = !args.includes('--no-suppress');
   const filterFixtures = !args.includes('--include-fixtures');
+  const excludeCache = !args.includes('--no-exclude-cache');
   const jsonMode = args.includes('--json');
   const rawMode = args.includes('--raw');
 
@@ -243,6 +252,7 @@ async function main() {
     fullMachine,
     suppress,
     filterFixtures,
+    excludeCache,
     humanizedProgress,
   });