[bug] The platform calls engine cost "measured" — Anthropic's docs say it is a list-price estimate

[serge-ivo]

The claim

The platform tells the user, in the Usage page's own words
(store/console/src/pages/Usage.tsx:276):

The Claude Code engine's own spend, shown as "Coding engine (measured)". It runs on your
machine, so the CLI reports what each turn cost and that figure is used as-is — the one line
here that is a measurement rather than an estimate.

and again in the page intro (:159):

Most rows are estimated from list prices on your own key (BYOK) — not a bill. Coding-engine
rows are the exception: the CLI reports what it actually spent.

Anthropic's documentation says the opposite

From Manage costs effectively:

Claude Code computes the dollar figure locally from token counts priced at standard list
rates, so it doesn't reflect promotional pricing or contracted discounts and may differ from
your actual bill. For authoritative billing, see the Usage page in the Claude Console.

Claude Max and Pro subscribers have usage included in their subscription, so the session cost
figure isn't relevant for billing purposes.

total_cost_usd is tokens × list price — precisely the same construction as our own
ai-pricing.ts estimate. The only difference is whose process did the multiplication.

So the engine row is not "the one measurement on the page". It is an estimate like every other row,
and it is the row most likely to correspond to no charge at all, because subscription-
authenticated engine work is the normal configuration.

The label reads Coding engine (measured). It is the least authoritative number on the page.

Three places assert this, and they reinforce each other

1. store/console/src/pages/Usage.tsx:159 and :276 — user-facing copy, quoted above.

2. workers/api/src/lib/usage.ts:135-141 — the docstring on recordEngineUsage:

   this is the one figure in the ledger that is a measurement — re-deriving it from
   ai-pricing.ts list prices would replace a real number with a worse one (and would get it
   wrong anyway, since the CLI knows about subscription pricing, service tiers and 1h-cache
   rates that the price table does not model)

   "The CLI knows about subscription pricing" is the load-bearing false statement. It does not —
   the docs say list rates, and that subscribers' figure is not billing-relevant. This sentence is
   why the number was given authority, and it will regenerate the bug if left standing.

3. workers/api/migrations/0080_ai_usage_cost_source.sql — the schema comment:

   that figure is the real thing rather than our arithmetic

   NULL vs 'reported' is a fine distinction to record. The comment then tells every future reader
   that one of them is real money, which is what turned a provenance flag into a licence to
   enforce.

The irony worth naming: #270 was closed by making this claim more prominent. #270's complaint
was that engine spend was invisible; the fix surfaced it and promoted it to "measured". A page
built to be more honest became less so.

Fix

Say the true thing, in all three places:

• Both figures are estimates at list prices. Ours and the CLI's. Neither is a bill.
• What differs is who pays — which is the ticket above (payer attribution), and the number a
  user actually wants.
• Point at the authoritative source per payer, as the docs do: the
  Claude Console usage page for API spend; claude.ai for
  subscription plan usage. Do not present our figure as a substitute for either.
• Retire the (measured) label.
• Keep the genuinely useful caveat that is already there and correct: Codex and Grok report no
  usage, so their spend appears nowhere.

Copy that would be true today, before payer attribution lands:

Everything here is estimated from published list prices — ours for platform calls, Claude
Code's own arithmetic for coding-engine rows. Neither is a bill. If a coding session signed in
with your Claude subscription, that row cost you nothing; it is shown because the tokens are
real. For what you were actually charged, see your provider's dashboard.

Verification

• No surface — page copy, code comment, migration comment, or column label — describes any cost
  figure as measured, actual, or real spend.
• The claim that Claude Code models subscription pricing appears nowhere.
• A grep for measured in the usage surfaces returns nothing that survives review.

Related

• The payer-attribution design ticket (root cause; this is the honesty half).
• [bug] The $50 circuit breaker is denominated in dollars for work nobody is billed for — subscription engine usage blocks delegations #343 — the same false premise, enforced instead of merely displayed.
• Usage page doesn't disclose what the cost estimate excludes (Engine spend) or over-counts (cache) #270 — closed; its fix introduced the copy corrected here.

[serge-ivo]

Shipped in 6141dad.

The claim was wrong and I am the reason it was in the product. When #267 shipped I relayed the CLI's figure as measured-not-estimated, and the Usage page was written to match: "the one line here that is a measurement rather than an estimate".

Anthropic's docs are explicit — Claude Code "computes the dollar figure locally from token counts priced at standard list rates… and may differ from your actual bill", and Max/Pro subscribers "have usage included in their subscription, so the session cost figure isn't relevant for billing purposes". That is tokens × list price: the same construction as lib/ai-pricing.ts, run by a different process.

Corrected on every surface — page intro, row label, lib/usage.ts docstring, routes/usage.ts, the MCP account tool, docs/coding-engines.md, and migration 0080's comment in place (comment only; its DDL is untouched), because that comment is where the wrong idea was written down.

usage-claims.test.ts pins all of them against the retired wording. It blanks comments before matching: each file explains the correction by quoting the old claim, so matching raw source would make explaining the rule a violation of it — the fourth scanner in this repo to hit that, after source-guard, gitleaks and control-labels. Mutation-checked: a real claim in code still fails it.