fullcourtdefense-cli 1.15.11 → 1.16.0

package/dist/commands/daemon.js

@@ -41,13 +41,16 @@ const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const config_1 = require("../config");
 const mcpGateway_1 = require("./mcpGateway");
+const protectionRepair_1 = require("./protectionRepair");
 const runtimeConfig_1 = require("../runtimeConfig");
+const discoverPaths_1 = require("./discoverPaths");
 const localSafetySnapshot_1 = require("../localSafetySnapshot");
 const telemetry_1 = require("../telemetry");
 const notify_1 = require("../notify");
 const integrity_1 = require("../integrity");
 const machineIdentity_1 = require("../machineIdentity");
 const discoveryMarker_1 = require("../discoveryMarker");
+const selfUpdate_1 = require("../selfUpdate");
 const COLOR = {
     reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
     red: '\x1b[31m', yellow: '\x1b[33m', green: '\x1b[32m', cyan: '\x1b[36m', gray: '\x1b[90m',
@@ -283,6 +286,7 @@ async function runDaemon(args, config) {
     log(`Shield: ${creds.shieldId || '(none — protect-only mode, telemetry disabled)'}  API: ${creds.apiUrl}`);
     // --- state ---------------------------------------------------------------
     const watchers = new Map(); // directory -> watcher
+    const rootWatchers = new Map(); // admin protection roots -> recursive watcher
     const watchedFiles = new Set(); // lowercased absolute file paths we react to
     let quietUntil = 0; // ignore events until this time (self-writes)
     let debounceTimer = null;
@@ -290,6 +294,8 @@ async function runDaemon(args, config) {
     let suspended = false;
     let stopped = false;
     const executingActionIds = new Set();
+    /** Latest org auto-update policy seen on a bundle poll. */
+    let autoUpdatePolicy;
     const reprotect = async (reasonPaths) => {
         if (reprotecting || stopped)
             return;
@@ -301,9 +307,10 @@ async function runDaemon(args, config) {
         quietUntil = Date.now() + SELF_WRITE_QUIET_MS;
         log(`Config drift detected: ${reasonPaths.join(', ')} — re-running protect-all.`);
         try {
-            await (0, mcpGateway_1.protectAllCommand)({ ...args, dryRun: undefined }, config);
+            const repaired = await (0, protectionRepair_1.repairProtection)({ ...args, dryRun: undefined }, config);
             quietUntil = Date.now() + SELF_WRITE_QUIET_MS;
-            log('Re-protection pass complete.');
+            log(`Re-protection pass complete (Cursor hooks ${repaired.cursorHooksHealthy ? 'healthy' : 'unhealthy'}, Claude hooks ${repaired.claudeHooksHealthy ? 'healthy' : 'unhealthy'}).`);
+            refreshWatchTargets();
             await uploadLogTail();
             if (!quiet) {
                 (0, notify_1.notifyOs)({
@@ -334,6 +341,25 @@ async function runDaemon(args, config) {
             clearTimeout(debounceTimer);
         debounceTimer = setTimeout(() => { void reprotect([full]); }, DEBOUNCE_MS);
     };
+    const onAdminRootEvent = (root, filename) => {
+        if (stopped || Date.now() < quietUntil || !filename)
+            return;
+        const full = path.resolve(root, filename.toString());
+        const normalized = full.replace(/\\/g, '/').toLowerCase();
+        if (normalized.includes('.fcd-backup-'))
+            return;
+        if (!/(?:\/\.cursor\/mcp\.json|\/\.mcp\.json|\/mcp\.json|\/\.claude\/settings\.json|\/\.vscode\/mcp\.json|\/\.codex\/config\.toml|\/\.gemini\/settings\.json)$/.test(normalized))
+            return;
+        const { disabledScanRoots } = (0, runtimeConfig_1.getCachedScanRootOverrides)();
+        if ((0, discoverPaths_1.isExcludedPath)(full, disabledScanRoots))
+            return;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            refreshWatchTargets();
+            void reprotect([full]);
+        }, DEBOUNCE_MS);
+    };
     /**
      * (Re)build the watch set from the current MCP client configs + hook files.
      * Watches parent directories (not files) so atomic replaces on Windows and
@@ -366,6 +392,27 @@ async function runDaemon(args, config) {
             }
             catch { /* directory may vanish; the rescan tick re-tries */ }
         }
+        const { extraScanRoots, disabledScanRoots } = (0, runtimeConfig_1.getCachedScanRootOverrides)();
+        const wantedRoots = new Set(extraScanRoots
+            .filter(root => !(0, discoverPaths_1.isExcludedPath)(root, disabledScanRoots) && fs.existsSync(root))
+            .map(discoverPaths_1.normalizedPath));
+        for (const [root, watcher] of rootWatchers) {
+            if (!wantedRoots.has((0, discoverPaths_1.normalizedPath)(root))) {
+                watcher.close();
+                rootWatchers.delete(root);
+            }
+        }
+        for (const root of extraScanRoots) {
+            const key = (0, discoverPaths_1.normalizedPath)(root);
+            if (!wantedRoots.has(key) || [...rootWatchers.keys()].some(existing => (0, discoverPaths_1.normalizedPath)(existing) === key))
+                continue;
+            try {
+                const watcher = fs.watch(path.resolve(root), { recursive: true }, (_event, filename) => onAdminRootEvent(root, filename ? String(filename) : null));
+                watcher.on('error', () => { watcher.close(); rootWatchers.delete(root); });
+                rootWatchers.set(path.resolve(root), watcher);
+            }
+            catch { /* unsupported/unreadable roots are retried on the rescan tick */ }
+        }
         return targets.length;
     };
     // Ship the REAL daemon log tail to the control plane so the dashboard's
@@ -472,7 +519,7 @@ async function runDaemon(args, config) {
                     throw new Error('Machine is suspended; resume it before repairing protection.');
                 log('Repair protection: running protect-all (IDE hooks + MCP gateways)…');
                 await uploadLogTail();
-                await (0, mcpGateway_1.protectAllCommand)({ ...args, dryRun: undefined }, config);
+                await (0, protectionRepair_1.repairProtection)({ ...args, dryRun: undefined }, config);
                 log('Repair protection: verifying hooks, gateways and daemon integrity…');
                 const verification = (0, integrity_1.getLocalIntegrityReport)({ requireDaemon: true });
                 if (!verification.ok) {
@@ -481,6 +528,24 @@ async function runDaemon(args, config) {
                 log(`Repair protection: verified (${verification.protectedMcpConfigs}/${verification.discoveredMcpConfigs} MCP configs wrapped).`);
                 resultSummary = 'AgentGuard hooks, gateways, and protection configuration were repaired and verified.';
             }
+            else if (action.type === 'upgrade_cli') {
+                // Explicit version in the action reason wins; otherwise the org
+                // auto-update target from the bundle (pinned or latest release).
+                const target = action.reason.match(/\d+\.\d+\.\d+/)?.[0] || autoUpdatePolicy?.targetVersion;
+                if (!target)
+                    throw new Error('No target version available — the control plane could not resolve the latest release.');
+                log(`Upgrade CLI: admin requested an upgrade to ${target}.`);
+                const outcome = (0, selfUpdate_1.maybeSelfUpdate)({ currentVersion: cliVersion(), targetVersion: target, enabled: true, log });
+                if (!outcome) {
+                    resultSummary = `CLI ${cliVersion() || 'unknown'} is already at ${target} (or an upgrade is in progress).`;
+                }
+                else if (outcome.started) {
+                    resultSummary = outcome.detail;
+                }
+                else {
+                    throw new Error(outcome.detail);
+                }
+            }
             else if (action.type === 'discovery_scan') {
                 log('Discovery scan: starting full surface sweep (MCP + secrets + agent files + posture)…');
                 await uploadLogTail();
@@ -541,6 +606,27 @@ async function runDaemon(args, config) {
             if (bundle.machineAction) {
                 void executeMachineAction(bundle.machineAction);
             }
+            // Silent auto-update: upgrade toward the org's target version. Skipped
+            // while a remote action runs, while suspended, and rate-limited so a
+            // pending upgrade isn't re-kicked every poll.
+            autoUpdatePolicy = bundle.autoUpdate;
+            // Mirror the org policy for the elevated MSI updater task (it runs as
+            // SYSTEM and cannot read the shield-key-authenticated bundle itself).
+            if (bundle.autoUpdate) {
+                try {
+                    fs.writeFileSync(path.join(daemonDir(), 'update-policy.json'), JSON.stringify({ ...bundle.autoUpdate, updatedAt: new Date().toISOString() }), 'utf8');
+                }
+                catch { /* mirror is best-effort; the updater defaults to enabled */ }
+            }
+            if (!suspended && bundle.autoUpdate?.enabled) {
+                (0, selfUpdate_1.maybeSelfUpdate)({
+                    currentVersion: cliVersion(),
+                    targetVersion: bundle.autoUpdate.targetVersion,
+                    enabled: true,
+                    busy: executingActionIds.size > 0,
+                    log,
+                });
+            }
         }
         catch { /* offline — cached stance applies */ }
     };
@@ -624,6 +710,8 @@ async function runDaemon(args, config) {
             clearTimeout(debounceTimer);
         for (const watcher of watchers.values())
             watcher.close();
+        for (const watcher of rootWatchers.values())
+            watcher.close();
         releasePidLock();
         process.exit(0);
     };

package/dist/commands/discover.js

@@ -774,6 +774,7 @@ function printPostureReport(posture, silent) {
     }
 }
 async function discoverCommand(args, config) {
+    const scanStartedAt = new Date().toISOString();
     const surfaces = parseSurfaces(args);
     const silent = args.silent === 'true';
     const uploadRequested = args.upload === 'true';
@@ -827,14 +828,18 @@ async function discoverCommand(args, config) {
     // covers them without extra flags. Default folders the admin explicitly
     // removed in the console are dropped from the sweep.
     const { extraScanRoots: adminScanRoots, disabledScanRoots } = (0, runtimeConfig_1.getCachedScanRootOverrides)();
-    const disabledRootSet = new Set(disabledScanRoots.map(root => path.resolve(root).toLowerCase()));
-    const isDisabledRoot = (root) => disabledRootSet.has(path.resolve(root).toLowerCase());
-    const scanRoots = [...new Set([...(0, discoverPaths_1.resolveScanRoots)(args.scanRoot), ...adminScanRoots])]
+    const normalizedDisabledRoots = (0, discoverPaths_1.uniqueNormalizedPaths)(disabledScanRoots);
+    const isDisabledRoot = (root) => (0, discoverPaths_1.isExcludedPath)(root, normalizedDisabledRoots);
+    const scanRoots = (0, discoverPaths_1.uniqueNormalizedPaths)([...(0, discoverPaths_1.resolveScanRoots)(args.scanRoot), ...adminScanRoots])
         .filter(root => !isDisabledRoot(root));
-    const sweep = scanRoots.length > 0 ? (0, discoverPaths_1.scanRootsForProjectConfigs)(scanRoots) : { candidates: [], scannedDirs: 0 };
+    const sweep = scanRoots.length > 0
+        ? (0, discoverPaths_1.scanRootsForProjectConfigs)(scanRoots, { excludedRoots: normalizedDisabledRoots })
+        : { candidates: [], scannedDirs: 0, excludedDirs: 0, truncated: false, maxDepth: 4, maxDirs: 25000 };
     // Admin roots are scanned for env/secrets even when no MCP config lives there.
-    const sweepProjectRoots = [...new Set([...deriveProjectRoots(sweep.candidates), ...adminScanRoots])];
-    const knownConfigCandidates = candidateConfigPaths(cwd, args.extraPath);
+    const sweepProjectRoots = (0, discoverPaths_1.uniqueNormalizedPaths)([...deriveProjectRoots(sweep.candidates), ...adminScanRoots])
+        .filter(root => !isDisabledRoot(root));
+    const knownConfigCandidates = candidateConfigPaths(cwd, args.extraPath)
+        .filter(candidate => !isDisabledRoot(candidate.path));
     const secretConfigFiles = [...knownConfigCandidates, ...sweep.candidates]
         .map(candidate => path.resolve(candidate.path))
         .filter(file => fs.existsSync(file));
@@ -881,11 +886,12 @@ async function discoverCommand(args, config) {
         }
     }
     const secrets = surfaces.has('secrets') || surfaces.has('posture')
-        ? (0, discoverSecrets_1.scanSecrets)({ cwd, extraRoots: sweepProjectRoots, disabledRoots: disabledScanRoots, configFiles: secretConfigFiles })
+        ? (0, discoverSecrets_1.scanSecrets)({ cwd, extraRoots: sweepProjectRoots, disabledRoots: normalizedDisabledRoots, configFiles: secretConfigFiles })
         : undefined;
-    const agentFiles = surfaces.has('agent-files') || surfaces.has('posture')
-        ? (0, discoverAgentFiles_1.scanAgentFiles)({ cwd, extraRoots: sweepProjectRoots })
+    const agentFileScan = surfaces.has('agent-files') || surfaces.has('posture')
+        ? (0, discoverAgentFiles_1.scanAgentFilesWithMetadata)({ cwd, extraRoots: sweepProjectRoots, disabledRoots: normalizedDisabledRoots })
         : undefined;
+    const agentFiles = agentFileScan?.findings;
     const posture = surfaces.has('posture')
         ? (0, discoverBlastRadius_1.computeBlastRadius)({
             mcpServers: found,
@@ -932,14 +938,43 @@ async function discoverCommand(args, config) {
                 `User-level AI rules, skills, hooks, and instruction files under ${home}`,
                 `Credential stores and shell history under ${home}`,
                 `Environment files under ${cwd}, ${path.join(home, 'dev')}, ${path.join(home, 'repos')}, ${path.join(home, 'projects')}, ${path.join(home, 'Documents')}, and ${path.join(home, 'code')}`,
-                ...adminScanRoots.map(root => `Admin-selected folder: ${root} (and subfolders)`),
+                ...adminScanRoots.map(root => `Admin-selected folder: ${root} (bounded descendant scan; exclusions and limits below)`),
             ],
             excluded: [
                 'Unrelated project folders outside the listed roots',
                 'Large/generated dependency and build folders such as node_modules, .git, dist, build, vendor, caches, and temp folders',
+                ...normalizedDisabledRoots.map(root => `Admin-excluded subtree: ${root}`),
                 'Full disk contents, browser profiles, email/chat archives, binary files, and operating-system folders',
             ],
-            note: 'Desktop posture is a targeted AI-development exposure scan, not a full-device forensic scan. Add folders from the machine page to expand coverage.',
+            note: `Desktop posture is a bounded AI-development exposure scan (project walk depth ${sweep.maxDepth}, up to ${sweep.maxDirs} folders), not a full-device forensic scan.`,
+            scannedAt: scanStartedAt,
+            limits: {
+                projectMaxDepth: sweep.maxDepth,
+                projectMaxDirectories: sweep.maxDirs,
+                secretMaxFileBytes: secrets?.limits?.maxFileBytes,
+                secretMaxCandidateFiles: secrets?.limits?.maxEnvFiles,
+                secretMaxFindings: secrets?.limits?.maxFindings,
+                agentFileMaxFiles: agentFileScan?.limits.maxFiles,
+                agentFileMaxBytes: agentFileScan?.limits.maxFileBytes,
+                agentFileMaxDepth: agentFileScan?.limits.maxDepth,
+            },
+            stats: {
+                projectDirectoriesScanned: sweep.scannedDirs,
+                projectConfigsFound: sweep.candidates.length,
+                projectRootsFound: sweepProjectRoots.length,
+                rootsScanned: scannedRoots.length,
+                secretCandidateFilesScanned: secrets?.scannedFiles ?? 0,
+                secretFindingsFound: secrets?.findings.length ?? 0,
+                secretFindingsUploaded: secrets?.findings.length ?? 0,
+                agentFilesScanned: agentFileScan?.stats.scannedFiles ?? 0,
+                excludedPathsSkipped: sweep.excludedDirs + (secrets?.stats?.excludedFiles ?? 0) + (agentFileScan?.stats.excludedPaths ?? 0),
+            },
+            truncated: {
+                projectDirectories: sweep.truncated,
+                secretCandidates: secrets?.truncated?.candidateFiles ?? false,
+                secretFindings: secrets?.truncated?.findings ?? false,
+                agentFiles: agentFileScan?.truncated ?? false,
+            },
         },
     };
     async function maybeUpload() {
@@ -967,6 +1002,7 @@ async function discoverCommand(args, config) {
             secrets,
             agentFiles,
             posture,
+            scanScope: uploadExtras.scanScope,
         }, null, 2));
         return;
     }

package/dist/commands/discoverAgentFiles.d.ts

@@ -10,7 +10,27 @@ export interface AgentFileFinding {
     riskTags: string[];
     excerpt?: string;
 }
+export interface AgentFilesScanResult {
+    findings: AgentFileFinding[];
+    limits: {
+        maxFiles: number;
+        maxFileBytes: number;
+        maxDepth: number;
+    };
+    stats: {
+        scannedFiles: number;
+        excludedPaths: number;
+    };
+    truncated: boolean;
+}
+export declare function scanAgentFilesWithMetadata(options?: {
+    cwd?: string;
+    extraRoots?: string[];
+    disabledRoots?: string[];
+}): AgentFilesScanResult;
+/** Backward-compatible findings-only API used by existing callers/tests. */
 export declare function scanAgentFiles(options?: {
     cwd?: string;
     extraRoots?: string[];
+    disabledRoots?: string[];
 }): AgentFileFinding[];

package/dist/commands/discoverAgentFiles.js

@@ -33,11 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanAgentFilesWithMetadata = scanAgentFilesWithMetadata;
 exports.scanAgentFiles = scanAgentFiles;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const discoverPaths_1 = require("./discoverPaths");
 const MAX_FILES = 150;
 const MAX_FILE_BYTES = 512 * 1024;
 const EXCERPT_LEN = 180;
@@ -131,9 +133,19 @@ function pushFinding(out, seen, input) {
         excerpt: excerpt || undefined,
     });
 }
-function walkDir(dir, out, seen, matcher, mapper, maxDepth = 4, depth = 0) {
-    if (depth > maxDepth || out.length >= MAX_FILES)
+function walkDir(dir, out, seen, matcher, mapper, maxDepth = 4, depth = 0, excludedRoots = [], stats) {
+    if (depth > maxDepth) {
+        if (stats)
+            stats.depthLimited = true;
         return;
+    }
+    if (out.length >= MAX_FILES)
+        return;
+    if ((0, discoverPaths_1.isExcludedPath)(dir, excludedRoots)) {
+        if (stats)
+            stats.excludedPaths += 1;
+        return;
+    }
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -145,10 +157,15 @@ function walkDir(dir, out, seen, matcher, mapper, maxDepth = 4, depth = 0) {
         if (out.length >= MAX_FILES)
             return;
         const full = path.join(dir, entry.name);
+        if ((0, discoverPaths_1.isExcludedPath)(full, excludedRoots)) {
+            if (stats)
+                stats.excludedPaths += 1;
+            continue;
+        }
         if (entry.isDirectory()) {
             if (['node_modules', '.git', 'dist', 'build'].includes(entry.name))
                 continue;
-            walkDir(full, out, seen, matcher, mapper, maxDepth, depth + 1);
+            walkDir(full, out, seen, matcher, mapper, maxDepth, depth + 1, excludedRoots, stats);
             continue;
         }
         if (!entry.isFile() || !matcher(full, entry.name))
@@ -159,12 +176,22 @@ function walkDir(dir, out, seen, matcher, mapper, maxDepth = 4, depth = 0) {
         pushFinding(out, seen, { ...mapper(full), ...parsed, content: parsed.content });
     }
 }
-function scanNamedFiles(roots, names, kind, titleFor, out, seen) {
+function scanNamedFiles(roots, names, kind, titleFor, out, seen, excludedRoots = [], stats) {
     for (const { root, client } of roots) {
+        if ((0, discoverPaths_1.isExcludedPath)(root, excludedRoots)) {
+            if (stats)
+                stats.excludedPaths += 1;
+            continue;
+        }
         if (!fs.existsSync(root))
             continue;
         for (const name of names) {
             const filePath = path.join(root, name);
+            if ((0, discoverPaths_1.isExcludedPath)(filePath, excludedRoots)) {
+                if (stats)
+                    stats.excludedPaths += 1;
+                continue;
+            }
             if (!fs.existsSync(filePath))
                 continue;
             const parsed = readAgentFile(filePath);
@@ -183,17 +210,22 @@ function scanNamedFiles(roots, names, kind, titleFor, out, seen) {
     }
 }
 /** Scan a single project root for agent instruction/rule/skill/hook files. */
-function scanProjectRootAgentFiles(root, clientLabel, out, seen) {
+function scanProjectRootAgentFiles(root, clientLabel, out, seen, excludedRoots = [], stats) {
+    if ((0, discoverPaths_1.isExcludedPath)(root, excludedRoots)) {
+        if (stats)
+            stats.excludedPaths += 1;
+        return;
+    }
     scanNamedFiles([{ root, client: clientLabel }], [
         'AGENTS.md',
         'CLAUDE.md',
         'GEMINI.md',
         '.cursorrules',
         '.windsurfrules',
-    ], 'instructions', name => `Agent instructions (${name})`, out, seen);
+    ], 'instructions', name => `Agent instructions (${name})`, out, seen, excludedRoots, stats);
     scanNamedFiles([{ root: path.join(root, '.github'), client: 'github' }], [
         'copilot-instructions.md',
-    ], 'instructions', () => 'GitHub Copilot instructions', out, seen);
+    ], 'instructions', () => 'GitHub Copilot instructions', out, seen, excludedRoots, stats);
     for (const base of [
         { dir: path.join(root, '.cursor', 'rules'), client: `Cursor (${clientLabel})`, kind: 'rules' },
         { dir: path.join(root, '.agents', 'skills'), client: `Agents (${clientLabel})`, kind: 'skills' },
@@ -207,7 +239,7 @@ function scanProjectRootAgentFiles(root, clientLabel, out, seen) {
             title: path.basename(filePath),
             sizeBytes: 0,
             lineCount: 0,
-        }));
+        }), 4, 0, excludedRoots, stats);
     }
     const hooksPath = path.join(root, '.cursor', 'hooks.json');
     if (fs.existsSync(hooksPath)) {
@@ -226,20 +258,24 @@ function scanProjectRootAgentFiles(root, clientLabel, out, seen) {
         }
     }
 }
