@agent-finops/core 0.5.8 → 0.6.0

package/dist/cutList.js

@@ -1,3 +1,4 @@
+import { hasCallLevelProvenance, hasModeledWorkloadEvidence, hasPricedEvidence } from "./schema.js";
 /**
  * Select a non-overlapping subset of cut actions, highest-savings first. An
  * action is added only if none of its records were already claimed by a
@@ -62,18 +63,31 @@ const downgradeSafeOperation = /triage|extract|classif|summary|summari|draft|rep
  * backlog is not.
  */
 const batchSafeOperation = /summar|extract|classif|embed|enrich|index|backfill|digest|report|translat|transcri|batch/i;
-/** Fraction of cost retained on the Batch API (both providers price it at 50%). */
-const batchCostRetained = 0.5;
+/** Published retained-cost fraction for providers whose Batch pricing we explicitly support. */
+const batchCostRetainedByProvider = {
+    openai: 0.5,
+    anthropic: 0.5
+};
 export function generateCutList(records) {
+    // Connected-provider rows are commonly billing buckets, usage aggregates,
+    // seats, or user totals. They may be real financial evidence, but they are
+    // not individual calls. Modeled cuts require an adapter to explicitly attest
+    // `call`/`invocation` granularity and provide a named workload operation.
+    // Local transcript aggregates remain eligible only for the observed-only
+    // context exposure path below; they never earn a modeled savings number.
+    const callLevelRecords = records.filter(hasModeledWorkloadEvidence);
+    const contextEvidenceRecords = records.filter((record) => isLocalAgentRecord(record) || (hasCallLevelProvenance(record) && hasPricedEvidence(record)));
     const actions = [
-        ...modelDowngradeActions(records),
-        ...contextTrimActions(records),
-        ...cacheActions(records),
-        ...batchActions(records)
+        ...modelDowngradeActions(callLevelRecords),
+        ...contextTrimActions(contextEvidenceRecords),
+        ...cacheActions(callLevelRecords),
+        ...batchActions(callLevelRecords)
     ];
     return actions
-        .filter((action) => action.estimatedMonthlySavingsUsd >= 0.5)
+        .filter((action) => (action.impactBasis === "observed_value_no_counterfactual" ||
+        action.estimatedMonthlySavingsUsd >= 0.5))
         .sort((left, right) => right.estimatedMonthlySavingsUsd - left.estimatedMonthlySavingsUsd ||
+        right.affectedSpendUsd - left.affectedSpendUsd ||
         left.id.localeCompare(right.id));
 }
 /** Sum of all per-action estimated monthly savings. */
