@clear-capabilities/agentic-security-scanner 0.132.0 → 0.133.0

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-a1f581521eaab4f89f26aa9f06af557e9443dbea7a8411da5ecd904f3b94acd3  agentic-security.mjs
+a868fa3988608a5a5c0867774d870781a52d79924daf0956652c62fa1384d782  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.132.0",
+  "version": "0.133.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,8 +61,8 @@
     "test": "npm run test:smoke && npm run test:glob && 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:glob": "node --test test/glob-compat.test.js",
-    "test:sast": "node --test test/llm.test.js test/llm-cost-advisor.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/file-upload.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/accuracy-scorecard.test.js test/scorecard-gate.test.js test/release-check.test.js test/pre-push-gate.test.js test/dependency-currency.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/deterministic-fix.test.js test/falsification.test.js test/verification-separation.test.js test/attestation.test.js test/determinism-cross-machine.test.js test/fix-honesty-gate.test.js test/model-routing.test.js test/root-cause-sweep.test.js test/entrypoint-inventory.test.js test/relevance.test.js test/untrusted.test.js test/agent-hardening.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-verify-tests.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/secret-live-check.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/execution-proof.test.js test/fix-metrics.test.js test/corpus-enroll.test.js test/scan-checkpoint.test.js test/llm-redact.test.js",
+    "test:sast": "node --test test/crypto-specialist.test.js test/llm.test.js test/llm-cost-advisor.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/file-upload.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/accuracy-scorecard.test.js test/scorecard-gate.test.js test/release-check.test.js test/pre-push-gate.test.js test/dependency-currency.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/deterministic-fix.test.js test/falsification.test.js test/verification-separation.test.js test/attestation.test.js test/determinism-cross-machine.test.js test/fix-honesty-gate.test.js test/model-routing.test.js test/root-cause-sweep.test.js test/entrypoint-inventory.test.js test/relevance.test.js test/untrusted.test.js test/agent-hardening.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-verify-tests.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/secret-live-check.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/execution-proof.test.js test/fix-metrics.test.js test/corpus-enroll.test.js test/prove-findings.test.js test/corpus-match.test.js test/corpus-provenance.test.js test/learning-quorum.test.js test/llm-cache-integrity.test.js test/integrity-legacy-key.test.js test/suppression-visibility.test.js test/cost-ceiling.test.js test/local-endpoint.test.js test/model-trust.test.js test/vuln-archaeology.test.js test/scan-checkpoint.test.js test/llm-redact.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/llm-validator-preset.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/ir-stats.test.js test/parser-cpp.test.js test/parser-js-decorators.test.js test/cpp-integration.test.js test/engine-reconnect.test.js test/phase2-scoping.test.js test/engine-recall.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/report-render.test.js",
@@ -98,6 +98,7 @@
     "bench:engine-recall": "node ../bench/engine-recall/measure.mjs",
     "scorecard": "node ../scripts/scorecard.mjs",
     "corpus:enroll": "node ../scripts/enroll-proven-finding.mjs",
+    "corpus:provenance": "node ../scripts/corpus-provenance-check.mjs",
     "determinism:attest": "node ../scripts/attest-fixture.mjs",
     "scorecard:check": "node ../scripts/scorecard-check.mjs",
     "release:check": "node ../scripts/release-check.mjs",

package/src/engine.js

@@ -90,6 +90,7 @@ import { scanOpenRedirect } from './sast/open-redirect.js';
 import { scanWrongContextSanitizer, scanSanitizerContextMismatch } from './sast/wrong-context-sanitizer.js';
 import { scanFrontendHygiene } from './sast/frontend-hygiene.js';
 import { scanCsvInjection } from './sast/csv-injection.js';
+import { scanCryptoSpecialist } from './sast/crypto-specialist.js';
 import { scanStoredTaint } from './sast/stored-taint.js';
 import { scanTreeSitterSinks } from './sast/tree-sitter-sinks.js';
 import { scanJavaStructural } from './sast/java-structural.js';
@@ -121,6 +122,8 @@ import { classifySecretCandidate as _entropyClassifySecret } from './sast/_secre
 import { annotateConfidence } from './posture/confidence.js';
 import { backfillFindingDefaults } from './posture/finding-defaults.js';
 import { annotatePocs } from './posture/poc-generator.js';
