budget: Budget as a first-class object parsed from x-token-* headers #185

Summary

Piece 2 of 6. Every response carrying x-token-* updates a Budget on the
Donkey instance. The developer never parses a header.

donkey.budget.limit          # int, tokens per window
donkey.budget.remaining      # int, from the last response
donkey.budget.reset_at       # datetime, converted from x-token-reset (ms)
donkey.budget.observed_at    # staleness of the above
donkey.budget.fraction_used  # 0.0-1.0

Honest limitation to state in the docstring

The gateway exposes budget only in-band. There is no budget-query endpoint,
so remaining is only as fresh as the last call and a new process knows
nothing until its first request. observed_at exists so nobody mistakes stale
data for live data. This is upstream gap #2.

Why it matters — Scenario A

fraction_used per agent on a dashboard. The owner sees it climbing at 14:00
and requests an increase before the 16:00 peak instead of after the outage.

Acceptance criteria

• x-token-reset in milliseconds converts correctly — fixture with a known
  value, assert reset_at to the second.
• Budget is per-Donkey, not global; two instances with different
  credentials never share state.
• observed_at is set on every parse and exposed publicly.
• Missing x-token-* headers leave the object in a defined "unobserved"
  state rather than raising.

Cross-surface impact

• core: the object and the _on_response hook wiring.
• area:simulator: the simulator must emit x-token-* on happy-path
  responses so this works against the mock.
• area:telemetry: donkey.budget.remaining becomes a span attribute (1.6).
• Upstream gaps: gap Epic: Pillar 1 — governed model access through the Omni Gateway LLM proxy #2 would make this live instead of stale.

Out of scope

Pacing (pace() / wait_for_reset()) — its own issue.