Cost basis on the remaining Usage cards, the Overview hero chip and Sessions transcript cost chips

[vivekchand]

Closes the remaining scope of #5937 that #5975 (released in 0.12.877) left open: the audit on 2026-09-14 found several Usage cards, the Overview hero cost chip and the Sessions transcript per-turn and per-tool chips still printing dollar amounts with no financial basis.

Factory requirement: REQ-OBS-CEA-025, extended with AC-OBS-CEA-025.8, .9 and .10 (non-goals and in-flight banner updated): https://factory.8090.ai/project/b415065f-ab2f-4f53-8864-0c009fd098cb/requirements/950d4687-45cc-45a8-9d58-0c0d82fd5d9b

What is now labelled

Every figure is usage value at published rates (published_rate), or unknown where nothing could be read. None claims contract or actual spend. Counterfactuals (projected savings, the month-end forecast, the same tokens on another model) carry the arithmetic basis estimated beside it.

Overview

• Hero cost chip: it now prints the Spending tile's own number and provenance entry through the shared component, with the badge beside it. It no longer reads the tile's text back off the page.
• Runtime-scoped Spending tile: it called an fmtCost that does not exist in that scope. The ReferenceError was swallowed, so the tile kept node-wide figures while the hero showed the runtime's. This is the "hero figure differs from the tile" noted on Cost figures: label vendor-reported vs contract vs estimated everywhere; split actual spend from API-equivalent #5937. The tile, its badge and the hero now share one entry, which also carries the financial basis.

Usage