+import { annotateExecutionProofs } from './posture/prove-findings.js';
+import { mineVulnHistory, annotateHistoricalRisk } from './posture/vuln-archaeology.js';
 import { annotateVerifierVerdicts } from './posture/verifier.js';
 import { annotateRegressionTests } from './posture/regression-test-gen.js';
 import { annotateCalibratedConfidence } from './posture/calibration.js';
@@ -7566,6 +7569,11 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
       aF.push(...scanSanitizerContextMismatch(p,c));
       aF.push(...scanFrontendHygiene(p,c));
       aF.push(...scanCsvInjection(p,c));
+      // R16 — specialist crypto-hygiene classes (constant-time comparison,
+      // secret zeroization). Narrow by design: keyed on the secret-ness of the
+      // identifier, and silent whenever the correct constant-time or
+      // guaranteed-wipe API is already present.
+      aF.push(...scanCryptoSpecialist(p,c));
       aF.push(...scanStoredTaint(p,c));
       aF.push(...scanJavaStructural(p,c));
       aF.push(...scanCsharpStructural(p,c));
@@ -7986,6 +7994,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // Every catch in this block writes into _annotatorErrors so the operator
   // can tell "didn't run" from "ran cleanly." The array is surfaced as
   // scan.annotatorErrors in the report; an empty array means clean.
