Per-agent epoch gas budget enforcement at block-builder level (runtime hint)

[abhicris]

Problem

gas_budget.py (PR #14) enforces budgets in the client middleware — the agent sends a tx, the middleware checks the rolling hour/day spend, refuses to broadcast if over. This works in the happy path but has two failure modes:

1. Out-of-band txs. Anything that bypasses switchboard middleware (a directly-signed RPC call, a different SDK, a buggy plugin) escapes the budget.
2. Multi-process race. Two switchboard processes for the same agent each check the budget independently, both pass, both broadcast, agent is rugged.

We need the budget enforced at the chain side so the agent's epoch cap is the chain's invariant, not the client's.

Proposed Approach

Promote the budget to a runtime-level hint surfaced to the block builder:

1. AgentBudget.sol at a well-known address. Stores per-agent (epoch, hourly_cap, daily_cap, hourly_spent, daily_spent, last_reset_block). Updated by AgentEscrow.release and x402_middleware settlement events (these are the only authoritative tx-cost emitters).
2. Block-builder hint: the builder consults AgentBudget for each tx in the mempool tagged with agent_id. If the tx would push spent over cap, defer to next epoch (or reject if --strict-budget flag set). This is a hint, not consensus — it does not invalidate the tx, it just lets validator policies enforce caps.
3. switchboard/budget_client.py: thin wrapper that reads AgentBudget state and short-circuits client-side before sending — keeps middleware behavior for legacy callers.
4. Waiver path: committee 2-of-N quorum can waiveEpoch(agentId, newCap) for emergency drain — see issue Security audit: gas-budget waive/cap escalation paths #84 (gas-budget waiver audit) for the security review.

Acceptance Criteria

• AgentBudget.sol deployed in contracts/ with epoch reset logic
• gas_budget.py updated to read on-chain state as authoritative
• Block-builder hint published in docs/block-builder-integration.md for validator operators
• Multi-process race test: two parallel writers cannot double-spend the cap
• Out-of-band tx test: a directly-signed tx from the agent key still surfaces in AgentBudget via settlement events

References

• PR feat: gas budget tracker with configurable hour/day limits (closes #5) #14 — gas budget tracker (client-side, the current floor)
• Issue Security audit: gas-budget waive/cap escalation paths #84 — gas-budget waiver security audit (to file alongside)
• internal: see stress-test 2026-06-01 section 3.2 on Hanzo durable-workflow checkpoint anchoring (same runtime hint surface)