feat(gastown): Billing integration — usage metering, limits, and cost visibility

[jrf0110]

Summary

Gastown currently has no billing integration. Agents consume LLM tokens (tracked via feature attribution #1154) but there are no spending limits, no cost visibility in the UI, and no guard rails to prevent runaway usage. This is a hard launch blocker.

Requirements

Metering & Limits

• Per-town spending cap (configurable in town settings, sensible default)
• Real-time usage tracking surfaced from microdollar_usage_metadata (already being written via Add gastown feature attribution for LLM usage tracking #1154)
• Agent dispatch blocked when spending cap is reached — reconciler should not emit dispatch_agent actions when the town is over budget
• Grace period or soft-limit warning before hard cutoff

Cost Visibility (UI)

• Town settings: current period spend, spending cap, usage breakdown by agent role
• Town overview: cost indicator (current spend / cap) — could be the "gas tank" gauge from Real-time throughput gauges and timeseries — tokens/sec, cost/sec, gas tank #1297
• Bead detail: cost attributed to this bead (sum of LLM calls made while agent was hooked)

Reconciler Integration

• reconcileBeads Rule 1 should check budget before assigning agents
• Running agents should not be killed mid-work when the cap is hit (let them finish current bead, but don't dispatch new work)
• Mayor should remain functional (can chat, answer questions) even when budget is exceeded — only polecat/refinery dispatch is blocked

Notes

• The microdollar_usage_metadata table already has feature = 'gastown' rows from Add gastown feature attribution for LLM usage tracking #1154. The data is there — this issue is about reading it and enforcing limits.
• Real-time throughput gauges and timeseries — tokens/sec, cost/sec, gas tank #1297 (throughput gauges) covers the fancy timeseries charts. This issue covers the minimum viable billing: a cap and a number.
• Per-bead cost attribution requires joining usage records with the agent's hooked bead at the time of the LLM call. The heartbeat watermark (last_event_at) could help correlate timestamps.

[kilo-code-bot]

This issue appears to be a duplicate of #1154.

Add gastown feature attribution for LLM usage tracking (#1154)

Similarity score: 90%

This comment was generated by Kilo Auto-Triage.