@clear-capabilities/agentic-security-scanner 0.120.0 → 0.122.0

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-40d6882dc7b5dbd62ac41f10cb01ec4e43fa42081dbcc0427553e0282748fedb  agentic-security.mjs
+3249693b62570256c597f206447598e9ed6b618032f0d0a5a25dbbf62d53afc8  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.120.0",
+  "version": "0.122.0",
   "description": "Scanner engine for the agentic-security Claude Code plugin — SAST, SCA (function-level reachability + CISA KEV), secrets, IaC, prompt-injection, MCP/agent-tool audit, auth/authZ deep analysis, attack chains, PoC generation, business logic, toxic-combinations scoring, SBOM, SARIF ingest, pipeline integrity, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",
@@ -61,12 +61,12 @@
     "test": "npm run test:smoke && npm run test:sast && npm run test:posture && npm run test:dataflow && npm run test:mcp && npm run test:report && npm run test:bench-modules && npm run test:lifecycle && npm run test:eval && AGENTIC_SECURITY_CPP_DATAFLOW=1 node --test test/cpp-dataflow.test.js",
     "test:smoke": "node --test test/smoke.test.js",
     "test:sast": "node --test test/llm.test.js test/llm-owasp.test.js test/logic.test.js test/authz.test.js test/model-load.test.js test/prompt-template.test.js test/business-logic.test.js test/python-sinks.test.js test/phase1-detectors.test.js test/phase2-detectors.test.js test/phase3-v3.test.js test/phase7-extensions.test.js test/phase8-extensions.test.js test/new-cwe-detectors.test.js test/llmsecops-detectors.test.js test/db-taint.test.js test/dart-swift.test.js test/redos-nfa.test.js test/weak-randomness.test.js test/csharp-pipeline.test.js test/post-quantum-crypto.test.js test/web3-advanced.test.js test/cloud-iam-k8s.test.js test/crypto-protocol.test.js test/ml-supply-chain.test.js test/wrong-context-sanitizer.test.js test/sanitizer-context.test.js test/frontend-hygiene.test.js test/csv-injection.test.js test/stored-taint.test.js test/tree-sitter-sinks.test.js test/kotlin-structural.test.js test/ruby-php-structural.test.js test/java-csharp-structural.test.js test/guard-recognition.test.js test/js-python-framework-structural.test.js test/go-structural.test.js test/secret-concat.test.js test/xss-reflected-multilang.test.js test/code-injection-multilang.test.js test/xxe-multilang.test.js test/xpath-injection-multilang.test.js test/gapfill-batch13.test.js test/agent-untrusted-flow.test.js test/api-authz.test.js test/event-entrypoint.test.js test/iac-terraform.test.js test/cross-service.test.js test/rbac-consistency.test.js",
