@agent-finops/core 0.9.5 → 0.9.7

package/README.md

@@ -41,9 +41,9 @@ keep provenance and confidence labels truthful: reserve `verified` for
 official provider-reported financial evidence, keep modeled/local value
 `estimated` or `missing`, and leave unvalidated adapters `untested`.
 
-This is the open foundation for aibill's financial-accountability mission. The
-published v0.9.1 package includes contracts for locally confirmed ownership,
-local self-attested approvals, and opt-in accepted GitHub outcomes. Those are
+This is the open foundation for aibill's financial-accountability mission. This
+package includes contracts for locally confirmed ownership, local
+self-attested approvals, and opt-in accepted GitHub outcomes. Those are
 not company-wide identity, RBAC, approval routing, invoice reconciliation, or
 verified business ROI.
 

package/dist/actionPlanner.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { localAgentFormatDescriptor } from "./localAgentFormats/registry.js";
 import { MAX_TOKEN_EXPERIMENT_SESSIONS_PER_PHASE_V0, MAX_WASTE_FINDING_EVIDENCE_REFS_V0, TOKEN_REDUCTION_EXPERIMENT_V0_KIND, TOKEN_REDUCTION_EXPERIMENT_V0_VERSION, WASTE_FINDING_V0_KIND, WASTE_FINDING_V0_VERSION, createActionVerificationReference, createTokenReductionExperimentV0, createWasteFindingV0 } from "./actionVerification.js";
+import { safeUntrustedLabel, WITHHELD_FILE_LABEL } from "./untrustedLabel.js";
 const MINIMUM_SESSIONS = 3;
 const CONTEXT_RATIO_THRESHOLD = 1.5;
 const FRESH_MS = 72 * 60 * 60 * 1_000;
@@ -196,7 +197,9 @@ export function resolveWasteFindingTargetV0(input) {
                 status: "resolved",
                 kind: "repeated_read_file",
                 ref: finding.target.ref,
-                file: match.file,
+                // Already neutralized upstream; re-applied because a resolved target
+                // is written into the Apply artifact an agent reads.
+                file: safeUntrustedLabel(match.file, WITHHELD_FILE_LABEL),
                 readCount: match.readCount,
                 localOnly: true
             }

package/dist/activitySnapshot.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { aggregateCalls, dedupeCumulativeSessionCalls } from "./localAgentLogs.js";
 import { localAgentFormatDescriptors } from "./localAgentFormats/registry.js";
