Usage visibility dashboard and org-settable budget gates for agent spend

I've thoroughly explored the codebase. Here's what I found: **What exists today:** - Every agent turn is already **priced** (`pricing.ts`) and **recorded** to `agent_usage_ledger` with per-model token rates in micro-dollars - `orgs.period_spend_micros` accumulates spend per billing period - **Soft operator alerts** fire via PostHog when an org crosses $20/mo (paid) or $1/mo (free) — but NOTHING blocks or even warns the user - The settings page shows subscription status ("Active") and "Unlimited usage" — but **raw spend is explicitly hidden**: the code comments say "Dollar/token figures are intentionally NOT surfaced to the user" - **No user-facing controls whatsoever** — no dashboard, no per-turn/per-period cost breakdown, no budget caps, no spend alerts So the data pipeline is complete but invisible. You have no dashboard, no budget controls, no way to cap or even see spend from the product UI. Let's start defining scope. The pricing ledger already has every turn costed and stored — the raw data for a dashboard is there, and the `period_alert_micros` field on orgs is a ready-made threshold mechanism. The question is which problem to solve first (or both in one spec).

Excellent question. The answer is yes, it's reliable to gate on — and the "one turn behind" pattern is actually the correct design for your constraint (never kill work in flight). Here's why: **Timing**: `recordTurnSpend()` runs in the turn **finalizer** — after the agent completes. It writes the priced cost into `agent_usage_ledger` and atomically adds it to `orgs.period_spend_micros` in a single transaction. So a budget gate that checks `period_spend_micros` BEFORE starting a new turn is looking at settled, complete data. **Failure handling**: A failed turn is recorded with `isError: true` and $0 cost — it's distinguishable from a clean free turn, but it doesn't pollute the spend total. So you won't lose your budget to errored turns. **The only edge case** is concurrent turns (two sessions running at once). Both could check the budget, see headroom, and start — then both record spend and overshoot by one turn each. For v1 that's probably acceptable (a few dollars at most on a $27.99 plan), but if you want to close it, a pre-reservation pattern (hold budget before starting, release unused on completion) would be the fix. Now let me capture what you described. Intent is at 0.85 with no blocking gaps. Two clarifying decisions remain — here's the one that most affects the architecture. You said "warning before the wall" and "at a threshold, not just at the limit." The architecture question is whether that threshold is a second knob the org owner tunes, or a fixed ratio of their budget. My recommendation is two knobs (configurable percentage) — an org with a $50 budget might want to hear at 60%, another at 90% — and setting it as a percentage of the budget keeps it simple. But if you'd rather ship one knob (just the hard budget) and let the product pick the warning point, that's simpler and still addresses the brief.

The concurrent-turn cap is the right answer. You effectively sketched it yourself. Here's why it wins: **Full pre-reservation** gives you phantom-hold risk (process dies, budget is stuck) and requires a release-fast path plus a ttl sweep — that's the engineering you're rightly wary of. **Concurrent-turn cap** (max simultaneously active agent sessions per org) bounds the overshoot with zero phantom-spend risk. No holds, no releases, just an atomic counter. Implementation is ~one column, one pre-turn check, one post-turn decrement. The bound is: > `max_active_turns × highest_realistic_turn_cost_for_the_orgs_model` With a cap of **5** (generous — most users run one session; five is for team-fan-out scenarios) and DeepSeek V4 Flash at ~$0.05/worst-case turn, that's $0.25 max overshoot. With Claude Opus at ~$5/worst-case long turn, that's $25 — still an order of magnitude below the $100+ a genuinely unbounded fan-out could hit. And you've shipped the bound as a stated property of the product: "You will never overshoot your budget by more than **5 × max single-turn cost for your model**." Let me capture everything and finalize intent. Done. Here's the summary of the concurrency decision: **Concurrent-turn cap (max 5 active sessions per org)** is the mechanism. It avoids the phantom-hold risk of pre-reservation, bounds overshoot to a stated value (`cap × model_max_turn_cost`), and is simple enough to implement as an atomic counter — increment on start, decrement on finish, reject when at cap. I've written it into the spec as a constraint block along with the fixed 80% warning threshold. Intent is at 0.95 with no blocking gaps. Ready for you to tell me to proceed to acceptance criteria, or raise anything else while intent is still open.