-function scanAgentFiles(options = {}) {
+function scanAgentFilesWithMetadata(options = {}) {
     const home = os.homedir();
     const cwd = options.cwd || process.cwd();
     const out = [];
     const seen = new Set();
+    const excludedRoots = (0, discoverPaths_1.uniqueNormalizedPaths)(options.disabledRoots ?? []);
+    // Count configured subtree exclusions even when pruning prevents the walker
+    // from ever enumerating their contents.
+    const stats = { excludedPaths: excludedRoots.length, depthLimited: false };
     // Current project + user-global locations.
-    scanProjectRootAgentFiles(cwd, 'project', out, seen);
+    scanProjectRootAgentFiles(cwd, 'project', out, seen, excludedRoots, stats);
     scanNamedFiles([{ root: home, client: 'user' }], [
         'AGENTS.md',
         'CLAUDE.md',
         'GEMINI.md',
         '.cursorrules',
         '.windsurfrules',
-    ], 'instructions', name => `Agent instructions (${name})`, out, seen);
+    ], 'instructions', name => `Agent instructions (${name})`, out, seen, excludedRoots, stats);
     for (const base of [
         { dir: path.join(home, '.cursor', 'rules'), client: 'Cursor', kind: 'rules' },
         { dir: path.join(home, '.agents', 'skills'), client: 'Agents', kind: 'skills' },
@@ -253,10 +289,10 @@ function scanAgentFiles(options = {}) {
             title: path.basename(filePath),
             sizeBytes: 0,
             lineCount: 0,
-        }));
+        }), 4, 0, excludedRoots, stats);
     }
     const homeHooks = path.join(home, '.cursor', 'hooks.json');