-import { canPriceTokenUsageAtScope, estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
+import { canPriceTokenUsageAtScope, estimateTokenCostsUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
 import { subscriptionPlans } from "./planMath.js";
 import { isBundledSampleUsage } from "./schema.js";
 import { sourceValidationCoverageValues } from "./sourceStatus.js";
@@ -937,13 +937,22 @@ function apiEquivalentObservations(records, calls, trustedProviderIds) {
     }
     return observations;
 }
+/**
+ * One call's API-equivalent cost with its tier taken from the largest single
+ * request it contains, matching the report's aggregation. Weighting a
+ * session-cumulative slice at its own cache-inflated prompt would put it on the
+ * wrong tier and skew the allocation.
+ */
+function callAmountUsd(call) {
+    return estimateTokenCostsUsd(call.model, [call.usage], [call.maxRequestPromptTokens]);
+}
 function allocateAggregateAmount(amountUsd, calls) {
     if (amountUsd === null)
         return calls.map(() => null);
-    const priceable = calls.map((call) => canPriceTokenUsageAtScope(call.model, call.usage, call.usageScope === "turn" ? "request" : "aggregate") && estimateTokenCostUsd(call.model, call.usage) !== undefined);
+    const priceable = calls.map((call) => canPriceTokenUsageAtScope(call.model, call.usage, call.usageScope === "turn" ? "request" : "aggregate", call.maxRequestPromptTokens) && callAmountUsd(call) !== undefined);
     if (priceable.some((supported) => !supported))
         return calls.map(() => null);
-    const weights = calls.map((call) => estimateTokenCostUsd(call.model, call.usage) ?? 0);
+    const weights = calls.map((call) => callAmountUsd(call) ?? 0);
     const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
     if (totalWeight <= 0) {
         return amountUsd === 0 ? calls.map(() => 0) : calls.map(() => null);

package/dist/analyze.js

@@ -1,4 +1,5 @@
 import { generateSpendInsights } from "./insights.js";
+import { safeUntrustedLabel, safeUntrustedLabels, WITHHELD_AGENT_LABEL, WITHHELD_ENTITY_LABEL, WITHHELD_OPERATION_LABEL } from "./untrustedLabel.js";
 import { costConfidenceValues, hasModeledWorkloadEvidence, hasPricedEvidence, spendComparisonKey, spendSummarySchema } from "./schema.js";
 const confidenceRank = {
     verified: 0,
@@ -154,11 +155,27 @@ export function generateWorkflowWatch(records) {
         const hasRunLevelEvidence = groupRecords.every(hasModeledWorkloadEvidence);
         const suggestedOptimization = workflowDiagnosticFor(workflowKey, agentId, hasRunLevelEvidence);
         return {
-            id: slugify(["workflow", clientId, projectId, workflowKey].join("-")),
-            clientId,
-            projectId,
-            workflowKey,
-            agentId,
+            // The id is a STRUCTURED field beside the neutralized prose and it is
+            // rendered. Slug the neutralized forms, not the raw grouping keys.
+            id: slugify([
+                "workflow",
+                safeEntity(clientId),
+                safeEntity(projectId),
+                safeWorkflowLabel(workflowKey)
+            ].join("-")),
+            // Neutralized, not raw. These fields ship inside the SpendSummary that
+            // the MCP tools hand to an agent, so leaving them raw beside neutralized
+            // prose is the same inversion as the repeated-read array: the human sees
+            // the redaction and the agent gets the payload.
+            //
+            // workflowWatchAmount re-matches these against the records to recompute
+            // a display amount. An ordinary name is byte-identical, so that match is
+            // unaffected; a name that reads like an instruction loses its amount,
+            // which is the right way round.
+            clientId: safeEntity(clientId),
+            projectId: safeEntity(projectId),
+            workflowKey: safeWorkflowLabel(workflowKey),
+            agentId: safeUntrustedLabel(agentId, WITHHELD_AGENT_LABEL),
             amountUsd,
             shareOfSpend,
             recordCount: groupRecords.length,
@@ -168,8 +185,8 @@ export function generateWorkflowWatch(records) {
             suggestedOptimization,
             applyArtifact: `Before changing this workload: ${suggestedOptimization}`,
             verificationPlan: hasRunLevelEvidence
-                ? `Reconcile ${workflowKey} to its owner and budget, then define one reversible candidate and compare matched future accepted outcomes plus provider-reported cost.`
-                : `Reconcile ${workflowKey} to its owner and budget, then collect call-level workload evidence before modeling or applying a cost change.`
+                ? `Reconcile ${safeWorkflowLabel(workflowKey)} to its owner and budget, then define one reversible candidate and compare matched future accepted outcomes plus provider-reported cost.`
+                : `Reconcile ${safeWorkflowLabel(workflowKey)} to its owner and budget, then collect call-level workload evidence before modeling or applying a cost change.`
         };
     })
         .filter((entry) => entry.amountUsd > 0)
@@ -186,16 +203,16 @@ export function generateRecommendations(records) {
         recommendations.push({
             id: "model-downgrade",
             title: "Review expensive model workloads for downgrade candidates",
-            rationale: `${topModel.key} is the largest cost driver in the current local sample.`,
+            rationale: `${safeEntity(topModel.key)} is the largest cost driver in the current local sample.`,
             whyItMatters: "Premium model usage tends to become invisible once agents are running in the background. Spend owners need a clear rule for which jobs deserve the expensive model.",
-            nextAction: `Audit the top ${topModel.key} operations and move low-risk summarization, extraction, and draft work to a cheaper model tier first.`,
+            nextAction: `Audit the top ${safeEntity(topModel.key)} operations and move low-risk summarization, extraction, and draft work to a cheaper model tier first.`,
             priority: "high",
             // The high-level recommendation does not know which model-specific rule
             // will pass quality verification. Dollar math lives in the exact cut
             // candidate; concentration alone earns no flat percentage.
             estimatedImpactUsd: 0,
             confidence: topModel.confidence,
-            relatedKeys: [topModel.key]
+            relatedKeys: [safeEntity(topModel.key)]
         });
     }
     const highInputTokenRecords = decisionRecords.filter((record) => record.inputTokens >= 100_000);
@@ -209,7 +226,7 @@ export function generateRecommendations(records) {
             priority: "high",
             estimatedImpactUsd: 0,
             confidence: combinedConfidence(highInputTokenRecords.map((record) => record.costConfidence)),
-            relatedKeys: unique(highInputTokenRecords.map((record) => record.model))
+            relatedKeys: safeUntrustedLabels(unique(highInputTokenRecords.map((record) => record.model)))
         });
     }
     // An operation label alone does not prove identical inputs. Require an
@@ -229,7 +246,7 @@ export function generateRecommendations(records) {
             priority: "medium",
             estimatedImpactUsd: roundMoney(sumRecords(cacheableRecords)),
             confidence: combinedConfidence(cacheableRecords.map((record) => record.costConfidence)),
-            relatedKeys: repeatedOperations
+            relatedKeys: safeUntrustedLabels(repeatedOperations, WITHHELD_OPERATION_LABEL)
         });
     }
     const agentSpend = breakdown(decisionRecords, (record) => record.agentId);
