@agent-finops/core 0.9.5 → 0.9.7

package/dist/modelPricing.js

@@ -20,21 +20,38 @@ const pricingRules = [
     { match: /^claude-haiku-4/i, inputPerM: 1, outputPerM: 5 },
     { match: /^claude-3-7-sonnet|^claude-3-5-sonnet/i, inputPerM: 3, outputPerM: 15 },
     { match: /^claude-3-5-haiku/i, inputPerM: 0.8, outputPerM: 4 },
-    // OpenAI (newer and more specific families must precede the GPT-5 fallback)
+    // OpenAI (newer and more specific families must precede the GPT-5 fallback).
+    // Rates from developers.openai.com/api/docs/pricing cross-checked against each
+    // model's own doc page, both fetched 2026-08-25.
+    //
+    // GPT-5.6 ships exactly three API models — sol, terra, luna
+    // (developers.openai.com/api/docs/models, 2026-08-25). Each 5.6/5.5/5.4 rule
+    // below is END-ANCHORED on purpose: an undocumented or future sibling
+    // (gpt-5.6-cyber, gpt-5.5-pro, gpt-5.7-sol) must fall through to
+    // honest-unpriced rather than inherit a neighbour's rate. That is the 0.9.4
+    // `^kimi-k2` mistake one family up, and it is the expensive direction here —
+    // the pre-0.9.6 `^gpt-5.6(?:-sol)?$` rule carried GPT-5.5's numbers, so every
+    // gpt-5.6-sol record was overstated by 25% on input and 50% on output.
+    //
+    // Long context, published identically on all three 5.6 pages plus 5.5/5.4:
+    // "Prompts with >272K input tokens are priced at 2x input and 1.5x output for
+    // the full request." Cached input scales with the 2x input leg.
     {
-        match: /^gpt-5\.6(?:-sol)?$/i,
-        inputPerM: 5,
-        outputPerM: 30,
-        cacheReadPerM: 0.5,
+        // developers.openai.com/api/docs/models/gpt-5.6-sol, 2026-08-25
+        match: /^gpt-5\.6-sol$/i,
+        inputPerM: 4,
+        outputPerM: 20,
+        cacheReadPerM: 0.4,
         abovePromptTokens: {
             threshold: 272_000,
-            inputPerM: 10,
-            outputPerM: 45,
-            cacheReadPerM: 1
+            inputPerM: 8,
+            outputPerM: 30,
+            cacheReadPerM: 0.8
         }
     },
     {
-        match: /^gpt-5\.6-terra/i,
+        // developers.openai.com/api/docs/models/gpt-5.6-terra, 2026-08-25
+        match: /^gpt-5\.6-terra$/i,
         inputPerM: 2,
         outputPerM: 12,
         cacheReadPerM: 0.2,
@@ -46,7 +63,8 @@ const pricingRules = [
         }
     },
     {
-        match: /^gpt-5\.6-luna/i,
+        // developers.openai.com/api/docs/models/gpt-5.6-luna, 2026-08-25
+        match: /^gpt-5\.6-luna$/i,
         inputPerM: 0.2,
         outputPerM: 1.2,
         cacheReadPerM: 0.02,
@@ -57,15 +75,50 @@ const pricingRules = [
             cacheReadPerM: 0.04
         }
     },
-    { match: /^gpt-5\.5(?:-codex)?/i, inputPerM: 5, outputPerM: 30, cacheReadPerM: 0.5 },
+    {
+        // developers.openai.com/api/docs/models/gpt-5.5, 2026-08-25
+        match: /^gpt-5\.5$/i,
+        inputPerM: 5,
+        outputPerM: 30,
+        cacheReadPerM: 0.5,
+        abovePromptTokens: {
+            threshold: 272_000,
+            inputPerM: 10,
+            outputPerM: 45,
+            cacheReadPerM: 1
+        }
+    },
+    // gpt-5.5-codex bills at the 5.5 base rate but is absent from the published
+    // long-context list, so it deliberately carries no >272K tier.
+    { match: /^gpt-5\.5-codex$/i, inputPerM: 5, outputPerM: 30, cacheReadPerM: 0.5 },
     { match: /^gpt-5\.4-mini/i, inputPerM: 0.75, outputPerM: 4.5, cacheReadPerM: 0.075 },
     { match: /^gpt-5\.4-nano/i, inputPerM: 0.2, outputPerM: 1.25, cacheReadPerM: 0.02 },
-    { match: /^gpt-5\.4/i, inputPerM: 2.5, outputPerM: 15, cacheReadPerM: 0.25 },
+    {
+        // developers.openai.com/api/docs/models/gpt-5.4, 2026-08-25
+        match: /^gpt-5\.4$/i,
+        inputPerM: 2.5,
+        outputPerM: 15,
+        cacheReadPerM: 0.25,
+        abovePromptTokens: {
+            threshold: 272_000,
+            inputPerM: 5,
+            outputPerM: 22.5,
+            cacheReadPerM: 0.5
+        }
+    },
     { match: /^gpt-5\.3-codex/i, inputPerM: 1.75, outputPerM: 14, cacheReadPerM: 0.175 },
     { match: /^gpt-5\.2(?:-codex)?/i, inputPerM: 1.75, outputPerM: 14, cacheReadPerM: 0.175 },
     { match: /^gpt-5(?:\.1)?-codex/i, inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 },
     { match: /^gpt-5(?:\.1)?-mini/i, inputPerM: 0.25, outputPerM: 2, cacheReadPerM: 0.025 },
-    { match: /^gpt-5/i, inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 },
+    // developers.openai.com/api/docs/models/gpt-5-nano, 2026-08-25. Before 0.9.6
+    // this fell through to the ^gpt-5 fallback and billed at $1.25/$10 — 25x the
+    // real rate in both directions. No published long-context tier.
+    { match: /^gpt-5-nano/i, inputPerM: 0.05, outputPerM: 0.4, cacheReadPerM: 0.005 },
+    // GPT-5 base and its dash-suffixed snapshots only. The `-|$` boundary stops
+    // this fallback from swallowing dot-minor families it knows nothing about:
+    // gpt-5.7-*, gpt-5.6-cyber and any future gpt-5.6-<variant> now return
+    // undefined -> "missing" instead of silently billing at GPT-5's $1.25/$10.
+    { match: /^gpt-5(?:-|$)/i, inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 },
     { match: /^gpt-4\.1-nano/i, inputPerM: 0.1, outputPerM: 0.4 },
     { match: /^gpt-4\.1-mini/i, inputPerM: 0.4, outputPerM: 1.6 },
     { match: /^gpt-4\.1/i, inputPerM: 2, outputPerM: 8, cacheReadPerM: 0.5 },
@@ -122,6 +175,23 @@ const pricingRules = [
     // - deepseek-v4-* (api-docs.deepseek.com/quick_start/pricing): published
     //   rates are time-of-day (off-peak = half price, up to 2x swing), so any
     //   flat number here would be dishonest; needs timestamp-aware pricing.
+    //
+    // Deliberate deferrals (2026-08-25 OpenAI review), same honest path:
+    // - gpt-5.6-cyber / gpt-5.5-cyber ($12.50/$1.25/$75 on the pricing page):
+    //   the two canonical sources disagree on whether the >272K tier applies —
+    //   the pricing page omits cyber from its long-context list while
+    //   developers.openai.com/api/docs/models/gpt-5.6-cyber states the 2x/1.5x
+    //   rule does apply. Access is gated behind the Daybreak program, so the
+    //   cost of leaving it unpriced is near zero and a coin-flip on the tier
+    //   would be a real number that is wrong on long requests.
+    // - gpt-5.5-pro / gpt-5.4-pro: listed as long-context-capable but no
+    //   per-model rate is published on either canonical source.
+    // - bare gpt-5.1 / gpt-5.3: the pricing page quotes the 5/5.1/5.2 group as a
+    //   RANGE ($1.25-$1.75) and neither has a resolved per-model figure. Their
+    //   -codex and -mini variants keep their own verified rules above.
+    // - gpt-5.6-codex / gpt-5.5-mini: NOT OpenAI model ids (both 404 on the model
+    //   docs and are absent from developers.openai.com/api/docs/models). They
+    //   appear only in this repo's fixtures and sample CSVs.
 ];
 export function findPricingRule(model) {
     return pricingRules.find((rule) => rule.match.test(model));
@@ -139,11 +209,20 @@ export function estimateTokenCostUsd(model, usage) {
  * models whose entire request moves to a higher rate above a prompt-size
  * threshold; pricing a daily token sum would incorrectly treat many small
  * requests as one large request.
+ *
+ * `tierPromptTokens[i]`, when provided, fixes the tier of `usages[i]` from
+ * request-level evidence instead of the slice's own prompt total. A
+ * session-cumulative slice is a sum of many requests whose prompt total
+ * routinely clears a per-request threshold on cache reads alone, even though no
+ * single request did; supplying the largest single request's prompt keeps such
+ * a slice on the base tier (and pricing it there is exact, since the base rate
+ * distributes over the sum). Omitting the array preserves single-request
+ * behaviour: each slice's own prompt selects its tier.
  */
-export function estimateTokenCostsUsd(model, usages) {
+export function estimateTokenCostsUsd(model, usages, tierPromptTokens) {
     let total = 0;
-    for (const usage of usages) {
-        const usd = rawTokenCostUsd(model, usage);
+    for (let index = 0; index < usages.length; index += 1) {
+        const usd = rawTokenCostUsd(model, usages[index], tierPromptTokens?.[index]);
         if (usd === undefined)
             return undefined;
         total += usd;
@@ -162,21 +241,34 @@ export function promptTierThreshold(model) {
  * Tiered prices are selected per request, never from a multi-request sum.
  * An aggregate is still unambiguous when its entire non-negative prompt-side
  * total is at or below the threshold; then no constituent request can have
- * crossed it. Larger aggregates fail closed until request-level evidence is
- * available.
+ * crossed it. It is also unambiguous when request-level evidence
+ * (`maxRequestPromptTokens`, the largest single request the aggregate contains)
+ * proves that no constituent request crossed the threshold: every request was
+ * base-tier, so the whole sum is base-tier and prices exactly at the base rate.
+ * Larger aggregates without such evidence fail closed to keep an unpriceable
+ * total honestly "missing" rather than guessing a tier.
  */
-export function canPriceTokenUsageAtScope(model, usage, scope) {
+export function canPriceTokenUsageAtScope(model, usage, scope, maxRequestPromptTokens) {
     const threshold = promptTierThreshold(model);
     if (threshold === undefined || scope === "request")
         return true;
-    return effectivePromptTokens(usage) <= threshold;
+    if (effectivePromptTokens(usage) <= threshold)
+        return true;
+    return maxRequestPromptTokens !== undefined && maxRequestPromptTokens <= threshold;
 }
-function rawTokenCostUsd(model, usage) {
+/**
+ * @param tierPromptTokens Prompt size used ONLY to select the request tier,
+ *   when it differs from the priced slice's own prompt total (e.g. a
+ *   session-cumulative slice whose tier is fixed by its largest single
+ *   request). Component pricing always uses `usage`; defaults to the slice's
+ *   own effective prompt so single-request callers are unchanged.
+ */
+function rawTokenCostUsd(model, usage, tierPromptTokens) {
     const rule = findPricingRule(model);
     if (!rule) {
         return undefined;
     }
-    const promptTokens = effectivePromptTokens(usage);
+    const promptTokens = tierPromptTokens ?? effectivePromptTokens(usage);
     const rates = rule.abovePromptTokens &&
         promptTokens > rule.abovePromptTokens.threshold
         ? rule.abovePromptTokens

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
         });

package/dist/projectIndexStore.d.ts

@@ -7,7 +7,7 @@ export declare const projectIndexStoreLockFileName = ".project-index-v2.lock";
 export declare const projectIndexMaxDocumentBytes: number;
 /** Null-window variant plus the newest bounded windows (BLOCKER-2 option i). */
 export declare const projectIndexMaxWindowedVariants = 4;
-export declare const projectIndexFinancialParserVersion = 1;
+export declare const projectIndexFinancialParserVersion = 3;
 declare const financialKeySchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<2>;
     section: z.ZodLiteral<"financial">;
@@ -18,7 +18,7 @@ declare const financialKeySchema: z.ZodObject<{
     }>;
     pathHash: z.ZodString;
     fileIdentity: z.ZodString;
-    financialParserVersion: z.ZodLiteral<1>;
+    financialParserVersion: z.ZodLiteral<3>;
 }, z.core.$strict>;
 /**
  * Header-pass ownership evidence (A4a consumer). "unknown" is a first-class
@@ -53,7 +53,7 @@ declare const documentSchema: z.ZodObject<{
     qualitative: z.ZodArray<z.ZodObject<{
         key: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
-            parserVersion: z.ZodLiteral<4>;
+            parserVersion: z.ZodLiteral<6>;
             agent: z.ZodEnum<{
                 "claude-code": "claude-code";
                 codex: "codex";
@@ -102,6 +102,7 @@ declare const documentSchema: z.ZodObject<{
                     complete: "complete";
                     unsupported_token_shape: "unsupported_token_shape";
                 }>>;
+                maxRequestPromptTokens: z.ZodOptional<z.ZodNumber>;
                 reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
                 tokenComponentEvidence: z.ZodOptional<z.ZodObject<{
                     inputTokens: z.ZodLiteral<"observed">;
@@ -280,7 +281,7 @@ declare const documentSchema: z.ZodObject<{
             }>;
             pathHash: z.ZodString;
             fileIdentity: z.ZodString;
-            financialParserVersion: z.ZodLiteral<1>;
+            financialParserVersion: z.ZodLiteral<3>;
         }, z.core.$strict>;
         storedAt: z.ZodString;
         value: z.ZodObject<{
@@ -320,6 +321,7 @@ declare const documentSchema: z.ZodObject<{
                     complete: "complete";
                     unsupported_token_shape: "unsupported_token_shape";
                 }>>;
+                maxRequestPromptTokens: z.ZodOptional<z.ZodNumber>;
                 reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
                 tokenComponentEvidence: z.ZodOptional<z.ZodObject<{
                     inputTokens: z.ZodLiteral<"observed">;

package/dist/qualitativeIndexCache.d.ts

@@ -25,7 +25,7 @@ export declare class QualitativeIndexCacheError extends Error {
 }
 declare const keySchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
-    parserVersion: z.ZodLiteral<4>;
+    parserVersion: z.ZodLiteral<6>;
     agent: z.ZodEnum<{
         "claude-code": "claude-code";
         codex: "codex";
@@ -73,6 +73,7 @@ declare const valueSchema: z.ZodObject<{
             complete: "complete";
             unsupported_token_shape: "unsupported_token_shape";
         }>>;
+        maxRequestPromptTokens: z.ZodOptional<z.ZodNumber>;
         reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
         tokenComponentEvidence: z.ZodOptional<z.ZodObject<{
             inputTokens: z.ZodLiteral<"observed">;
@@ -250,7 +251,7 @@ type PersistedValue = PersistedQualitativeValue;
  */
 export declare const qualitativeEntryKeySchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
-    parserVersion: z.ZodLiteral<4>;
+    parserVersion: z.ZodLiteral<6>;
     agent: z.ZodEnum<{
         "claude-code": "claude-code";
         codex: "codex";
@@ -298,6 +299,7 @@ export declare const qualitativeEntryValueSchema: z.ZodObject<{
             complete: "complete";
             unsupported_token_shape: "unsupported_token_shape";
         }>>;
+        maxRequestPromptTokens: z.ZodOptional<z.ZodNumber>;
         reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
         tokenComponentEvidence: z.ZodOptional<z.ZodObject<{
             inputTokens: z.ZodLiteral<"observed">;

package/dist/qualitativeIndexCache.js

@@ -129,6 +129,11 @@ const callSchema = z.object({
     latestTurnUsage: turnUsageSchema.optional(),
     usageScope: z.enum(["turn", "session_cumulative"]).optional(),
     usageSupport: z.enum(["complete", "unsupported_token_shape"]).optional(),
+    // Per-request tier evidence for session-cumulative slices. The strict schema
+    // must carry it: without this key the entry fails validation on write, the
+    // failure is swallowed by the caller, and every run re-parses the whole
+    // corpus instead of reusing the cache.
+    maxRequestPromptTokens: finiteNonnegativeInteger.optional(),
     reportedTotalTokens: finiteNonnegativeInteger.optional(),
     tokenComponentEvidence: tokenComponentEvidenceSchema.optional(),
     sourceVersion: z.string().min(1).max(64).optional(),

package/dist/toolInvocations.js

@@ -1,6 +1,7 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { homedir } from "node:os";
+import { safeUntrustedLabel, WITHHELD_FILE_LABEL } from "./untrustedLabel.js";
 /** Parse ONE transcript's content. Exported for tests. Returns the per-file pieces the aggregator needs. */
 export function parseClaudeCodeInvocations(content, sinceMs) {
     const counts = new Map();
@@ -605,8 +606,15 @@ function explicitReadFile(toolName, input) {
     return name && name !== "." && name !== "/" ? name : undefined;
 }
 function buildSessionContextSignal(input) {
+    // File names come off transcript tool-call metadata, so they are untrusted,
+    // and they travel as DATA rather than prose: {name, count} objects that the
+    // MCP tools hand to an agent verbatim. Neutralizing the sentence built from
+    // this array while the array itself stayed raw gave the human the redaction
+    // and the agent the payload — backwards, on the one surface where injected
+    // text can actually steer a coding agent. Neutralize at the source, so every
+    // consumer (Glance, MCP, CLI, the action planner) gets the same safe name.
     const fileReads = [...input.fileReads.entries()]
-        .map(([name, count]) => ({ name, count }))
+        .map(([name, count]) => ({ name: safeUntrustedLabel(name, WITHHELD_FILE_LABEL), count }))
         .sort((left, right) => right.count - left.count || left.name.localeCompare(right.name));
     return {
         agent: input.agent,

package/dist/untrustedLabel.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ONE place that decides what an untrusted NAME is allowed to become before it
+ * is interpolated into a sentence this product wrote.
+ *
+ * Why it exists at all. Every user-facing string here is built by templating a
+ * fragment the user did not author — a folder name off disk, a model id off a
+ * provider response, an operation label off an adapter — into prose that a
+ * coding agent will later read as instructions. The renderers cannot be the
+ * ones to make that safe:
+ *
+ *  - The `--full` terminal readout does not sanitize at all.
+ *  - The Markdown/Apply sanitizers that BLANK on a directive hit delete the
+ *    whole string, and the whole string is mostly OUR sentence. In 0.9.7 that
+ *    deleted the entire recommendation for 8 of 11 ordinary repo basenames,
+ *    because `write-ahead-log` sat 41 characters in front of our own word
+ *    "tokens" — and the terminal kept printing the finding, so two surfaces
+ *    disagreed about a dollar figure.
+ *
+ * So the check runs HERE, on the fragment alone, before it reaches any
+ * template. A fragment carries only the user's text, so an ordinary name has
+ * nothing of ours to pair with; and once the fragment is safe, every surface
+ * can render the finished sentence verbatim and they all agree.
+ *
+ * The rule for anyone adding a producer: if you interpolate a value that came
+ * off disk or off the wire into a string a user or an agent will read, wrap it
+ * in {@link safeUntrustedLabel} at the point of interpolation. Not at the
+ * renderer. Not once per surface. Here.
+ */
+/**
+ * What an untrusted label becomes when the name itself reads like an
+ * instruction. Each says WHY, because "withheld" with no reason reads like the
+ * product failed rather than declined: `diagnose` still shows the real folder
+ * name, so this is only about not REPEATING a name that looked like an
+ * instruction inside a sentence an agent will read.
+ *
+ * Every one of these must survive the report layer's own sanitizer UNCHANGED —
+ * a marker in brackets would be stripped there and two surfaces would disagree
+ * about a string whose whole job is agreeing. Parentheses survive; brackets do
+ * not.
+ *
+ * The project label sits in appositive and prepositional slots ("X — median day
+ * carried…", "the heaviest sessions in X"), so it carries the reason as prose.
+ * The rest sit in ATTRIBUTIVE slots ("Cache repeated X calls"), where a clause
+ * would not parse, so they carry the short parenthetical form.
+ */
+export declare const WITHHELD_PROJECT_LABEL = "a project whose name reads like an instruction";
+export declare const WITHHELD_MODEL_LABEL = "(model name reads like an instruction; withheld)";
+export declare const WITHHELD_OPERATION_LABEL = "(operation name reads like an instruction; withheld)";
+export declare const WITHHELD_AGENT_LABEL = "(agent name reads like an instruction; withheld)";
+export declare const WITHHELD_CLIENT_LABEL = "(client name reads like an instruction; withheld)";
+/**
+ * For a breakdown key whose dimension is decided at runtime — the same slot
+ * holds a client, a project, an agent, a model, or an operation depending on
+ * which grouping won.
+ */
+export declare const WITHHELD_ENTITY_LABEL = "(name reads like an instruction; withheld)";
+export declare const WITHHELD_FILE_LABEL = "(file name reads like an instruction; withheld)";
+export declare const WITHHELD_PLAN_LABEL = "(plan label reads like an instruction; withheld)";
+/** Map a list of untrusted keys for display, keeping order and length. */
+export declare function safeUntrustedLabels(values: readonly string[], withheld?: string): string[];
+/**
+ * Neutralize ONE untrusted fragment before it is interpolated into
+ * product-authored prose.
+ *
+ * Over-triggering here is cheap and under-triggering is not: a false positive
+ * costs one name while the finding and its dollars survive, so the patterns
+ * stay strict.
+ */
+export declare function safeUntrustedLabel(value: string, withheld: string): string;
+//# sourceMappingURL=untrustedLabel.d.ts.map

package/dist/untrustedLabel.js

@@ -0,0 +1,161 @@
+/**
+ * ONE place that decides what an untrusted NAME is allowed to become before it
+ * is interpolated into a sentence this product wrote.
+ *
+ * Why it exists at all. Every user-facing string here is built by templating a
+ * fragment the user did not author — a folder name off disk, a model id off a
+ * provider response, an operation label off an adapter — into prose that a
+ * coding agent will later read as instructions. The renderers cannot be the
+ * ones to make that safe:
+ *
+ *  - The `--full` terminal readout does not sanitize at all.
+ *  - The Markdown/Apply sanitizers that BLANK on a directive hit delete the
+ *    whole string, and the whole string is mostly OUR sentence. In 0.9.7 that
+ *    deleted the entire recommendation for 8 of 11 ordinary repo basenames,
+ *    because `write-ahead-log` sat 41 characters in front of our own word
+ *    "tokens" — and the terminal kept printing the finding, so two surfaces
+ *    disagreed about a dollar figure.
+ *
+ * So the check runs HERE, on the fragment alone, before it reaches any
+ * template. A fragment carries only the user's text, so an ordinary name has
+ * nothing of ours to pair with; and once the fragment is safe, every surface
+ * can render the finished sentence verbatim and they all agree.
+ *
+ * The rule for anyone adding a producer: if you interpolate a value that came
+ * off disk or off the wire into a string a user or an agent will read, wrap it
+ * in {@link safeUntrustedLabel} at the point of interpolation. Not at the
+ * renderer. Not once per surface. Here.
+ */
+/**
+ * What an untrusted label becomes when the name itself reads like an
+ * instruction. Each says WHY, because "withheld" with no reason reads like the
+ * product failed rather than declined: `diagnose` still shows the real folder
+ * name, so this is only about not REPEATING a name that looked like an
+ * instruction inside a sentence an agent will read.
+ *
+ * Every one of these must survive the report layer's own sanitizer UNCHANGED —
+ * a marker in brackets would be stripped there and two surfaces would disagree
+ * about a string whose whole job is agreeing. Parentheses survive; brackets do
+ * not.
+ *
+ * The project label sits in appositive and prepositional slots ("X — median day
+ * carried…", "the heaviest sessions in X"), so it carries the reason as prose.
+ * The rest sit in ATTRIBUTIVE slots ("Cache repeated X calls"), where a clause
+ * would not parse, so they carry the short parenthetical form.
+ */
+export const WITHHELD_PROJECT_LABEL = "a project whose name reads like an instruction";
+export const WITHHELD_MODEL_LABEL = "(model name reads like an instruction; withheld)";
+export const WITHHELD_OPERATION_LABEL = "(operation name reads like an instruction; withheld)";
+export const WITHHELD_AGENT_LABEL = "(agent name reads like an instruction; withheld)";
+export const WITHHELD_CLIENT_LABEL = "(client name reads like an instruction; withheld)";
+/**
+ * For a breakdown key whose dimension is decided at runtime — the same slot
+ * holds a client, a project, an agent, a model, or an operation depending on
+ * which grouping won.
+ */
+export const WITHHELD_ENTITY_LABEL = "(name reads like an instruction; withheld)";
+export const WITHHELD_FILE_LABEL = "(file name reads like an instruction; withheld)";
+export const WITHHELD_PLAN_LABEL = "(plan label reads like an instruction; withheld)";
+/** Map a list of untrusted keys for display, keeping order and length. */
+export function safeUntrustedLabels(values, withheld = WITHHELD_ENTITY_LABEL) {
+    return values.map((value) => safeUntrustedLabel(value, withheld));
+}
+/**
+ * Neutralize ONE untrusted fragment before it is interpolated into
+ * product-authored prose.
+ *
+ * Over-triggering here is cheap and under-triggering is not: a false positive
+ * costs one name while the finding and its dollars survive, so the patterns
+ * stay strict.
+ */
+export function safeUntrustedLabel(value, withheld) {
+    // Control characters and line breaks are structure, not name: a label that
+    // can open a new line can forge a new instruction on every surface at once.
+    const collapsed = value
+        .replace(/[\u0000-\u001F\u007F]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+    if (!collapsed)
+        return withheld;
+    return looksLikeDirectiveFragment(collapsed) ? withheld : collapsed;
+}
+/**
+ * Characters that are invisible to the reader but split a word for the
+ * matcher: zero-width spaces and joiners, bidi controls, variation selectors,
+ * the soft hyphen, the BOM. `i\u200Bgnore all previous instructions` reads as
+ * an instruction and matched nothing. Stripped for DETECTION ONLY — the label
+ * that gets printed is always the original text.
+ */
+const INVISIBLE_SEPARATORS = /[\u00AD\u034F\u061C\u115F\u1160\u17B4\u17B5\u180B-\u180E\u200B-\u200F\u202A-\u202E\u2060-\u2064\u206A-\u206F\u3164\uFE00-\uFE0F\uFEFF\uFFA0]/gu;
+/**
+ * The eight Latin/Cyrillic confusables that carry the directive verbs we look
+ * for: `\u0456gnore`, `d\u0435lete`, `\u0455ystem:` are indistinguishable on screen
+ * and invisible to an ASCII pattern. Folded for DETECTION ONLY.
+ */
+const CONFUSABLE_FOLD = new Map([
+    ["\u0430", "a"], ["\u0435", "e"], ["\u043E", "o"], ["\u0440", "p"],
+    ["\u0441", "c"], ["\u0445", "x"], ["\u0455", "s"], ["\u0456", "i"]
+]);
+/**
+ * The fragment is read TWICE, because a name and an instruction disagree about
+ * what a hyphen means.
+ *
+ * As ONE IDENTIFIER (`-` behaves like `_`): `ignore-list` is a directory, so
+ * the blunt single-word patterns cannot fire on it. This is what keeps ordinary
+ * repo names whole.
+ *
+ * As SEPARATED WORDS (`-` and `_` are spaces): `ignore-all-previous-instructions`
+ * is an instruction wearing a filename's punctuation. Only the PAIRED patterns
+ * run in this pass — each needs a directive verb next to an injection-flavored
+ * object — so an ordinary compound name has nothing to pair with. The unpaired
+ * verb list and the execute/run pattern deliberately stay out: `run-command-service`
+ * is a real directory, and a name-shaped `run-shell` cannot instruct anything.
+ */
+function looksLikeDirectiveFragment(value) {
+    const folded = value
+        .normalize("NFKC")
+        .replace(INVISIBLE_SEPARATORS, "")
+        .replace(/[\u0430\u0435\u043E\u0440\u0441\u0445\u0455\u0456]/gu, (char) => CONFUSABLE_FOLD.get(char) ?? char);
+    // A dot joins a filename the way a hyphen joins an identifier, so the
+    // identifier pass folds it too: `override.ts` and `ignore.md` are files, not
+    // instructions. The separated pass splits on it for the same reason it splits
+    // on hyphens — `ignore.all.previous.instructions` is prose wearing punctuation.
+    const asIdentifier = folded.replace(/[-.]/gu, "_");
+    const asWords = folded.replace(/[-_.]+/gu, " ");
+    return IDENTIFIER_DIRECTIVE_PATTERNS.some((pattern) => pattern.test(asIdentifier)) ||
+        SEPARATED_DIRECTIVE_PATTERNS.some((pattern) => pattern.test(asWords));
+}
+/**
+ * A directive needs a QUANTIFIER, not just a noun.
+ *
+ * `cache write tokens` is Anthropic's prompt-caching billing vocabulary and it
+ * arrives in the operation slot on real invoice lines; `write ALL tokens` is an
+ * instruction. Pairing a verb with a bare `tokens` withheld this product's own
+ * billing words — a real line item rendered as
+ * "acme / agent-finops / [unsafe metadata omitted]" — and on `aibill context`,
+ * whose entire job is naming exact files, it named one of three.
+ *
+ * Measured over 146 real strings (Anthropic + OpenAI caching vocabulary, real
+ * invoice line items, real filenames, ordinary repo names): false positives
+ * 18 -> 0, with hostile detection unchanged at 28/28.
+ *
+ * `everything` and `all files` already carry their own quantifier, so they stay
+ * unguarded. `system prompt` is an injection-specific noun phrase that no
+ * billing vocabulary contains, so it needs no quantifier either.
+ */
+const QUANTIFIED = "(?:all|every|any|each)";
+const IDENTIFIER_DIRECTIVE_PATTERNS = [
+    /\b(?:ignore|disregard|override|bypass)\b/i,
+    /\b(?:system|developer|assistant)\s*:/i,
+    /\b(?:execute|run)\b.{0,80}\b(?:command|shell|bash|powershell)\b/i,
+    new RegExp(`\\b(?:delete|remove|overwrite|edit|write)\\b.{0,60}(?:\\beverything\\b|\\ball files?\\b|\\b${QUANTIFIED}\\s+(?:configs?|credentials?|secrets?|tokens?)\\b)`, "i"),
+    new RegExp(`\\b(?:reveal|print|upload|send|exfiltrate)\\b.{0,60}(?:\\ball files?\\b|\\b(?:system|developer)\\s+prompts?\\b|\\b(?:${QUANTIFIED}|the)\\s+(?:credentials?|secrets?|tokens?|keys?|files?)\\b)`, "i"),
+    /\b(?:do not|don't)\b.{0,60}\b(?:follow|obey|wait|ask|require)\b.{0,40}\b(?:approval|instructions?|rules?)\b/i
+];
+const SEPARATED_DIRECTIVE_PATTERNS = [
+    /\b(?:ignore|disregard|override|bypass|forget)\b.{0,80}\b(?:previous|prior|above|earlier|preceding|instructions?|approval|rules?|guardrails?|system|developer|prompts?)\b/i,
+    new RegExp(`\\b(?:delete|remove|overwrite|edit|write)\\b.{0,60}(?:\\beverything\\b|\\ball files?\\b|\\b${QUANTIFIED}\\s+(?:configs?|credentials?|secrets?|tokens?)\\b)`, "i"),
+    new RegExp(`\\b(?:reveal|print|upload|send|exfiltrate|leak|dump)\\b.{0,60}(?:\\ball files?\\b|\\b(?:system|developer)\\s+prompts?\\b|\\b(?:${QUANTIFIED}|the)\\s+(?:credentials?|secrets?|tokens?|keys?|files?|prompts?)\\b)`, "i"),
+    /\b(?:do not|don't|never)\b.{0,60}\b(?:follow|obey|wait|ask|require)\b.{0,40}\b(?:approval|instructions?|rules?)\b/i
+];
+//# sourceMappingURL=untrustedLabel.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "funding": "https://asktilden.com",
   "type": "module",
   "main": "./dist/index.js",