-    "test:posture": "node --test test/material-change.test.js test/drift.test.js test/scorecard.test.js test/mttr.test.js test/license-policy.test.js test/aibom.test.js test/sbom.test.js test/api-inventory.test.js test/iam-policy.test.js test/container.test.js test/container-runtime.test.js test/image-packages.test.js test/kev.test.js test/dep-confusion.test.js test/sca-deprecated.test.js test/sca-batch.test.js test/composite-risk.test.js test/sca-coverage.test.js test/gradle-deps.test.js test/sca-route-reachable.test.js test/sca-policy.test.js test/sca-verdict.test.js test/install-script.test.js test/sca-linked-findings.test.js test/packs.test.js test/flow-narration.test.js test/regression-test-gen.test.js test/rule-synthesis.test.js test/policy-gate.test.js test/agents-memory.test.js test/cve-lookup.test.js test/cve-alert-daemon.test.js test/fix-verify-loop.test.js test/fix-acceptance.test.js test/exploitability-probability.test.js test/history-scan.test.js test/viral-features.test.js test/viral-v074.test.js test/state-dir.test.js test/license-graph.test.js test/attack-taxonomy.test.js test/triage-memory.test.js test/pr-augment.test.js test/chat-batch2.test.js test/chat-batch3.test.js test/chat-batch4.test.js test/chat-batch5.test.js test/chat-batch6.test.js test/router.test.js test/legacy-alias-redirect.test.js test/coverage-report.test.js test/corpus-status.test.js test/provenance.test.js test/secret-history.test.js",
+    "test:posture": "node --test test/material-change.test.js test/drift.test.js test/scorecard.test.js test/mttr.test.js test/license-policy.test.js test/aibom.test.js test/sbom.test.js test/api-inventory.test.js test/iam-policy.test.js test/container.test.js test/container-runtime.test.js test/image-packages.test.js test/kev.test.js test/dep-confusion.test.js test/sca-deprecated.test.js test/sca-batch.test.js test/composite-risk.test.js test/sca-coverage.test.js test/gradle-deps.test.js test/sca-route-reachable.test.js test/sca-policy.test.js test/sca-verdict.test.js test/install-script.test.js test/sca-linked-findings.test.js test/packs.test.js test/flow-narration.test.js test/regression-test-gen.test.js test/rule-synthesis.test.js test/policy-gate.test.js test/agents-memory.test.js test/cve-lookup.test.js test/cve-alert-daemon.test.js test/fix-verify-loop.test.js test/fix-acceptance.test.js test/exploitability-probability.test.js test/history-scan.test.js test/viral-features.test.js test/viral-v074.test.js test/state-dir.test.js test/license-graph.test.js test/attack-taxonomy.test.js test/triage-memory.test.js test/pr-augment.test.js test/chat-batch2.test.js test/chat-batch3.test.js test/chat-batch4.test.js test/chat-batch5.test.js test/chat-batch6.test.js test/router.test.js test/legacy-alias-redirect.test.js test/cache-economics.test.js test/coverage-report.test.js test/corpus-status.test.js test/provenance.test.js test/secret-history.test.js",
     "test:dataflow": "node --test test/fn-reach.test.js test/deep-taint.test.js test/calibration.test.js test/holdout-eval.test.js test/cross-lang-meta.test.js test/cross-lang-queues.test.js test/phase5-xlang.test.js test/phase5-coverage.test.js test/phase6-taint.test.js test/llm-validator-consistency.test.js test/llm-validator-default-on.test.js test/parser-py-cst.test.js test/parser-cs-kt.test.js test/parser-go.test.js test/parser-php-rb.test.js test/interproc-k2.test.js test/proven-clean.test.js test/backward-default.test.js test/incremental-cache.test.js test/string-regex-lattice.test.js test/closure-capture.test.js test/points-to.test.js test/type-stubs.test.js test/soft-taint.test.js test/ifds.test.js test/symbolic-exec-proof.test.js test/ifds-summary-edges.test.js test/stub-aware-filter.test.js test/cross-repo.test.js test/proof-gate.test.js test/proof-safe.test.js test/collection-taint.test.js test/kcfa-context.test.js test/kcfa-callstring.test.js test/flow-parity.test.js test/callgraph-resolve.test.js test/import-reachability.test.js",
     "test:mcp": "node --test test/mcp.test.js test/mcp-audit.test.js test/audit-cli.test.js test/mcp-scratchpad.test.js test/mcp-offload.test.js test/sca-upgrade.test.js",
     "test:report": "node --test test/sarif-ingest.test.js test/junit.test.js test/ci.test.js test/poc-generator.test.js test/verifier.test.js test/verifier-target.test.js test/annotator-errors.test.js test/grader-calibration.test.js test/pr-delta-gate.test.js test/vex.test.js",
     "test:bench-modules": "node --test test/phase4-harness.test.js test/pipeline.test.js",
-    "test:lifecycle": "node --test test/dead-code.test.js test/no-dead-modules.test.js test/stop-hook.test.js test/plugin-self-check.test.js test/skills-registry.test.js test/bodyguard.test.js && node ../scripts/lint-command-descriptions.mjs",
+    "test:lifecycle": "node --test test/dead-code.test.js test/no-dead-modules.test.js test/stop-hook.test.js test/plugin-self-check.test.js test/skills-registry.test.js test/bodyguard.test.js test/cache-invalidator-guard.test.js && node ../scripts/lint-command-descriptions.mjs",
     "test:eval": "node --test test/independent-eval.test.js",
     "eval:independent": "node ../bench/independent-eval/runner.mjs",
     "eval:independent:gate": "node ../bench/independent-eval/runner.mjs --gate default",