@@ -238,13 +255,13 @@ export function generateRecommendations(records) {
         recommendations.push({
             id: "agent-caps",
             title: "Confirm the owner and budget for the highest-cost agent",
-            rationale: `${topAgent.key} accounts for a material share of sampled usage.`,
+            rationale: `${safeEntity(topAgent.key)} accounts for a material share of sampled usage.`,
             whyItMatters: "Concentration is an accountability signal, but it does not by itself prove abnormal behavior or an avoidable dollar amount.",
-            nextAction: `Confirm ${topAgent.key}'s owner and approved range, then collect run-level evidence before proposing a warning threshold or hard cap.`,
+            nextAction: `Confirm ${safeEntity(topAgent.key)}'s owner and approved range, then collect run-level evidence before proposing a warning threshold or hard cap.`,
             priority: "high",
             estimatedImpactUsd: 0,
             confidence: topAgent.confidence,
-            relatedKeys: [topAgent.key]
+            relatedKeys: [safeEntity(topAgent.key)]
         });
     }
     const batchableRecords = decisionRecords.filter((record) => record.workloadSemantics?.batchEligible === true &&
@@ -262,7 +279,7 @@ export function generateRecommendations(records) {
                 return total + (record.amountUsd ?? 0) * (1 - retained);
             }, 0)),
             confidence: combinedConfidence(batchableRecords.map((record) => record.costConfidence)),
-            relatedKeys: unique(batchableRecords.map((record) => record.operation).filter(isPresent))
+            relatedKeys: safeUntrustedLabels(unique(batchableRecords.map((record) => record.operation).filter(isPresent)), WITHHELD_OPERATION_LABEL)
         });
     }
     return recommendations;
