Per-spec cost visibility with operator spend ceiling

Let me explore the codebase first. Good structure. Let me dig into the spend-related files. Now let me look at the database schema for the orgs table and the `recordSpend` function to see what columns exist and whether any budget numbers are actually enforced. Let me look at the database schema for the `orgs` table and the `agent_usage_ledger` table. Let me check what the billing UI currently shows the user, and also look at how the settings page renders org data. Let me also check the configuration env settings and how existing usage-metering gallery spec looks. Here's what I found after reading the code across `turn-spend.ts`, `pricing.ts`, `stripe-client.ts`, `stripe.ts` (the routes), `spec-quota.ts`, the database schema, and the UI components. **What's recorded per turn:** Every agent turn gets priced in micro-dollars (via `costMicros` in `pricing.ts`, using a hardcoded per-model rate table) and written to `agent_usage_ledger` with token counts, model, cost, and an error flag. The org's `periodSpendMicros` accumulates in the same atomic UPDATE. **What the org-row columns mean:** - `periodSpendMicros` — running backend-cost total this period (tracks to the micro-dollar) - `periodAlertMicros` — soft threshold that fires an operator alert (free: $1, paid: $20). Pages ops, never blocks - `periodBudgetMicros` — **legacy retired hard cap.** The code explicitly says "no longer enforced anywhere" and "nothing reads it." It's a dead column kept for row readability only. - `specLimit` / `specsCreatedTotal` — the ONLY actual gate: free tier capped at 10 specs lifetime **What actually gates a free user:** Only the 10-spec lifetime limit. The `credits_exhausted` concept is documented as "retired" in the toast handler. Nothing anywhere blocks a turn based on spend. A free user running Opus ($15/$75 per 1M tokens) can rack up hundreds of dollars in backend cost and the system just takes it. **What the user sees today:** Nothing about cost. The pricing page promises "unlimited — no per-run charges and no overage billing." The settings UI deliberately hides the usage meter: "The paid plan is unlimited... so we deliberately do NOT render a usage meter here." The billing snapshot API returns only subscription status, spec counts, and period dates — zero spend data to the frontend. So your read is correct. The ledger has granular per-turn cost data that could power any visibility or gating feature, but right now it's invisible to the user and unenforced. The old hard-cap column (`periodBudgetMicros`) was explicitly stripped of all enforcement. Two gaps to nail down before I write the first block: The code tells a clear story: you have a complete per-turn costing pipeline that feeds a ledger, but it's invisible to the user and unenforced. The old `periodBudgetMicros` cap was deliberately retired and nothing replaced it. The first question above cuts to the core choice: do you want to just show users what things cost, or actually let them enforce a limit?

Noted and accepted. The hard-cap-overwrite-mid-turn is ruled out. The "refusal at the door" model you described for the spec cap is the right analogy — check before anything starts, so the user never gets half-rewritten work and a "pay up" wall. That gives two entirely different mechanisms for the "stop costing a fortune" half of your problem. Let me ask the right question now that the first bad answer is off the table. You ruled out the destructive mid-turn kill. The cleanest alternatives all follow the "refusal at the door" spec-cap pattern — check before the turn starts, not during. The question above asks which mechanism you want. My recommendation is B because it matches your existing product model (free tier has limits checked before work starts, paid is unlimited) while giving you the cost protection you need. Visibility alone (A) solves the "can't tell them" gap but leaves the "can't stop them" gap wide open.

That's a clear, internally consistent answer. Let me capture it into blocks and score intent. The key distinctions I hear: - **Visibility** is per-spec, post-hoc, in dollars, and honest about unknowns - **The ceiling** is operator-set, org-level, checked at session start, never mid-turn - The fail-loud pricing rule carries into the UI The rejected block prescribed route names I hadn't verified — and the behavior is already covered by "No mid-turn spend kill." Let me just add the per-org constraint. Let me now score the intent section. We have three goals and four constraints that crisply define the boundaries the user set. Intent is scored and clean — 0.9 with no blocking findings. Here's what's captured in the spec so far: **Goals** - Per-spec authoring cost in dollars (post-hoc from the ledger, shown to the spec's author) - Operator-set per-period spend ceiling (checked at session start, never mid-turn) - Priced-model integrity in the UI (unknown models show "Unable to price," never $0 or a guess) **Constraints** - No mid-turn spend kill — ceiling only refuses new sessions, not in-flight turns - No running cost ticker — post-hoc, settled numbers only - No user-facing budget configuration — the ceiling is operator-only - Dollar-denominated — no tokens or micro-dollars shown to users - Per-org, not per-user Ready to move to the acceptance section when you are, or grill me on anything I'm missing.

Clear. Let me capture the non-goals and acceptance criteria, then score and generate tasks. Now let me score both remaining sections. All three sections pass. Let me verify the agent session route for the task titles, then generate. Both tasks created. Now the complete trace graph. Everything is committed and validated. Here's the final spec: **Title:** Per-spec cost visibility with operator spend ceiling **2 tasks, 6 acceptance criteria, 3 goals, 7 constraints — full trace coverage.** **Task 1: Show per-spec authoring cost in the spec detail view** Aggregates `agent_usage_ledger.costMicros` per spec into a dollar total rendered in the spec view post-hoc. Unpriced models show "Unable to price." Must reconcile exactly to `SUM(costMicros)`. **Task 2: Gate POST /v1/agent/sessions behind the per-org spend ceiling** Reads the org's ceiling and current `periodSpendMicros` at session start. Rejects new sessions when spend is at or above the ceiling. In-flight turns complete without interruption. Ceiling of 0 = unlimited; changes don't retroactively apply. The key product decisions this rests on: - **No mid-turn kill** — the ceiling refuses new sessions at the door, never terminates work in progress (you called this "the most important call in the spec") - **Dollar-denominated, post-hoc, no ticker** — users see a settled number, not a running anxiety meter - **No pre-flight estimates** — if we can't predict accurately, we don't show a number that will be treated as a quote - **No per-member breakdown** — cost is spec-level and org-level only, never a surveillance tool - **Fail-loud pricing extends to the UI** — unknown models show "Unable to price," never $0 or a fabricated figure