@@ -81,6 +81,9 @@
     "bench:cve-replay:ci": "node ../bench/cve-replay/runner.mjs --ci",
     "bench:cve-replay:check": "node ../bench/cve-replay/runner.mjs --check-baseline",
     "bench:cve-replay:update-baseline": "node ../bench/cve-replay/runner.mjs --update-baseline",
+    "bench:router-replay": "node ../bench/router-replay/runner.mjs",
+    "bench:router-replay:check": "node ../bench/router-replay/runner.mjs --check-baseline",
+    "bench:router-replay:update-baseline": "node ../bench/router-replay/runner.mjs --update-baseline",
     "bench:bigquery:smoke": "node ../bench/bigquery-github/bin/run-cycle.mjs --smoke",
     "bench:bigquery": "node ../bench/bigquery-github/bin/run-cycle.mjs",
     "bench:agent-tasks": "node ../bench/agent-tasks/security-fixer/runner.mjs",

package/src/mcp/tools.js

@@ -18,6 +18,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { applyFix as applyFixHistory, fixAcceptanceRate } from '../posture/fix-history.js';
 import { verifyLastScan } from '../posture/integrity.js';
+import { analyzeTranscript, formatCacheReport, renderCacheStatusLine } from '../posture/cache-economics.js';
 import { redactString, redactFinding } from './redact.js';
 
 // Lazy-loaded: these transitively pull in npm packages (fast-glob,
@@ -1021,6 +1022,32 @@ export const lookup_cve = {
   },
 };
 
+export const query_cache_telemetry = {
+  name: 'query_cache_telemetry',
+  description: 'Read prompt-cache economics for the current session from the Claude Code transcript: cache-hit %, $ saved by caching, $ wasted on avoidable cache misses (model switches / TTL gaps / prefix changes), and a per-model breakdown. Read-only, no network. Use to reason about token-cost efficiency and whether a model switch is worth the cache rewarm.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      // Optional explicit transcript path; otherwise derived from the session root.
+      transcript_path: { type: 'string', minLength: 1, maxLength: 4096 },
+    },
+    required: [],
+  },
+  async handler({ transcript_path } = {}, ctx) {
+    const result = analyzeTranscript({ transcriptPath: transcript_path, projectDir: ctx?.sessionRoot || process.cwd() });
+    if (!result.ok) return { _meta: META, ok: false, reason: result.reason };
+    return {
+      _meta: META,
+      ok: true,
+      metrics: result.metrics,
+      leaks: result.leaks,
+      report: formatCacheReport(result),
+      statusline: renderCacheStatusLine(result.metrics),
+    };
+  },
+};
+
 // ─── synthesize_sca_upgrade ───────────────────────────────────────────────
 // Phase 3 / Item 5 of the SCA improvement plan. Read-only counterpart to
 // apply_sca_upgrade — produces a structured upgrade plan via the
@@ -1095,4 +1122,4 @@ export const apply_sca_upgrade = {
   },
 };
 
-export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory];
+export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry];

package/src/posture/cache-economics.js

