@agent-finops/core 0.5.4 → 0.5.6

package/dist/contextHealth.js

@@ -0,0 +1,371 @@
+import { loadAgentInventory } from "./agentInventory.js";
+import { computeDeadContext } from "./deadContext.js";
+import { loadToolInvocations } from "./toolInvocations.js";
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_WINDOW_DAYS = 30;
+/**
+ * Load one canonical Context Health snapshot. CLI, MCP, and Glance all consume
+ * this contract so their recommendation and provenance cannot drift.
+ */
+export async function loadContextHealth(calls, options = {}) {
+    const inventory = options.inventory ?? await loadAgentInventory(options);
+    const invocations = options.invocations ?? await loadToolInvocations(options);
+    const windowDays = options.windowDays ?? DEFAULT_WINDOW_DAYS;
+    const deadContext = computeDeadContext(inventory.items, invocations, {
+        windowDays,
+        pricingModel: options.pricingModel ?? "claude-sonnet-4"
+    });
+    return buildContextHealth({
+        calls,
+        inventory,
+        invocations,
+        deadContext,
+        now: options.now,
+        activeWithinMinutes: options.activeWithinMinutes,
+        windowDays
+    });
+}
+/** Pure Context Health contract builder for deterministic tests and adapters. */
+export function buildContextHealth(input = {}) {
+    const now = input.now ?? new Date();
+    const calls = input.calls ?? [];
+    const items = input.inventory?.items ?? [];
+    const invocations = input.invocations ?? emptyInvocations();
+    const windowDays = input.windowDays ?? input.deadContext?.windowDays ?? DEFAULT_WINDOW_DAYS;
+    const deadContext = input.deadContext ?? computeDeadContext(items, invocations, {
+        windowDays,
+        pricingModel: "claude-sonnet-4"
+    });
+    const sessionGroups = contextSessions(calls);
+    const latestSession = latestContextSession(sessionGroups);
+    const currentSession = buildCurrentSession(sessionGroups, now, input.activeWithinMinutes ?? 20);
+    const contextChurn = buildContextChurn(latestSession, invocations);
+    const activation = activationSummary(items, invocations);
+    const hookItems = items.filter((item) => item.activation === "hook_injected");
+    const evidence = [];
+    if (currentSession) {
+        evidence.push({
+            kind: "session_history",
+            summary: currentSession.ratioToMedian === null
+                ? `${currentSession.totalTokens.toLocaleString("en-US")} local transcript tokens; no same-agent baseline yet.`
+                : `${currentSession.totalTokens.toLocaleString("en-US")} local transcript tokens, ${currentSession.ratioToMedian}× the median of ${currentSession.comparisonSessions} prior same-agent session${currentSession.comparisonSessions === 1 ? "" : "s"}.`,
+            source: `${currentSession.agent} local transcripts`,
+            confidence: currentSession.ratioToMedian === null ? "observed" : "derived"
+        });
+    }
+    if ((contextChurn.compactionEvents ?? 0) > 0) {
+        evidence.push({
+            kind: "context_churn",
+            summary: `${contextChurn.compactionEvents} explicit compaction event${contextChurn.compactionEvents === 1 ? "" : "s"} observed in the current session transcript.`,
+            source: `${currentSession?.agent ?? "coding-agent"} local transcript event metadata`,
+            confidence: "observed"
+        });
+    }
+    if ((contextChurn.repeatedReadEvents ?? 0) > 0) {
+        const files = contextChurn.repeatedFiles
+            .slice(0, 3)
+            .map((file) => `${file.file} ×${file.readCount}`)
+            .join(", ");
+        evidence.push({
+            kind: "context_churn",
+            summary: `${contextChurn.repeatedReadEvents} repeat read event${contextChurn.repeatedReadEvents === 1 ? "" : "s"} observed through explicit file-read tools${files ? ` (${files})` : ""}.`,
+            source: "local transcript tool-call metadata; basenames only",
+            confidence: "observed"
+        });
+    }
+    if (currentSession?.cacheWriteRatioToMedian !== null &&
+        currentSession?.cacheWriteRatioToMedian !== undefined &&
+        currentSession.cacheWriteRatioToMedian >= 1.5) {
+        evidence.push({
+            kind: "context_churn",
+            summary: `${currentSession.cacheWriteTokens.toLocaleString("en-US")} cache-write tokens, ${currentSession.cacheWriteRatioToMedian}× the median of prior same-agent sessions with cache-write data.`,
+            source: `${currentSession.agent} local transcript usage metadata`,
+            confidence: "derived"
+        });
+    }
+    for (const hook of hookItems.slice(0, 3)) {
+        evidence.push({
+            kind: "hook_config",
+            summary: `${hook.group ?? hook.name} is configured on ${hook.event ?? "a lifecycle event"} for ${hostLabel(hook.host)}.`,
+            source: hook.path ?? "installed plugin metadata",
+            confidence: "unmeasured"
+        });
+    }
+    if (hookItems.length > 3) {
+        evidence.push({
+            kind: "hook_config",
+            summary: `${hookItems.length - 3} additional hook-injected context source${hookItems.length - 3 === 1 ? "" : "s"} detected.`,
+            source: "installed plugin metadata",
+            confidence: "unmeasured"
+        });
+    }
+    if (deadContext.deadCount > 0) {
+        evidence.push({
+            kind: "inventory_usage",
+            summary: `${deadContext.deadCount} of ${deadContext.loadedCount} discoverable/schema-loaded item${deadContext.loadedCount === 1 ? "" : "s"} were not invoked in the parsed window.`,
+            source: "local inventory compared with local transcript invocations",
+            confidence: deadContext.unmeasuredDeadCount > 0 ? "unmeasured" : "derived"
+        });
+    }
+    if (activation.invocationUnobservableItems > 0) {
+        evidence.push({
+            kind: "inventory_usage",
+            summary: `${activation.invocationUnobservableItems} configured item${activation.invocationUnobservableItems === 1 ? "" : "s"} cannot be matched to an explicit invocation in the available transcript format and were excluded from never-invoked counts.`,
+            source: "local inventory and transcript capability metadata",
+            confidence: "unmeasured"
+        });
+    }
+    const decision = contextDecision({
+        currentSession,
+        contextChurn,
+        hookInjectedItems: activation.hookInjectedItems,
+        deadContext
+    });
+    return {
+        schemaVersion: 1,
+        generatedAt: now.toISOString(),
+        ...decision,
+        currentSession,
+        activation,
+        deadContext: {
+            loadedItems: deadContext.loadedCount,
+            neverInvokedItems: deadContext.deadCount,
+            measuredNeverInvokedItems: deadContext.measuredDeadCount,
+            unmeasuredNeverInvokedItems: deadContext.unmeasuredDeadCount,
+            windowDays
+        },
+        contextChurn,
+        evidence,
+        provenance: {
+            inventory: "local_agent_configuration",
+            invocations: "local_claude_code_and_codex_transcripts",
+            session: "local_transcript_metadata",
+            hookPayload: "not_executed_or_inferred",
+            uploaded: false
+        },
+        caveats: [
+            "Hook commands are never run by aibill. Configuration proves activation, but runtime output and token size remain unmeasured.",
+            "A session comparison uses local transcript token totals from the same coding agent; it is not a provider charge or a universal context-window measurement.",
+            "Never-invoked means no matching invocation was observed in the selected local transcript window, not that an item has no future value.",
+            "Items whose host transcript does not expose explicit invocation evidence are excluded from never-invoked counts.",
+            "Repeated-read evidence includes only explicit file-read tools and returns basenames only. Shell commands are not guessed to be reads.",
+            "Compaction counts come from explicit transcript markers; absence means not observed in the parsed format, not proof that compaction never occurred.",
+            "No per-session savings claim is made without an observed counterfactual baseline."
+        ]
+    };
+}
+function contextDecision(input) {
+    const ratio = input.currentSession?.ratioToMedian;
+    if (ratio !== null && ratio !== undefined && ratio >= 1.5) {
+        return {
+            status: "start_fresh",
+            recommendation: "start_fresh",
+            headline: `This session is ${ratio}× your same-agent token median.`,
+            action: "Start fresh before a new task; keep this session only while its existing context is directly useful.",
+            confidence: input.currentSession.comparisonSessions >= 3 ? "high" : "medium"
+        };
+    }
+    if ((input.contextChurn.compactionEvents ?? 0) >= 2) {
+        const count = input.contextChurn.compactionEvents;
+        return {
+            status: "start_fresh",
+            recommendation: "start_fresh",
+            headline: `This session has compacted ${count} times.`,
+            action: "Start fresh before the next task; preserve only the concrete state you still need.",
+            confidence: "high"
+        };
+    }
+    if (input.hookInjectedItems > 0) {
+        return {
+            status: "watch",
+            recommendation: "review_hooks",
+            headline: `${input.hookInjectedItems} hook-injected context source${input.hookInjectedItems === 1 ? "" : "s"} detected.`,
+            action: "Review the installed hook sources before removing anything; their runtime payload size is not measurable from configuration.",
+            confidence: "medium"
+        };
+    }
+    if (input.deadContext.hasData && input.deadContext.deadCount > 0) {
+        return {
+            status: "watch",
+            recommendation: "trim_dead_context",
+            headline: `${input.deadContext.deadCount} loaded item${input.deadContext.deadCount === 1 ? "" : "s"} were not invoked in this window.`,
+            action: "Lazy-load or remove only the items you do not expect to need, then re-run Context Health.",
+            confidence: input.deadContext.unmeasuredDeadCount > 0 ? "medium" : "high"
+        };
+    }
+    if (input.currentSession && input.currentSession.comparisonSessions > 0) {
+        return {
+            status: "healthy",
+            recommendation: "continue",
+            headline: "No evidence-backed context action is needed.",
+            action: "Continue in this session while its context remains useful.",
+            confidence: input.currentSession.comparisonSessions >= 3 ? "high" : "medium"
+        };
+    }
+    return {
+        status: "insufficient_data",
+        recommendation: "collect_more_history",
+        headline: "More local session history is needed for a context recommendation.",
+        action: "Keep using your coding agents, then re-run Context Health after a few sessions.",
+        confidence: "low"
+    };
+}
+function buildCurrentSession(sessions, now, activeWithinMinutes) {
+    const latest = latestContextSession(sessions);
+    if (!latest)
+        return null;
+    const comparisons = sessions.filter((session) => (session.key !== latest.key &&
+        session.agent === latest.agent &&
+        session.totalTokens > 0));
+    const baseline = median(comparisons.map((session) => session.totalTokens));
+    const cacheWriteBaseline = median(comparisons
+        .map((session) => session.cacheWriteTokens)
+        .filter((tokens) => tokens > 0));
+    const ratio = baseline && baseline > 0
+        ? roundRatio(latest.totalTokens / baseline)
+        : null;
+    const ageMs = Math.max(0, now.getTime() - Date.parse(latest.lastActivityAt));
+    return {
+        status: ageMs <= activeWithinMinutes * 60_000 ? "active" : "recent",
+        agent: latest.agent,
+        project: latest.project,
+        totalTokens: latest.totalTokens,
+        ratioToMedian: ratio,
+        comparisonSessions: comparisons.length,
+        cacheWriteTokens: latest.cacheWriteTokens,
+        cacheWriteRatioToMedian: cacheWriteBaseline && latest.cacheWriteTokens > 0
+            ? roundRatio(latest.cacheWriteTokens / cacheWriteBaseline)
+            : null,
+        source: "local_transcript_metadata"
+    };
+}
+function contextSessions(calls) {
+    const groups = new Map();
+    calls.forEach((call, index) => {
+        const fallback = `${call.project ?? "unattributed"}:${call.model}:${call.timestamp}:${index}`;
+        const key = `${call.agent}:${call.sessionId ?? fallback}`;
+        groups.set(key, [...(groups.get(key) ?? []), call]);
+    });
+    return [...groups.entries()].map(([key, grouped]) => {
+        const ordered = grouped.slice().sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+        const latest = ordered[ordered.length - 1];
+        return {
+            key,
+            agent: latest.agent,
+            project: latest.project ?? ordered[0]?.project,
+            lastActivityAt: latest.timestamp,
+            totalTokens: ordered.reduce((total, call) => total + (call.usage.inputTokens +
+                call.usage.outputTokens +
+                (call.usage.cacheReadTokens ?? 0) +
+                (call.usage.cacheWrite5mTokens ?? 0) +
+                (call.usage.cacheWrite1hTokens ?? 0)), 0),
+            cacheWriteTokens: ordered.reduce((total, call) => total + ((call.usage.cacheWrite5mTokens ?? 0) +
+                (call.usage.cacheWrite1hTokens ?? 0)), 0)
+        };
+    });
+}
+function latestContextSession(sessions) {
+    return sessions
+        .slice()
+        .sort((left, right) => right.lastActivityAt.localeCompare(left.lastActivityAt))[0];
+}
+function buildContextChurn(latest, invocations) {
+    const signals = invocations.sessionSignals ?? [];
+    const currentSignal = latest
+        ? signals.find((signal) => (signal.agent === latest.agent &&
+            signal.sessionId &&
+            latest.key === `${signal.agent}:${signal.sessionId}`))
+        : undefined;
+    const repeatedFiles = (currentSignal?.repeatedFileReads ?? [])
+        .map((file) => ({ file: file.name, readCount: file.count }));
+    return {
+        currentSessionEvidence: !latest
+            ? "no_current_session"
+            : currentSignal
+                ? "matched"
+                : "not_matched",
+        compactionEvents: currentSignal?.compactionEvents ?? null,
+        explicitFileReads: currentSignal
+            ? currentSignal.fileReads.reduce((total, file) => total + file.count, 0)
+            : null,
+        repeatedReadEvents: currentSignal
+            ? repeatedFiles.reduce((total, file) => total + file.readCount - 1, 0)
+            : null,
+        repeatedFiles,
+        readCoverage: currentSignal?.readCoverage ?? "not_available",
+        currentSessionScope: currentSignal
+            ? currentSignal.isSubagent
+                ? "subagent"
+                : "parent"
+            : latest
+                ? "unknown"
+                : null,
+        observedParentSessions: signals.filter((signal) => !signal.isSubagent).length,
+        observedSubagentSessions: signals.filter((signal) => signal.isSubagent).length
+    };
+}
+function activationSummary(items, invocations) {
+    return {
+        discoverableItems: items.filter((item) => item.activation === "discoverable").length,
+        explicitlyInvokedItems: items.filter((item) => itemWasInvoked(item, invocations)).length,
+        hookInjectedItems: items.filter((item) => item.activation === "hook_injected").length,
+        lifecycleHooks: items.filter((item) => item.activation === "lifecycle_hook").length,
+        mcpSchemaLoadedItems: items.filter((item) => item.activation === "mcp_schema_loaded").length,
+        unmeasuredItems: items.filter((item) => item.weightConfidence !== "estimated").length,
+        invocationUnobservableItems: items.filter((item) => item.kind !== "hook" && item.invocationTracking === "not_observable").length
+    };
+}
+function itemWasInvoked(item, invocations) {
+    if (item.invocationTracking === "not_observable")
+        return false;
+    switch (item.kind) {
+        case "skill":
+            return invocations.invokedSkills.includes(item.name);
+        case "subagent":
+            return invocations.invokedSubagents.includes(item.name);
+        case "command":
+            return invocations.invokedCommands.includes(item.name);
+        case "mcp_tool":
+            return invocations.invokedMcpTools.includes(item.name);
+        case "mcp_server":
+            return invocations.invokedMcpTools.some((tool) => tool.split("__")[1] === item.name);
+        case "hook":
+            return false;
+    }
+}
+function emptyInvocations() {
+    return {
+        invocations: [],
+        invokedMcpTools: [],
+        invokedSkills: [],
+        invokedSubagents: [],
+        invokedCommands: [],
+        sessions: 0,
+        totalAssistantTurns: 0,
+        sessionTurnCounts: [],
+        sourceSessions: { claudeCode: 0, codex: 0 }
+    };
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = values.slice().sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[middle - 1] + sorted[middle]) / 2
+        : sorted[middle];
+}
+function roundRatio(value) {
+    return Math.round(value * 10) / 10;
+}
+function hostLabel(host) {
+    if (host === "claude-code")
+        return "Claude Code";
+    if (host === "codex")
+        return "Codex";
+    return "an agent host";
+}
+/** Exposed for deterministic benchmark fixtures. */
+export const CONTEXT_HEALTH_DEFAULT_WINDOW_DAYS = DEFAULT_WINDOW_DAYS;
+export const CONTEXT_HEALTH_DAY_MS = DAY_MS;
+//# sourceMappingURL=contextHealth.js.map

