[H-7 / Phase 3] [HIGH] Real token-usage accounting

[matthewod11-stack]

Full spec: docs/hardening-roadmap-2026-04-16.md#h-7

Description

Two layers of fiction stack: ESTIMATED_COST_PER_SCORING_CALL = 0.005 (handlers.ts:315) and AI_COST_PER_CANDIDATE = 0.01 (budget-estimator.ts:14) are flat constants. Neither varies by model, input length, or cache hits. Budget gate trusts these, so Opus 4.7 runs silently blow the cap.

Current State

• Flat constants at two sites.
• AIProvider interface lacks usage in return types.
• No per-model pricing table.

Suggested Fix

• Extend AIProvider.chat() / .structuredOutput() return types with usage: { inputTokens, outputTokens, cachedTokens }.
• Populate from SDK response (response.usage).
• Add ModelPricing map in @sourcerer/ai/pricing.ts keyed by model ID → { inputPer1M, outputPer1M, cacheReadPer1M }. Seed: claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5, gpt-4o, gpt-4o-mini.
• Compute real cost per call; thread through costIncurred in PhaseResult.
• Budget estimator: accept optional model, use ModelPricing + rough heuristic (~1K in, ~500 out per call) instead of flat 0.01.

Verification

• pnpm build passes
• pnpm test passes
• pnpm typecheck clean
• Run's run-meta.json cost ≈ sum of per-call costs (±2%)
• Integration test: budget gate triggers with maxCostUsd: 0.01
• sourcerer runs show <id> displays token counts per phase

Automation Hints

scope: packages/core/src/ai.ts, packages/ai/src, packages/scoring/src, apps/cli/src/handlers.ts, apps/cli/src/budget-estimator.ts
do-not-touch: data adapters
approach: refactor-types
risk: medium
max-files-changed: 12
blocked-by: none
bail-if: scoring tests fail

Priority

High