@@ -85,13 +99,13 @@ function modelDowngradeActions(records) {
     const groups = new Map();
     for (const record of records) {
         const rule = downgradeRules.find((candidate) => candidate.match.test(record.model));
-        if (!rule) {
+        if (!rule || !record.operation || record.workloadSemantics?.downgradeSafe !== true) {
             continue;
         }
-        const operation = record.operation ?? "general";
-        // Only suggest downgrades for clearly downgrade-safe operations, OR when
-        // the operation is unknown (we still flag it, but caveat via confidence).
-        if (record.operation && !downgradeSafeOperation.test(operation)) {
+        const operation = record.operation;
+        // A named, clearly downgrade-safe workload is required. Unknown operations
+        // are not sufficient evidence for a routing counterfactual.
+        if (!downgradeSafeOperation.test(operation)) {
             continue;
         }
         const key = `${record.model}::${operation}::${rule.target}`;
@@ -111,7 +125,8 @@ function modelDowngradeActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
-            recordUnit: groupRecords.every(isLocalAgentRecord) ? "session-days" : "calls",
+            recordUnit: groupRecords.every(isLocalAgentRecord) ? "daily-aggregates" : "calls",
+            impactBasis: "modeled_savings",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "model_downgrade"
@@ -120,7 +135,6 @@ function modelDowngradeActions(records) {
     return actions;
 }
 function contextTrimActions(records) {
-    const window = windowDays(records);
     const heavy = records.filter((record) => record.inputTokens >= 100_000);
     if (heavy.length === 0) {
         return [];
@@ -128,31 +142,40 @@ function contextTrimActions(records) {
     const byOperation = new Map();
     for (const record of heavy) {
         const operation = record.operation ?? "large-context calls";
-        byOperation.set(operation, [...(byOperation.get(operation) ?? []), record]);
+        const key = isLocalAgentRecord(record)
+            ? `local::${record.agentId ?? "unknown-agent"}::${record.projectId ?? "unattributed"}`
+            : `connected::${operation}`;
+        byOperation.set(key, [...(byOperation.get(key) ?? []), record]);
     }
     const actions = [];
-    for (const [operation, groupRecords] of byOperation) {
+    for (const [key, groupRecords] of byOperation) {
         const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
-        // Trimming oversized retrieval/context conservatively recovers ~25% of the
-        // input-token cost on these large calls.
-        const windowSavings = affectedSpendUsd * 0.25;
-        const monthlySavings = roundMoney(toMonthly(windowSavings, window));
         const sessionAggregates = groupRecords.every(isLocalAgentRecord);
+        const operation = sessionAggregates
+            ? groupRecords[0]?.operation ?? "coding-agent activity"
+            : key.replace(/^connected::/, "");
         const count = groupRecords.length;
+        const agent = groupRecords[0]?.agentId ?? "coding-agent";
+        const project = groupRecords[0]?.projectId;
+        // Large token volume proves exposure, not that context is removable or
+        // what quality/cost delta a change would produce. Context remains an
+        // inspect-only action until matched before/after evidence exists.
+        const monthlySavings = 0;
         actions.push({
-            id: `trim-${slug(operation)}`,
+            id: sessionAggregates
+                ? `inspect-context-${slug(agent)}-${slug(project ?? "unattributed")}`
+                : `inspect-context-${slug(operation)}`,
             title: sessionAggregates
-                ? `Trim heavy context in ${operation}`
-                : `Trim oversized context on ${operation}`,
-            // Coding-agent sessions are aggregated per day — the honest levers are
-            // the context loaded every turn, not "prompt size" on a single call.
+                ? `Investigate cumulative context in ${agent}${project ? ` · ${project}` : " · Unattributed"}`
+                : `Inspect oversized context on ${operation}`,
             action: sessionAggregates
-                ? `${count} session-day${count === 1 ? "" : "s"} averaged >=100k input tokens per record. Cut dead context first (unused MCP servers/skills — see above), keep CLAUDE.md/AGENTS.md lean, and avoid pulling whole directories into context.`
-                : `Cap retrieval/prompt size on ${count} large ${operation} call${count === 1 ? "" : "s"} (>=100k input tokens) before they fan out.`,
+                ? `${count} day + agent + model + project aggregate${count === 1 ? "" : "s"} contained at least 100k summed input/cache tokens. Inspect per-session context, compactions, repeated reads, and measured instruction-file size before proposing one reversible change.`
+                : `${count} call-level ${operation} record${count === 1 ? "" : "s"} exceeded 100k input tokens. Inspect retrieved chunks and prompt history, then run a matched before/after before claiming savings.`,
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: count,
-            recordUnit: sessionAggregates ? "session-days" : "calls",
+            recordUnit: sessionAggregates ? "daily-aggregates" : "calls",
+            impactBasis: "observed_value_no_counterfactual",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "context_trim"
@@ -164,7 +187,8 @@ function cacheActions(records) {
     const window = windowDays(records);
     const counts = new Map();
     for (const record of records) {
-        if (!record.operation) {
+        const fingerprint = record.workloadSemantics?.stableInputFingerprint;
+        if (!record.operation || !fingerprint) {
             continue;
         }
         // Local agent logs aggregate interactive sessions under one operation
@@ -174,25 +198,35 @@ function cacheActions(records) {
         if (isLocalAgentRecord(record)) {
             continue;
         }
-        counts.set(record.operation, [...(counts.get(record.operation) ?? []), record]);
+        const key = JSON.stringify([record.source.provider, record.model, record.operation, fingerprint]);
+        const current = counts.get(key);
+        counts.set(key, {
+            operation: record.operation,
+            records: [...(current?.records ?? []), record]
+        });
     }
     const actions = [];
-    for (const [operation, groupRecords] of counts) {
-        if (groupRecords.length < 3) {
+    for (const [key, group] of counts) {
+        const { operation, records: groupRecords } = group;
+        if (groupRecords.length < 2) {
             continue;
         }
+        const chronological = [...groupRecords].sort((left, right) => left.timestamp.localeCompare(right.timestamp) || left.id.localeCompare(right.id));
+        // The first observation is the canonical miss. Only subsequent calls with
+        // the same explicit fingerprint are modeled as avoidable cache hits.
+        const avoidableRecords = chronological.slice(1);
         const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
-        // Caching repeated identical-ish operations conservatively recovers ~20%.
-        const windowSavings = affectedSpendUsd * 0.2;
+        const windowSavings = sumRecords(avoidableRecords);
         const monthlySavings = roundMoney(toMonthly(windowSavings, window));
         actions.push({
-            id: `cache-${slug(operation)}`,
+            id: `cache-${slug(operation)}-${stableSuffix(key)}`,
             title: `Cache repeated ${operation} calls`,
-            action: `Add a result cache for ${operation} (${groupRecords.length} repeated call${groupRecords.length === 1 ? "" : "s"}) so identical inputs do not re-bill.`,
+            action: `Keep the earliest ${operation} call as the canonical miss and cache the ${avoidableRecords.length} subsequent call${avoidableRecords.length === 1 ? "" : "s"} with the same adapter-provided input fingerprint.`,
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
             recordUnit: "calls",
+            impactBasis: "modeled_savings",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "cache"
@@ -204,27 +238,43 @@ function batchActions(records) {
     const window = windowDays(records);
     const byOperation = new Map();
     for (const record of records) {
-        if (!record.operation || !batchSafeOperation.test(record.operation)) {
+        if (!record.operation ||
+            record.workloadSemantics?.batchEligible !== true ||
+            batchCostRetainedByProvider[record.source.provider] === undefined ||
+            !batchSafeOperation.test(record.operation)) {
             continue;
         }
-        byOperation.set(record.operation, [...(byOperation.get(record.operation) ?? []), record]);
+        const key = JSON.stringify([
+            record.source.id,
+            record.source.provider,
+            record.model,
+            record.operation
+        ]);
+        const current = byOperation.get(key);
+        byOperation.set(key, {
+            operation: record.operation,
+            records: [...(current?.records ?? []), record]
+        });
     }
     const actions = [];
-    for (const [operation, groupRecords] of byOperation) {
+    for (const [key, group] of byOperation) {
+        const { operation, records: groupRecords } = group;
         if (groupRecords.length < 3) {
             continue;
         }
         const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
-        const windowSavings = affectedSpendUsd * (1 - batchCostRetained);
+        const retainedCost = batchCostRetainedByProvider[groupRecords[0].source.provider];
+        const windowSavings = affectedSpendUsd * (1 - retainedCost);
         const monthlySavings = roundMoney(toMonthly(windowSavings, window));
         actions.push({
-            id: `batch-${slug(operation)}`,
+            id: `batch-${slug(operation)}-${stableSuffix(key)}`,
             title: `Move ${operation} calls to the Batch API`,
             action: `Submit ${groupRecords.length} ${operation} call${groupRecords.length === 1 ? "" : "s"} through the provider's Batch API (flat 50% off; results within 24h, fine for offline work).`,
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
             recordUnit: "calls",
+            impactBasis: "modeled_savings",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "batch"
@@ -265,6 +315,14 @@ function combinedConfidence(confidences) {
 function slug(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "x";
 }
+function stableSuffix(value) {
+    let hash = 2_166_136_261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return (hash >>> 0).toString(36);
+}
 function roundMoney(value) {
     return Math.round(value * 100) / 100;
 }

package/dist/deadContext.d.ts

@@ -4,11 +4,15 @@ import type { CutAction } from "./cutList.js";
 export type DeadContextItem = {
     kind: InventoryItem["kind"];
     name: string;
+    scope: InventoryItem["scope"];
+    activation: InventoryItem["activation"];
+    host?: InventoryItem["host"];
+    invocationTracking: InventoryItem["invocationTracking"];
     alwaysLoadedTokens: number;
     weightConfidence: InventoryItem["weightConfidence"];
-    /** Config file the item is loaded from — the place to remove it. */
+    /** Config/catalog file where the item was observed. */
     path?: string;
-    /** Project dirs that load this item (where `claude mcp remove` must run). */
+    /** Owning project dirs when scope is local or project. */
     ownerDirs?: string[];
 };
 export type DeadContextResult = {
@@ -18,7 +22,7 @@ export type DeadContextResult = {
     isSample?: boolean;
     /** Prunable inventory items considered (built-ins excluded upstream). */
     loadedCount: number;
-    /** Items never invoked across the parsed window (the defensible headline). */
+    /** Observable items with no matching invocation in the parsed window. */
     deadCount: number;
     /** Dead items whose token weight we MEASURED (skills/subagents/commands). */
     measuredDeadCount: number;
@@ -34,7 +38,7 @@ export type DeadContextResult = {
     monthlyUsd: number;
     /** Upper bound (no prompt caching), measured items only. */
     monthlyUsdUpperBound: number;
-    /** The never-used items, heaviest first. */
+    /** The not-observed candidates, measured weight first. */
     deadItems: DeadContextItem[];
     sessions: number;
     totalTurns: number;

package/dist/deadContext.js

@@ -2,20 +2,20 @@ import { loadAgentInventory } from "./agentInventory.js";
 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 agent inventory (skills, subagents, slash commands, MCP
- * servers — {@link loadAgentInventory}) against what real transcripts show was
- * invoked ({@link loadToolInvocations}).
+ * Inventory-use evidence: compare locally configured/discoverable agent items
+ * with explicit invocations in supported transcripts. Configuration alone does
+ * not prove an item's full payload was loaded, and absence of an observed call
+ * does not prove that an item has no future value.
  *
  * ACCURACY CONTRACT (this is the credibility lever — read before changing):
  *  - The COUNT + utilization % is always defensible and is the headline.
  *  - A token/$ magnitude is ONLY computed from items whose weight we actually
  *    MEASURED — skill/subagent/command frontmatter (weightConfidence
  *    "estimated"). We never price items whose weight we could not measure.
- *  - MCP servers have NO readable schemas in local config, so their real
- *    weight is unknown. They are COUNTED as dead but NEVER assigned a $/token
- *    figure — to size them we'd have to query each server's tools/list. They
- *    surface as `unmeasuredDeadCount` so the renderer can say "not measurable".
+ *  - MCP config has no runtime schemas and current hosts can defer tool loading.
+ *    Configured servers are counted as not-observed candidates but NEVER
+ *    assigned a $/token figure. Explicit alwaysLoad is preserved as activation
+ *    evidence while its payload size remains unmeasured.
  *  - 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
@@ -29,8 +29,10 @@ const DEFAULT_WINDOW_DAYS = 30;
 const DEFAULT_PRICING_MODEL = "claude-sonnet-4";
 /** Load inventory + invocations from disk (or use injected ones) and price the waste. */
 export async function loadDeadContext(options = {}) {
-    const inventory = options.inventory ?? (await loadAgentInventory(options));
-    const invocations = options.invocations ?? (await loadToolInvocations(options));
+    const [inventory, invocations] = await Promise.all([
+        options.inventory ?? loadAgentInventory(options),
+        options.invocations ?? loadToolInvocations(options)
+    ]);
     return computeDeadContext(inventory.items, invocations, {
         windowDays: options.windowDays ?? DEFAULT_WINDOW_DAYS,
         pricingModel: options.pricingModel ?? DEFAULT_PRICING_MODEL
@@ -68,12 +70,6 @@ export function computeDeadContext(items, invocations, config) {
     const windowDays = Math.max(1, config.windowDays);
     const sessions = invocations.sessions;
     const totalTurns = invocations.totalAssistantTurns;
-    const usedSkills = new Set(invocations.invokedSkills);
-    const usedSubagents = new Set(invocations.invokedSubagents);
-    const usedCommands = new Set(invocations.invokedCommands);
-    const usedMcpTools = new Set(invocations.invokedMcpTools);
-    // An MCP server counts as "used" if any invoked mcp tool belongs to it.
-    const usedMcpServers = new Set(invocations.invokedMcpTools.map((tool) => tool.split("__")[1]).filter((id) => Boolean(id)));
     const dead = [];
     let loadedCount = 0;
     for (const item of items) {
@@ -82,13 +78,30 @@ export function computeDeadContext(items, invocations, config) {
         // like a skill/tool, so classifying them as "never invoked" would be false.
         if (item.kind === "hook" || item.invocationTracking === "not_observable")
             continue;
+        const evidence = invocationEvidenceFor(item.host, invocations);
+        const hasMatchingHostCoverage = evidence.sessions > 0 && evidence.totalAssistantTurns > 0;
+        // Once host-isolated evidence is available, another host's transcripts are
+        // never an observation opportunity for this item and do not enter the
+        // candidate denominator. Hostless legacy fixtures keep the old global
+        // inventory-count behavior while still producing no candidate without data.
+        if (item.host && invocations.byHost && !hasMatchingHostCoverage)
+            continue;
         loadedCount += 1;
-        if (!isDead(item, { usedSkills, usedSubagents, usedCommands, usedMcpTools, usedMcpServers })) {
+        // Configuration without an observed assistant turn in the selected window
+        // is inventory, not evidence that an item went unused. Keep the configured
+        // count available for coverage reporting, but do not classify candidates.
+        if (!hasMatchingHostCoverage)
+            continue;
+        if (!isDead(item, invocationSets(evidence))) {
             continue;
         }
         dead.push({
             kind: item.kind,
             name: item.name,
+            scope: item.scope,
+            activation: item.activation,
+            host: item.host,
+            invocationTracking: item.invocationTracking,
             alwaysLoadedTokens: item.alwaysLoadedTokens,
             weightConfidence: item.weightConfidence,
             path: item.path,
@@ -101,13 +114,31 @@ export function computeDeadContext(items, invocations, config) {
     const measuredDead = dead.filter((item) => item.weightConfidence === "estimated");
     const unmeasuredDead = dead.filter((item) => item.weightConfidence !== "estimated");
     const measuredTokens = measuredDead.reduce((total, item) => total + item.alwaysLoadedTokens, 0);
-    const hasData = items.length > 0 && sessions > 0 && dead.length > 0;
+    const hasData = loadedCount > 0 && dead.length > 0;
     const rates = pricingRates(config.pricingModel);
-    // Cached: one cache write per session + a cache read on every later turn.
-    const cacheReads = Math.max(0, totalTurns - sessions);
-    const windowCachedUsd = (measuredTokens * (sessions * rates.write5mPerM + cacheReads * rates.cacheReadPerM)) / 1_000_000;
-    const windowUncachedUsd = (measuredTokens * totalTurns * rates.inputPerM) / 1_000_000;
     const monthFactor = DEFAULT_WINDOW_DAYS / windowDays;
+    let windowCachedUsd = 0;
+    let windowUncachedUsd = 0;
+    let monthlyDeadTokens = 0;
+    const measuredByCoverage = new Map();
+    for (const item of measuredDead) {
+        const key = item.host && invocations.byHost ? item.host : "global";
+        const current = measuredByCoverage.get(key) ?? {
+            tokens: 0,
+            evidence: invocationEvidenceFor(item.host, invocations)
+        };
+        current.tokens += item.alwaysLoadedTokens;
+        measuredByCoverage.set(key, current);
+    }
+    for (const { tokens, evidence } of measuredByCoverage.values()) {
+        // Cached: one cache write per same-host session + a cache read on every
+        // later same-host turn. Cross-host turns never price this inventory.
+        const cacheReads = Math.max(0, evidence.totalAssistantTurns - evidence.sessions);
+        windowCachedUsd += (tokens * (evidence.sessions * rates.write5mPerM +
+            cacheReads * rates.cacheReadPerM)) / 1_000_000;
+        windowUncachedUsd += (tokens * evidence.totalAssistantTurns * rates.inputPerM) / 1_000_000;
+        monthlyDeadTokens += tokens * evidence.totalAssistantTurns * monthFactor;
+    }
     return {
         hasData,
         loadedCount,
@@ -115,7 +146,7 @@ export function computeDeadContext(items, invocations, config) {
         measuredDeadCount: measuredDead.length,
         unmeasuredDeadCount: unmeasuredDead.length,
         deadTokens: measuredTokens,
-        monthlyDeadTokens: Math.round(measuredTokens * totalTurns * monthFactor),
+        monthlyDeadTokens: Math.round(monthlyDeadTokens),
         wastePercent: loadedCount > 0 ? dead.length / loadedCount : 0,
         monthlyUsd: roundMoney(windowCachedUsd * monthFactor),
         monthlyUsdUpperBound: roundMoney(windowUncachedUsd * monthFactor),
@@ -138,11 +169,12 @@ export function deadContextCutAction(result) {
     const pct = Math.round(result.wastePercent * 100);
     return {
         id: "dead-context",
-        title: `Trim ${result.measuredDeadCount} loaded tool${result.measuredDeadCount === 1 ? "" : "s"} your agent never calls`,
-        action: `Remove or lazy-load ${result.deadCount} of ${result.loadedCount} loaded item${result.loadedCount === 1 ? "" : "s"} ` +
-            `(${pct}% never invoked) to reclaim ~${result.deadTokens.toLocaleString("en-US")} tokens of dead context per turn.`,
+        title: `Review ${result.measuredDeadCount} discoverable item${result.measuredDeadCount === 1 ? "" : "s"} with no observed invocation`,
+        action: `Inspect ${result.deadCount} of ${result.loadedCount} observable inventory item${result.loadedCount === 1 ? "" : "s"} ` +
+            `(${pct}% had no matching invocation) before proposing a scoped disable, lazy-load, or removal.`,
         estimatedMonthlySavingsUsd: result.monthlyUsd,
         affectedSpendUsd: result.monthlyUsd,
+        impactBasis: "modeled_savings",
         recordCount: result.deadCount,
         recordUnit: "tools",
         // Dead-context savings come from inventory, not priced usage records, so
@@ -152,6 +184,31 @@ export function deadContextCutAction(result) {
         kind: "context_trim"
     };
 }
+function invocationEvidenceFor(host, invocations) {
+    if (host && invocations.byHost)
+        return invocations.byHost[host];
+    return {
+        sessions: invocations.sessions,
+        totalAssistantTurns: invocations.totalAssistantTurns,
+        sessionTurnCounts: invocations.sessionTurnCounts,
+        invokedMcpTools: invocations.invokedMcpTools,
+        invokedSkills: invocations.invokedSkills,
+        invokedSubagents: invocations.invokedSubagents,
+        invokedCommands: invocations.invokedCommands
+    };
+}
+function invocationSets(evidence) {
+    return {
+        usedSkills: new Set(evidence.invokedSkills),
+        usedSubagents: new Set(evidence.invokedSubagents),
+        usedCommands: new Set(evidence.invokedCommands),
+        usedMcpTools: new Set(evidence.invokedMcpTools),
+        // An MCP server counts as used only when a same-host MCP tool belongs to it.
+        usedMcpServers: new Set(evidence.invokedMcpTools
+            .map((tool) => tool.split("__")[1])
+            .filter((id) => Boolean(id)))
+    };
+}
 function isDead(item, used) {
     switch (item.kind) {
         case "skill":

package/dist/discovery.d.ts

@@ -2,6 +2,7 @@ export type UsageSignalKind = "dependency" | "config" | "environment" | "source_
 export type UsageSignal = {
     provider: string;
     kind: UsageSignalKind;
+    /** Deterministic opaque reference; never a repository-controlled filename. */
     filePath: string;
     /** Stable rule identity; present on scanner-produced signals. */
     ruleId?: string;
@@ -12,6 +13,7 @@ export type UsageSignal = {
     confidence: number;
 };
 export type UsageSignalEvidence = {
+    /** Same deterministic opaque reference as UsageSignal.filePath. */
     file: string;
     provider: string;
     signal: UsageSignalKind;
@@ -20,12 +22,14 @@ export type UsageSignalEvidence = {
 export type LocalDiscoveryResult = {
     rootPath: string;
     scannedFiles: number;
+    /** Deterministic opaque references for denied/heavy descendant directories. */
     skippedDirectories: string[];
-    /** Symbolic links found below the approved root. They are never followed. */
+    /** Opaque references for symbolic links below the approved root. They are never followed. */
     skippedSymlinks: string[];
-    /** Paths that could not be read (permissions, vanished entries, non-UTF8) — skipped, never fatal. */
+    /** Opaque references for unreadable descendants — skipped, never fatal. */
     unreadablePaths: string[];
     signals: UsageSignal[];
+    /** Deterministic opaque references for detected secret assignments. */
     secretsDetected: string[];
     redactedEvidence: string[];
 };

package/dist/discovery.js

@@ -1,5 +1,6 @@
 import { lstat, readdir, readFile } from "node:fs/promises";
-import { basename, join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { basename, join, relative, sep } from "node:path";
 import { resolveSafeScanRoot } from "./scanGuard.js";
 const skippedDirectoryNames = new Set([
     ".git",
@@ -93,13 +94,15 @@ export async function scanLocalUsageSignals(rootPath) {
             return;
         }
         const redacted = redactSecrets(raw);
-        const relativePath = relative(canonicalRoot, path) || basename(path);
+        const relativePath = relative(canonicalRoot, path) || ".";
+        const pathReference = opaquePathReference(relativePath);
         result.scannedFiles += 1;
         for (const name of detectSecretNames(raw)) {
-            secrets.add(name);
-            result.redactedEvidence.push(`${relativePath}: ${name}=[REDACTED]`);
+            const secretReference = opaqueSecretReference(name);
+            secrets.add(secretReference);
+            result.redactedEvidence.push(`${pathReference}: ${secretReference}=[REDACTED]`);
         }
-        for (const signal of detectExportSignals(relativePath, redacted)) {
+        for (const signal of detectExportSignals(relativePath, redacted, pathReference)) {
             result.signals.push(signal);
         }
         for (const rule of providerRules) {
@@ -108,11 +111,11 @@ export async function scanLocalUsageSignals(rootPath) {
                 continue;
             }
             const kind = inferKind(path, rule.kind);
-            const evidenceMeta = buildEvidence(relativePath, rule.provider, kind, rule.id);
+            const evidenceMeta = buildEvidence(pathReference, rule.provider, kind, rule.id);
             result.signals.push({
                 provider: rule.provider,
                 kind,
-                filePath: relativePath,
+                filePath: pathReference,
                 ruleId: rule.id,
                 evidenceMeta,
                 evidence: encodeEvidence(evidenceMeta),
@@ -120,12 +123,14 @@ export async function scanLocalUsageSignals(rootPath) {
             });
         }
     }, skipped, symlinks, unreadable);
-    result.skippedDirectories = Array.from(skipped).sort();
+    result.skippedDirectories = Array.from(skipped)
+        .map((path) => opaquePathReference(relative(canonicalRoot, path) || "."))
+        .sort();
     result.skippedSymlinks = Array.from(symlinks)
-        .map((path) => relative(canonicalRoot, path) || basename(path))
+        .map((path) => opaquePathReference(relative(canonicalRoot, path) || "."))
         .sort();
     result.unreadablePaths = Array.from(unreadable)
-        .map((path) => relative(canonicalRoot, path) || basename(path))
+        .map((path) => opaquePathReference(relative(canonicalRoot, path) || "."))
         .sort();
     result.secretsDetected = Array.from(secrets).sort();
     result.signals = dedupeSignals(result.signals).sort((left, right) => {
@@ -169,7 +174,7 @@ async function walk(rootPath, visit, skipped, symlinks, unreadable) {
         }
         if (entry.isDirectory()) {
             if (skippedDirectoryNames.has(entry.name)) {
-                skipped.add(entry.name);
+                skipped.add(path);
                 continue;
             }
             await walk(path, visit, skipped, symlinks, unreadable);
@@ -203,7 +208,7 @@ function inferKind(path, fallback) {
     }
     return fallback;
 }
-function detectExportSignals(filePath, redacted) {
+function detectExportSignals(filePath, redacted, pathReference) {
     const lowerPath = filePath.toLowerCase();
     const lowerText = redacted.toLowerCase();
     const providers = ["openai", "anthropic", "cursor", "helicone", "langfuse", "gemini", "google", "replit"];
@@ -219,11 +224,11 @@ 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);
+    const evidenceMeta = buildEvidence(pathReference, normalizedProvider, kind, ruleId);
     return [{
             provider: normalizedProvider,
             kind,
-            filePath,
+            filePath: pathReference,
             ruleId,
             evidenceMeta,
             evidence: encodeEvidence(evidenceMeta),
@@ -236,6 +241,23 @@ function buildEvidence(file, provider, signal, ruleId) {
 function encodeEvidence(evidence) {
     return JSON.stringify(evidence);
 }
+/**
+ * Repository-controlled descendant names are untrusted metadata. Discovery may
+ * use the real relative path internally for classification, but persisted and
+ * agent-facing output receives only this stable, non-semantic reference.
+ */
+function opaquePathReference(relativePath) {
+    // Normalize only the current platform's separator. A literal backslash is
+    // a valid POSIX filename character and must not alias a nested POSIX path.
+    const normalized = (relativePath || ".").split(sep).join("/");
+    const digest = createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 16);
+    return `path-${digest}`;
+}
+/** Repository-controlled environment names are untrusted metadata too. */
+function opaqueSecretReference(name) {
+    const digest = createHash("sha256").update(name, "utf8").digest("hex").slice(0, 16);
+    return `secret-${digest}`;
+}
 function dedupeSignals(signals) {
     const byKey = new Map();
     for (const signal of signals) {

package/dist/glance.d.ts

@@ -11,8 +11,12 @@ export type GlanceSession = {
     durationMinutes: number;
     apiEquivalentUsd: number | null;
     costConfidence: "estimated" | "missing";
-    inputTokens: number;
-    outputTokens: number;
+    /** Null when the transcript reports only a total and no priceable breakdown. */
+    inputTokens: number | null;
+    /** Null when the transcript reports only a total and no priceable breakdown. */
+    outputTokens: number | null;
+    /** Provider-reported total retained without inventing input/output components. */
+    reportedTotalTokens?: number;
 };
 export type GlanceLimit = {
     agent: LocalAgentCall["agent"];
@@ -57,6 +61,8 @@ export type GlanceFocus = {
     confidence: "high" | "medium" | "low";
 };
 export type GlancePrimaryAction = {
+    /** Glance is a bounded session handoff, not the CLI financial apply plan. */
+    kind: "session_handoff";
     intent: "start_fresh" | "review_context" | "trim_context" | "protect_runway" | "continue_focus" | "resume_focus" | "inspect_current_work";
     label: string;
     detail: string;
@@ -67,6 +73,7 @@ export type GlancePrimaryAction = {
     confidence: "high" | "medium" | "low";
     execution: "copy_prompt";
     requiresUserConfirmation: true;
+    evidenceWindowDays: number;
 };
 export type GlanceProvenance = {
     session: {