docs(pricing): document testing cost and scale display precision

Cost precision now scales in three bands rather than two. Between a cent
and a dime the third decimal is what distinguishes one evaluator from
another — $0.037 vs $0.049 is a third more expensive, but both round to
the same two-decimal figure — so that band keeps it. From a dime up the
precision is noise, so a run total reads as money ($0.18, not $0.177).
Sub-cent amounts keep two significant figures as before, since a fixed
decimal count renders them "$0.0000" and they read as free.

docs/cli.md said "No cost estimation is performed", which this feature
made false. That section is now "Token usage and testing cost" and
covers the per-model split, where prices come from, and the accuracy
caveats — chiefly that multi-turn runs read high, because providers
discount repeated context and opfor prices every input token at full
rate. Users budgeting off this number should know it is conservative.

Also documents that "testing cost" is opfor's own spend and excludes the
target's inference cost, and that an unpriced model is never counted as
free. Same summary added to the README and referenced from the browser
extension guide.

Note: the SDK's report type exposes neither tokenUsage nor cost. That
gap predates this work and is left alone here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: arunSunnyKVS

README.md

@@ -111,6 +111,26 @@ When you run a scan, opfor:
 
 Each run lands in its own subfolder under `.opfor/reports/run-report-<compactTs>-<slug>-<shortId>/` containing `<slug>-report.html` and `<slug>-report.json`. Autonomous `opfor hunt` runs use the same layout under `hunt-report-<compactTs>-<slug>-<shortId>/`.
 
+### Testing cost
+
+Every run reports what it cost to run, broken down by model:
+
+```
+Token usage: 51,323 input / 6,057 output (57,380 total)
+Testing cost: ≈$0.18
+   deepseek/deepseek-v4-pro [attacker]: ≈$0.037
+   anthropic/claude-opus-5 [judge]: ≈$0.14
+```
+
+This is **opfor's own spend** — the attacker and judge LLMs. It excludes your target's inference cost, which opfor cannot see from the outside. The per-model split is the useful part: the judge is often the bigger share, and pointing it at a cheaper model is usually the easiest saving.
+
+Prices come from a snapshot of LiteLLM's public price map that ships with the package, so runs work offline and a report re-rendered later produces the same figure. Two caveats worth knowing:
+
+- **Multi-turn runs read high.** Providers discount repeated context, and a multi-turn attack re-sends the conversation each turn — opfor prices every input token at full rate, so the real bill is usually lower.
+- **Unknown models are never counted as free.** A model missing from the price table is reported as unpriced and the total is marked a lower bound, rather than silently reading as $0.
+
+→ [Token usage and testing cost](docs/cli.md#token-usage-and-testing-cost)
+
 ## Evaluator coverage
 
 Opfor ships with curated suites that map to industry standards. Pick a suite or run individual evaluators.

core/src/pricing/estimateCost.ts

@@ -68,20 +68,24 @@ export function estimateRunCost(breakdown?: ModelTokenUsage[]): RunCost | undefi
 }
 
 /**
- * Format a USD amount for display.
+ * Format a USD amount for display, with precision that scales to the amount.
  *
- * Fractions of a cent are the norm here — a smoke suite on a cheap model lands
- * around $0.00003 — and a fixed number of decimals renders those as "$0.0000",
- * which reads as free. So small amounts are shown to two significant figures
- * instead, and anything below a millionth of a dollar is labelled as such rather
- * than rounded away.
+ * Three bands, each solving a different problem:
+ *   - Below a cent, a fixed decimal count renders "$0.0000" and reads as free,
+ *     so these show two significant figures instead ("$0.0034").
+ *   - Between a cent and a dime, the third decimal is what distinguishes one
+ *     evaluator from another — "$0.037" vs "$0.049" is a third more expensive,
+ *     but both round to the same two-decimal figure.
+ *   - From a dime up, that precision is noise; show it as money ("$0.18").
+ *
+ * Anything below a millionth of a dollar is labelled rather than rounded away.
  */
 export function formatUsd(usd: number): string {
   if (usd === 0) return "$0.00";
   if (usd < 0.000001) return "<$0.000001";
   // Number() strips the trailing zeros toPrecision leaves behind (0.0034 stays
   // "0.0034" rather than becoming "0.0034000").
   if (usd < 0.01) return `$${Number(usd.toPrecision(2))}`;
-  if (usd < 1) return `$${usd.toFixed(3)}`;
+  if (usd < 0.1) return `$${usd.toFixed(3)}`;
   return `$${usd.toFixed(2)}`;
 }

core/tests/pricing.test.ts

