Persist an audit trail for extra-usage transitions and provider-reported billing state

Problem

The monitor now supports extra usage, provenance labels, official rate_limits, machine-readable snapshots, and a durable local warehouse. One important boundary is still hard to reconstruct after the fact: when a paid subscriber moved from included plan usage to provider-billed extra usage, and what each source reported at that moment.

That distinction matters during provider-side billing incidents. A public July 17 Anthropic incident acknowledged incorrect usage-credit routing, while multiple customers reported paid-credit consumption despite substantial plan headroom. In one documented case, six invoices totaled $599.35, but Anthropic selected a 30-minute correction window and issued only $3.11 in account credit.

Public incident/evidence links:

• https://status.anthropic.com/incidents/g613ntyj2pwf
• https://github.com/anthropics/claude-code/issues/81703
• https://coolak.github.io/anthropic-claude-billing-incident/july-17-reporter-brief.html

This is not a claim that claude-monitor caused or can correct provider billing. It is a request to make the local audit record strong enough to reconcile what the client observed against a later provider ledger.

Proposed feature

When --warehouse is enabled, persist an immutable transition/event record whenever any of these values changes materially:

• included-plan utilization (5-hour and weekly, when officially available);
• extra-usage enabled/disabled state;
• local estimate of base-versus-extra consumption;
• provider-reported extra-usage or credit-consumption state, when an authoritative source exposes it;
• source/provenance (official, local_estimate, experimental, unknown);
• capture time, provider timestamp/reset window, account/source identifier, and raw-source hash;
• the previous and new values that triggered the event.

Suggested machine-readable shape:

{
  "event": "extra_usage_transition",
  "captured_at": "...",
  "provider_window": {"five_hour": 0.24, "weekly": 0.28},
  "extra_usage_enabled": true,
  "estimated_paid_usage": null,
  "provider_reported_paid_usage": null,
  "provenance": "official",
  "raw_source_hash": "...",
  "previous": {...},
  "current": {...}
}

estimated_paid_usage and provider_reported_paid_usage should remain separate nullable fields. A token-price estimate must never silently become an assertion that Anthropic actually billed that amount.

Useful output

A command such as:

claude-monitor --warehouse --view billing-transitions --from 2026-07-17 --to 2026-07-18 --output json

could produce a support-ready timeline without exposing prompt contents. A warning would also be valuable when provider-reported paid-credit consumption appears while official included-plan headroom remains.

Privacy / scope

• local-only and opt-in with the warehouse;
• no prompt or response text;
• stable pseudonymous account/source IDs;
• retention and export follow existing warehouse controls;
• label missing provider billing data as unavailable, not zero.

This would turn the monitor's existing provenance and warehouse features into a defensible incident-reconciliation record while keeping provider-billed facts separate from local cost estimates.