Dollar budgets: count unpriced calls and sub-agents, fail closed (#222)

[antiv]

Closes #222.

A dollar budget could quietly never trigger, for three reasons:

• calls on a model with no price added nothing to the spend;
• a database error while summing counted as $0;
• an agent's budget left out what its sub-agents spent.

Changes

• TokenUsageService.get_spend_since replaces get_cost_since.
  • It returns (dollars, unpriced calls), or None on a database error.
  • For an agent scope it can include the agent's sub-agents, found by following agents_config.parent_agents. get_agent_tokens_since can do the same.
• rate_limit_config gets two new columns, block_unpriced and include_sub_agents (migration V043 for SQLite, PostgreSQL and MySQL). Both are off by default.
  • block_unpriced: unpriced calls in the period count as over the dollar budget.
  • include_sub_agents: an agent's daily token limit and its dollar budgets also cover its sub-agents. The API forces it to false for any scope other than agent, and refuses non-boolean values with a 400.
• A block dollar budget now refuses the request when the spend can't be read. Before, it allowed it.
• Rate Limits page:
  • The form has both switches.
  • Usage vs Limits warns when the scope had unpriced calls.
• Dollar budget alerts say how many calls had no price, and skip a round whose spend can't be read.

Docs

• Updated: docs/user/rate-limits.md, docs/user/alerts.md, docs/dev/alerts.md, the generated docs/reference/database.md, and CHANGELOG.md.
• gen_docs.py drift also lists three guides. They still hold because none of them describes the changed parts:
  • docs/user/usage-and-audit.md covers the Usage page, not dollar spend per scope.
  • docs/dev/database-and-migrations.md covers the migration mechanics, which didn't change.
  • docs/dev/template-format.md doesn't touch rate limits.

Testing

• The full suite passes (python -m unittest discover -s shared/test): 1483 tests, 1 skipped.
• test_usd_budgets.py has new cases for unpriced calls, the sub-agent tree, fail-closed on a database error, and validation of the switches.
• python scripts/gen_docs.py --check passes.

---

Generated by Claude Code