@@ -0,0 +1,269 @@
+// Prompt-cache economics — turn Claude Code's own transcript usage into a
+// dollarized report: how much prompt caching saved, how much was wasted on
+// avoidable cache misses, and what invalidated the cache.
+//
+// Source of truth: the Claude Code transcript at
+//   ~/.claude/projects/<enc>/<session>.jsonl
+// where <enc> is CLAUDE_PROJECT_DIR with `/` and `.` replaced by `-`. Each
+// assistant turn carries `message.usage` with input/output/cache_read/
+// cache_creation token counts (and a 5m/1h write split). We price those against
+// per-model rates to compute real economics — no estimates, no network.
+//
+// Pure compute on parsed records; only `locateTranscript`/`parseTranscriptUsage`
+// touch the filesystem. ESM (scanner tree). A trimmed CJS twin lives at
+// hooks/lib/transcript.js for the CJS hooks; test/cache-economics.test.js asserts
+// the two agree.
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+// Cents-scale money formatter (fmtUsd in risk-dollars.js targets five-figure
+// breach costs and won't round sub-dollar values).
+function money(n) {
+  const v = Number(n) || 0;
+  return Math.abs(v) >= 1 ? `$${v.toFixed(2)}` : `$${v.toFixed(4)}`;
+}
+
+// Per-1M-token rates (input / output). Mirror hooks/model-cost-advisor.js MODELS.
+const MODEL_RATES = {
+  opus:   { label: 'Opus 4.8',   in: 5, out: 25 },
+  sonnet: { label: 'Sonnet 4.6', in: 3, out: 15 },
+  haiku:  { label: 'Haiku 4.5',  in: 1, out: 5 },
+};
+const CACHE_READ_MULT = 0.1;   // cache read ≈ 0.1× input
+const CACHE_WRITE_MULT = 1.25; // 5-minute cache write ≈ 1.25× input
+const CACHE_WRITE_1H_MULT = 2.0; // 1-hour cache write ≈ 2× input
+const TTL_MS = 5 * 60 * 1000;
+
+// Map any model string to a rate family. Returns null for unpriceable models
+// (e.g. "<synthetic>" sidechain/compaction turns) so they're skipped.
+function rateFor(model) {
+  if (typeof model !== 'string') return null;
+  const s = model.toLowerCase();
+  if (s.includes('haiku')) return MODEL_RATES.haiku;
+  if (s.includes('sonnet')) return MODEL_RATES.sonnet;
+  if (s.includes('opus')) return MODEL_RATES.opus;
+  return null;
+}
+
+// ── Transcript discovery + parse ─────────────────────────────────────────────
+
+function encodeProjectDir(dir) {
+  return String(dir).replace(/[/.]/g, '-');
+}
+
+// Locate the session transcript. Prefer an explicit (hook-provided) path; else
+// derive the project's transcript dir and take the most-recently-modified jsonl.
+function locateTranscript({ transcriptPath, projectDir } = {}) {
+  try {
+    if (transcriptPath && fs.existsSync(transcriptPath)) return transcriptPath;
+  } catch { /* fall through */ }
+  try {
+    const dir = path.join(os.homedir(), '.claude', 'projects', encodeProjectDir(projectDir || process.cwd()));
+    if (!fs.existsSync(dir)) return null;
+    const files = fs.readdirSync(dir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => ({ f: path.join(dir, f), m: fs.statSync(path.join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.m - a.m);
+    return files.length ? files[0].f : null;
+  } catch { return null; }
+}
+
+// Parse a transcript jsonl into per-assistant-turn usage records. Skips lines
+// that aren't priceable assistant turns.
+function parseTranscriptUsage(jsonlPath) {
+  let raw;
+  try { raw = fs.readFileSync(jsonlPath, 'utf8'); } catch { return []; }
+  const records = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    let o;
+    try { o = JSON.parse(t); } catch { continue; }
+    if (o.type !== 'assistant') continue;
+    const msg = o.message;
+    const u = msg && msg.usage;
+    if (!u || !msg.model || !rateFor(msg.model)) continue;
+    const cc = u.cache_creation || {};
+    records.push({
+      model: msg.model,
+      input: u.input_tokens || 0,
+      output: u.output_tokens || 0,
+      cacheRead: u.cache_read_input_tokens || 0,
+      cacheCreate: u.cache_creation_input_tokens || 0,
+      cacheCreate5m: cc.ephemeral_5m_input_tokens || 0,
+      cacheCreate1h: cc.ephemeral_1h_input_tokens || 0,
+      ts: o.timestamp ? Date.parse(o.timestamp) : null,
+    });
+  }
+  return records;
+}
+
+// ── Pure economics ───────────────────────────────────────────────────────────
+
+function writeCostUsd(r, inRate) {
+  const m5 = r.cacheCreate5m || 0, m1 = r.cacheCreate1h || 0;
+  if (m5 + m1 > 0) return (m5 * CACHE_WRITE_MULT + m1 * CACHE_WRITE_1H_MULT) * inRate;
+  return (r.cacheCreate || 0) * CACHE_WRITE_MULT * inRate; // breakdown absent
+}
+
+// Aggregate economics over parsed records.
+function computeCacheEconomics(records) {
+  let turns = 0, inTok = 0, outTok = 0, cacheRead = 0, cacheCreate = 0;
+  let actualUsd = 0, uncachedUsd = 0, writePremiumUsd = 0;
+  const perModel = {};
+
+  for (const r of records) {
+    const rate = rateFor(r.model);
+    if (!rate) continue;
+    turns++;
+    const inRate = rate.in / 1e6, outRate = rate.out / 1e6;
+
+    const readCost = r.cacheRead * inRate * CACHE_READ_MULT;
+    const writeCost = writeCostUsd(r, inRate);
+    const inCost = r.input * inRate;
+    const outCost = r.output * outRate;
+    const turnActual = readCost + writeCost + inCost + outCost;
+    // What this turn would have cost with NO caching: every input-side token full price.
+    const turnUncached = (r.cacheRead + r.cacheCreate + r.input) * inRate + outCost;
+
+    actualUsd += turnActual;
+    uncachedUsd += turnUncached;
+    writePremiumUsd += writeCost - (r.cacheCreate * inRate); // the >1× premium paid to cache
+
+    inTok += r.input; outTok += r.output; cacheRead += r.cacheRead; cacheCreate += r.cacheCreate;
+
+    const key = rate.label;
+    const pm = perModel[key] || (perModel[key] = { turns: 0, actualUsd: 0, cacheRead: 0, inputSide: 0 });
+    pm.turns++; pm.actualUsd += turnActual; pm.cacheRead += r.cacheRead;
+    pm.inputSide += r.cacheRead + r.cacheCreate + r.input;
+  }
+
+  const inputSide = cacheRead + cacheCreate + inTok;
+  return {
+    turns,
+    tokens: { input: inTok, output: outTok, cacheRead, cacheCreate },
+    actualUsd,
+    uncachedUsd,
+    savedUsd: uncachedUsd - actualUsd,         // net $ caching saved (can dip negative early)
+    writePremiumUsd,                            // $ invested establishing caches
+    cacheHitRatio: inputSide ? cacheRead / inputSide : 0,
+    costPerTurnUsd: turns ? actualUsd / turns : 0,
+    perModel,
+  };
+}
+
+// Attribute cache drops: a turn that re-ingests a large prefix cold after a warm
+// prior turn. Cause = model-switch | cache-expired | prefix-change.
+function detectInvalidators(records) {
+  const leaks = [];
+  const MIN_WARM = 2000;
+  for (let i = 1; i < records.length; i++) {
+    const prev = records[i - 1], cur = records[i];
+    const prevWarm = prev.cacheRead + prev.input + prev.cacheCreate;
+    if (prevWarm < MIN_WARM) continue;
+    const curFresh = cur.input + cur.cacheCreate;
+    const coldish = cur.cacheRead < prevWarm * 0.25 && curFresh > prevWarm * 0.5;
+    if (!coldish) continue;
+
+    let cause;
+    if (cur.model !== prev.model) cause = 'model-switch';
+    else if (cur.ts && prev.ts && (cur.ts - prev.ts) > TTL_MS) cause = 'cache-expired';
+    else cause = 'prefix-change';
+
+    const rate = rateFor(cur.model);
+    const inRate = rate ? rate.in / 1e6 : 0;
+    // Extra paid vs. having kept the prefix as a cheap cache read.
+    const wastedUsd = prevWarm * inRate * (1 - CACHE_READ_MULT);
+    leaks.push({ turn: i, cause, wastedUsd, model: cur.model });
+  }
+  return leaks;
+}
+
+// Convenience: locate → parse → compute → detect. Returns { ok:false } when no
+// transcript is available.
+export function analyzeTranscript(opts = {}) {
+  const transcript = locateTranscript(opts);
+  if (!transcript) return { ok: false, reason: 'no-transcript' };
+  const records = parseTranscriptUsage(transcript);
+  if (!records.length) return { ok: false, reason: 'no-priceable-turns', transcript };
+  return {
+    ok: true,
+    transcript,
+    metrics: computeCacheEconomics(records),
+    leaks: detectInvalidators(records),
+  };
+}
+
+// ── Report formatting ────────────────────────────────────────────────────────
+
+const CAUSE_LABEL = {
+  'model-switch': 'model switch (cache is model-scoped)',
+  'cache-expired': 'cache expired (gap > 5-min TTL)',
+  'prefix-change': 'prefix changed (system prompt / tools / context edit)',
+};
+
+// F6 — one-line HUD for a Claude Code statusLine command (mirrors
+// watch-mode.js renderStatusLine). Takes the metrics from computeCacheEconomics.
+export function renderCacheStatusLine(metrics) {
+  if (!metrics || !metrics.turns) return 'agentic-security: no session cost yet';
+  const hit = Math.round(metrics.cacheHitRatio * 100);
+  return `agentic-security: ${money(metrics.actualUsd)} · ${hit}% cached · ${money(metrics.costPerTurnUsd)}/turn`;
+}
+
+export function formatCacheReport(result) {
+  if (!result.ok) {
+    return result.reason === 'no-transcript'
+      ? 'agentic-security: no Claude Code transcript found for this project yet.'
+      : 'agentic-security: transcript has no priceable model turns yet.';
+  }
+  const m = result.metrics;
+  const lines = [];
+  lines.push('');
+  lines.push('  Prompt-cache economics — this session');
+  lines.push(`  ${result.turns ?? m.turns} model turns\n`);
+  lines.push(`  cache hit ratio     ${(m.cacheHitRatio * 100).toFixed(1)}%  (input-side tokens served from cache)`);
+  lines.push(`  spent               ${money(m.actualUsd)}   (~${money(m.costPerTurnUsd)}/turn)`);
+  lines.push(`  ▶ saved by caching  ${money(m.savedUsd)}   vs. ${money(m.uncachedUsd)} with no cache`);
+  lines.push(`  invested in caches  ${money(m.writePremiumUsd)}   (write premium over base input)`);
+  lines.push('');
+  lines.push('  tokens: '
+    + `${m.tokens.cacheRead.toLocaleString()} cached-read · `
+    + `${m.tokens.cacheCreate.toLocaleString()} cache-write · `
+    + `${m.tokens.input.toLocaleString()} fresh-in · `
+    + `${m.tokens.output.toLocaleString()} out`);
+
+  const models = Object.keys(m.perModel);
+  if (models.length > 1) {
+    lines.push('\n  by model:');
+    for (const k of models.sort()) {
+      const pm = m.perModel[k];
+      const hr = pm.inputSide ? (pm.cacheRead / pm.inputSide * 100).toFixed(0) : '0';
+      lines.push(`    ${k.padEnd(12)} ${pm.turns} turns · ${money(pm.actualUsd)} · ${hr}% cached`);
+    }
+  }
+
+  if (result.leaks && result.leaks.length) {
+    const wasted = result.leaks.reduce((s, l) => s + l.wastedUsd, 0);
+    lines.push(`\n  ⚠ cache leaks (${result.leaks.length}, ~${money(wasted)} wasted re-ingesting context):`);
+    const byCause = {};
+    for (const l of result.leaks) {
+      (byCause[l.cause] || (byCause[l.cause] = { n: 0, usd: 0 })).n++;
+      byCause[l.cause].usd += l.wastedUsd;
+    }
+    for (const c of Object.keys(byCause).sort()) {
+      lines.push(`    · ${byCause[c].n}× ${CAUSE_LABEL[c] || c} — ~${money(byCause[c].usd)}`);
+    }
+    lines.push('    Keep one model + a stable system prompt within a working window to avoid these.');
+  } else {
+    lines.push('\n  ✓ no cache leaks detected — your context stayed warm.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Test surface (underscore export is exempt from the dead-module gate).
+export const _internal = {
+  MODEL_RATES, CACHE_READ_MULT, CACHE_WRITE_MULT, CACHE_WRITE_1H_MULT,
+  rateFor, locateTranscript, parseTranscriptUsage, computeCacheEconomics, detectInvalidators,
+};