-    if (fs.existsSync(homeHooks)) {
+    if (!(0, discoverPaths_1.isExcludedPath)(homeHooks, excludedRoots) && fs.existsSync(homeHooks)) {
         const parsed = readAgentFile(homeHooks);
         if (parsed) {
             pushFinding(out, seen, {
@@ -274,13 +310,26 @@ function scanAgentFiles(options = {}) {
     // Additional project roots (e.g. from `discover --scan-root`) — reference agent
     // files in every mapped project, not just the current folder.
     const cwdKey = path.resolve(cwd).toLowerCase();
-    for (const extra of options.extraRoots ?? []) {
+    for (const extra of (0, discoverPaths_1.uniqueNormalizedPaths)(options.extraRoots ?? [])) {
         if (path.resolve(extra).toLowerCase() === cwdKey)
             continue;
+        if ((0, discoverPaths_1.isExcludedPath)(extra, excludedRoots)) {
+            stats.excludedPaths += 1;
+            continue;
+        }
         if (!fs.existsSync(extra))
             continue;
-        scanProjectRootAgentFiles(extra, 'scanned project', out, seen);
+        scanProjectRootAgentFiles(extra, 'scanned project', out, seen, excludedRoots, stats);
     }
     out.sort((a, b) => b.riskTags.length - a.riskTags.length || b.sizeBytes - a.sizeBytes);
-    return out;
+    return {
+        findings: out,
+        limits: { maxFiles: MAX_FILES, maxFileBytes: MAX_FILE_BYTES, maxDepth: 4 },
+        stats: { scannedFiles: out.length, excludedPaths: stats.excludedPaths },
+        truncated: stats.depthLimited || out.length >= MAX_FILES,
+    };
+}
+/** Backward-compatible findings-only API used by existing callers/tests. */
+function scanAgentFiles(options = {}) {
+    return scanAgentFilesWithMetadata(options).findings;
 }

package/dist/commands/discoverBlastRadius.d.ts

@@ -7,6 +7,11 @@ export interface BlastRadiusCombo {
     severity: BlastSeverity;
     title: string;
     detail: string;
+    /** Exact entities that caused this combo; IDs are stable across rescans. */
+    evidenceRefs: Array<{
+        kind: 'mcp_server' | 'secret_finding' | 'agent_file' | 'client';
+        id: string;
+    }>;
 }
 export interface BlastRadiusReport {
     score: number;
@@ -16,6 +21,7 @@ export interface BlastRadiusReport {
 }
 interface McpServerLike {
     serverName: string;
+    configPath?: string;
     riskLevel: 'critical' | 'high' | 'medium' | 'low';
     riskTags: string[];
     proxyStatus: string;

package/dist/commands/discoverBlastRadius.js

@@ -29,12 +29,25 @@ function computeBlastRadius(input) {
     const shellHistorySecrets = criticalSecrets.filter(f => f.category === 'shell_history');
     const packagePublisherSecrets = criticalSecrets.filter(f => ['npm', 'pypi', 'github'].includes(f.provider || ''));
     const riskyAgentFiles = agentFiles.filter(f => f.riskTags.length > 0);
+    const mcpRefs = (servers) => servers.map(server => ({
+        kind: 'mcp_server',
+        // Config path disambiguates identically named servers in different repos.
+        id: JSON.stringify([server.serverName, server.configPath || '']),
+    }));
+    const secretRefs = (findings) => findings.map(finding => ({ kind: 'secret_finding', id: finding.id }));
+    const agentRefs = (findings) => findings.map(finding => ({ kind: 'agent_file', id: finding.id }));
+    const clientRefs = (clients) => clients.map(client => ({
+        kind: 'client',
+        id: `${client.clientKey}:${client.configPath}`,
+    }));
+    const tagged = (tag) => directServers.filter(server => server.riskTags.includes(tag));
     if (hasTag(directServers, 'shell/exec', true)) {
         combos.push({
             id: 'unproxied_shell',
             severity: 'critical',
             title: 'Direct shell/exec MCP',
             detail: 'At least one shell or command-runner MCP is not routed through Full Court Defense gateway.',
+            evidenceRefs: mcpRefs(tagged('shell/exec')),
         });
     }
     if (hasTag(directServers, 'database', true)) {
@@ -43,6 +56,7 @@ function computeBlastRadius(input) {
             severity: 'critical',
             title: 'Direct database MCP',
             detail: 'Database MCP tools are reachable without gateway policy enforcement.',
+            evidenceRefs: mcpRefs(tagged('database')),
         });
     }
     if (hasTag(directServers, 'shell/exec', true) && hasTag(directServers, 'filesystem', true)) {
@@ -51,6 +65,7 @@ function computeBlastRadius(input) {
             severity: 'critical',
             title: 'Shell + filesystem combo (direct)',
             detail: 'Agent can execute commands and read/write files without gateway — high blast radius.',
+            evidenceRefs: mcpRefs(directServers.filter(s => s.riskTags.includes('shell/exec') || s.riskTags.includes('filesystem'))),
         });
     }
     if (hasTag(mcpServers, 'shell/exec', true) && criticalSecrets.length > 0) {
@@ -59,6 +74,7 @@ function computeBlastRadius(input) {
             severity: 'critical',
             title: 'Shell MCP + secrets on disk',
             detail: `${criticalSecrets.length} high/critical secret(s) on this machine while shell/exec MCP is enabled.`,
+            evidenceRefs: [...mcpRefs(tagged('shell/exec')), ...secretRefs(criticalSecrets)],
         });
     }
     if (directServers.length > 0 && credentialStoreSecrets.length > 0) {
@@ -67,6 +83,7 @@ function computeBlastRadius(input) {
             severity: 'critical',
             title: 'Direct MCP + credential stores',
             detail: `${credentialStoreSecrets.length} credential-store secret(s) are readable while direct MCP tools are configured.`,
+            evidenceRefs: [...mcpRefs(directServers), ...secretRefs(credentialStoreSecrets)],
         });
     }
     if (shellHistorySecrets.length > 0) {
@@ -75,6 +92,7 @@ function computeBlastRadius(input) {
             severity: hasTag(directServers, 'shell/exec', true) ? 'critical' : 'high',
             title: 'Secrets in shell history',
             detail: `${shellHistorySecrets.length} token or credential value(s) were found in recent shell history.`,
+            evidenceRefs: secretRefs(shellHistorySecrets),
         });
     }
     if (hasTag(directServers, 'web/network', true) && criticalSecrets.length > 0) {
@@ -83,6 +101,7 @@ function computeBlastRadius(input) {
             severity: 'high',
             title: 'Browser/network MCP + local secrets',
             detail: 'Web or browser automation MCP combined with API keys in .env or credential stores.',
+            evidenceRefs: [...mcpRefs(tagged('web/network')), ...secretRefs(criticalSecrets)],
         });
     }
     const clientsWithMcp = clientCoverage.filter(c => c.mcpServerCount > 0);
@@ -93,6 +112,7 @@ function computeBlastRadius(input) {
             severity: 'high',
             title: 'No gateway on any AI client',
             detail: `${clientsWithMcp.length} AI client(s) have MCP configured but no FCD gateway or runtime hooks.`,
+            evidenceRefs: clientRefs(missingGateway),
         });
     }
     if (countDirect(mcpServers, 'critical') >= 2) {
@@ -101,6 +121,7 @@ function computeBlastRadius(input) {
             severity: 'high',
             title: 'Multiple unproxied critical MCPs',
             detail: `${countDirect(mcpServers, 'critical')} critical MCP server(s) run direct.`,
+            evidenceRefs: mcpRefs(directServers.filter(server => server.riskLevel === 'critical')),
         });
     }
     const unencryptedSsh = secrets.findings.find(f => f.category === 'ssh_key' && f.severity === 'high');