• Where the money goes: a caption carries the totals and the category-split badges (SVG text cannot hold a badge). Every label goes through cmProv.text, and the table cells through the shared figure.
• Cards and tables through the shared figure: Cost Forecast, Cache Re-read Tax, cache hit rate, cache performance, savings ideas, routing advisor, compression potential, Cost By Plugin / Skill legend, Cost Comparison, Spend Optimization, Skill Cost Leaderboard and Cost by Team.
• Cost Comparison: "Your actual spend (30 days)" now reads "Your usage value at published rates (30 days)" (AC-OBS-CEA-025.9).
• Skill Cost Leaderboard: the local API sends total_cost_usd / avg_cost_usd, but the renderer read total_cost / avg_cost (the hosted synthesiser's shape), so every local row printed $0.00. It now reads both shapes.

Sessions

• Transcript payloads (/api/transcript/<id>, /api/transcript-page/<id>) carry a messages[].cost_usd entry.
• The per-turn and per-tool chips render through the shared figure with the basis in their hover text.
• The transcript header shows the badge once rather than once per chip, which keeps the keyboard stops down.

Server side and cloud parity (FLYWHEEL §0a)

• clawmetry/cost_basis_surfaces.py (new) holds the entries for every surface above, in one place.
• clawmetry/efficiency.py and clawmetry/spend_flow.py stamp them inside the engines. /api/efficiency, /api/spend-flow, every byRuntime scope and the hosted snapshot's efficiency and spendFlow slices therefore carry identical entries. The cloud interceptor's per-runtime copy of spendFlow keeps them too.
• routes/usage.py stamps the forecast, cost comparison, cache trends, spend optimization, cache risk, compression, by-plugin, skill attribution and by-team payloads, on both the DuckDB and the legacy paths. The hosted forecast, costComparison, cacheTrends and spendOptimization snapshot slices reuse those builders.
• routes/sessions.py stamps the transcript dict. The hosted snapshot's transcripts slice reuses it, and cm-cloud-transcript returns that object whole.
• provenance.js adds cmCostFigure: the shared figure for a cost whose basis may not have arrived. It badges when an entry exists and never invents one.

Guards

• tests/test_provenance_render_coverage.py
  • Whole-file unbadged ceiling: 62 -> 43.
  • New per-tab ratchet, discovered from the tab templates rather than a hand-kept list: a function belongs to a tab when it touches an id in templates/tabs/<tab>.html, plus its helpers three calls deep, and local money formatters are discovered by shape. Ceilings: overview 24, usage 0, transcripts 5.
  • The named surfaces must route every figure through the shared component.
  • Discovery must reach them, so the ratchet cannot pass vacuously.
• tests/test_cost_basis_remaining_surfaces.py (15 tests, added to CI's provenance step)
  • Payloads: efficiency and spend-flow scopes, the Usage card routes, and the hosted snapshot usage and transcripts slices.
  • Shipped renderers under node: hero chip, spend flow, comparison, plugin legend, skills, team and cache risk, transcript chips.
  • A class guard: no function may call a formatter that only another function defines.
• Proved against origin/main: with the fix's code absent, 20 of 21 tests in the two files fail. The one pass is the pre-existing ceiling-padding test.
• AC-OBS-CEA-025.8 to .10 are mirrored into docs/acceptance_criteria.json with no duplicate ids. docs/ac_coverage_baseline.json and docs/MODULE_MAP.md are regenerated.

Verified

• pytest passes for the four provenance and cost-basis files (79 tests), plus 195 tests across the efficiency, spend flow, cache trends, compression, transcript, usage and cost optimizer suites.
• Checks: node --check, module map --check, AC traceability, and ruff clean on the new files. Ruff counts on the changed route files are unchanged from main.
• Headless browser against a scratch install:
  • Setup: scratch HOME, random port, seeded DuckDB, local_only. The dashboard's spawned daemon was pointed at the worktree code.
  • Usage: forecast, cache performance, plugin legend, cost comparison, efficiency and routing advisor showed "published rates" badges.
  • Transcript: the header badge rendered, and turn chips carried the basis in their hover text.
  • Overview, node-wide and ?runtime=claude_code: the Spending tile and hero chip printed the same figure with the same entry, with no page errors. The scoped tile now renders; before, it failed silently.
  • The scratch page's own initial load timed out (the cold-load problem fix(dashboard): first load no longer times out its own startup requests (#5935) #5957 fixes), so the Overview renderers were driven with the live payloads.
• tests/test_usage_forecast_local_store_v3.py: 3 tests fail identically on a clean origin/main checkout (a 6/7 daily rate near midnight). This predates this change.

Overlap with other PRs (all merged, resolved on this branch)

Rebased linearly onto main, no merge commits. Resolved semantically:

• fix(dashboard): first load no longer times out its own startup requests (#5935) #5957 (cold load): kept its shared _cmFetchOverviewShared path and "still loading" states; the hero chip label and the scoped Spending tile fix sit on top.
• LiteLLM gateway: team-attributed, gateway-reported spend without double counting #5965 (LiteLLM gateway): the Cost by Team card keeps its gateway section and escaping; team cost carries the basis, and /api/usage/by-team returns both gateway and the label.
• Project attribution and per-project budgets: burn against budget #5968 (project budgets): its project and budget routes and Cost basis labels: published-rate usage value, subscription value and metered usage kept apart #5975 labels are unchanged; it adds no money render in app.js, so the ratchet counts did not move (whole file 43, Overview 24, Usage 0, Sessions 5).
• Two CI fixes this PR needed: the empty skill-attribution total stays a number (API Tests), and the hero keeps the shape tests/test_live_session_truth.py checks (MOAT Verifier).

Not in this change

• Other Overview and Sessions panels. Run and cohort comparison, anomaly panel, waste summary, loop sources, similar runs and the orchestration panel stay unlabelled; their payloads carry no basis yet. The per-tab ceilings hold them and can only fall.
• Hosted synthesiser. The hosted dashboard synthesises Cost By Plugin / Skill and the Skill Cost Leaderboard in the browser (cm-tokens-synth in clawmetry-cloud), so those two cards show figures with no badge on hosted until the cloud side adds entries.
• Cloud pin. Hosted billingCoverage, brain and cost-breakdown pass-through remains as listed on Cost figures: label vendor-reported vs contract vs estimated everywhere; split actual spend from API-equivalent #5937, and the new snapshot entries reach hosted with the next cloud pin.
• Other bases. Contract and actual spend, and the cache and window reconciliation audit, are out of scope.
• CHANGELOG. No CHANGELOG entry here; it is carried by the release PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jm9d7s4fN55hN3YzQo75o9

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[github-actions]

Visual diff

Bot run failed before producing screenshots. Check the workflow logs.

This check is non-blocking.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.