@@ -216,10 +216,24 @@ test("sub-cent runs keep enough precision not to read as free", () => {
   assert.equal(formatUsd(0.000001), "$0.000001");
   assert.equal(formatUsd(0.0034), "$0.0034");
   assert.equal(formatUsd(0.0099), "$0.0099");
-  assert.equal(formatUsd(0.25), "$0.250");
   assert.equal(formatUsd(12.3456), "$12.35");
 });
 
+test("cent-to-dime amounts keep the digit that separates one evaluator from another", () => {
+  // Real per-evaluator figures from a run. At two decimals these collapse to
+  // $0.04 / $0.05 / $0.06 and you can no longer see which evaluator is dearest.
+  assert.equal(formatUsd(0.037), "$0.037");
+  assert.equal(formatUsd(0.049), "$0.049");
+  assert.equal(formatUsd(0.055), "$0.055");
+});
+
+test("a dime and up reads as plain money, not false precision", () => {
+  assert.equal(formatUsd(0.1), "$0.10");
+  assert.equal(formatUsd(0.177), "$0.18");
+  assert.equal(formatUsd(0.25), "$0.25");
+  assert.equal(formatUsd(0.999), "$1.00");
+});
+
 test("amounts too small to show are labelled, never rounded to zero", () => {
   assert.equal(formatUsd(0.0000000001), "<$0.000001");
 });

docs/browser-extension.md

@@ -88,7 +88,7 @@ The extension uses a **single LLM configuration** for all operations (attack gen
 
 The extension runs up to **20 turns per evaluator** (default 10). It stops a given evaluator early when the judge returns a definitive verdict.
 
-**Token usage** is tracked per evaluator and shown on the Done screen and in the downloadable HTML report.
+**Token usage and testing cost** are tracked per evaluator and shown on the Done screen and in the downloadable HTML report. Cost covers the attacker and judge LLMs you configured in Options — the chat UI you are testing is driven through the browser, so there is nothing to bill for the target itself. See [Token usage and testing cost](cli.md#token-usage-and-testing-cost) for how the figure is derived and its caveats.
 
 ---
 

docs/cli.md

@@ -215,21 +215,38 @@ Partial reports include all completed evaluator results and are marked with `sto
 
 ---
 
-## Token usage tracking
+## Token usage and testing cost
 
-Every LLM call (attacker generation, adaptive follow-ups, judge) is metered. After the run completes, the CLI prints a summary line:
+Every LLM call (attacker generation, adaptive follow-ups, judge) is metered, and each is attributed to the model that made it. After the run completes, the CLI prints:
 
 ```
 Results: 5 passed, 2 failed, 0 errors
 Safety score: 71%
 Token usage: 51,323 input / 6,057 output (57,380 total)
+Testing cost: ≈$0.18
+   deepseek/deepseek-v4-pro [attacker]: ≈$0.037
+   anthropic/claude-opus-5 [judge]: ≈$0.14
 ```
 
-Token usage is also included in the JSON report (`summary.tokenUsage` and per-evaluator `tokenUsage` fields) and in the HTML report's executive summary card. When using `--events`, the `run_finish` event includes token counts in its `summary` payload.
+The per-model split is the actionable part — the judge is frequently the larger share, and switching it to a cheaper model is usually the easiest saving.
 
-The browser extension shows a `Tokens` stat on its Done screen.
+Both are included in the JSON report (`summary.tokenUsage`, `summary.tokenUsageByModel`, `summary.cost`, plus the same fields per evaluator) and in the HTML report's executive summary. When using `--events`, the `run_finish` event includes them in its `summary` payload.
 
-> Token counts reflect raw model usage (input + output tokens). No cost estimation is performed — provider pricing varies and changes frequently.
+The browser extension shows the same figures on its Done screen.
+
+### What the cost figure covers
+
+**"Testing cost" is opfor's own spend — the attacker and judge LLM calls.** It excludes your target's inference cost, which opfor cannot observe from the outside.
+
+Prices come from a snapshot of LiteLLM's public price map, vendored into the package. Nothing is downloaded at runtime, so runs work offline and a report re-rendered months later produces the same figure. The snapshot version is recorded in the JSON as `summary.cost.priceTableVersion`.
+
+Maintainers refresh it with `npm run build:pricing` (`-- --check` reports whether it has drifted from upstream).
+
+### Accuracy caveats
+
+- **Multi-turn runs are over-estimated.** Providers discount repeated context — and multi-turn attacks re-send the whole conversation each turn — but opfor prices every input token at the full rate. The more turns, the more conservative the figure.
+- **List prices only.** Negotiated rates, credits, and proxy markup are not reflected.
+- **Unknown models are never counted as free.** If a model isn't in the price table, the report says so and marks the total a lower bound (`≥` instead of `≈`, or `unpriced` when nothing could be priced). Treat `totalUsd` as a floor whenever `summary.cost.complete` is `false`.
 
 ---