package/dist/deadContext.js

@@ -3,7 +3,7 @@ import { findPricingRule } from "./modelPricing.js";
 import { loadToolInvocations } from "./toolInvocations.js";
 /**
  * Dead-context: the tools an agent LOADS into context but NEVER calls. Compares
- * the local Claude Code inventory (skills, subagents, slash commands, MCP
+ * the local agent inventory (skills, subagents, slash commands, MCP
  * servers — {@link loadAgentInventory}) against what real transcripts show was
  * invoked ({@link loadToolInvocations}).
  *
@@ -18,6 +18,8 @@ import { loadToolInvocations } from "./toolInvocations.js";
  *    surface as `unmeasuredDeadCount` so the renderer can say "not measurable".
  *  - Pricing is cache-aware (one cache write/session + a read/turn), never the
  *    inflated full-input-rate-every-turn number.
+ *  - Items whose host transcript does not expose matchable invocation evidence
+ *    are excluded instead of being falsely classified as dead.
  */
 const DEFAULT_WINDOW_DAYS = 30;
 /**
@@ -75,6 +77,11 @@ export function computeDeadContext(items, invocations, config) {
     const dead = [];
     let loadedCount = 0;
     for (const item of items) {
+        // Lifecycle hooks are activation evidence, not prunable inventory. Their
+        // runtime output cannot be inferred from config and they cannot be called
+        // like a skill/tool, so classifying them as "never invoked" would be false.
+        if (item.kind === "hook" || item.invocationTracking === "not_observable")
+            continue;
         loadedCount += 1;
         if (!isDead(item, { usedSkills, usedSubagents, usedCommands, usedMcpTools, usedMcpServers })) {
             continue;
@@ -157,6 +164,8 @@ function isDead(item, used) {
             return !used.usedMcpTools.has(item.name);
         case "mcp_server":
             return !used.usedMcpServers.has(item.name);
+        case "hook":
+            return false;
         default:
             return false;
     }

package/dist/discovery.d.ts

@@ -3,14 +3,27 @@ export type UsageSignal = {
     provider: string;
     kind: UsageSignalKind;
     filePath: string;
+    /** Stable rule identity; present on scanner-produced signals. */
+    ruleId?: string;
+    /** Structured, non-content evidence; present on scanner-produced signals. */
+    evidenceMeta?: UsageSignalEvidence;
+    /** JSON encoding of evidenceMeta retained for registry/backward compatibility. */
     evidence: string;
     confidence: number;
 };