+  let _executionProofSummary = null, _vulnHistory = null;
   const _annotatorErrors = [];
   const _runAnnotator = (phase, fn) => {
     try { return fn(); }
@@ -8195,6 +8204,28 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   _runAnnotator("annotatePocs", () => { annotatePocs(finalFindings, { routes: aR, fileContents: fc }); });
   // FR-VER-3: regression-test generator (builds on the PoC artifact).
   _runAnnotator("annotateRegressionTests", () => { annotateRegressionTests(finalFindings); });
+  // R2 — execution proof. Synthesizes a SANDBOX-RUNNABLE PoC (the HTTP PoCs
+  // above need a live server, so they can never be executed by the prover)
+  // and lets R1's sandbox decide the tier. Opt-in via AGENTIC_SECURITY_PROVE=1
+  // because it executes code derived from the scanned project; with the flag
+  // unset, or with no confinement backend, nothing runs and no tier moves.
+  // Awaited rather than fire-and-forget: a proof that lands after the report
+  // is emitted is not evidence anyone sees.
+  // R14 — vulnerability archaeology. Mines git history for where this team has
+  // introduced security bugs before and attaches an ADVISORY per-file prior.
+  // Never a finding and never a severity change: those bugs are fixed, and a
+  // historical fix is not evidence of a present defect. Opt-in because it
+  // shells out to git over up to 500 commits.
+  _runAnnotator('annotateHistoricalRisk', () => {
+    if (process.env.AGENTIC_SECURITY_ARCHAEOLOGY !== '1' || !scanRoot) return;
+    _vulnHistory = mineVulnHistory(scanRoot);
+    annotateHistoricalRisk(finalFindings, _vulnHistory);
+  });
+  try {
+    _executionProofSummary = await annotateExecutionProofs(finalFindings, { fileContents: fc });
+  } catch (e) {
+    _annotatorErrors.push({ phase: 'annotateExecutionProofs', err: String((e && e.message) || e) });
+  }
   // Phase-1 next-gen P1.2 (FR-VER-3, FR-VER-6, FR-VER-7): per-finding
   // verifier verdict — verified-exploit (live PoC ran), verified-by-llm,
   // verified-sanitizer-absence, unverified-by-design, or cannot-verify.
@@ -8731,7 +8762,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // Addition #3 — root-cause sweep: from confirmed findings, find sibling instances
   // detectors missed, with total-count accounting. Confirmed-only (cheap by default).
   let _rootCauseSweep = null; try { _rootCauseSweep = sweepRootCauses(finalFindings, fc); } catch { _rootCauseSweep = null; }
-  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
+  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,executionProof:_executionProofSummary,vulnHistory:_vulnHistory,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
 // Orphans (no finding linkage) are bucketed by file-local heuristic so the UI shows binary states only.

package/src/llm-validator/cost-ceiling.js

@@ -0,0 +1,199 @@
+// R12 — a hard cost ceiling for the LLM validator tier.
+//
+// A cost *advisor* already exists (`hooks/model-cost-advisor.js`): it biases a
+// quality/cost dial and warns as spend approaches a soft budget. What did not
+// exist is a CAP — something that refuses to spend rather than advising about
+// it. A soft budget you can sail past is not a ceiling, and "it warned you" is
+// no comfort on an invoice.
+//
+// THE DISTINCTION THAT MATTERS: this never degrades quality to fit a budget.
+// It stops. Silently switching to a cheaper model or a shorter prompt to stay
+// under a cap would change what the scan MEANS while reporting the same shape,
+// and a finding validated by a model the operator did not choose is a
+// different claim than the one they asked for. When the cap binds, remaining
+// findings are left explicitly `unvalidated` with a reason naming the cap.
+//
+// FAIL CLOSED ON UNKNOWN PRICING. A ceiling that cannot price a call cannot
+// enforce anything. Rather than spending unmetered and reporting a $0.00
+// ledger, an unpriceable model refuses every call. Operators override with
+// `AGENTIC_SECURITY_LLM_PRICE_USD_PER_MTOK="<in>,<out>"`.
+//
+// PRICES ARE OPERATOR-SUPPLIED FACTS, NOT ENGINE FACTS. The built-in table is a
+// convenience for the shipped preset, and list prices change. It is deliberately
+// small, it is stamped with the date it was last checked, and anything not in it
+// must be priced explicitly. Do not grow this table casually — a stale price
+// here silently mis-enforces every ceiling built on it.
+
+// USD per 1,000,000 tokens, {input, output}. Last checked: 2026-08-07.
+const PRICES = Object.freeze({
+  'claude-haiku-4-5': { input: 1.00, output: 5.00 },
+});
+
+export class CapExceeded extends Error {
+  constructor(msg) { super(msg); this.name = 'CapExceeded'; }
+}
+
+/** Parse the configured cap. Returns null when no cap is set (feature off). */
+export function parseCapUsd(env = process.env) {
+  const raw = env.AGENTIC_SECURITY_LLM_MAX_USD;
+  if (raw == null || raw === '') return null;
+  const n = Number(raw);
+  // A malformed cap is refused rather than ignored: treating "abc" or a
+  // negative as "no cap" turns a typo into unlimited spend.
+  if (!Number.isFinite(n) || n < 0) {
+    throw new CapExceeded(`AGENTIC_SECURITY_LLM_MAX_USD is not a non-negative number: ${JSON.stringify(raw)}`);
+  }
+  return n;
+}
+
+/** Resolve {input, output} USD per 1M tokens for a model, or null if unknown. */
+export function priceFor(model, env = process.env) {
+  const override = env.AGENTIC_SECURITY_LLM_PRICE_USD_PER_MTOK;
+  if (override) {
+    const parts = String(override).split(',').map(s => Number(s.trim()));
+    if (parts.length === 2 && parts.every(n => Number.isFinite(n) && n >= 0)) {
+      return { input: parts[0], output: parts[1], source: 'override' };
+    }
+    return null; // malformed override -> unpriceable, so fail closed
+  }
+  const p = PRICES[model];
+  return p ? { ...p, source: 'built-in' } : null;
+}
+
+export function costOf({ inputTokens = 0, outputTokens = 0 }, price) {
+  if (!price) return null;
+  return (inputTokens / 1e6) * price.input + (outputTokens / 1e6) * price.output;
+}
+
+/**
+ * A ledger enforcing a hard ceiling.
+ *
+ * `capUsd === null` means no ceiling was configured: `canAfford` always allows
+ * and nothing is enforced. That is the default, and it is the ONLY state in
+ * which unpriceable models are permitted — without a cap there is nothing to
+ * enforce, so refusing would break existing behaviour for no benefit.
+ */
+export function createCostLedger({ capUsd = null, model = 'unknown', env = process.env } = {}) {
+  const price = priceFor(model, env);
+  let spentUsd = 0, calls = 0, refusals = 0;
+  // How much of `spentUsd` came from ESTIMATES rather than reported usage.
+  // Tracked separately because the two are not the same kind of number: the
+  // estimate charges the full permitted output length, which most replies
+  // never reach, so a ledger fed only estimates reports an upper bound. That
+  // is fine for ENFORCEMENT (it can only stop early, never late) and wrong for
+  // REPORTING. Callers get told which they are looking at.
+  let estimatedUsd = 0, estimatedCalls = 0;
+
+  const enforcing = capUsd != null;
+
+  return {
+    enforcing,
+    capUsd,
+    model,
+    price,
+    spentUsd: () => spentUsd,
+    calls: () => calls,
+    refusals: () => refusals,
+    remainingUsd: () => (enforcing ? Math.max(0, capUsd - spentUsd) : Infinity),
+
+    /**
+     * May a call costing at most `estimate` tokens proceed?
+     * @returns {{ok:boolean, reason?:string}}
+     */
+    canAfford({ inputTokens = 0, outputTokens = 0 } = {}) {
+      if (!enforcing) return { ok: true };
+      if (!price) {
+        refusals++;
+        return {
+          ok: false,
+          reason: `no price is known for model '${model}', so a spend ceiling cannot be enforced. `
+            + 'Set AGENTIC_SECURITY_LLM_PRICE_USD_PER_MTOK="<input>,<output>" (USD per 1M tokens) '
+            + 'or remove AGENTIC_SECURITY_LLM_MAX_USD. Refusing rather than spending unmetered.',
+        };
+      }
+      // Charge the ESTIMATE before the call, not the actual after it. Checking
+      // afterwards would let a single call blow through the cap and report the
+      // overrun as a fait accompli.
+      const projected = spentUsd + (costOf({ inputTokens, outputTokens }, price) || 0);
+      if (projected > capUsd) {
+        refusals++;
+        return {
+          ok: false,
+          reason: `cost ceiling reached: this call would bring spend to $${projected.toFixed(4)}, `
+            + `over the $${capUsd.toFixed(4)} cap (AGENTIC_SECURITY_LLM_MAX_USD). `
+            + 'Remaining findings are left unvalidated rather than validated by a cheaper substitute.',
+        };
+      }
+      return { ok: true };
+    },
+
+    /**
+     * Record usage after a call.
+     * @param {object} usage {inputTokens, outputTokens}
+     * @param {object} [opts]
+     * @param {boolean} [opts.measured] true when the figures came from the
+     *   provider's own usage report; false when they are our pre-call
+     *   estimate. Defaults to false — the conservative reading, so a caller
+     *   that forgets to say cannot accidentally upgrade an estimate into a
+     *   measurement.
+     */
+    record({ inputTokens = 0, outputTokens = 0 } = {}, { measured = false } = {}) {
+      calls++;
+      const c = costOf({ inputTokens, outputTokens }, price);
+      // Unpriceable usage is not free. With no cap it is simply not tracked;
+      // with a cap, `canAfford` already refused, so this branch cannot spend.
+      if (c != null) spentUsd += c;
+      if (!measured) {
+        estimatedCalls++;
+        if (c != null) estimatedUsd += c;
+      }
+      return spentUsd;
+    },
+
+    /** Reportable state. Always carries the cap so a figure cannot be read alone. */
+    state() {
+      return {
+        enforcing,
+        capUsd,
+        model,
+        priceSource: price?.source || null,
+        priceable: !!price,
+        spentUsd: Number(spentUsd.toFixed(6)),
+        remainingUsd: enforcing ? Number(Math.max(0, capUsd - spentUsd).toFixed(6)) : null,
+        calls,
+        refusals,
+        // Disclosure, not decoration. `spentUsd` is an UPPER BOUND to the
+        // extent these are non-zero, and a reader has no way to know that
+        // without being told.
+        estimatedCalls,
+        estimatedUsd: Number(estimatedUsd.toFixed(6)),
+        fullyMeasured: estimatedCalls === 0,
+      };
+    },
+  };
+}
+
+/** One-line summary; null when no ceiling is configured. */
+export function renderCostCeiling(s) {
+  if (!s || !s.enforcing) return null;
+  if (!s.priceable) {
+    return `LLM cost ceiling: ENFORCED but model '${s.model}' is unpriceable — ${s.refusals} call(s) refused, nothing spent.`;
+  }
+  // Say "at most" whenever any part of the figure is an estimate. The word is
+  // the whole point: without it an upper bound reads as a measurement.
+  const qualifier = s.fullyMeasured ? '' : 'at most ';
+  const base = `LLM spend ${qualifier}$${s.spentUsd.toFixed(4)} of $${s.capUsd.toFixed(4)} cap across ${s.calls} call(s)`;
+  const parts = [base];
+  if (!s.fullyMeasured) {
+    parts.push(
+      `${s.estimatedCalls} of those call(s) reported no token usage, so their cost is ESTIMATED at the `
+      + 'full permitted output length — the true spend is lower',
+    );
+  }
+  if (s.refusals) {
+    parts.push(`${s.refusals} call(s) REFUSED at the ceiling — those findings are unvalidated, not validated`);
+  }
+  return parts.join('; ') + '.';
+}
+
+export const _internals = { PRICES };