[usage] Stop a run at a cumulative token budget

[yusiwen]

Closes #179. Roadmap entry A3 (tracker: #168).

What changed

• config.BudgetConfig — budget.max_tokens_per_run, budget.max_tokens_per_session — plus
  Config.TokenBudgets(). Both default to 0 = unlimited; a negative value in a file is ignored
  rather than read as "no limit", so a typo cannot widen the fence.
• agent: BudgetTokensPerRun / BudgetTokensPerSession, a per-run runUsage (reset by each
  Run), and the check at the top of the ReAct loop — before the call that would spend. A run that
  reaches either limit returns a message naming the budget, the spend and the knob to raise
  (budget.max_tokens_per_run / …_session), in the same shape as the step-limit summary.
• callSpend / recordUsage: a reported record wins; a call whose endpoint reports nothing is
  counted as an estimate of its output, and that estimate never fires OnUsage.
• tool/task.go, tool/bgtask.go, main.go: sub-agents are built with the same limits and count
  against themselves.
• tui/view.go: tokens: spent/limit when a session budget is configured; byte-identical to before
  when none is.
• Docs: docs/roadmap.md (A3 carries its issue link), CHANGELOG.md, CODEBASE.md, and the
  config.example.json block.

Why

The status bar's counter and Agent.UsageTotal already knew what a run cost, and nothing acted on
it: the only limits were MaxSteps and a per-request output cap, neither of which accumulates.
Checking before the provider call is the whole point — an after-the-fact check lets every run
overshoot by exactly one call, which is the call the budget existed to prevent.

Rejected alternative: an error instead of a message when the budget fires. The step limit already
sets the precedent that a limit the user configured is an outcome to read rather than a failure to
handle, and the TUI would render an error where the user wants the explanation.

Two deliberate calls worth reviewing:

• Estimating for a silent provider. A budget that an endpoint can switch off by omitting usage
  is not a budget, so such a call advances the total by an estimate of its output (undercounting the
  prompt, which is why a reported record always wins). The estimate never fires OnUsage, so no
  consumer is handed an estimate dressed as a provider number. This changes [usage] Surface provider-reported token usage instead of only estimating it #174's total for
  unreported calls, and its test was updated with it rather than left green by accident.
• Tokens, not money. Cost needs a per-model price table, which no command in this repository can
  produce. A3's title mentions cost; that half is explicitly not here.

Verification

• go test ./... -count=1 → 13 packages ok, 0 failed. go test ./... -count=1 -race → same.

• make staticcheck (v0.8.1) → exit 0. gofmt -l . → no output.

• Six mutations of the new behaviour, each failing on an assertion:

  Mutation	What the test said
  budget check removed	provider called 11 times, want 2 for a 100-token budget at 60 tokens per call
  session budget ignored	first run called the provider 11 times, want 2
  estimate fallback removed	provider called 11 times, want 1
  estimate fires the usage event	OnUsage fired 1 times for a call that reported nothing
  run total not reset between runs	provider called 2 times over two runs, want 4
  status bar always shows a fraction	bar = "… tokens: 1200/0 …", want a plain 'tokens: 1200'

• The comparison class is a counted provider-call total, not a timing: ceil(N/M) calls for a
  budget of N at M tokens per call, and an exact-call-count control with no budget configured (which
  is how "off by default" is asserted rather than claimed).

• The 27 committed frame goldens pass unchanged, because the bar only gains the fraction when a
  session budget is configured.

Honest scope

• No live provider call was made; the providers in the tests are scripted.
• The estimate fallback covers output only, so a silent provider's prompt tokens are not counted
  against the budget. The boundary still advances on every call; it just undercounts those.
• A sub-agent enforces the same limits against its own spend, so a session budget can be exceeded in
  aggregate by delegation. Attributing a sub-agent's tokens to its parent is roadmap G1, and
  reporting a number that cannot be computed would be worse than naming the gap.
• Cost and pricing remain open, per the design note above.