The spend visibility question is straightforward — it needs one clarifying decision before I can write the AC concretely. My recommendation is **D — both Settings and inline**. The per-period summary with budget controls is the natural place in Settings (where subscription management already lives), and inline cost-per-session in the spec editor answers "what did this conversation cost me" at the moment the user is having it — which I suspect is where most of the anxiety lives. They're different information needs on different surfaces. But it's your call — if you want to pick one to keep the scope tighter, say so.

Understood. Settings-only for visibility. That's a clean scope cut. Let me write the acceptance criteria and propose the split. All three sections are at 0.9+. Here's my proposed task split. **Two tasks — one per distinct user-visible capability:** **Task 1 — Add per-period spend breakdown with spec and session drill-down to the Settings page** Read-only surface. Queries `agent_usage_ledger` aggregated by current period → by spec → by session. Renders total spend, with expandable rows per spec showing sessions within it. Lives alongside the existing subscription status panel in Settings (shown only for paid orgs). No agent turn behavior changes at all. Owns AC: spend visibility in Settings. **Task 2 — Add budget controls to Settings with pre-turn enforcement, concurrent-turn cap, and distinct blocked states** The enforcement machinery. Settings gets a budget input (default off, unlimited behavior preserved). The agent turn start flow gets two pre-checks: budget gate (read `period_spend_micros` against org-set budget) and concurrent-turn cap counter (increment, refused if ≥5, decremented on finish). The 80% warning triggers as an in-product notification on the crossing turn's completion. Two distinct refusal states (budget exhausted vs. concurrency cap reached) with different messages and resolve paths. Owns ACs: no kill-in-flight, blocked-by-budget with explanation, 80% warning, concurrent cap with stated bound, distinguishable refusals, free tier unchanged. **Why two, not one**: They're independently shippable. You could ship the spend breakdown while enforcement is still in review, and a user could see what they spent without any budget behavior changing. Conversely, you could ship enforcement first (set a budget, get blocked, see distinct states) and add the breakdown a week later. Each is a complete demo on its own, not half of one. **Why not three**: The 80% warning is triggered by the same lifecycle as the budget gate — it fires when the post-turn spend accumulation crosses 80% of the budget. It's not a separate capability; it's a notification fired by the enforcement route. Folding it into Task 2 keeps each task a whole capability rather than one task per lifecycle event. Does that split work for you, or do you see a different seam?

Good — I've confirmed the surfaces. `BillingPanel` in `settings.tsx` for the visibility UI, `runAgentTurn` in `agent.ts` for the enforcement point. Let me create the tasks. The second task's description was too long. Let me tighten both. Both tasks created. Now building the complete trace graph. 26 edges committed, trace coverage complete. Let me clean up the answered questions. The spec is complete. Here's what shipped: **Spec: Usage visibility dashboard and org-settable budget gates for agent spend** **2 tasks, 7 acceptance criteria, 26 trace edges.** | Task | Owns | What it delivers | |------|------|------------------| | **1 — Spend breakdown in Settings BillingPanel** | 1 AC | Per-period spend by spec and session, read-only, paid orgs only | | **2 — Budget gate + concurrent cap + blocked states** | 6 ACs | Budget input, pre-turn enforcement, concurrent-turn cap (max 5), distinct blocked-by-budget vs. blocked-by-concurrency messages, 80% in-product warning, free tier unchanged | **Key product decisions captured in the spec:** - Visibility lives in Settings only (not inline in the agent chat) — you don't want a per-message price tag nudging users toward terse specs - Budgets are the paid-tier control; free tier keeps its existing spec-count quota — separate mechanisms, never unified - The concurrent-turn cap (max 5 active sessions) bounds overshoot to `5 × worst-case single-turn cost for the org's model` — no phantom-hold risk - 80% warning threshold is fixed, not user-configurable — the product owns the choice - Budget crossing never kills work in flight — the turn completes, the *next* turn is refused - Two distinct refusal messages: "concurrency cap" and "budget exhausted" — the user never has to guess which limit they hit