feat(FAFF-604): telemetry adapter seam — budget/economics read an engine-declared spend source

[alechill]

Closes FAFF-604.

budget and economics have always read spend from one place: the Claude Code transcript. That was the deepest Claude-only coupling left after FAFF-593 landed the codex spawn family — a codex build lane's spend was simply invisible, so a mixed-fleet run under a dollar ceiling silently under-counted. This makes each engine declare where its spend can be read, and unions the two sources behind one layer.

What changed

backends: gains a telemetry field — transcript-jsonl | exec-json-events | none, derive-with-override with family-capability constraints, exactly the auth/egress pattern. anthropic derives transcript-jsonl, codex exec-json-events, everything else none. A backend can't claim a source its family can't serve; that fails at normalize time, where the symptom is a named error rather than a silently missing contribution.

The codex call boundary records spend. codex exec is --ephemeral — no session file, temp cwd already gone — so nothing codex-side survives to attribute later. The caller is the only place that knows both the usage and the run, so runCodexCall gains an injectable sink that appends one record per completed call to a run-owned engine-spend.jsonl. A sink fault warns and leaves the exit code alone: metering must never break a producer dispatch.

One combining layer. measureRunSpend owns the union; budget check and economics both call it. Engine records are run-scoped, so they need no run-start baseline — and because they fold in before the window baseline, the window governor needed no changes at all: a mixed-fleet window ceiling is a true combined total by construction.

The refusal. An engine with telemetry: none under a dollar ceiling refuses at the lights-out mint, where refusing is free. budget check degrades loudly instead — cost: null plus a warning naming both remedies, exit unchanged — because a non-zero exit there is read as unbreached by sentryReadBudget, so refusing that way would fail the whole budget signal open. The waiver (budget.allow_unmetered) lives on the budget block, not the backend record: accepting unmetered spend under a ceiling is a policy owned by whoever set the ceiling.

Honest labels. Additive spend_sources and unmetered_engines on both surfaces, plus a per-row source on economics --by model. All omitted on a single-source run, so unchanged runs emit byte-identical JSON.

Acceptance criteria

• A run with no engine-spend.jsonl produces byte-identical budget + economics output — asserted down to the absent key, not just the values
• budget.js:422-534 and parseCodexEvents textually unchanged — proven by function-text comparison against main, not just by test
• telemetry derives per family, explicit wins, closed enum, family-capability constraints enforced
• budget.allow_unmetered parsed; a dead waiver naming no configured backend warns in faff config check
• A successful codex call appends one class-mapped SpendRecord (selftest via injected sink — zero real I/O)
• engine call --run-dir, latest-run fallback, warn-and-skip outside a run
• Sink write failure → stderr warning, exit code untouched
• Mixed-fleet total unions both sources; window draw includes engine spend
• Estimate mode: measured engine spend still counts, and a partial cost is named as partial on both surfaces
• Malformed spend lines skipped and counted, never fatal
• Mint-time refusal names the engine and both remedies; budget check degrades at exit 0
• unmetered_engines present whenever the fleet has one, waived or not — never reported as spending 0
• spend_sources + per-row source; both omitted on transcript-only runs

Gates: lint pass, 2,505 tests pass, 0 fail.

Review

Three iterations. The first found seven real problems, including two that would have shipped as silent money bugs: the allow_unmetered waiver was inert on the ledger-envelope path (the normal path), which would have cost operators the dollar ceiling they were trying to keep; and cached codex tokens were counted — and would have been billed — twice, because the Anthropic four-class model is disjoint while codex reports cached input inside input_tokens. The second iteration caught two more introduced by that fix pass, including economics reporting a partial cost as if it were the run total.

The third iteration passed, and the adversarial second opinion (GLM-5.2) returned five findings, all refuted with cited evidence — details in the tracker comment.

CI then went red on faff regions check: budget.js is governance and may not require backends.js (factory), and a lazy require inside a function is still a require edge. That lint has no suppression mechanism by design, so the fix was to move the code — the fleet resolver now lives in backends.js where it belongs, measureRunSpend takes the resolved list as data, and the dispatch shell (exempt by design) is where the two regions meet. A fourth review pass covered the relocation and returned pass.

Two notes against my own account of that fix. The commit message for 878e323 claims it also caught lights-out.js using a symbol without importing it; that is wrong — the symbol was imported from its then-home in ./budget, and the commit merely re-pointed the import. No defect either way, but the claim overstates it. And the local gate ladder passed while CI failed, because faff gates run discovered only lint and unit from a workflow that runs some seventy steps; that gap is filed as discovered scope.

Follow-up (not blocking)

• economics --by class / --by day reconcile true while covering only the transcript half on a mixed fleet. Discoverable (the breakdown carries source, the same JSON carries spend_sources), but worth tidying.
• The source label is JSON-only — no column in the rendered --by model table.
• Unchecked assumption, carried from FAFF-593: the codex turn.completed usage field names are pinned from codex-rs source, not a live binary — none is installed here. The cached-input subset semantics are inferred from codex-rs's non_cached_input() helper. Worth one live codex exec --json call to confirm before a codex lane meters real money. The drift observable is a run whose spend_sources shows an exec-json-events entry with 0 tokens while the codex lane demonstrably ran.

ADR-0091 records the seam.

🤖 Generated with Claude Code

https://claude.ai/code/session_016jMqrXT3E21jv8vrqLYJa2