feat(agents,budget): per-persona spending-cap primitive (OpenRouter Phase 0)

[thinmintdev]

Summary

• New [persona.budget] TOML block + BudgetLedger (append-only JSONL at /var/lib/hal0/agents/{id}/personas/{pid}/spend.jsonl)
• /api/agents/{id}/personas/{pid}/budget REST surface (GET / PUT / check / charge)
• React UI editor in personas-tab.jsx (PersonaBudgetPanel + TanStack hooks)
• Persona seed (hermes + coder) keeps an empty budget block; operator opts in

Why now

DA review of the OpenRouter integration plan flagged this as P0 must-fix #3 (fusion 4.4x cost + recursion = $200/credit drain risk). Lands BEFORE V1 OpenRouter provider + V2 fusion MCP so they have a budget gate from day 1.

Scope locked

• Per-persona only for v0.3 (PLANNING.md §5 Q2 default). Per-agent + platform caps deferred to v0.4 — both are strict supersets of this primitive.
• Append-only JSONL ledger: no SQLite dependency, fsync per write, operator-inspectable with tail -f + jq.
• hard_cap=True default (block over budget); hard_cap=False is warn-only.
• Race tolerance: check-then-record is NOT serialised; periodic over-spend within one window tolerated (documented in module docstring).
• No provider charges to this primitive yet — V1 OpenRouter upstream wires it in.

Test plan

• Pure-Python unit tests: Budget dataclass, parse_budget, BudgetLedger round-trip, check_budget edge cases (no cap → allow; over daily → block; over per-call → block; hard_cap=False → warn; most-restrictive wins; day-boundary aggregation)
• Persona TOML round-trip preserves budget block (incl. seed empty budget + explicit zero + hard_cap=False + other-fields preserved)
• REST CRUD + check + charge happy path + 404 unknown agent/persona + 400 malformed body / invalid estimate / invalid charge
• ruff format --check / ruff check / mypy / pytest (58 passed)
• UI clean rebuild + tsc --noEmit typecheck
• Live LXC smoke deferred to V1 (no charge surface yet)

Idempotency

hal0 agent reprovision hermes after the operator PUTs a budget preserves the caps: _phase_persona_seed calls seed_default_personas(overwrite=False) which skips existing files. Only --repair re-writes seeds back to canonical empty.

Refs openrouter-research-2026-05-28/PLANNING.md §3 Phase 0 + §5 Q2.

🤖 Generated with Claude Code