@agent-finops/core 0.9.6 → 0.9.7

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,

package/dist/deadContext.js

@@ -1,4 +1,5 @@
 import { loadAgentInventory } from "./agentInventory.js";
+import { safeUntrustedLabel, WITHHELD_ENTITY_LABEL, WITHHELD_FILE_LABEL } from "./untrustedLabel.js";
 import { findPricingRule } from "./modelPricing.js";
 import { loadToolInvocations } from "./toolInvocations.js";
 /**
@@ -97,15 +98,21 @@ export function computeDeadContext(items, invocations, config) {
         }
         dead.push({
             kind: item.kind,
-            name: item.name,
+            // Skill, subagent, slash-command, hook and MCP SERVER names, read off
+            // disk. They are printed by name on the readout and in the artifact.
+            name: safeUntrustedLabel(item.name, WITHHELD_ENTITY_LABEL),
             scope: item.scope,
             activation: item.activation,
+            // The STRUCTURED siblings travel with the name to every surface the name
+            // does, including the Apply artifact. Neutralizing the name and leaving
+            // the path beside it raw is the same inversion Blocker A was.
+            // `host` is the InventoryHost enum, not free text — bounded by the type.
             host: item.host,
             invocationTracking: item.invocationTracking,
             alwaysLoadedTokens: item.alwaysLoadedTokens,
             weightConfidence: item.weightConfidence,
-            path: item.path,
-            ownerDirs: item.ownerDirs
+            path: item.path === undefined ? undefined : safeUntrustedLabel(item.path, WITHHELD_FILE_LABEL),
+            ownerDirs: item.ownerDirs?.map((dir) => safeUntrustedLabel(dir, WITHHELD_FILE_LABEL))
         });
     }
     dead.sort((a, b) => b.alwaysLoadedTokens - a.alwaysLoadedTokens);

package/dist/insights.js

@@ -1,4 +1,5 @@
 import { hasCallLevelProvenance, hasPricedEvidence, spendComparisonKey, spendInsightSchema } from "./schema.js";
+import { safeUntrustedLabel, safeUntrustedLabels, WITHHELD_ENTITY_LABEL, WITHHELD_OPERATION_LABEL } from "./untrustedLabel.js";
 const confidenceRank = {
     verified: 0,
     estimated: 1,
@@ -32,7 +33,10 @@ function spikeInsights(records, summary) {
         const topProject = topBreakdown(currentRecords, (record) => record.projectId);
         const topModels = breakdown(currentRecords, (record) => record.model).slice(0, 2).map((entry) => entry.key);
         const deltaUsd = roundMoney(anomaly.currentAmountUsd - anomaly.previousAmountUsd);
-        const likelyOwner = topAgent?.key ?? topProject?.key ?? topClient?.key ?? "an unassigned owner";
+        // Ownership lead is an agent/project/client id off the records — it lands
+        // mid-sentence in `summary`, so it is neutralized at the interpolation
+        // point like every other untrusted fragment.
+        const likelyOwner = safeEntity(topAgent?.key ?? topProject?.key ?? topClient?.key ?? "an unassigned owner");
         const cohortSuffix = stableSuffix(anomaly.comparisonKey ?? "legacy");
         const isProviderBilledCost = currentRecords.length > 0 && currentRecords.every((record) => record.usageGranularity === "billing_bucket" &&
             record.costConfidence === "verified");
@@ -50,14 +54,14 @@ function spikeInsights(records, summary) {
                 { label: `Previous cohort ${isProviderBilledCost ? "spend" : "value"}`, value: formatUsd(anomaly.previousAmountUsd) },
                 { label: `Current cohort ${isProviderBilledCost ? "spend" : "value"}`, value: formatUsd(anomaly.currentAmountUsd) },
                 { label: `${evidenceLabel} increase`, value: formatUsd(deltaUsd), detail: `${formatMultiplier(anomaly.multiplier)} day-over-day multiplier` },
-                topAgent ? { label: "Ownership lead", value: topAgent.key, detail: `${formatUsd(topAgent.amountUsd)} across ${topAgent.recordCount} cohort records` } : undefined,
-                topClient ? { label: "Client concentration", value: topClient.key, detail: `${formatUsd(topClient.amountUsd)} on spike day` } : undefined,
-                topModels.length > 0 ? { label: "Dominant models", value: topModels.join(", ") } : undefined
+                topAgent ? { label: "Ownership lead", value: safeEntity(topAgent.key), detail: `${formatUsd(topAgent.amountUsd)} across ${topAgent.recordCount} cohort records` } : undefined,
+                topClient ? { label: "Client concentration", value: safeEntity(topClient.key), detail: `${formatUsd(topClient.amountUsd)} on spike day` } : undefined,
+                topModels.length > 0 ? { label: "Dominant models", value: safeUntrustedLabels(topModels).join(", ") } : undefined
             ]),
-            affectedClients: keysFrom(currentRecords, (record) => record.clientId),
-            affectedProjects: keysFrom(currentRecords, (record) => record.projectId),
-            affectedAgents: keysFrom(currentRecords, (record) => record.agentId),
-            affectedModels: keysFrom(currentRecords, (record) => record.model),
+            affectedClients: safeUntrustedLabels(keysFrom(currentRecords, (record) => record.clientId)),
+            affectedProjects: safeUntrustedLabels(keysFrom(currentRecords, (record) => record.projectId)),
+            affectedAgents: safeUntrustedLabels(keysFrom(currentRecords, (record) => record.agentId)),
+            affectedModels: safeUntrustedLabels(keysFrom(currentRecords, (record) => record.model)),
             estimatedImpactUsd: deltaUsd,
             confidence: anomaly.confidence,
             recommendedAction: `Review and reconcile the provider-cohort records from ${anomaly.key}, confirm the accountable owner, and obtain run-level evidence before diagnosing behavior or changing a policy.`,
@@ -81,24 +85,27 @@ function agentCostDriverInsights(records, summary) {
     const topModel = topBreakdown(agentRecords, (record) => record.model);
     const hasRunLevelEvidence = agentRecords.length > 0 && agentRecords.every(hasCallLevelProvenance);
     return [{
-            id: `agent-spend-concentration-${topAgent.key}`,
+            // The id is a STRUCTURED field beside the neutralized title, and it is
+            // rendered (`Canonical candidate ID: ...`). Slug the neutralized form, not
+            // the raw key.
+            id: `agent-spend-concentration-${slug(safeEntity(topAgent.key))}`,
             kind: "optimization_opportunity",
             severity: "medium",
-            title: `${topAgent.key} spend concentration needs owner and budget review`,
-            summary: `${topAgent.key} is attached to ${formatPercent(share)} of tracked spend. Concentration alone does not prove abnormal behavior or an avoidable dollar amount${hasRunLevelEvidence ? "." : "; the evidence is aggregate rather than run-level."}`,
+            title: `${safeEntity(topAgent.key)} spend concentration needs owner and budget review`,
+            summary: `${safeEntity(topAgent.key)} is attached to ${formatPercent(share)} of tracked spend. Concentration alone does not prove abnormal behavior or an avoidable dollar amount${hasRunLevelEvidence ? "." : "; the evidence is aggregate rather than run-level."}`,
             evidence: compactEvidence([
                 { label: "Attributed spend", value: formatUsd(topAgent.amountUsd), detail: `${topAgent.recordCount} ${hasRunLevelEvidence ? "call-level" : "aggregate"} record${topAgent.recordCount === 1 ? "" : "s"}` },
                 { label: "Share of tracked spend", value: formatPercent(share) },
-                topModel ? { label: "Dominant model or billing label", value: topModel.key, detail: `${formatUsd(topModel.amountUsd)} in this concentration` } : undefined,
-                topOperation ? { label: "Operation label", value: topOperation.key, detail: hasRunLevelEvidence ? "Call-level attribution" : "Not verified as one call or run" } : undefined
+                topModel ? { label: "Dominant model or billing label", value: safeEntity(topModel.key), detail: `${formatUsd(topModel.amountUsd)} in this concentration` } : undefined,
+                topOperation ? { label: "Operation label", value: safeEntity(topOperation.key), detail: hasRunLevelEvidence ? "Call-level attribution" : "Not verified as one call or run" } : undefined
             ]),
-            affectedClients: keysFrom(agentRecords, (record) => record.clientId),
-            affectedProjects: keysFrom(agentRecords, (record) => record.projectId),
-            affectedAgents: [topAgent.key],
-            affectedModels: keysFrom(agentRecords, (record) => record.model),
+            affectedClients: safeUntrustedLabels(keysFrom(agentRecords, (record) => record.clientId)),
+            affectedProjects: safeUntrustedLabels(keysFrom(agentRecords, (record) => record.projectId)),
+            affectedAgents: [safeEntity(topAgent.key)],
+            affectedModels: safeUntrustedLabels(keysFrom(agentRecords, (record) => record.model)),
             estimatedImpactUsd: 0,
             confidence: topAgent.confidence,
-            recommendedAction: `Confirm who owns ${topAgent.key}, reconcile the spend to its approved budget, and collect behavioral evidence before setting a cap or savings target.`,
+            recommendedAction: `Confirm who owns ${safeEntity(topAgent.key)}, reconcile the spend to its approved budget, and collect behavioral evidence before setting a cap or savings target.`,
             verificationNeeded: "Confirm the budget owner and expected range; concentration alone is not behavioral evidence."
         }];
 }
@@ -113,7 +120,7 @@ function contextBloatInsights(records) {
     const scopedRecords = topOperation
         ? highInputRecords.filter((record) => record.operation === topOperation.key)
         : highInputRecords;
-    const operationLabel = topOperation?.key ?? "large-context calls";
+    const operationLabel = safeUntrustedLabel(topOperation?.key ?? "large-context calls", WITHHELD_OPERATION_LABEL);
     const totalInputTokens = scopedRecords.reduce((total, record) => total + record.inputTokens, 0);
     const scopedSpend = roundMoney(sumRecords(scopedRecords));
     if (scopedSpend < 20) {
@@ -131,16 +138,27 @@ function contextBloatInsights(records) {
                 { label: "Spend attached to large context", value: formatUsd(scopedSpend) },
                 { label: "Dominant operation", value: operationLabel }
             ],
-            affectedClients: keysFrom(scopedRecords, (record) => record.clientId),
-            affectedProjects: keysFrom(scopedRecords, (record) => record.projectId),
-            affectedAgents: keysFrom(scopedRecords, (record) => record.agentId),
-            affectedModels: keysFrom(scopedRecords, (record) => record.model),
+            affectedClients: safeUntrustedLabels(keysFrom(scopedRecords, (record) => record.clientId)),
+            affectedProjects: safeUntrustedLabels(keysFrom(scopedRecords, (record) => record.projectId)),
+            affectedAgents: safeUntrustedLabels(keysFrom(scopedRecords, (record) => record.agentId)),
+            affectedModels: safeUntrustedLabels(keysFrom(scopedRecords, (record) => record.model)),
             estimatedImpactUsd: 0,
             confidence: combinedConfidence(scopedRecords.map((record) => record.costConfidence)),
             recommendedAction: `Inspect representative ${operationLabel} prompts locally and run a matched before/after with the same acceptance criteria before proposing one reversible context change.`,
             verificationNeeded: "Measure token and quality deltas on matched calls; no savings counterfactual is present yet."
         }];
 }
+/**
+ * A breakdown key rendered for a HUMAN. The same slot holds a client, a
+ * project, an agent, a model or an operation depending on which grouping won,
+ * so it takes the dimension-neutral marker.
+ *
+ * Display only. The raw key is still what `records.filter(...)` matches on —
+ * rewriting a matching key would silently empty the cohort behind the finding.
+ */
+function safeEntity(value) {
+    return safeUntrustedLabel(value, WITHHELD_ENTITY_LABEL);
+}
 function topBreakdown(records, select) {
     return breakdown(records, select)[0];
 }