@@ -110,6 +131,7 @@ function computeBlastRadius(input) {
             severity: 'high',
             title: 'Unencrypted SSH private key',
             detail: unencryptedSsh.filePath,
+            evidenceRefs: secretRefs([unencryptedSsh]),
         });
     }
     if (riskyAgentFiles.some(f => f.riskTags.includes('allows_shell') || f.riskTags.includes('broad_filesystem'))) {
@@ -118,6 +140,7 @@ function computeBlastRadius(input) {
             severity: 'medium',
             title: 'Permissive agent rules/skills',
             detail: 'Cursor rules or skills mention shell, filesystem, or weak guardrails — review what the agent is allowed to do.',
+            evidenceRefs: agentRefs(riskyAgentFiles.filter(f => f.riskTags.includes('allows_shell') || f.riskTags.includes('broad_filesystem'))),
         });
     }
     if (riskyAgentFiles.some(f => f.riskTags.includes('allows_shell')
@@ -129,6 +152,8 @@ function computeBlastRadius(input) {
             severity: 'high',
             title: 'Agent can reach local credentials',
             detail: `${criticalSecrets.length} high-risk credential(s) are on this machine, and agent instructions allow broad actions such as shell, filesystem, auto-approval, or network sends. If the agent is hijacked, those credentials could be read or used.`,
+            evidenceRefs: [...secretRefs(criticalSecrets), ...agentRefs(riskyAgentFiles.filter(f => f.riskTags.includes('allows_shell') || f.riskTags.includes('weak_guardrails')
+                    || f.riskTags.includes('auto_approval') || f.riskTags.includes('network_exfil')))],
         });
     }
     if (packagePublisherSecrets.length > 0 && riskyAgentFiles.some(f => f.riskTags.includes('destructive_actions')
@@ -139,6 +164,7 @@ function computeBlastRadius(input) {
             severity: 'high',
             title: 'Publishing token exposed to agent actions',
             detail: `${packagePublisherSecrets.length} package/repository token(s) are on this machine while agent rules allow command execution, auto-approval, or publishing actions. A hijacked agent could publish packages or push code with those credentials.`,
+            evidenceRefs: [...secretRefs(packagePublisherSecrets), ...agentRefs(riskyAgentFiles.filter(f => f.riskTags.includes('destructive_actions') || f.riskTags.includes('allows_shell') || f.riskTags.includes('auto_approval')))],
         });
     }
     if (agentFiles.length >= 5 && !clientCoverage.some(c => c.cursorHooksInstalled)) {
@@ -147,20 +173,16 @@ function computeBlastRadius(input) {
             severity: 'medium',
             title: 'Many instruction files, no runtime hooks',
             detail: `${agentFiles.length} agent instruction/skill files found but runtime hooks are not installed.`,
+            evidenceRefs: [...agentRefs(agentFiles), ...clientRefs(clientCoverage.filter(c => !c.cursorHooksInstalled))],
         });
     }
+    // Score underlying exposure categories once. Combos explain interactions but
+    // do not repeatedly penalize the same MCP/secret/agent-file evidence.
     let score = 100;
-    for (const combo of combos) {
-        if (combo.severity === 'critical')
-            score -= 22;
-        else if (combo.severity === 'high')
-            score -= 12;
-        else
-            score -= 6;
-    }
-    score -= Math.min(30, criticalSecrets.length * 8);
-    score -= Math.min(15, countDirect(mcpServers, 'high') * 4);
-    score -= Math.min(10, riskyAgentFiles.length * 2);
+    score -= Math.min(35, criticalSecrets.reduce((sum, finding) => sum + (finding.severity === 'critical' ? 10 : 5), 0));
+    score -= Math.min(30, directServers.reduce((sum, server) => sum + (server.riskLevel === 'critical' ? 10 : server.riskLevel === 'high' ? 6 : 3), 0));
+    score -= Math.min(15, riskyAgentFiles.length * 3);
+    score -= Math.min(15, missingGateway.length * 5);
     score = Math.max(0, Math.min(100, score));
     if (criticalSecrets.length)
         drivers.push(`${criticalSecrets.length} exposed secret(s)`);