Coding Engine spend is invisible in the usage ledger — the largest real cost isn't recorded

[serge-ivo]

The gap

ai_usage is written at exactly one choke point — runUserWorkersAi in lib/user-ai.ts (plus recordVoiceUsage for the key-proxy and recordPlatformUsage for Workers-AI). The coding Engine never passes through any of them. Claude Code / Codex / Grok run on the user's own machine, spending on their own subscription or key, and the platform records nothing.

Measured on the live ledger (30d, operator account):

kind	cost	calls
chat	$18.95	814
voice	$8.51	840
overseer	$7.45	326
copilot	$4.85	244
coding	$0.70	67

That coding row is only the cloud-side Pilot deciding what to do next. The Engine's own consumption — almost certainly the single largest item for anyone using Coder in earnest — is absent. So the Usage page reads $40.92 when real spend is materially higher, and there is no signal that anything is missing.

Why this matters beyond curiosity

• Cost governance ([3P] Cost governance & abuse controls (gates the public open) #56) gates the public open. You cannot govern spend you cannot see.
• Metering → payouts ([3P] Metering → payout-ready (payouts built behind a flag, launch deferred) #57) sizes creator payouts by usage share. An agent whose work happens in the Engine looks near-free next to a chat agent, which would systematically underpay exactly the agents the platform is best at.
• [Admin][API] Cloudflare billing-actuals for authoritative platform AI spend #45 gets Cloudflare actuals for platform Workers AI — which is $0.00 here. It does not touch this.

The implementation path is already open

packages/browser-runner/src/coding/headless.ts parses Claude Code's stream-json and already handles the result event (line ~497) — it reads is_error/result/subtype and discards the usage and total_cost_usd fields on the same object. The data is flowing through today and being thrown away.

1. In the result case, capture usage (input/output/cache tokens) + total_cost_usd when present.
2. Report it with the existing session event channel (/coding/event) — no new transport, no relay change.
3. Cloud side: ledger it as kind:"engine", provider:"anthropic", with the CLI-reported cost — this is the one number that is not an estimate, since Claude Code computes it itself.
4. Raw (non-Claude) engines emit no such event → record nothing rather than guess. Codex/Grok stay invisible until each exposes an equivalent; say so in the UI rather than implying zero.

Acceptance

• A Coder session on the claude engine produces ai_usage rows with kind:"engine".
• The Usage page distinguishes engine spend from platform-mediated spend, and states which engines report (Claude) and which cannot (raw).
• Cost from the CLI is stored as reported and marked authoritative, not re-estimated through ai-pricing.ts.
• A session on a raw engine records nothing and does not fabricate a zero.

Found while answering "what is $40.92 and is it real". Related: #45 (platform actuals), #56, #57, #68.

[serge-ivo]

Shipped in 7718e4a.

Verified first

• The discard is real. headless.ts case "result" read is_error/result/subtype and threw the rest away.
• Confirmed the payload empirically, not from docs — ran claude -p --output-format stream-json (2.1.223) and read the actual result event. It carries total_cost_usd, usage (input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens) and modelUsage, keyed by model with a per-model costUSD — so the real model id was available too, which the issue did not mention.
• One claim in the issue was wrong. Step 2 proposed reporting over /coding/event. That channel is cloud→runner (coding-session.ts calls it via callRunner; the runner just acks {ok:true} and ignores it). The relay is strictly request/response with no runner→cloud push, so there was no existing outbound event channel to reuse.

What was built

Reporting rides the capture round-trip instead — still no new transport and no relay protocol change.

• Runner — coding/engine-usage.ts parses a result event into a record; HeadlessSession queues them (bounded) and takeUsage() drains.
• Drain is opt-in (drainUsage on /coding/capture). Nine cloud sites call capture; only the two that write the ledger may consume records, or a chat-context capture would silently eat them. /coding/end returns whatever is left — the last turn of a session routinely lands after the final poll, so without it the ledger would lose the closing turn of every session, which is a bias rather than noise.
• Cloud — recordEngineUsage writes kind:"engine", distinct from coding (the Pilot). Rows are keyed deterministically and inserted OR IGNORE, so two drainers racing, or a retried workflow step, cannot double-charge a turn.
• Cost stored as reported. Migration 0080 (not 0078 — 0078_user_suspension and 0079_mcp_tool_consent landed while this was in flight) adds cost_source; NULL = estimated, true of every pre-existing row, so no backfill.
• Raw engines record nothing — structurally, not as a special case: raw mode never parses JSON, so there is nothing to queue.
• Usage page — Coding (Pilot) vs Coding engine (measured), and the <Scope> disclosure added by Usage page doesn't disclose what the cost estimate excludes (Engine spend) or over-counts (cache) #270 has had its "engine spend is missing" bullet replaced by the figure, exactly as its own comment asked. The exclusion shrank rather than vanished, so Codex/Grok are now named as the remaining gap.

Acceptance

• Claude-engine session produces ai_usage rows with kind:"engine"
• Usage page distinguishes engine from platform-mediated spend and says which engines report
• Cost stored as reported and marked authoritative (cost_source=reported), never through ai-pricing.ts
• Raw engine records nothing, fabricates no zero

Tests

20 new unit tests (engine-usage.test.ts on both sides) plus two integration tests in headless.test.ts driving a fake Claude that emits the real event shape, and a raw engine asserting the no-op. The existing FAKE_CLAUDE fixture now emits usage, so the whole suite exercises the real field names — snake_case in usage, camelCase in modelUsage, which is precisely how this silently reports zeros.

pnpm typecheck green; targeted suites green; full suite 3430/3430 green on this commit. Biome findings unchanged from baseline (30/285 before and after).

Not done, deliberately

• No backfill. Past engine spend was never observed and cannot be reconstructed.
• Best-effort, so a drained record whose D1 write fails is lost. Matches every other recorder — a ledger write must never break a coding session — and the alternative (acking drains) needs a protocol this issue explicitly ruled out.
• provider is hardcoded anthropic, which is correct only because Claude Code is the only engine that reports. A second reporting engine must revisit it.

Shipping note: the runner is bundled into the published CLI, so this reaches users only once CI publishes — packages/cli bumped to 0.4.33 in the same commit.