package/dist/planMath.js

@@ -1,3 +1,15 @@
+import { safeUntrustedLabel, WITHHELD_ENTITY_LABEL, WITHHELD_PLAN_LABEL } from "./untrustedLabel.js";
+/**
+ * The plan label and the limit signal are read out of the agent's own local
+ * config files, so both are untrusted text that lands mid-sentence in a
+ * headline the readout, the report and `doctor` all print verbatim.
+ */
+function safePlanLabel(value) {
+    return safeUntrustedLabel(value, WITHHELD_PLAN_LABEL);
+}
+function safeLimitSignal(value) {
+    return safeUntrustedLabel(value, WITHHELD_ENTITY_LABEL);
+}
 export const subscriptionPlans = [
     { id: "claude-pro", provider: "anthropic", agent: "claude-code", name: "Claude Pro", monthlyUsd: 20, coversUpToUsd: 50 },
     { id: "claude-max-5x", provider: "anthropic", agent: "claude-code", name: "Claude Max 5x", monthlyUsd: 100, coversUpToUsd: 250 },
@@ -61,21 +73,21 @@ export function computePlanChecks(records, detectedPlans = []) {
                 const nextTier = subscriptionPlans.find((plan) => plan.agent === agent && plan.coversUpToUsd > detectedKnown.coversUpToUsd);
                 // A local limit signal upgrades "might hit limits" to hard evidence.
                 const evidence = detected?.limitSignal
-                    ? `local metadata reports ${detected.limitSignal}`
+                    ? `local metadata reports ${safeLimitSignal(detected.limitSignal)}`
                     : `if the provider reports active rate limits`;
                 upgradeHint = nextTier
                     ? `API-equivalent projection exceeds the rough ${detectedKnown.name} comparison threshold (~$${detectedKnown.coversUpToUsd}/mo); ${evidence}. ${nextTier.name} ($${nextTier.monthlyUsd}/mo) is the next listed tier, but verify account limits before changing plans; trimming context (below) may buy headroom.`
                     : `API-equivalent projection exceeds the rough ${detectedKnown.name} comparison threshold (~$${detectedKnown.coversUpToUsd}/mo); verify account limits before changing plans. Trimming context (below) may buy headroom.`;
             }
             else if (detected?.limitSignal) {
-                upgradeHint = `local metadata reports ${detected.limitSignal}; verify the live provider window. Trimming context (below) may buy headroom.`;
+                upgradeHint = `local metadata reports ${safeLimitSignal(detected.limitSignal)}; verify the live provider window. Trimming context (below) may buy headroom.`;
             }
         }
         else if (detected) {
             // Detected a plan we can't price (e.g. an unrecognized tier): state the
             // fact, then fall back to suggestion math without pretending certainty.
             headline =
-                `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — compared with ${detected.planLabel} ` +
+                `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — compared with ${safePlanLabel(detected.planLabel)} ` +
                     `(label detected locally; price not in our table)` +
                     (suggested ? `; reference listed plan: ${suggested.name} ($${suggested.monthlyUsd}/mo).` : `.`);
         }
@@ -100,7 +112,16 @@ export function computePlanChecks(records, detectedPlans = []) {
             suggestedPlan: detectedKnown ?? suggested,
             monthlySavingsVsApiUsd: effectiveSavings,
             valueMultiple,
-            detectedPlan: detected,
+            // The STRUCTURED sibling of the headline. Neutralizing the sentence and
+            // shipping the raw label beside it in the same object is the inversion
+            // that let a hostile name reach an agent while the human saw a redaction.
+            detectedPlan: detected === undefined ? undefined : {
+                ...detected,
+                planLabel: safePlanLabel(detected.planLabel),
+                ...(detected.limitSignal === undefined
+                    ? {}
+                    : { limitSignal: safeLimitSignal(detected.limitSignal) })
+            },
             upgradeHint,
             headline
         });