@@ -335,9 +352,33 @@ function isLocalAgentRecord(record) {
     return record.providerCostType === "local_agent_logs";
 }
 function workflowDiagnosticFor(workflowKey, agentId, hasRunLevelEvidence) {
+    const workflow = safeWorkflowLabel(workflowKey);
+    const agent = safeUntrustedLabel(agentId, WITHHELD_AGENT_LABEL);
     return hasRunLevelEvidence
-        ? `Confirm the owner and approved budget for ${workflowKey} (${agentId}), reconcile the observed spend, and define one reversible candidate with an accepted-outcome quality bar before approval.`
-        : `Confirm the owner and approved budget for ${workflowKey} (${agentId}), reconcile the observed spend, and collect call-level provenance before proposing a reversible optimization.`;
+        ? `Confirm the owner and approved budget for ${workflow} (${agent}), reconcile the observed spend, and define one reversible candidate with an accepted-outcome quality bar before approval.`
+        : `Confirm the owner and approved budget for ${workflow} (${agent}), reconcile the observed spend, and collect call-level provenance before proposing a reversible optimization.`;
+}
+/**
+ * The workflow key IS `record.operation` — a provider/adapter string, untrusted
+ * end to end. It reaches `suggestedOptimization`, `applyArtifact` and
+ * `verificationPlan`, and those three are rendered as product prose that the
+ * report layer deliberately never blanks. So it is neutralized here, at the
+ * interpolation point, exactly as the cut-list builders do.
+ *
+ * The ENTRY's own identity fields are neutralized too: they travel inside the
+ * SpendSummary that the MCP tools return, so a raw field sitting beside
+ * neutralized prose hands an agent exactly what the human was protected from.
+ */
+function safeWorkflowLabel(workflowKey) {
+    return safeUntrustedLabel(workflowKey, WITHHELD_OPERATION_LABEL);
+}
+/**
+ * A breakdown key rendered for a HUMAN — a model id, an agent id, an
+ * operation label. Display only: the raw key is still what the record filters
+ * match on, and rewriting a matching key would empty the cohort.
+ */
+function safeEntity(value) {
+    return safeUntrustedLabel(value, WITHHELD_ENTITY_LABEL);
 }
 function slugify(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");

package/dist/contextHealth.js

@@ -1,3 +1,4 @@
+import { safeUntrustedLabel, WITHHELD_FILE_LABEL, WITHHELD_PROJECT_LABEL } from "./untrustedLabel.js";
 import { loadAgentInventory } from "./agentInventory.js";
 import { computeDeadContext } from "./deadContext.js";
 import { localAgentFormatSupports } from "./localAgentFormats/registry.js";
@@ -74,7 +75,9 @@ export function buildContextHealth(input = {}) {
     if ((contextChurn.repeatedReadEvents ?? 0) > 0) {
         const files = contextChurn.repeatedFiles
             .slice(0, 3)
-            .map((file) => `${file.file} ×${file.readCount}`)
+            // Basenames, but a basename is still a name the user did not author,
+            // and this sentence is returned verbatim by the MCP context-health tool.
+            .map((file) => `${safeUntrustedLabel(file.file, WITHHELD_FILE_LABEL)} ×${file.readCount}`)
             .join(", ");
         evidence.push({
             kind: "context_churn",
@@ -231,6 +234,9 @@ function contextDecision(input) {
 const MIN_EXACT_COMPARISONS = 2;
 const MIN_SESSION_TYPE_COMPARISONS = 2;
 const MAX_DISPLAY_RATIO = 20;
+function safeOptionalProject(value) {
+    return value === undefined ? undefined : safeUntrustedLabel(value, WITHHELD_PROJECT_LABEL);
+}
 function buildCurrentSession(sessions, now, activeWithinMinutes) {
     const latest = latestContextSession(sessions);
     if (!latest)
@@ -273,7 +279,9 @@ function buildCurrentSession(sessions, now, activeWithinMinutes) {
     return {
         status: ageMs <= activeWithinMinutes * 60_000 ? "active" : "recent",
         agent: latest.agent,
-        project: latest.project,
+        project: latest.project === undefined
+            ? undefined
+            : safeUntrustedLabel(latest.project, WITHHELD_PROJECT_LABEL),
         totalTokens: latest.totalTokens,
         contextTokens: latest.contextTokens,
         usageSource: latest.usageSource,
@@ -308,7 +316,7 @@ function contextSessions(calls) {
         return {
             key,
             agent: latest.agent,
-            project: latest.project ?? ordered[0]?.project,
+            project: safeOptionalProject(latest.project ?? ordered[0]?.project),
             lastActivityAt: latest.timestamp,
             totalTokens: turnUsage?.totalTokens ?? 0,
             contextTokens: turnUsage?.contextTokens ?? 0,
@@ -350,8 +358,11 @@ function buildContextChurn(latest, invocations) {
             signal.sessionId &&
             latest.key === `${signal.agent}:${signal.sessionId}`))
         : undefined;
+    // Neutralized at the source in toolInvocations.ts; re-applied here because a
+    // signal can also arrive from a cache written by an earlier version, and
+    // because this array is handed to an agent verbatim by the MCP tool.
     const repeatedFiles = (currentSignal?.repeatedFileReads ?? [])
-        .map((file) => ({ file: file.name, readCount: file.count }));
+        .map((file) => ({ file: safeUntrustedLabel(file.name, WITHHELD_FILE_LABEL), readCount: file.count }));
     return {
         currentSessionEvidence: !latest
             ? "no_current_session"

package/dist/cutList.d.ts

@@ -40,7 +40,30 @@ export type CutAction = {
      * by two actions (see {@link buildRecommendedPlan}).
      */
     recordIds: string[];
+    /**
+     * Median DAY's summed input+cache tokens for this candidate, computed over
+     * calendar days (not over records — a project running two models emits two
+     * records per day, and calling that "per day" would halve the number).
+     *
+     * Exists so a grouped render can tell two members apart by the quantity that
+     * explains their dollars instead of by the rounded dollar alone. Optional and
+     * absent on candidates with no day-level evidence; every renderer MUST drop
+     * the figure rather than print a placeholder.
+     */
+    medianDailyInputTokens?: number;
 };
+/**
+ * Compact token count for prose: 2,140,000 -> "2.1M", 8,300 -> "8.3K".
+ * Lives in core because the cut-list guidance strings are built here, and is
+ * re-used by the renderers so one candidate's token magnitude reads the same
+ * on every surface.
+ *
+ * The ladder runs to T. It used to stop at B, so a fleet-scale window printed
+ * "4212.7B" — a number the reader has to count digits on to place, from a
+ * product whose whole claim is arithmetic you can read at a glance. Past T the
+ * mantissa gets thousands separators rather than a fourteenth silent digit.
+ */
+export declare function formatTokenCount(tokens: number): string;
 /**
  * A non-overlapping "recommended plan" plus the leftover overlapping
  * opportunities. The recommended-plan total is the only savings number safe to

package/dist/cutList.js

@@ -1,5 +1,37 @@
 import { hasCallLevelProvenance, hasModeledWorkloadEvidence, hasPricedEvidence } from "./schema.js";
 import { localAgentFormatSupports } from "./localAgentFormats/registry.js";
+import { safeUntrustedLabel, WITHHELD_AGENT_LABEL, WITHHELD_MODEL_LABEL, WITHHELD_OPERATION_LABEL, WITHHELD_PROJECT_LABEL } from "./untrustedLabel.js";
+/**
+ * Compact token count for prose: 2,140,000 -> "2.1M", 8,300 -> "8.3K".
+ * Lives in core because the cut-list guidance strings are built here, and is
+ * re-used by the renderers so one candidate's token magnitude reads the same
+ * on every surface.
+ *
+ * The ladder runs to T. It used to stop at B, so a fleet-scale window printed
+ * "4212.7B" — a number the reader has to count digits on to place, from a
+ * product whose whole claim is arithmetic you can read at a glance. Past T the
+ * mantissa gets thousands separators rather than a fourteenth silent digit.
+ */
+export function formatTokenCount(tokens) {
+    if (!Number.isFinite(tokens))
+        return "0";
+    const value = Math.max(0, tokens);
+    if (value >= 1_000_000_000_000)
+        return `${formatMantissa(value / 1_000_000_000_000)}T`;
+    if (value >= 1_000_000_000)
+        return `${(value / 1_000_000_000).toFixed(1)}B`;
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(1)}M`;
+    if (value >= 1_000)
+        return `${(value / 1_000).toFixed(1)}K`;
+    return String(Math.round(value));
+}
+/** Top of the ladder: keep one decimal until the integer part needs commas. */
+function formatMantissa(value) {
+    return value >= 1_000
+        ? Math.round(value).toLocaleString("en-US")
+        : value.toFixed(1);
+}
 /**
  * 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
@@ -126,10 +158,18 @@ function modelDowngradeActions(records) {
         const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
         const windowSavings = affectedSpendUsd * (1 - rule.costRetained);
         const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        // Both untrusted. The model gate is anchored but open-ended
+        // (`^claude-opus-4(?:[.-].*)?$` accepts anything after the dash), and
+        // `downgradeSafeOperation` is a SUBSTRING allowlist — "summary" anywhere
+        // in the label passes the whole label through. Neutralize before either
+        // reaches a title or an instruction. IDs keep the raw values: an id is
+        // identity, not display, and it is rendered through a blanking guard.
+        const modelLabel = safeUntrustedLabel(model, WITHHELD_MODEL_LABEL);
+        const operationLabel = safeUntrustedLabel(operation, WITHHELD_OPERATION_LABEL);
         actions.push({
             id: `downgrade-${slug(model)}-${slug(operation)}`,
-            title: `Move ${model} ${operation} calls to ${target}`,
-            action: `Route ${groupRecords.length} ${operation} call${groupRecords.length === 1 ? "" : "s"} from ${model} to ${target} (keep ${model} only when output is rejected).`,
+            title: `Move ${modelLabel} ${operationLabel} calls to ${target}`,
+            action: `Route ${groupRecords.length} ${operationLabel} call${groupRecords.length === 1 ? "" : "s"} from ${modelLabel} to ${target} (keep ${modelLabel} only when output is rejected).`,
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
@@ -155,6 +195,30 @@ function contextTrimActions(records) {
             : `connected::${operation}`;
         byOperation.set(key, [...(byOperation.get(key) ?? []), record]);
     }
+    // ONE denominator, and it is the set the sentence is already talking about:
+    // this agent's OWN flagged projects. It is both the share's denominator and
+    // the rank clause's population, so the percentage, the rank, and the entry's
+    // own dollars two lines below all reconcile, and the members of one fan-out
+    // sum to 100%.
+    //
+    // 0.9.7 shipped three denominators in one sentence — a machine-wide local
+    // total for the share, this agent's flagged projects for the rank, and the
+    // entry's own total underneath. Every figure was individually true, which is
+    // exactly why the sentence read as an arithmetic error. Never reintroduce a
+    // denominator the sentence does not name.
+    const flaggedSpendByAgent = new Map();
+    for (const [key, groupRecords] of byOperation) {
+        const [scope, agentId] = key.split("::");
+        if (scope !== "local" || !agentId)
+            continue;
+        // roundMoney, matching `affectedSpendUsd` exactly: comparing a rounded
+        // group against unrounded peers made a candidate outrank ITSELF and
+        // report "rank 2 of 8" for the largest project on the list.
+        flaggedSpendByAgent.set(agentId, [
+            ...(flaggedSpendByAgent.get(agentId) ?? []),
+            roundMoney(sumRecords(groupRecords))
+        ]);
+    }
     const actions = [];
     for (const [key, groupRecords] of byOperation) {
         const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
@@ -164,7 +228,26 @@ function contextTrimActions(records) {
             : key.replace(/^connected::/, "");
         const count = groupRecords.length;
         const agent = groupRecords[0]?.agentId ?? "coding-agent";
+        // `agent` stays raw as the map key and the id slug; only the DISPLAY
+        // form is neutralized. Bounded to the adapter enum for local rows in
+        // practice, but nothing in the type system enforces that.
+        const agentLabel = safeUntrustedLabel(agent, WITHHELD_AGENT_LABEL);
         const project = groupRecords[0]?.projectId;
+        const evidence = sessionAggregates ? dailyContextEvidence(groupRecords) : null;
+        const flaggedSpend = flaggedSpendByAgent.get(agent) ?? [];
+        // The project label is UNTRUSTED — it is a directory name off the user's
+        // disk. Neutralize it ONCE, here, so the title, the guidance, and every
+        // surface that re-derives a label from the title all carry the same
+        // already-safe text and cannot disagree about it.
+        const projectLabel = project
+            ? safeUntrustedLabel(project, WITHHELD_PROJECT_LABEL)
+            : "Unattributed";
+        // The connected path's operation label is a raw provider/adapter string
+        // with NO allowlist in front of it, and it lands in both the title and the
+        // instruction. It has to be neutralized here for the same reason the
+        // project label is: the report layer's prose sanitizer never blanks, and
+        // it is only safe to never blank because core neutralized first.
+        const operationLabel = safeUntrustedLabel(operation, WITHHELD_OPERATION_LABEL);
         // 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.
@@ -174,11 +257,18 @@ function contextTrimActions(records) {
                 ? `inspect-context-${slug(agent)}-${slug(project ?? "unattributed")}`
                 : `inspect-context-${slug(operation)}`,
             title: sessionAggregates
-                ? `Investigate cumulative context in ${agent}${project ? ` · ${project}` : " · Unattributed"}`
-                : `Inspect oversized context on ${operation}`,
+                ? `Investigate cumulative context in ${agentLabel} · ${projectLabel}`
+                : `Inspect oversized context on ${operationLabel}`,
             action: sessionAggregates
-                ? `${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.`,
+                ? localContextTrimGuidance({
+                    count,
+                    agent: agentLabel,
+                    projectLabel,
+                    evidence,
+                    groupSpendUsd: affectedSpendUsd,
+                    flaggedSpend
+                })
+                : `${count} call-level ${operationLabel} 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,
@@ -186,11 +276,172 @@ function contextTrimActions(records) {
             impactBasis: "observed_value_no_counterfactual",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
-            kind: "context_trim"
+            kind: "context_trim",
+            ...(evidence ? { medianDailyInputTokens: evidence.medianDailyInputTokens } : {})
         });
     }
     return actions;
 }
+function dailyContextEvidence(records) {
+    if (records.length === 0)
+        return null;
+    const byDay = new Map();
+    for (const record of records) {
+        const day = record.timestamp.slice(0, 10);
+        const current = byDay.get(day) ?? { input: 0, output: 0 };
+        current.input += record.inputTokens;
+        current.output += record.outputTokens;
+        byDay.set(day, current);
+    }
+    const days = [...byDay.entries()].sort((left, right) => left[0].localeCompare(right[0]));
+    const first = days[0];
+    if (!first)
+        return null;
+    // ONE REAL DAY, not two independent medians. The sentence says "median day
+    // carried X input+cache tokens against Y output"; if X and Y came from
+    // different calendar days that sentence would describe a day that never
+    // happened. So: order the days by input+cache, take the middle OBSERVED day
+    // (the lower of the two middles on an even sample, never their average), and
+    // read every median figure off that one day.
+    const byInput = [...days].sort((left, right) => left[1].input - right[1].input || left[0].localeCompare(right[0]));
+    const medianDay = byInput[Math.floor((byInput.length - 1) / 2)];
+    const medianDailyInputTokens = medianDay[1].input;
+    const medianDailyOutputTokens = medianDay[1].output;
+    const peak = days.reduce((best, entry) => (entry[1].input > best[1].input ? entry : best), first);
+    const spendByModel = new Map();
+    for (const record of records) {
+        spendByModel.set(record.model, (spendByModel.get(record.model) ?? 0) + (record.amountUsd ?? 0));
+    }
+    return {
+        activeDays: days.length,
+        medianDailyInputTokens,
+        medianDailyOutputTokens,
+        peakDay: peak[0],
+        peakDayInputTokens: peak[1].input,
+        peakOverMedian: medianDailyInputTokens > 0 ? peak[1].input / medianDailyInputTokens : 0,
+        inputPerOutput: medianDailyOutputTokens > 0
+            ? medianDailyInputTokens / medianDailyOutputTokens
+            : null,
+        models: [...spendByModel.entries()]
+            .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+            .map(([model]) => model)
+    };
+}
+/**
+ * The guidance a local context candidate carries.
+ *
+ * Two hard constraints shape it:
+ *
+ *  1. TRUTH. Every clause states something OBSERVED — a median, a date, a
+ *     ratio, a share of a single-basis total. Nothing predicts a reduction,
+ *     nothing prices a change, and no clause is emitted when the evidence
+ *     behind it is absent. Sharper means more specific about what was seen,
+ *     never more confident about what would happen.
+ *
+ *  2. GEOMETRY. The grouped terminal/report render quotes this string from its
+ *     LARGEST member and drops everything before the first ". " (see
+ *     `groupedCutActionLines` / `rankCutCandidates` in @agent-finops/report).
+ *     So sentence 1 carries only per-member counts, and sentence 2 onward
+ *     NAMES the project it describes — otherwise one project's median would be
+ *     read as the whole group's. For the same reason sentence 1 interpolates
+ *     no free text: a label containing ". " would truncate the string at the
+ *     wrong point.
+ */
+function localContextTrimGuidance(input) {
+    const { count, evidence } = input;
+    // Idempotent: `contextTrimActions` already neutralized the label for the
+    // title, and re-running the check on an already-neutral label is a no-op.
+    // Repeating it here keeps the guarantee attached to the function that does
+    // the interpolating, not to one of its callers.
+    const projectLabel = safeUntrustedLabel(input.projectLabel, WITHHELD_PROJECT_LABEL);
+    const plural = count === 1 ? "" : "s";
+    if (!evidence) {
+        // No day-level evidence to quote. Stay honest and short rather than
+        // reciting a checklist the product cannot perform.
+        return `${count} day + agent + model + project aggregate${plural} each carried at least 100k summed input/cache tokens. ` +
+            `Inspect the heaviest sessions in ${projectLabel} before proposing one reversible change.`;
+    }
+    const dayPlural = evidence.activeDays === 1 ? "" : "s";
+    const sentences = [
+        `${count} day + agent + model + project aggregate${plural} over ${evidence.activeDays} active day${dayPlural}.`
+    ];
+    const ratio = evidence.inputPerOutput === null ? null : formatRatio(evidence.inputPerOutput);
+    sentences.push(evidence.medianDailyOutputTokens > 0
+        ? `${projectLabel} — median day carried ${formatTokenCount(evidence.medianDailyInputTokens)} input+cache tokens ` +
+            `against ${formatTokenCount(evidence.medianDailyOutputTokens)} output${ratio ? ` (${ratio}:1)` : ""}.`
+        : `${projectLabel} — median day carried ${formatTokenCount(evidence.medianDailyInputTokens)} input+cache tokens ` +
+            "with no output tokens recorded that day.");
+    // Only when there is a real lead. A uniform project gets no false one.
+    if (evidence.peakOverMedian >= 2) {
+        sentences.push(`Heaviest day ${evidence.peakDay} carried ${formatTokenCount(evidence.peakDayInputTokens)}, ` +
+            `${formatRatio(evidence.peakOverMedian)}× the median day; dates are each session's last activity.`);
+    }
+    const share = concentrationClause(input);
+    if (share)
+        sentences.push(share);
+    if (evidence.models.length > 1) {
+        // Model ids come off the same untrusted logs the project name does.
+        const shown = evidence.models
+            .slice(0, 3)
+            .map((model) => safeUntrustedLabel(model, WITHHELD_MODEL_LABEL));
+        const rest = evidence.models.length - shown.length;
+        sentences.push(`${evidence.models.length} models ran there: ${shown.join(", ")}${rest > 0 ? ` and ${rest} more` : ""}.`);
+    }
+    sentences.push(evidence.peakOverMedian >= 2
+        ? `Inspect the sessions behind ${evidence.peakDay} before proposing one reversible change.`
+        : `Inspect the heaviest sessions in ${projectLabel} before proposing one reversible change.`);
+    return sentences.join(" ");
+}
+/**
+ * "…holds 76% of the flagged claude-code value observed in this window (rank 1
+ * of 8 flagged projects)." An accounting fact about ONE denominator — not a
+ * savings claim, not a projection.
+ *
+ * The denominator is this agent's own flagged total, which is also the rank
+ * clause's population and the sum of the per-project dollars the same readout
+ * prints two lines below. So the percentage, the rank, and the entry's own
+ * total reconcile, and the members of one fan-out sum to 100%.
+ *
+ * 0.9.7 divided by a machine-wide local total instead: `--full` printed a
+ * by-project table saying 83%, this sentence said 46%, and the entry's own
+ * dollars implied 76% — three true numbers that read as an arithmetic error.
+ * No clamp is needed now and none belongs here: the numerator is one member of
+ * the set in the denominator, so a ratio above 1 would be a real bug worth
+ * seeing rather than a cosmetic one worth hiding.
+ */
+function concentrationClause(input) {
+    const { agent, groupSpendUsd, flaggedSpend } = input;
+    const flaggedTotalUsd = flaggedSpend.reduce((total, spend) => total + spend, 0);
+    if (!(flaggedTotalUsd > 0) || !(groupSpendUsd > 0))
+        return null;
+    const ratio = groupSpendUsd / flaggedTotalUsd;
+    if (!Number.isFinite(ratio) || ratio <= 0)
+        return null;
+    const percent = Math.round(ratio * 100);
+    const rank = flaggedSpend.filter((spend) => spend > groupSpendUsd).length + 1;
+    const total = flaggedSpend.length;
+    // A ceiling, mirroring the "under 1%" floor. The ordinary solo-dev shape is
+    // one main repo and two small side projects: at 99.5%–99.9% the rounded
+    // figure prints "100%" on the same screen as an across-line that lists two
+    // more flagged projects WITH DOLLARS — which reads as exactly the
+    // arithmetic error this sentence's denominator was fixed to kill. "over 99%"
+    // is the same fact without the contradiction. A lone flagged project keeps
+    // the literal 100%, because there is nothing beside it to contradict.
+    const share = percent < 1
+        ? "under 1%"
+        : percent >= 100 && total > 1 ? "over 99%" : `${percent}%`;
+    const rankClause = total > 1 ? ` (rank ${rank} of ${total} flagged projects)` : "";
+    return `That project holds ${share} of the flagged ${agent} value observed in this window${rankClause}.`;
+}
+/**
+ * "519", "4.4" — integers once the ratio is big enough that a decimal is noise.
+ * Shared by the input:output ratio and the "N× the median day" multiple so the
+ * two never disagree about precision. Separated above 999, because a bare
+ * "1904762:1" is a digit-counting exercise, not a figure.
+ */
+function formatRatio(value) {
+    return value >= 10 ? Math.round(value).toLocaleString("en-US") : value.toFixed(1);
+}
 function cacheActions(records) {
     const window = windowDays(records);
     const counts = new Map();
@@ -226,10 +477,13 @@ function cacheActions(records) {
         const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
         const windowSavings = sumRecords(avoidableRecords);
         const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        // No allowlist stands in front of this one at all — any operation label
+        // with a stable fingerprint reaches the title and the instruction.
+        const operationLabel = safeUntrustedLabel(operation, WITHHELD_OPERATION_LABEL);
         actions.push({
             id: `cache-${slug(operation)}-${stableSuffix(key)}`,
-            title: `Cache repeated ${operation} calls`,
-            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.`,
+            title: `Cache repeated ${operationLabel} calls`,
+            action: `Keep the earliest ${operationLabel} 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,
@@ -274,10 +528,13 @@ function batchActions(records) {
         const retainedCost = batchCostRetainedByProvider[groupRecords[0].source.provider];
         const windowSavings = affectedSpendUsd * (1 - retainedCost);
         const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        // `batchSafeOperation` is a SUBSTRING allowlist: "summar" anywhere in the
+        // label admits the whole label, injected prose included.
+        const operationLabel = safeUntrustedLabel(operation, WITHHELD_OPERATION_LABEL);
         actions.push({
             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).`,
+            title: `Move ${operationLabel} calls to the Batch API`,
+            action: `Submit ${groupRecords.length} ${operationLabel} 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,