+export type UsageSignalEvidence = {
+    file: string;
+    provider: string;
+    signal: UsageSignalKind;
+    ruleId: string;
+};
 export type LocalDiscoveryResult = {
     rootPath: string;
     scannedFiles: number;
     skippedDirectories: string[];
-    /** Paths that could not be read (permissions, dangling symlinks, non-UTF8) — skipped, never fatal. */
+    /** Symbolic links found below the approved root. They are never followed. */
+    skippedSymlinks: string[];
+    /** Paths that could not be read (permissions, vanished entries, non-UTF8) — skipped, never fatal. */
     unreadablePaths: string[];
     signals: UsageSignal[];
     secretsDetected: string[];

package/dist/discovery.js

@@ -1,5 +1,6 @@
-import { readdir, readFile, stat } from "node:fs/promises";
+import { lstat, readdir, readFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
+import { resolveSafeScanRoot } from "./scanGuard.js";
 const skippedDirectoryNames = new Set([
     ".git",
     "node_modules",
@@ -8,24 +9,25 @@ const skippedDirectoryNames = new Set([
     ".next",
     ".turbo",
     "coverage",
+    ".ai-spend-agent",
     ".ssh",
     "Keychains"
 ]);
 const maxFileBytes = 512_000;
 const providerRules = [
-    { provider: "anthropic", kind: "dependency", patterns: [/@anthropic-ai\/sdk/, /anthropic/i], confidence: 0.9 },
-    { provider: "langfuse", kind: "dependency", patterns: [/langfuse/i], confidence: 0.82 },
-    { provider: "openai", kind: "dependency", patterns: [/"openai"\s*:/, /from\s+["']openai["']/, /OPENAI_API_KEY/], confidence: 0.9 },
-    { provider: "vercel-ai-sdk", kind: "dependency", patterns: [/"ai"\s*:/, /from\s+["']ai["']/], confidence: 0.78 },
-    { provider: "litellm", kind: "config", patterns: [/litellm/i, /model_list:/], confidence: 0.84 },
-    { provider: "helicone", kind: "environment", patterns: [/HELICONE_API_KEY/, /helicone/i], confidence: 0.8 },
-    { provider: "cursor", kind: "invoice", patterns: [/cursor/i], confidence: 0.76 },
-    { provider: "replit", kind: "invoice", patterns: [/replit/i], confidence: 0.72 }
+    { id: "provider.anthropic.dependency", provider: "anthropic", kind: "dependency", patterns: [/@anthropic-ai\/sdk/, /anthropic/i], confidence: 0.9 },
+    { id: "provider.langfuse.dependency", provider: "langfuse", kind: "dependency", patterns: [/langfuse/i], confidence: 0.82 },
+    { id: "provider.openai.dependency", provider: "openai", kind: "dependency", patterns: [/"openai"\s*:/, /from\s+["']openai["']/, /OPENAI_API_KEY/], confidence: 0.9 },
+    { id: "provider.vercel-ai-sdk.dependency", provider: "vercel-ai-sdk", kind: "dependency", patterns: [/"ai"\s*:/, /from\s+["']ai["']/], confidence: 0.78 },
+    { id: "provider.litellm.config", provider: "litellm", kind: "config", patterns: [/litellm/i, /model_list:/], confidence: 0.84 },
+    { id: "provider.helicone.environment", provider: "helicone", kind: "environment", patterns: [/HELICONE_API_KEY/, /helicone/i], confidence: 0.8 },
+    { id: "provider.cursor.invoice", provider: "cursor", kind: "invoice", patterns: [/cursor/i], confidence: 0.76 },
+    { id: "provider.replit.invoice", provider: "replit", kind: "invoice", patterns: [/replit/i], confidence: 0.72 }
 ];
 // Name-based redaction: any UPPER_SNAKE env-style assignment whose name ends
 // in a secret-ish suffix. `KEY` deliberately subsumes API_KEY/ADMIN_KEY/etc —
 // over-redacting a public key is harmless; leaking a private one is not.
-const secretAssignmentPattern = /\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|AUTH))\s*=\s*([^\s#"']+)/g;
+const secretAssignmentPattern = /\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|AUTH))\s*(?:=|:)\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s#]+)/g;
 // Value-based redaction: known secret shapes regardless of how they're named.
 const providerSecretPatterns = [
     /sk-proj-[A-Za-z0-9_-]{20,}/g,
@@ -48,10 +50,12 @@ const providerSecretPatterns = [
     /\bnpm_[A-Za-z0-9]{30,}\b/g
 ];
 export async function scanLocalUsageSignals(rootPath) {
+    const canonicalRoot = await resolveSafeScanRoot(rootPath);
     const result = {
-        rootPath,
+        rootPath: canonicalRoot,
         scannedFiles: 0,
         skippedDirectories: [],
+        skippedSymlinks: [],
         unreadablePaths: [],
         signals: [],
         secretsDetected: [],
@@ -59,18 +63,24 @@ export async function scanLocalUsageSignals(rootPath) {
     };
     const secrets = new Set();
     const skipped = new Set();
+    const symlinks = new Set();
     const unreadable = new Set();
-    await walk(rootPath, async (path) => {
-        // A dangling symlink, permission-denied entry, or unreadable file must
-        // never reject the whole scan — real machines are messy. Skip and report.
+    await walk(canonicalRoot, async (path) => {
+        // A permission-denied, vanished, or unreadable file must never reject the
+        // whole scan — real machines are messy. Symlinks are handled by walk and
+        // never reach this callback.
         let fileInfo;
         try {
-            fileInfo = await stat(path);
+            fileInfo = await lstat(path);
         }
         catch {
             unreadable.add(path);
             return;
         }
+        if (fileInfo.isSymbolicLink()) {
+            symlinks.add(path);
+            return;
+        }
         if (fileInfo.size > maxFileBytes || !isInterestingFile(path)) {
             return;
         }
@@ -83,7 +93,7 @@ export async function scanLocalUsageSignals(rootPath) {
             return;
         }
         const redacted = redactSecrets(raw);
-        const relativePath = relative(rootPath, path) || basename(path);
+        const relativePath = relative(canonicalRoot, path) || basename(path);
         result.scannedFiles += 1;
         for (const name of detectSecretNames(raw)) {
             secrets.add(name);
@@ -97,19 +107,25 @@ export async function scanLocalUsageSignals(rootPath) {
             if (!matchedPattern) {
                 continue;
             }
-            const evidence = buildEvidence(relativePath, rule.provider, redacted);
+            const kind = inferKind(path, rule.kind);
+            const evidenceMeta = buildEvidence(relativePath, rule.provider, kind, rule.id);
             result.signals.push({
                 provider: rule.provider,
-                kind: inferKind(path, rule.kind),
+                kind,
                 filePath: relativePath,
-                evidence,
+                ruleId: rule.id,
+                evidenceMeta,
+                evidence: encodeEvidence(evidenceMeta),
                 confidence: rule.confidence
             });
         }
-    }, skipped, unreadable);
+    }, skipped, symlinks, unreadable);
     result.skippedDirectories = Array.from(skipped).sort();
+    result.skippedSymlinks = Array.from(symlinks)
+        .map((path) => relative(canonicalRoot, path) || basename(path))
+        .sort();
     result.unreadablePaths = Array.from(unreadable)
-        .map((path) => relative(rootPath, path) || basename(path))
+        .map((path) => relative(canonicalRoot, path) || basename(path))
         .sort();
     result.secretsDetected = Array.from(secrets).sort();
     result.signals = dedupeSignals(result.signals).sort((left, right) => {
@@ -135,7 +151,7 @@ function detectSecretNames(text) {
     }
     return Array.from(names);
 }
-async function walk(rootPath, visit, skipped, unreadable) {
+async function walk(rootPath, visit, skipped, symlinks, unreadable) {
     let entries;
     try {
         entries = await readdir(rootPath, { withFileTypes: true });
@@ -147,15 +163,19 @@ async function walk(rootPath, visit, skipped, unreadable) {
     }
     for (const entry of entries) {
         const path = join(rootPath, entry.name);
+        if (entry.isSymbolicLink()) {
+            symlinks.add(path);
+            continue;
+        }
         if (entry.isDirectory()) {
             if (skippedDirectoryNames.has(entry.name)) {
                 skipped.add(entry.name);
                 continue;
             }
-            await walk(path, visit, skipped, unreadable);
+            await walk(path, visit, skipped, symlinks, unreadable);
             continue;
         }
-        if (entry.isFile() || entry.isSymbolicLink()) {
+        if (entry.isFile()) {
             await visit(path);
         }
     }
@@ -198,17 +218,23 @@ function detectExportSignals(filePath, redacted) {
     }
     const normalizedProvider = provider === "google" ? "gemini" : provider;
     const kind = isInvoice ? "invoice" : "provider_export";
+    const ruleId = `export.${normalizedProvider}.${kind}`;
+    const evidenceMeta = buildEvidence(filePath, normalizedProvider, kind, ruleId);
     return [{
             provider: normalizedProvider,
             kind,
             filePath,
-            evidence: `${filePath}: detected ${normalizedProvider} ${kind.replace("_", " ")}`,
+            ruleId,
+            evidenceMeta,
+            evidence: encodeEvidence(evidenceMeta),
             confidence: isInvoice ? 0.82 : 0.88
         }];
 }
-function buildEvidence(filePath, provider, redacted) {
-    const line = redacted.split(/\r?\n/).find((candidate) => candidate.toLowerCase().includes(provider.split("-")[0]));
-    return line ? `${filePath}: ${line.trim()}` : `${filePath}: detected ${provider} usage signal`;
+function buildEvidence(file, provider, signal, ruleId) {
+    return { file, provider, signal, ruleId };
+}
+function encodeEvidence(evidence) {
+    return JSON.stringify(evidence);
 }
 function dedupeSignals(signals) {
     const byKey = new Map();