feat(costs): add billing, quota, and budget control plane

2026-03-14 22:00:12 -05:00
parent 656b4659fc
commit 76e6cc08a6
91 changed files with 22406 additions and 769 deletions
--- a/ui/src/api/budgets.ts
+++ b/ui/src/api/budgets.ts
@@ -0,0 +1,20 @@
+import type {
+  BudgetIncident,
+  BudgetIncidentResolutionInput,
+  BudgetOverview,
+  BudgetPolicySummary,
+  BudgetPolicyUpsertInput,
+} from "@paperclipai/shared";
+import { api } from "./client";
+
+export const budgetsApi = {
+  overview: (companyId: string) =>
+    api.get<BudgetOverview>(`/companies/${companyId}/budgets/overview`),
+  upsertPolicy: (companyId: string, data: BudgetPolicyUpsertInput) =>
+    api.post<BudgetPolicySummary>(`/companies/${companyId}/budgets/policies`, data),
+  resolveIncident: (companyId: string, incidentId: string, data: BudgetIncidentResolutionInput) =>
+    api.post<BudgetIncident>(
+      `/companies/${companyId}/budget-incidents/${encodeURIComponent(incidentId)}/resolve`,
+      data,
+    ),
+};
--- a/ui/src/api/costs.ts
+++ b/ui/src/api/costs.ts
@@ -1,4 +1,17 @@
-import type { CostSummary, CostByAgent, CostByProviderModel, CostByAgentModel, CostByProject, CostWindowSpendRow, ProviderQuotaResult } from "@paperclipai/shared";
+import type {
+  CostSummary,
+  CostByAgent,
+  CostByProviderModel,
+  CostByBiller,
+  CostByAgentModel,
+  CostByProject,
+  CostWindowSpendRow,
+  FinanceSummary,
+  FinanceByBiller,
+  FinanceByKind,
+  FinanceEvent,
+  ProviderQuotaResult,
+} from "@paperclipai/shared";
 import { api } from "./client";

 function dateParams(from?: string, to?: string): string {
@@ -20,8 +33,27 @@ export const costsApi = {
    api.get<CostByProject[]>(`/companies/${companyId}/costs/by-project${dateParams(from, to)}`),
  byProvider: (companyId: string, from?: string, to?: string) =>
    api.get<CostByProviderModel[]>(`/companies/${companyId}/costs/by-provider${dateParams(from, to)}`),
+  byBiller: (companyId: string, from?: string, to?: string) =>
+    api.get<CostByBiller[]>(`/companies/${companyId}/costs/by-biller${dateParams(from, to)}`),
+  financeSummary: (companyId: string, from?: string, to?: string) =>
+    api.get<FinanceSummary>(`/companies/${companyId}/costs/finance-summary${dateParams(from, to)}`),
+  financeByBiller: (companyId: string, from?: string, to?: string) =>
+    api.get<FinanceByBiller[]>(`/companies/${companyId}/costs/finance-by-biller${dateParams(from, to)}`),
+  financeByKind: (companyId: string, from?: string, to?: string) =>
+    api.get<FinanceByKind[]>(`/companies/${companyId}/costs/finance-by-kind${dateParams(from, to)}`),
+  financeEvents: (companyId: string, from?: string, to?: string, limit: number = 100) =>
+    api.get<FinanceEvent[]>(`/companies/${companyId}/costs/finance-events${dateParamsWithLimit(from, to, limit)}`),
  windowSpend: (companyId: string) =>
    api.get<CostWindowSpendRow[]>(`/companies/${companyId}/costs/window-spend`),
  quotaWindows: (companyId: string) =>
    api.get<ProviderQuotaResult[]>(`/companies/${companyId}/costs/quota-windows`),
 };
+
+function dateParamsWithLimit(from?: string, to?: string, limit?: number): string {
+  const params = new URLSearchParams();
+  if (from) params.set("from", from);
+  if (to) params.set("to", to);
+  if (limit) params.set("limit", String(limit));
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
--- a/ui/src/components/AccountingModelCard.tsx
+++ b/ui/src/components/AccountingModelCard.tsx
@@ -0,0 +1,69 @@
+import { Database, Gauge, ReceiptText } from "lucide-react";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+
+const SURFACES = [
+  {
+    title: "Inference ledger",
+    description: "Request-scoped usage and billed runs from cost_events.",
+    icon: Database,
+    points: ["tokens + billed dollars", "provider, biller, model", "subscription and overage aware"],
+    tone: "from-sky-500/12 via-sky-500/6 to-transparent",
+  },
+  {
+    title: "Finance ledger",
+    description: "Account-level charges that are not one prompt-response pair.",
+    icon: ReceiptText,
+    points: ["top-ups, refunds, fees", "Bedrock provisioned or training charges", "credit expiries and adjustments"],
+    tone: "from-amber-500/14 via-amber-500/6 to-transparent",
+  },
+  {
+    title: "Live quotas",
+    description: "Provider or biller windows that can stop traffic in real time.",
+    icon: Gauge,
+    points: ["provider quota windows", "biller credit systems", "errors surfaced directly"],
+    tone: "from-emerald-500/14 via-emerald-500/6 to-transparent",
+  },
+] as const;
+
+export function AccountingModelCard() {
+  return (
+    <Card className="relative overflow-hidden border-border/70">
+      <div className="absolute inset-0 bg-[radial-gradient(circle_at_top_left,rgba(244,114,182,0.08),transparent_35%),radial-gradient(circle_at_bottom_right,rgba(56,189,248,0.1),transparent_32%)]" />
+      <CardHeader className="relative px-5 pt-5 pb-2">
+        <CardTitle className="text-sm font-semibold uppercase tracking-[0.22em] text-muted-foreground">
+          Accounting model
+        </CardTitle>
+        <CardDescription className="max-w-2xl text-sm leading-6">
+          Paperclip now separates request-level inference usage from account-level finance events.
+          That keeps provider reporting honest when the biller is OpenRouter, Cloudflare, Bedrock, or another intermediary.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="relative grid gap-3 px-5 pb-5 md:grid-cols-3">
+        {SURFACES.map((surface) => {
+          const Icon = surface.icon;
+          return (
+            <div
+              key={surface.title}
+              className={`rounded-2xl border border-border/70 bg-gradient-to-br ${surface.tone} p-4 shadow-sm`}
+            >
+              <div className="mb-3 flex items-center gap-3">
+                <div className="flex h-10 w-10 items-center justify-center rounded-full border border-border/70 bg-background/80">
+                  <Icon className="h-4 w-4 text-foreground" />
+                </div>
+                <div>
+                  <div className="text-sm font-semibold">{surface.title}</div>
+                  <div className="text-xs text-muted-foreground">{surface.description}</div>
+                </div>
+              </div>
+              <div className="space-y-1.5 text-xs text-muted-foreground">
+                {surface.points.map((point) => (
+                  <div key={point}>{point}</div>
+                ))}
+              </div>
+            </div>
+          );
+        })}
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/ApprovalCard.tsx
+++ b/ui/src/components/ApprovalCard.tsx
@@ -33,6 +33,9 @@ export function ApprovalCard({
 }) {
  const Icon = typeIcon[approval.type] ?? defaultTypeIcon;
  const label = typeLabel[approval.type] ?? approval.type;
+  const showResolutionButtons =
+    approval.type !== "budget_override_required" &&
+    (approval.status === "pending" || approval.status === "revision_requested");

  return (
    <div className="border border-border rounded-lg p-4 space-y-0">
@@ -67,7 +70,7 @@ export function ApprovalCard({
      )}

      {/* Actions */}
-      {(approval.status === "pending" || approval.status === "revision_requested") && (
+      {showResolutionButtons && (
        <div className="flex gap-2 mt-4 pt-3 border-t border-border">
          <Button
            size="sm"
--- a/ui/src/components/ApprovalPayload.tsx
+++ b/ui/src/components/ApprovalPayload.tsx
@@ -1,13 +1,16 @@
-import { UserPlus, Lightbulb, ShieldCheck } from "lucide-react";
+import { UserPlus, Lightbulb, ShieldAlert, ShieldCheck } from "lucide-react";
+import { formatCents } from "../lib/utils";

 export const typeLabel: Record<string, string> = {
  hire_agent: "Hire Agent",
  approve_ceo_strategy: "CEO Strategy",
+  budget_override_required: "Budget Override",
 };

 export const typeIcon: Record<string, typeof UserPlus> = {
  hire_agent: UserPlus,
  approve_ceo_strategy: Lightbulb,
+  budget_override_required: ShieldAlert,
 };

 export const defaultTypeIcon = ShieldCheck;
@@ -69,7 +72,28 @@ export function CeoStrategyPayload({ payload }: { payload: Record<string, unknow
  );
 }

+export function BudgetOverridePayload({ payload }: { payload: Record<string, unknown> }) {
+  const budgetAmount = typeof payload.budgetAmount === "number" ? payload.budgetAmount : null;
+  const observedAmount = typeof payload.observedAmount === "number" ? payload.observedAmount : null;
+  return (
+    <div className="mt-3 space-y-1.5 text-sm">
+      <PayloadField label="Scope" value={payload.scopeName ?? payload.scopeType} />
+      <PayloadField label="Window" value={payload.windowKind} />
+      <PayloadField label="Metric" value={payload.metric} />
+      {(budgetAmount !== null || observedAmount !== null) ? (
+        <div className="rounded-md bg-muted/40 px-3 py-2 text-xs text-muted-foreground">
+          Limit {budgetAmount !== null ? formatCents(budgetAmount) : "—"} · Observed {observedAmount !== null ? formatCents(observedAmount) : "—"}
+        </div>
+      ) : null}
+      {!!payload.guidance && (
+        <p className="text-muted-foreground">{String(payload.guidance)}</p>
+      )}
+    </div>
+  );
+}
+
 export function ApprovalPayloadRenderer({ type, payload }: { type: string; payload: Record<string, unknown> }) {
  if (type === "hire_agent") return <HireAgentPayload payload={payload} />;
+  if (type === "budget_override_required") return <BudgetOverridePayload payload={payload} />;
  return <CeoStrategyPayload payload={payload} />;
 }
--- a/ui/src/components/BillerSpendCard.tsx
+++ b/ui/src/components/BillerSpendCard.tsx
@@ -0,0 +1,145 @@
+import { useMemo } from "react";
+import type { CostByBiller, CostByProviderModel } from "@paperclipai/shared";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { QuotaBar } from "./QuotaBar";
+import { billingTypeDisplayName, formatCents, formatTokens, providerDisplayName } from "@/lib/utils";
+
+interface BillerSpendCardProps {
+  row: CostByBiller;
+  weekSpendCents: number;
+  budgetMonthlyCents: number;
+  totalCompanySpendCents: number;
+  providerRows: CostByProviderModel[];
+}
+
+export function BillerSpendCard({
+  row,
+  weekSpendCents,
+  budgetMonthlyCents,
+  totalCompanySpendCents,
+  providerRows,
+}: BillerSpendCardProps) {
+  const providerBreakdown = useMemo(() => {
+    const map = new Map<string, { provider: string; costCents: number; inputTokens: number; outputTokens: number }>();
+    for (const entry of providerRows) {
+      const current = map.get(entry.provider) ?? {
+        provider: entry.provider,
+        costCents: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+      };
+      current.costCents += entry.costCents;
+      current.inputTokens += entry.inputTokens + entry.cachedInputTokens;
+      current.outputTokens += entry.outputTokens;
+      map.set(entry.provider, current);
+    }
+    return Array.from(map.values()).sort((a, b) => b.costCents - a.costCents);
+  }, [providerRows]);
+
+  const billingTypeBreakdown = useMemo(() => {
+    const map = new Map<string, number>();
+    for (const entry of providerRows) {
+      map.set(entry.billingType, (map.get(entry.billingType) ?? 0) + entry.costCents);
+    }
+    return Array.from(map.entries()).sort((a, b) => b[1] - a[1]);
+  }, [providerRows]);
+
+  const providerBudgetShare =
+    budgetMonthlyCents > 0 && totalCompanySpendCents > 0
+      ? (row.costCents / totalCompanySpendCents) * budgetMonthlyCents
+      : budgetMonthlyCents;
+  const budgetPct =
+    providerBudgetShare > 0
+      ? Math.min(100, (row.costCents / providerBudgetShare) * 100)
+      : 0;
+
+  return (
+    <Card>
+      <CardHeader className="px-4 pt-4 pb-0 gap-1">
+        <div className="flex items-start justify-between gap-3">
+          <div className="min-w-0">
+            <CardTitle className="text-sm font-semibold">
+              {providerDisplayName(row.biller)}
+            </CardTitle>
+            <CardDescription className="text-xs mt-0.5">
+              <span className="font-mono">{formatTokens(row.inputTokens + row.cachedInputTokens)}</span> in
+              {" · "}
+              <span className="font-mono">{formatTokens(row.outputTokens)}</span> out
+              {" · "}
+              {row.providerCount} provider{row.providerCount === 1 ? "" : "s"}
+              {" · "}
+              {row.modelCount} model{row.modelCount === 1 ? "" : "s"}
+            </CardDescription>
+          </div>
+          <span className="text-xl font-bold tabular-nums shrink-0">
+            {formatCents(row.costCents)}
+          </span>
+        </div>
+      </CardHeader>
+
+      <CardContent className="px-4 pb-4 pt-3 space-y-4">
+        {budgetMonthlyCents > 0 && (
+          <QuotaBar
+            label="Period spend"
+            percentUsed={budgetPct}
+            leftLabel={formatCents(row.costCents)}
+            rightLabel={`${Math.round(budgetPct)}% of allocation`}
+          />
+        )}
+
+        <div className="text-xs text-muted-foreground">
+          {row.apiRunCount > 0 ? `${row.apiRunCount} metered run${row.apiRunCount === 1 ? "" : "s"}` : "0 metered runs"}
+          {" · "}
+          {row.subscriptionRunCount > 0
+            ? `${row.subscriptionRunCount} subscription run${row.subscriptionRunCount === 1 ? "" : "s"}`
+            : "0 subscription runs"}
+          {" · "}
+          {formatCents(weekSpendCents)} this week
+        </div>
+
+        {billingTypeBreakdown.length > 0 && (
+          <>
+            <div className="border-t border-border" />
+            <div className="space-y-2">
+              <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+                Billing types
+              </p>
+              <div className="space-y-1.5">
+                {billingTypeBreakdown.map(([billingType, costCents]) => (
+                  <div key={billingType} className="flex items-center justify-between gap-2 text-xs">
+                    <span className="text-muted-foreground">{billingTypeDisplayName(billingType as any)}</span>
+                    <span className="font-medium tabular-nums">{formatCents(costCents)}</span>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </>
+        )}
+
+        {providerBreakdown.length > 0 && (
+          <>
+            <div className="border-t border-border" />
+            <div className="space-y-2">
+              <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+                Upstream providers
+              </p>
+              <div className="space-y-1.5">
+                {providerBreakdown.map((entry) => (
+                  <div key={entry.provider} className="flex items-center justify-between gap-2 text-xs">
+                    <span className="text-muted-foreground">{providerDisplayName(entry.provider)}</span>
+                    <div className="text-right tabular-nums">
+                      <div className="font-medium">{formatCents(entry.costCents)}</div>
+                      <div className="text-muted-foreground">
+                        {formatTokens(entry.inputTokens + entry.outputTokens)} tok
+                      </div>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/BudgetIncidentCard.tsx
+++ b/ui/src/components/BudgetIncidentCard.tsx
@@ -0,0 +1,100 @@
+import { useState } from "react";
+import type { BudgetIncident } from "@paperclipai/shared";
+import { AlertOctagon, ArrowUpRight, PauseCircle } from "lucide-react";
+import { formatCents } from "../lib/utils";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+
+function centsInputValue(value: number) {
+  return (value / 100).toFixed(2);
+}
+
+function parseDollarInput(value: string) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return null;
+  return Math.round(parsed * 100);
+}
+
+export function BudgetIncidentCard({
+  incident,
+  onRaiseAndResume,
+  onKeepPaused,
+  isMutating,
+}: {
+  incident: BudgetIncident;
+  onRaiseAndResume: (amountCents: number) => void;
+  onKeepPaused: () => void;
+  isMutating?: boolean;
+}) {
+  const [draftAmount, setDraftAmount] = useState(
+    centsInputValue(Math.max(incident.amountObserved + 1000, incident.amountLimit)),
+  );
+  const parsed = parseDollarInput(draftAmount);
+
+  return (
+    <Card className="overflow-hidden border-red-500/20 bg-[linear-gradient(180deg,rgba(255,70,70,0.10),rgba(255,255,255,0.02))]">
+      <CardHeader className="px-5 pt-5 pb-3">
+        <div className="flex items-start justify-between gap-3">
+          <div>
+            <div className="text-[11px] uppercase tracking-[0.22em] text-red-200/80">
+              {incident.scopeType} hard stop
+            </div>
+            <CardTitle className="mt-1 text-base text-red-50">{incident.scopeName}</CardTitle>
+            <CardDescription className="mt-1 text-red-100/70">
+              Spending reached {formatCents(incident.amountObserved)} against a limit of {formatCents(incident.amountLimit)}.
+            </CardDescription>
+          </div>
+          <div className="rounded-full border border-red-400/30 bg-red-500/10 p-2 text-red-200">
+            <AlertOctagon className="h-4 w-4" />
+          </div>
+        </div>
+      </CardHeader>
+      <CardContent className="space-y-4 px-5 pb-5 pt-0">
+        <div className="flex items-start gap-2 rounded-xl border border-red-400/20 bg-red-500/10 px-3 py-2 text-sm text-red-50/90">
+          <PauseCircle className="mt-0.5 h-4 w-4 shrink-0" />
+          <div>
+            {incident.scopeType === "project"
+              ? "Project execution is paused. New work in this project will not start until you resolve the budget incident."
+              : "This scope is paused. New heartbeats will not start until you resolve the budget incident."}
+          </div>
+        </div>
+
+        <div className="rounded-xl border border-border/60 bg-background/60 p-3">
+          <label className="text-[11px] uppercase tracking-[0.18em] text-muted-foreground">
+            New budget (USD)
+          </label>
+          <div className="mt-2 flex flex-col gap-3 sm:flex-row">
+            <Input
+              value={draftAmount}
+              onChange={(event) => setDraftAmount(event.target.value)}
+              inputMode="decimal"
+              placeholder="0.00"
+            />
+            <Button
+              className="gap-2"
+              disabled={isMutating || parsed === null || parsed <= incident.amountObserved}
+              onClick={() => {
+                if (typeof parsed === "number") onRaiseAndResume(parsed);
+              }}
+            >
+              <ArrowUpRight className="h-4 w-4" />
+              {isMutating ? "Applying..." : "Raise budget & resume"}
+            </Button>
+          </div>
+          {parsed !== null && parsed <= incident.amountObserved ? (
+            <p className="mt-2 text-xs text-red-200/80">
+              The new budget must exceed current observed spend.
+            </p>
+          ) : null}
+        </div>
+
+        <div className="flex justify-end">
+          <Button variant="ghost" className="text-muted-foreground" disabled={isMutating} onClick={onKeepPaused}>
+            Keep paused
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/BudgetPolicyCard.tsx
+++ b/ui/src/components/BudgetPolicyCard.tsx
@@ -0,0 +1,153 @@
+import { useEffect, useState } from "react";
+import type { BudgetPolicySummary } from "@paperclipai/shared";
+import { AlertTriangle, PauseCircle, ShieldAlert, Wallet } from "lucide-react";
+import { cn, formatCents } from "../lib/utils";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+
+function centsInputValue(value: number) {
+  return (value / 100).toFixed(2);
+}
+
+function parseDollarInput(value: string) {
+  const normalized = value.trim();
+  if (normalized.length === 0) return 0;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return null;
+  return Math.round(parsed * 100);
+}
+
+function windowLabel(windowKind: BudgetPolicySummary["windowKind"]) {
+  return windowKind === "lifetime" ? "Lifetime budget" : "Monthly UTC budget";
+}
+
+function statusTone(status: BudgetPolicySummary["status"]) {
+  if (status === "hard_stop") return "text-red-300 border-red-500/30 bg-red-500/10";
+  if (status === "warning") return "text-amber-200 border-amber-500/30 bg-amber-500/10";
+  return "text-emerald-200 border-emerald-500/30 bg-emerald-500/10";
+}
+
+export function BudgetPolicyCard({
+  summary,
+  onSave,
+  isSaving,
+  compact = false,
+}: {
+  summary: BudgetPolicySummary;
+  onSave?: (amountCents: number) => void;
+  isSaving?: boolean;
+  compact?: boolean;
+}) {
+  const [draftBudget, setDraftBudget] = useState(centsInputValue(summary.amount));
+
+  useEffect(() => {
+    setDraftBudget(centsInputValue(summary.amount));
+  }, [summary.amount]);
+
+  const parsedDraft = parseDollarInput(draftBudget);
+  const canSave = typeof parsedDraft === "number" && parsedDraft !== summary.amount && Boolean(onSave);
+  const progress = summary.amount > 0 ? Math.min(100, summary.utilizationPercent) : 0;
+  const StatusIcon = summary.status === "hard_stop" ? ShieldAlert : summary.status === "warning" ? AlertTriangle : Wallet;
+
+  return (
+    <Card className={cn("overflow-hidden border-border/70 bg-card/80", compact ? "" : "shadow-[0_20px_80px_-40px_rgba(0,0,0,0.55)]")}>
+      <CardHeader className={cn("gap-3", compact ? "px-4 pt-4 pb-2" : "px-5 pt-5 pb-3")}>
+        <div className="flex items-start justify-between gap-3">
+          <div>
+            <div className="text-[11px] uppercase tracking-[0.22em] text-muted-foreground">
+              {summary.scopeType}
+            </div>
+            <CardTitle className="mt-1 text-base">{summary.scopeName}</CardTitle>
+            <CardDescription className="mt-1">{windowLabel(summary.windowKind)}</CardDescription>
+          </div>
+          <div className={cn("inline-flex items-center gap-2 rounded-full border px-3 py-1 text-[11px] uppercase tracking-[0.18em]", statusTone(summary.status))}>
+            <StatusIcon className="h-3.5 w-3.5" />
+            {summary.paused ? "Paused" : summary.status === "warning" ? "Warning" : summary.status === "hard_stop" ? "Hard stop" : "Healthy"}
+          </div>
+        </div>
+      </CardHeader>
+      <CardContent className={cn("space-y-4", compact ? "px-4 pb-4 pt-0" : "px-5 pb-5 pt-0")}>
+        <div className="grid gap-3 sm:grid-cols-2">
+          <div className="rounded-xl border border-border/70 bg-black/[0.18] px-4 py-3">
+            <div className="text-[11px] uppercase tracking-[0.18em] text-muted-foreground">Observed</div>
+            <div className="mt-2 text-xl font-semibold tabular-nums">{formatCents(summary.observedAmount)}</div>
+            <div className="mt-1 text-xs text-muted-foreground">
+              {summary.amount > 0 ? `${summary.utilizationPercent}% of limit` : "No cap configured"}
+            </div>
+          </div>
+          <div className="rounded-xl border border-border/70 bg-black/[0.18] px-4 py-3">
+            <div className="text-[11px] uppercase tracking-[0.18em] text-muted-foreground">Budget</div>
+            <div className="mt-2 text-xl font-semibold tabular-nums">
+              {summary.amount > 0 ? formatCents(summary.amount) : "Disabled"}
+            </div>
+            <div className="mt-1 text-xs text-muted-foreground">
+              Soft alert at {summary.warnPercent}%{summary.paused && summary.pauseReason ? ` · ${summary.pauseReason} pause` : ""}
+            </div>
+          </div>
+        </div>
+
+        <div className="space-y-2">
+          <div className="flex items-center justify-between text-xs text-muted-foreground">
+            <span>Remaining</span>
+            <span>{summary.amount > 0 ? formatCents(summary.remainingAmount) : "Unlimited"}</span>
+          </div>
+          <div className="h-2 overflow-hidden rounded-full bg-muted/70">
+            <div
+              className={cn(
+                "h-full rounded-full transition-[width,background-color] duration-200",
+                summary.status === "hard_stop"
+                  ? "bg-red-400"
+                  : summary.status === "warning"
+                    ? "bg-amber-300"
+                    : "bg-emerald-300",
+              )}
+              style={{ width: `${progress}%` }}
+            />
+          </div>
+        </div>
+
+        {summary.paused ? (
+          <div className="flex items-start gap-2 rounded-xl border border-red-500/30 bg-red-500/10 px-3 py-2 text-sm text-red-100">
+            <PauseCircle className="mt-0.5 h-4 w-4 shrink-0" />
+            <div>
+              {summary.scopeType === "project"
+                ? "Execution is paused for this project until the budget is raised or the incident is dismissed."
+                : "Heartbeats are paused for this scope until the budget is raised or the incident is dismissed."}
+            </div>
+          </div>
+        ) : null}
+
+        {onSave ? (
+          <div className="rounded-xl border border-border/70 bg-background/50 p-3">
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-end">
+              <div className="min-w-0 flex-1">
+                <label className="text-[11px] uppercase tracking-[0.18em] text-muted-foreground">
+                  Budget (USD)
+                </label>
+                <Input
+                  value={draftBudget}
+                  onChange={(event) => setDraftBudget(event.target.value)}
+                  className="mt-2"
+                  inputMode="decimal"
+                  placeholder="0.00"
+                />
+              </div>
+              <Button
+                onClick={() => {
+                  if (typeof parsedDraft === "number" && onSave) onSave(parsedDraft);
+                }}
+                disabled={!canSave || isSaving || parsedDraft === null}
+              >
+                {isSaving ? "Saving..." : summary.amount > 0 ? "Update budget" : "Set budget"}
+              </Button>
+            </div>
+            {parsedDraft === null ? (
+              <p className="mt-2 text-xs text-destructive">Enter a valid non-negative dollar amount.</p>
+            ) : null}
+          </div>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/ClaudeSubscriptionPanel.tsx
+++ b/ui/src/components/ClaudeSubscriptionPanel.tsx
@@ -0,0 +1,140 @@
+import type { QuotaWindow } from "@paperclipai/shared";
+import { cn, quotaSourceDisplayName } from "@/lib/utils";
+
+interface ClaudeSubscriptionPanelProps {
+  windows: QuotaWindow[];
+  source?: string | null;
+  error?: string | null;
+}
+
+const WINDOW_ORDER = [
+  "currentsession",
+  "currentweekallmodels",
+  "currentweeksonnetonly",
+  "currentweeksonnet",
+  "currentweekopusonly",
+  "currentweekopus",
+  "extrausage",
+] as const;
+
+function normalizeLabel(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function detailText(window: QuotaWindow): string | null {
+  if (typeof window.detail === "string" && window.detail.trim().length > 0) return window.detail.trim();
+  if (window.resetsAt) {
+    const formatted = new Date(window.resetsAt).toLocaleString(undefined, {
+      month: "short",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+      timeZoneName: "short",
+    });
+    return `Resets ${formatted}`;
+  }
+  return null;
+}
+
+function orderedWindows(windows: QuotaWindow[]): QuotaWindow[] {
+  return [...windows].sort((a, b) => {
+    const aIndex = WINDOW_ORDER.indexOf(normalizeLabel(a.label) as (typeof WINDOW_ORDER)[number]);
+    const bIndex = WINDOW_ORDER.indexOf(normalizeLabel(b.label) as (typeof WINDOW_ORDER)[number]);
+    return (aIndex === -1 ? WINDOW_ORDER.length : aIndex) - (bIndex === -1 ? WINDOW_ORDER.length : bIndex);
+  });
+}
+
+function fillClass(usedPercent: number | null): string {
+  if (usedPercent == null) return "bg-zinc-700";
+  if (usedPercent >= 90) return "bg-red-400";
+  if (usedPercent >= 70) return "bg-amber-400";
+  return "bg-primary/70";
+}
+
+export function ClaudeSubscriptionPanel({
+  windows,
+  source = null,
+  error = null,
+}: ClaudeSubscriptionPanelProps) {
+  const ordered = orderedWindows(windows);
+
+  return (
+    <div className="border border-border px-4 py-4">
+      <div className="flex items-start justify-between gap-3 border-b border-border pb-3">
+        <div className="min-w-0">
+          <div className="text-[11px] font-semibold uppercase tracking-[0.2em] text-muted-foreground">
+            Anthropic subscription
+          </div>
+          <div className="mt-1 text-sm text-muted-foreground">
+            Live Claude quota windows.
+          </div>
+        </div>
+        {source ? (
+          <span className="shrink-0 border border-border px-2.5 py-1 text-[10px] font-semibold uppercase tracking-[0.16em] text-muted-foreground">
+            {quotaSourceDisplayName(source)}
+          </span>
+        ) : null}
+      </div>
+
+      {error ? (
+        <div className="mt-4 border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+          {error}
+        </div>
+      ) : null}
+
+      <div className="mt-4 space-y-4">
+        {ordered.map((window) => {
+          const normalized = normalizeLabel(window.label);
+          const detail = detailText(window);
+          if (normalized === "extrausage") {
+            return (
+              <div
+                key={window.label}
+                className="border border-border px-3.5 py-3"
+              >
+                <div className="flex items-center justify-between gap-3">
+                  <div className="text-sm font-medium text-foreground">{window.label}</div>
+                  {window.valueLabel ? (
+                    <div className="text-sm font-medium text-foreground">{window.valueLabel}</div>
+                  ) : null}
+                </div>
+                {detail ? (
+                  <div className="mt-2 text-sm text-muted-foreground">{detail}</div>
+                ) : null}
+              </div>
+            );
+          }
+
+          const width = Math.min(100, Math.max(0, window.usedPercent ?? 0));
+          return (
+            <div
+              key={window.label}
+              className="border border-border px-3.5 py-3"
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0">
+                  <div className="text-sm font-medium text-foreground">{window.label}</div>
+                  {detail ? (
+                    <div className="mt-1 text-xs text-muted-foreground">{detail}</div>
+                  ) : null}
+                </div>
+                {window.usedPercent != null ? (
+                  <div className="shrink-0 text-sm font-semibold tabular-nums text-foreground">
+                    {window.usedPercent}% used
+                  </div>
+                ) : null}
+              </div>
+
+              <div className="mt-3 h-2 overflow-hidden bg-muted">
+                <div
+                  className={cn("h-full transition-[width] duration-200", fillClass(window.usedPercent))}
+                  style={{ width: `${width}%` }}
+                />
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
--- a/ui/src/components/CodexSubscriptionPanel.tsx
+++ b/ui/src/components/CodexSubscriptionPanel.tsx
@@ -0,0 +1,157 @@
+import type { QuotaWindow } from "@paperclipai/shared";
+import { cn, quotaSourceDisplayName } from "@/lib/utils";
+
+interface CodexSubscriptionPanelProps {
+  windows: QuotaWindow[];
+  source?: string | null;
+  error?: string | null;
+}
+
+const WINDOW_PRIORITY = [
+  "5hlimit",
+  "weeklylimit",
+  "credits",
+] as const;
+
+function normalizeLabel(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function orderedWindows(windows: QuotaWindow[]): QuotaWindow[] {
+  return [...windows].sort((a, b) => {
+    const aBase = normalizeLabel(a.label).replace(/^gpt53codexspark/, "");
+    const bBase = normalizeLabel(b.label).replace(/^gpt53codexspark/, "");
+    const aIndex = WINDOW_PRIORITY.indexOf(aBase as (typeof WINDOW_PRIORITY)[number]);
+    const bIndex = WINDOW_PRIORITY.indexOf(bBase as (typeof WINDOW_PRIORITY)[number]);
+    return (aIndex === -1 ? WINDOW_PRIORITY.length : aIndex) - (bIndex === -1 ? WINDOW_PRIORITY.length : bIndex);
+  });
+}
+
+function detailText(window: QuotaWindow): string | null {
+  if (typeof window.detail === "string" && window.detail.trim().length > 0) return window.detail.trim();
+  if (!window.resetsAt) return null;
+  const formatted = new Date(window.resetsAt).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    timeZoneName: "short",
+  });
+  return `Resets ${formatted}`;
+}
+
+function fillClass(usedPercent: number | null): string {
+  if (usedPercent == null) return "bg-zinc-700";
+  if (usedPercent >= 90) return "bg-red-400";
+  if (usedPercent >= 70) return "bg-amber-400";
+  return "bg-primary/70";
+}
+
+function isModelSpecific(label: string): boolean {
+  const normalized = normalizeLabel(label);
+  return normalized.includes("gpt53codexspark") || normalized.includes("gpt5");
+}
+
+export function CodexSubscriptionPanel({
+  windows,
+  source = null,
+  error = null,
+}: CodexSubscriptionPanelProps) {
+  const ordered = orderedWindows(windows);
+  const accountWindows = ordered.filter((window) => !isModelSpecific(window.label));
+  const modelWindows = ordered.filter((window) => isModelSpecific(window.label));
+
+  return (
+    <div className="border border-border px-4 py-4">
+      <div className="flex items-start justify-between gap-3 border-b border-border pb-3">
+        <div className="min-w-0">
+          <div className="text-[11px] font-semibold uppercase tracking-[0.2em] text-muted-foreground">
+            Codex subscription
+          </div>
+          <div className="mt-1 text-sm text-muted-foreground">
+            Live Codex quota windows.
+          </div>
+        </div>
+        {source ? (
+          <span className="shrink-0 border border-border px-2.5 py-1 text-[10px] font-semibold uppercase tracking-[0.16em] text-muted-foreground">
+            {quotaSourceDisplayName(source)}
+          </span>
+        ) : null}
+      </div>
+
+      {error ? (
+        <div className="mt-4 border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+          {error}
+        </div>
+      ) : null}
+
+      <div className="mt-4 space-y-5">
+        <div className="space-y-3">
+          <div className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+            Account windows
+          </div>
+          <div className="space-y-3">
+            {accountWindows.map((window) => (
+              <QuotaWindowRow key={window.label} window={window} />
+            ))}
+          </div>
+        </div>
+
+        {modelWindows.length > 0 ? (
+          <div className="space-y-3">
+            <div className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+              Model windows
+            </div>
+            <div className="space-y-3">
+              {modelWindows.map((window) => (
+                <QuotaWindowRow key={window.label} window={window} />
+              ))}
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function QuotaWindowRow({ window }: { window: QuotaWindow }) {
+  const detail = detailText(window);
+  if (window.usedPercent == null) {
+    return (
+      <div className="border border-border px-3.5 py-3">
+        <div className="flex items-center justify-between gap-3">
+          <div className="text-sm font-medium text-foreground">{window.label}</div>
+          {window.valueLabel ? (
+            <div className="text-sm font-semibold tabular-nums text-foreground">{window.valueLabel}</div>
+          ) : null}
+        </div>
+        {detail ? (
+          <div className="mt-2 text-xs text-muted-foreground">{detail}</div>
+        ) : null}
+      </div>
+    );
+  }
+
+  return (
+    <div className="border border-border px-3.5 py-3">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="text-sm font-medium text-foreground">{window.label}</div>
+          {detail ? (
+            <div className="mt-1 text-xs text-muted-foreground">{detail}</div>
+          ) : null}
+        </div>
+        <div className="shrink-0 text-sm font-semibold tabular-nums text-foreground">
+          {window.usedPercent}% used
+        </div>
+      </div>
+
+      <div className="mt-3 h-2 overflow-hidden bg-muted">
+        <div
+          className={cn("h-full transition-[width] duration-200", fillClass(window.usedPercent))}
+          style={{ width: `${Math.max(0, Math.min(100, window.usedPercent))}%` }}
+        />
+      </div>
+    </div>
+  );
+}
--- a/ui/src/components/FinanceBillerCard.tsx
+++ b/ui/src/components/FinanceBillerCard.tsx
@@ -0,0 +1,44 @@
+import type { FinanceByBiller } from "@paperclipai/shared";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { formatCents, providerDisplayName } from "@/lib/utils";
+
+interface FinanceBillerCardProps {
+  row: FinanceByBiller;
+}
+
+export function FinanceBillerCard({ row }: FinanceBillerCardProps) {
+  return (
+    <Card>
+      <CardHeader className="px-4 pt-4 pb-1">
+        <div className="flex items-start justify-between gap-3">
+          <div>
+            <CardTitle className="text-base">{providerDisplayName(row.biller)}</CardTitle>
+            <CardDescription className="mt-1 text-xs">
+              {row.eventCount} event{row.eventCount === 1 ? "" : "s"} across {row.kindCount} kind{row.kindCount === 1 ? "" : "s"}
+            </CardDescription>
+          </div>
+          <div className="text-right">
+            <div className="text-lg font-semibold tabular-nums">{formatCents(row.netCents)}</div>
+            <div className="text-[11px] uppercase tracking-[0.16em] text-muted-foreground">net</div>
+          </div>
+        </div>
+      </CardHeader>
+      <CardContent className="space-y-3 px-4 pb-4 pt-3">
+        <div className="grid gap-2 text-sm sm:grid-cols-3">
+          <div className="border border-border p-3">
+            <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground">debits</div>
+            <div className="mt-1 font-medium tabular-nums">{formatCents(row.debitCents)}</div>
+          </div>
+          <div className="border border-border p-3">
+            <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground">credits</div>
+            <div className="mt-1 font-medium tabular-nums">{formatCents(row.creditCents)}</div>
+          </div>
+          <div className="border border-border p-3">
+            <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground">estimated</div>
+            <div className="mt-1 font-medium tabular-nums">{formatCents(row.estimatedDebitCents)}</div>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/FinanceKindCard.tsx
+++ b/ui/src/components/FinanceKindCard.tsx
@@ -0,0 +1,43 @@
+import type { FinanceByKind } from "@paperclipai/shared";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { financeEventKindDisplayName, formatCents } from "@/lib/utils";
+
+interface FinanceKindCardProps {
+  rows: FinanceByKind[];
+}
+
+export function FinanceKindCard({ rows }: FinanceKindCardProps) {
+  return (
+    <Card>
+      <CardHeader className="px-4 pt-4 pb-1">
+        <CardTitle className="text-base">Financial event mix</CardTitle>
+        <CardDescription>Account-level charges grouped by event kind.</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-2 px-4 pb-4 pt-3">
+        {rows.length === 0 ? (
+          <p className="text-sm text-muted-foreground">No finance events in this period.</p>
+        ) : (
+          rows.map((row) => (
+            <div
+              key={row.eventKind}
+              className="flex items-center justify-between gap-3 border border-border px-3 py-2"
+            >
+              <div className="min-w-0">
+                <div className="truncate text-sm font-medium">{financeEventKindDisplayName(row.eventKind)}</div>
+                <div className="text-xs text-muted-foreground">
+                  {row.eventCount} event{row.eventCount === 1 ? "" : "s"} · {row.billerCount} biller{row.billerCount === 1 ? "" : "s"}
+                </div>
+              </div>
+              <div className="text-right tabular-nums">
+                <div className="text-sm font-medium">{formatCents(row.netCents)}</div>
+                <div className="text-xs text-muted-foreground">
+                  {formatCents(row.debitCents)} debits
+                </div>
+              </div>
+            </div>
+          ))
+        )}
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/FinanceTimelineCard.tsx
+++ b/ui/src/components/FinanceTimelineCard.tsx
@@ -0,0 +1,71 @@
+import type { FinanceEvent } from "@paperclipai/shared";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  financeDirectionDisplayName,
+  financeEventKindDisplayName,
+  formatCents,
+  formatDateTime,
+  providerDisplayName,
+} from "@/lib/utils";
+
+interface FinanceTimelineCardProps {
+  rows: FinanceEvent[];
+  emptyMessage?: string;
+}
+
+export function FinanceTimelineCard({
+  rows,
+  emptyMessage = "No financial events in this period.",
+}: FinanceTimelineCardProps) {
+  return (
+    <Card>
+      <CardHeader className="px-4 pt-4 pb-1">
+        <CardTitle className="text-base">Recent financial events</CardTitle>
+        <CardDescription>Top-ups, fees, credits, commitments, and other non-request charges.</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-3 px-4 pb-4 pt-3">
+        {rows.length === 0 ? (
+          <p className="text-sm text-muted-foreground">{emptyMessage}</p>
+        ) : (
+          rows.map((row) => (
+            <div
+              key={row.id}
+              className="border border-border p-3"
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0 space-y-2">
+                  <div className="flex flex-wrap items-center gap-2">
+                    <Badge variant="secondary">{financeEventKindDisplayName(row.eventKind)}</Badge>
+                    <Badge variant={row.direction === "credit" ? "outline" : "secondary"}>
+                      {financeDirectionDisplayName(row.direction)}
+                    </Badge>
+                    <span className="text-xs text-muted-foreground">{formatDateTime(row.occurredAt)}</span>
+                  </div>
+                  <div className="text-sm font-medium">
+                    {providerDisplayName(row.biller)}
+                    {row.provider ? ` -> ${providerDisplayName(row.provider)}` : ""}
+                    {row.model ? <span className="ml-1 font-mono text-xs text-muted-foreground">{row.model}</span> : null}
+                  </div>
+                  {(row.description || row.externalInvoiceId || row.region || row.pricingTier) && (
+                    <div className="space-y-1 text-xs text-muted-foreground">
+                      {row.description ? <div>{row.description}</div> : null}
+                      {row.externalInvoiceId ? <div>invoice {row.externalInvoiceId}</div> : null}
+                      {row.region ? <div>region {row.region}</div> : null}
+                      {row.pricingTier ? <div>tier {row.pricingTier}</div> : null}
+                    </div>
+                  )}
+                </div>
+                <div className="text-right tabular-nums">
+                  <div className="text-sm font-semibold">{formatCents(row.amountCents)}</div>
+                  <div className="text-xs text-muted-foreground">{row.currency}</div>
+                  {row.estimated ? <div className="text-[11px] uppercase tracking-[0.12em] text-amber-600">estimated</div> : null}
+                </div>
+              </div>
+            </div>
+          ))
+        )}
+      </CardContent>
+    </Card>
+  );
+}
--- a/ui/src/components/ProviderQuotaCard.tsx
+++ b/ui/src/components/ProviderQuotaCard.tsx
@@ -1,8 +1,17 @@
 import { useMemo } from "react";
 import type { CostByProviderModel, CostWindowSpendRow, QuotaWindow } from "@paperclipai/shared";
 import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { Skeleton } from "@/components/ui/skeleton";
 import { QuotaBar } from "./QuotaBar";
-import { formatCents, formatTokens, providerDisplayName } from "@/lib/utils";
+import { ClaudeSubscriptionPanel } from "./ClaudeSubscriptionPanel";
+import { CodexSubscriptionPanel } from "./CodexSubscriptionPanel";
+import {
+  billingTypeDisplayName,
+  formatCents,
+  formatTokens,
+  providerDisplayName,
+  quotaSourceDisplayName,
+} from "@/lib/utils";

 // ordered display labels for rolling-window rows
 const ROLLING_WINDOWS = ["5h", "24h", "7d"] as const;
@@ -21,6 +30,9 @@ interface ProviderQuotaCardProps {
  showDeficitNotch: boolean;
  /** live subscription quota windows from the provider's own api */
  quotaWindows?: QuotaWindow[];
+  quotaError?: string | null;
+  quotaSource?: string | null;
+  quotaLoading?: boolean;
 }

 export function ProviderQuotaCard({
@@ -32,6 +44,9 @@ export function ProviderQuotaCard({
  windowRows,
  showDeficitNotch,
  quotaWindows = [],
+  quotaError = null,
+  quotaSource = null,
+  quotaLoading = false,
 }: ProviderQuotaCardProps) {
  // single-pass aggregation over rows — memoized so the 8 derived values are not
  // recomputed on every parent render tick (providers tab polls every 30s, and each
@@ -108,6 +123,11 @@ export function ProviderQuotaCard({
    () => Math.max(...windowRows.map((r) => r.costCents), 0),
    [windowRows],
  );
+  const isClaudeQuotaPanel = provider === "anthropic";
+  const isCodexQuotaPanel = provider === "openai" && quotaSource?.startsWith("codex-");
+  const supportsSubscriptionQuota = provider === "anthropic" || provider === "openai";
+  const showSubscriptionQuotaSection =
+    supportsSubscriptionQuota && (quotaLoading || quotaWindows.length > 0 || quotaError != null);

  return (
    <Card>
@@ -183,7 +203,7 @@ export function ProviderQuotaCard({
                        </span>
                        <span className="font-medium tabular-nums">{formatCents(cents)}</span>
                      </div>
-                      <div className="h-1.5 w-full border border-border overflow-hidden">
+                      <div className="h-2 w-full border border-border overflow-hidden">
                        <div
                          className="h-full bg-primary/60 transition-[width] duration-150"
                          style={{ width: `${barPct}%` }}
@@ -197,56 +217,6 @@ export function ProviderQuotaCard({
          </>
        )}

-        {/* subscription quota windows from provider api — shown when data is available */}
-        {quotaWindows.length > 0 && (
-          <>
-            <div className="border-t border-border" />
-            <div className="space-y-2">
-              <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
-                Subscription quota
-              </p>
-              <div className="space-y-2.5">
-                {quotaWindows.map((qw) => {
-                  const fillColor =
-                    qw.usedPercent == null
-                      ? null
-                      : qw.usedPercent >= 90
-                        ? "bg-red-400"
-                        : qw.usedPercent >= 70
-                          ? "bg-yellow-400"
-                          : "bg-green-400";
-                  return (
-                    <div key={qw.label} className="space-y-1">
-                      <div className="flex items-center justify-between gap-2 text-xs">
-                        <span className="font-mono text-muted-foreground shrink-0">{qw.label}</span>
-                        <span className="flex-1" />
-                        {qw.valueLabel != null ? (
-                          <span className="font-medium tabular-nums">{qw.valueLabel}</span>
-                        ) : qw.usedPercent != null ? (
-                          <span className="font-medium tabular-nums">{qw.usedPercent}% used</span>
-                        ) : null}
-                      </div>
-                      {qw.usedPercent != null && fillColor != null && (
-                        <div className="h-1.5 w-full border border-border overflow-hidden">
-                          <div
-                            className={`h-full transition-[width] duration-150 ${fillColor}`}
-                            style={{ width: `${qw.usedPercent}%` }}
-                          />
-                        </div>
-                      )}
-                      {qw.resetsAt && (
-                        <p className="text-xs text-muted-foreground">
-                          resets {new Date(qw.resetsAt).toLocaleDateString(undefined, { month: "short", day: "numeric" })}
-                        </p>
-                      )}
-                    </div>
-                  );
-                })}
-              </div>
-            </div>
-          </>
-        )}
-
        {/* subscription usage — shown when any subscription-billed runs exist */}
        {totalSubRuns > 0 && (
          <>
@@ -258,6 +228,12 @@ export function ProviderQuotaCard({
              <p className="text-xs text-muted-foreground">
                <span className="font-mono text-foreground">{totalSubRuns}</span> runs
                {" · "}
+                {totalSubTokens > 0 && (
+                  <>
+                    <span className="font-mono text-foreground">{formatTokens(totalSubTokens)}</span> total
+                    {" · "}
+                  </>
+                )}
                <span className="font-mono text-foreground">{formatTokens(totalSubInputTokens)}</span> in
                {" · "}
                <span className="font-mono text-foreground">{formatTokens(totalSubOutputTokens)}</span> out
@@ -292,9 +268,14 @@ export function ProviderQuotaCard({
                  <div key={`${row.provider}:${row.model}`} className="space-y-1.5">
                    {/* model name and cost */}
                    <div className="flex items-center justify-between gap-2">
-                      <span className="text-xs text-muted-foreground truncate font-mono">
-                        {row.model}
-                      </span>
+                      <div className="min-w-0">
+                        <span className="text-xs text-muted-foreground truncate font-mono block">
+                          {row.model}
+                        </span>
+                        <span className="text-[11px] text-muted-foreground truncate block">
+                          {providerDisplayName(row.biller)} · {billingTypeDisplayName(row.billingType)}
+                        </span>
+                      </div>
                      <div className="flex items-center gap-3 shrink-0 tabular-nums text-xs">
                        <span className="text-muted-foreground">
                          {formatTokens(rowTokens)} tok
@@ -303,7 +284,7 @@ export function ProviderQuotaCard({
                      </div>
                    </div>
                    {/* token share bar */}
-                    <div className="relative h-1.5 w-full border border-border overflow-hidden">
+                    <div className="relative h-2 w-full border border-border overflow-hidden">
                      <div
                        className="absolute inset-y-0 left-0 bg-primary/60 transition-[width] duration-150"
                        style={{ width: `${tokenPct}%` }}
@@ -322,7 +303,114 @@ export function ProviderQuotaCard({
            </div>
          </>
        )}
+
+        {/* subscription quota windows from provider api — shown when data is available */}
+        {showSubscriptionQuotaSection && (
+          <>
+            <div className="border-t border-border" />
+            <div className="space-y-2">
+              <div className="flex items-center justify-between gap-3">
+                <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+                  Subscription quota
+                </p>
+                {quotaSource && !isClaudeQuotaPanel && !isCodexQuotaPanel ? (
+                  <span className="text-[10px] uppercase tracking-[0.16em] text-muted-foreground">
+                    {quotaSourceDisplayName(quotaSource)}
+                  </span>
+                ) : null}
+              </div>
+              {quotaLoading ? (
+                <QuotaPanelSkeleton />
+              ) : isClaudeQuotaPanel ? (
+                <ClaudeSubscriptionPanel windows={quotaWindows} source={quotaSource} error={quotaError} />
+              ) : isCodexQuotaPanel ? (
+                <CodexSubscriptionPanel windows={quotaWindows} source={quotaSource} error={quotaError} />
+              ) : (
+                <>
+                  {quotaError ? (
+                    <p className="text-xs text-destructive">
+                      {quotaError}
+                    </p>
+                  ) : null}
+                  <div className="space-y-2.5">
+                    {quotaWindows.map((qw) => {
+                      const fillColor =
+                        qw.usedPercent == null
+                          ? null
+                          : qw.usedPercent >= 90
+                            ? "bg-red-400"
+                            : qw.usedPercent >= 70
+                              ? "bg-yellow-400"
+                              : "bg-green-400";
+                      return (
+                        <div key={qw.label} className="space-y-1">
+                          <div className="flex items-center justify-between gap-2 text-xs">
+                            <span className="font-mono text-muted-foreground shrink-0">{qw.label}</span>
+                            <span className="flex-1" />
+                            {qw.valueLabel != null ? (
+                              <span className="font-medium tabular-nums">{qw.valueLabel}</span>
+                            ) : qw.usedPercent != null ? (
+                              <span className="font-medium tabular-nums">{qw.usedPercent}% used</span>
+                            ) : null}
+                          </div>
+                          {qw.usedPercent != null && fillColor != null && (
+                            <div className="h-2 w-full border border-border overflow-hidden">
+                              <div
+                                className={`h-full transition-[width] duration-150 ${fillColor}`}
+                                style={{ width: `${qw.usedPercent}%` }}
+                              />
+                            </div>
+                          )}
+                          {qw.detail ? (
+                            <p className="text-xs text-muted-foreground">
+                              {qw.detail}
+                            </p>
+                          ) : qw.resetsAt ? (
+                            <p className="text-xs text-muted-foreground">
+                              resets {new Date(qw.resetsAt).toLocaleDateString(undefined, { month: "short", day: "numeric" })}
+                            </p>
+                          ) : null}
+                        </div>
+                      );
+                    })}
+                  </div>
+                </>
+              )}
+            </div>
+          </>
+        )}
      </CardContent>
    </Card>
  );
 }
+
+function QuotaPanelSkeleton() {
+  return (
+    <div className="border border-border px-4 py-4">
+      <div className="flex items-start justify-between gap-3 border-b border-border pb-3">
+        <div className="min-w-0 space-y-2">
+          <Skeleton className="h-3 w-36" />
+          <Skeleton className="h-4 w-64 max-w-full" />
+        </div>
+        <Skeleton className="h-7 w-28" />
+      </div>
+      <div className="mt-4 space-y-3">
+        {Array.from({ length: 3 }).map((_, index) => (
+          <div
+            key={index}
+            className="border border-border px-3.5 py-3"
+          >
+            <div className="flex items-start justify-between gap-3">
+              <div className="min-w-0 space-y-2">
+                <Skeleton className="h-4 w-32" />
+                <Skeleton className="h-3 w-44 max-w-full" />
+              </div>
+              <Skeleton className="h-4 w-20" />
+            </div>
+            <Skeleton className="mt-3 h-2 w-full" />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
--- a/ui/src/lib/inbox.test.ts
+++ b/ui/src/lib/inbox.test.ts
@@ -164,6 +164,12 @@ const dashboard: DashboardSummary = {
    monthUtilizationPercent: 90,
  },
  pendingApprovals: 1,
+  budgets: {
+    activeIncidents: 0,
+    pendingApprovals: 0,
+    pausedAgents: 0,
+    pausedProjects: 0,
+  },
 };

 describe("inbox helpers", () => {
--- a/ui/src/lib/queryKeys.ts
+++ b/ui/src/lib/queryKeys.ts
@@ -43,6 +43,9 @@ export const queryKeys = {
    list: (companyId: string) => ["goals", companyId] as const,
    detail: (id: string) => ["goals", "detail", id] as const,
  },
+  budgets: {
+    overview: (companyId: string) => ["budgets", "overview", companyId] as const,
+  },
  approvals: {
    list: (companyId: string, status?: string) =>
      ["approvals", companyId, status] as const,
@@ -73,6 +76,16 @@ export const queryKeys = {
    ["costs", companyId, from, to] as const,
  usageByProvider: (companyId: string, from?: string, to?: string) =>
    ["usage-by-provider", companyId, from, to] as const,
+  usageByBiller: (companyId: string, from?: string, to?: string) =>
+    ["usage-by-biller", companyId, from, to] as const,
+  financeSummary: (companyId: string, from?: string, to?: string) =>
+    ["finance-summary", companyId, from, to] as const,
+  financeByBiller: (companyId: string, from?: string, to?: string) =>
+    ["finance-by-biller", companyId, from, to] as const,
+  financeByKind: (companyId: string, from?: string, to?: string) =>
+    ["finance-by-kind", companyId, from, to] as const,
+  financeEvents: (companyId: string, from?: string, to?: string, limit: number = 100) =>
+    ["finance-events", companyId, from, to, limit] as const,
  usageWindowSpend: (companyId: string) =>
    ["usage-window-spend", companyId] as const,
  usageQuotaWindows: (companyId: string) =>
--- a/ui/src/lib/utils.ts
+++ b/ui/src/lib/utils.ts
@@ -1,6 +1,7 @@
 import { type ClassValue, clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
 import { deriveAgentUrlKey, deriveProjectUrlKey } from "@paperclipai/shared";
+import type { BillingType, FinanceDirection, FinanceEventKind } from "@paperclipai/shared";

 export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
@@ -53,6 +54,8 @@ export function providerDisplayName(provider: string): string {
  const map: Record<string, string> = {
    anthropic: "Anthropic",
    openai: "OpenAI",
+    openrouter: "OpenRouter",
+    chatgpt: "ChatGPT",
    google: "Google",
    cursor: "Cursor",
    jetbrains: "JetBrains AI",
@@ -60,6 +63,84 @@ export function providerDisplayName(provider: string): string {
  return map[provider.toLowerCase()] ?? provider;
 }

+export function billingTypeDisplayName(billingType: BillingType): string {
+  const map: Record<BillingType, string> = {
+    metered_api: "Metered API",
+    subscription_included: "Subscription",
+    subscription_overage: "Subscription overage",
+    credits: "Credits",
+    fixed: "Fixed",
+    unknown: "Unknown",
+  };
+  return map[billingType];
+}
+
+export function quotaSourceDisplayName(source: string): string {
+  const map: Record<string, string> = {
+    "anthropic-oauth": "Anthropic OAuth",
+    "claude-cli": "Claude CLI",
+    "codex-rpc": "Codex app server",
+    "codex-wham": "ChatGPT WHAM",
+  };
+  return map[source] ?? source;
+}
+
+function coerceBillingType(value: unknown): BillingType | null {
+  if (
+    value === "metered_api" ||
+    value === "subscription_included" ||
+    value === "subscription_overage" ||
+    value === "credits" ||
+    value === "fixed" ||
+    value === "unknown"
+  ) {
+    return value;
+  }
+  return null;
+}
+
+function readRunCostUsd(payload: Record<string, unknown> | null): number {
+  if (!payload) return 0;
+  for (const key of ["costUsd", "cost_usd", "total_cost_usd"] as const) {
+    const value = payload[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return 0;
+}
+
+export function visibleRunCostUsd(
+  usage: Record<string, unknown> | null,
+  result: Record<string, unknown> | null = null,
+): number {
+  const billingType = coerceBillingType(usage?.billingType) ?? coerceBillingType(result?.billingType);
+  if (billingType === "subscription_included") return 0;
+  return readRunCostUsd(usage) || readRunCostUsd(result);
+}
+
+export function financeEventKindDisplayName(eventKind: FinanceEventKind): string {
+  const map: Record<FinanceEventKind, string> = {
+    inference_charge: "Inference charge",
+    platform_fee: "Platform fee",
+    credit_purchase: "Credit purchase",
+    credit_refund: "Credit refund",
+    credit_expiry: "Credit expiry",
+    byok_fee: "BYOK fee",
+    gateway_overhead: "Gateway overhead",
+    log_storage_charge: "Log storage",
+    logpush_charge: "Logpush",
+    provisioned_capacity_charge: "Provisioned capacity",
+    training_charge: "Training",
+    custom_model_import_charge: "Custom model import",
+    custom_model_storage_charge: "Custom model storage",
+    manual_adjustment: "Manual adjustment",
+  };
+  return map[eventKind];
+}
+
+export function financeDirectionDisplayName(direction: FinanceDirection): string {
+  return direction === "credit" ? "Credit" : "Debit";
+}
+
 /** Build an issue URL using the human-readable identifier when available. */
 export function issueUrl(issue: { id: string; identifier?: string | null }): string {
  return `/issues/${issue.identifier ?? issue.id}`;
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useState, useRef } from "react";
 import { useParams, useNavigate, Link, Navigate, useBeforeUnload } from "@/lib/router";
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
 import { agentsApi, type AgentKey, type ClaudeLoginResult } from "../api/agents";
+import { budgetsApi } from "../api/budgets";
 import { heartbeatsApi } from "../api/heartbeats";
 import { ApiError } from "../api/client";
 import { ChartCard, RunActivityChart, PriorityChart, IssueStatusChart, SuccessRateChart } from "../components/ActivityCharts";
@@ -24,8 +25,9 @@ import { CopyText } from "../components/CopyText";
 import { EntityRow } from "../components/EntityRow";
 import { Identity } from "../components/Identity";
 import { PageSkeleton } from "../components/PageSkeleton";
+import { BudgetPolicyCard } from "../components/BudgetPolicyCard";
 import { ScrollToBottom } from "../components/ScrollToBottom";
-import { formatCents, formatDate, relativeTime, formatTokens } from "../lib/utils";
+import { formatCents, formatDate, relativeTime, formatTokens, visibleRunCostUsd } from "../lib/utils";
 import { cn } from "../lib/utils";
 import { Button } from "@/components/ui/button";
 import { Tabs } from "@/components/ui/tabs";
@@ -58,7 +60,15 @@ import {
 import { Input } from "@/components/ui/input";
 import { AgentIcon, AgentIconPicker } from "../components/AgentIconPicker";
 import { RunTranscriptView, type TranscriptMode } from "../components/transcript/RunTranscriptView";
-import { isUuidLike, type Agent, type HeartbeatRun, type HeartbeatRunEvent, type AgentRuntimeState, type LiveEvent } from "@paperclipai/shared";
+import {
+  isUuidLike,
+  type Agent,
+  type BudgetPolicySummary,
+  type HeartbeatRun,
+  type HeartbeatRunEvent,
+  type AgentRuntimeState,
+  type LiveEvent,
+} from "@paperclipai/shared";
 import { redactHomePathUserSegments, redactHomePathUserSegmentsInValue } from "@paperclipai/adapter-utils";
 import { agentRouteRef } from "../lib/utils";

@@ -204,8 +214,7 @@ function runMetrics(run: HeartbeatRun) {
    "cache_read_input_tokens",
  );
  const cost =
-    usageNumber(usage, "costUsd", "cost_usd", "total_cost_usd") ||
-    usageNumber(result, "total_cost_usd", "cost_usd", "costUsd");
+    visibleRunCostUsd(usage, result);
  return {
    input,
    output,
@@ -294,11 +303,50 @@ export function AgentDetail() {
    enabled: !!resolvedCompanyId,
  });

+  const { data: budgetOverview } = useQuery({
+    queryKey: queryKeys.budgets.overview(resolvedCompanyId ?? "__none__"),
+    queryFn: () => budgetsApi.overview(resolvedCompanyId!),
+    enabled: !!resolvedCompanyId,
+    refetchInterval: 30_000,
+    staleTime: 5_000,
+  });
+
  const assignedIssues = (allIssues ?? [])
    .filter((i) => i.assigneeAgentId === agent?.id)
    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
  const reportsToAgent = (allAgents ?? []).find((a) => a.id === agent?.reportsTo);
  const directReports = (allAgents ?? []).filter((a) => a.reportsTo === agent?.id && a.status !== "terminated");
+  const agentBudgetSummary = useMemo(() => {
+    const matched = budgetOverview?.policies.find(
+      (policy) => policy.scopeType === "agent" && policy.scopeId === (agent?.id ?? routeAgentRef),
+    );
+    if (matched) return matched;
+    const budgetMonthlyCents = agent?.budgetMonthlyCents ?? 0;
+    const spentMonthlyCents = agent?.spentMonthlyCents ?? 0;
+    return {
+      policyId: "",
+      companyId: resolvedCompanyId ?? "",
+      scopeType: "agent",
+      scopeId: agent?.id ?? routeAgentRef,
+      scopeName: agent?.name ?? "Agent",
+      metric: "billed_cents",
+      windowKind: "calendar_month_utc",
+      amount: budgetMonthlyCents,
+      observedAmount: spentMonthlyCents,
+      remainingAmount: Math.max(0, budgetMonthlyCents - spentMonthlyCents),
+      utilizationPercent:
+        budgetMonthlyCents > 0 ? Number(((spentMonthlyCents / budgetMonthlyCents) * 100).toFixed(2)) : 0,
+      warnPercent: 80,
+      hardStopEnabled: true,
+      notifyEnabled: true,
+      isActive: budgetMonthlyCents > 0,
+      status: budgetMonthlyCents > 0 && spentMonthlyCents >= budgetMonthlyCents ? "hard_stop" : "ok",
+      paused: agent?.status === "paused",
+      pauseReason: agent?.pauseReason ?? null,
+      windowStart: new Date(),
+      windowEnd: new Date(),
+    } satisfies BudgetPolicySummary;
+  }, [agent, budgetOverview?.policies, resolvedCompanyId, routeAgentRef]);
  const mobileLiveRun = useMemo(
    () => (heartbeats ?? []).find((r) => r.status === "running" || r.status === "queued") ?? null,
    [heartbeats],
@@ -360,6 +408,24 @@ export function AgentDetail() {
    },
  });

+  const budgetMutation = useMutation({
+    mutationFn: (amount: number) =>
+      budgetsApi.upsertPolicy(resolvedCompanyId!, {
+        scopeType: "agent",
+        scopeId: agent?.id ?? routeAgentRef,
+        amount,
+        windowKind: "calendar_month_utc",
+      }),
+    onSuccess: () => {
+      if (!resolvedCompanyId) return;
+      queryClient.invalidateQueries({ queryKey: queryKeys.budgets.overview(resolvedCompanyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(routeAgentRef) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agentLookupRef) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(resolvedCompanyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.dashboard(resolvedCompanyId) });
+    },
+  });
+
  const updateIcon = useMutation({
    mutationFn: (icon: string) => agentsApi.update(agentLookupRef, { icon }, resolvedCompanyId ?? undefined),
    onSuccess: () => {
@@ -579,6 +645,15 @@ export function AgentDetail() {
        </Tabs>
      )}

+      {!urlRunId && resolvedCompanyId ? (
+        <BudgetPolicyCard
+          summary={agentBudgetSummary}
+          isSaving={budgetMutation.isPending}
+          compact
+          onSave={(amount) => budgetMutation.mutate(amount)}
+        />
+      ) : null}
+
      {actionError && <p className="text-sm text-destructive">{actionError}</p>}
      {isPendingApproval && (
        <p className="text-sm text-amber-500">
@@ -849,8 +924,8 @@ function CostsSection({
 }) {
  const runsWithCost = runs
    .filter((r) => {
-      const u = r.usageJson as Record<string, unknown> | null;
-      return u && (u.cost_usd || u.total_cost_usd || u.input_tokens);
+      const metrics = runMetrics(r);
+      return metrics.cost > 0 || metrics.input > 0 || metrics.output > 0 || metrics.cached > 0;
    })
    .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());

@@ -892,16 +967,16 @@ function CostsSection({
            </thead>
            <tbody>
              {runsWithCost.slice(0, 10).map((run) => {
-                const u = run.usageJson as Record<string, unknown>;
+                const metrics = runMetrics(run);
                return (
                  <tr key={run.id} className="border-b border-border last:border-b-0">
                    <td className="px-3 py-2">{formatDate(run.createdAt)}</td>
                    <td className="px-3 py-2 font-mono">{run.id.slice(0, 8)}</td>
-                    <td className="px-3 py-2 text-right tabular-nums">{formatTokens(Number(u.input_tokens ?? 0))}</td>
-                    <td className="px-3 py-2 text-right tabular-nums">{formatTokens(Number(u.output_tokens ?? 0))}</td>
+                    <td className="px-3 py-2 text-right tabular-nums">{formatTokens(metrics.input)}</td>
+                    <td className="px-3 py-2 text-right tabular-nums">{formatTokens(metrics.output)}</td>
                    <td className="px-3 py-2 text-right tabular-nums">
-                      {(u.cost_usd || u.total_cost_usd)
-                        ? `$${Number(u.cost_usd ?? u.total_cost_usd ?? 0).toFixed(4)}`
+                      {metrics.cost > 0
+                        ? `$${metrics.cost.toFixed(4)}`
                        : "-"
                      }
                    </td>
--- a/ui/src/pages/ApprovalDetail.tsx
+++ b/ui/src/pages/ApprovalDetail.tsx
@@ -147,6 +147,7 @@ export function ApprovalDetail() {
  const payload = approval.payload as Record<string, unknown>;
  const linkedAgentId = typeof payload.agentId === "string" ? payload.agentId : null;
  const isActionable = approval.status === "pending" || approval.status === "revision_requested";
+  const isBudgetApproval = approval.type === "budget_override_required";
  const TypeIcon = typeIcon[approval.type] ?? defaultTypeIcon;
  const showApprovedBanner = searchParams.get("resolved") === "approved" && approval.status === "approved";
  const primaryLinkedIssue = linkedIssues?.[0] ?? null;
@@ -260,7 +261,7 @@ export function ApprovalDetail() {
          </div>
        )}
        <div className="flex flex-wrap items-center gap-2">
-          {isActionable && (
+          {isActionable && !isBudgetApproval && (
            <>
              <Button
                size="sm"
@@ -280,6 +281,11 @@ export function ApprovalDetail() {
              </Button>
            </>
          )}
+          {isBudgetApproval && approval.status === "pending" && (
+            <p className="text-sm text-muted-foreground">
+              Resolve this budget stop from the budget controls on <Link to="/costs" className="underline underline-offset-2">/costs</Link>.
+            </p>
+          )}
          {approval.status === "pending" && (
            <Button
              size="sm"
--- a/ui/src/pages/Costs.tsx
+++ b/ui/src/pages/Costs.tsx
--- a/ui/src/pages/Dashboard.tsx
+++ b/ui/src/pages/Dashboard.tsx
@@ -19,7 +19,7 @@ import { ActivityRow } from "../components/ActivityRow";
 import { Identity } from "../components/Identity";
 import { timeAgo } from "../lib/timeAgo";
 import { cn, formatCents } from "../lib/utils";
-import { Bot, CircleDot, DollarSign, ShieldCheck, LayoutDashboard } from "lucide-react";
+import { Bot, CircleDot, DollarSign, ShieldCheck, LayoutDashboard, PauseCircle } from "lucide-react";
 import { ActiveAgentsPanel } from "../components/ActiveAgentsPanel";
 import { ChartCard, RunActivityChart, PriorityChart, IssueStatusChart, SuccessRateChart } from "../components/ActivityCharts";
 import { PageSkeleton } from "../components/PageSkeleton";
@@ -210,6 +210,25 @@ export function Dashboard() {

      {data && (
        <>
+          {data.budgets.activeIncidents > 0 ? (
+            <div className="flex items-start justify-between gap-3 rounded-xl border border-red-500/20 bg-[linear-gradient(180deg,rgba(255,80,80,0.12),rgba(255,255,255,0.02))] px-4 py-3">
+              <div className="flex items-start gap-2.5">
+                <PauseCircle className="mt-0.5 h-4 w-4 shrink-0 text-red-300" />
+                <div>
+                  <p className="text-sm font-medium text-red-50">
+                    {data.budgets.activeIncidents} active budget incident{data.budgets.activeIncidents === 1 ? "" : "s"}
+                  </p>
+                  <p className="text-xs text-red-100/70">
+                    {data.budgets.pausedAgents} agents paused · {data.budgets.pausedProjects} projects paused · {data.budgets.pendingApprovals} pending budget approvals
+                  </p>
+                </div>
+              </div>
+              <Link to="/costs" className="text-sm underline underline-offset-2 text-red-100">
+                Open budgets
+              </Link>
+            </div>
+          ) : null}
+
          <div className="grid grid-cols-2 xl:grid-cols-4 gap-1 sm:gap-2">
            <MetricCard
              icon={Bot}
@@ -251,12 +270,14 @@ export function Dashboard() {
            />
            <MetricCard
              icon={ShieldCheck}
-              value={data.pendingApprovals}
+              value={data.pendingApprovals + data.budgets.pendingApprovals}
              label="Pending Approvals"
              to="/approvals"
              description={
                <span>
-                  Awaiting board review
+                  {data.budgets.pendingApprovals > 0
+                    ? `${data.budgets.pendingApprovals} budget overrides awaiting board review`
+                    : "Awaiting board review"}
                </span>
              }
            />
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -13,7 +13,7 @@ import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { queryKeys } from "../lib/queryKeys";
 import { readIssueDetailBreadcrumb } from "../lib/issueDetailBreadcrumb";
 import { useProjectOrder } from "../hooks/useProjectOrder";
-import { relativeTime, cn, formatTokens } from "../lib/utils";
+import { relativeTime, cn, formatTokens, visibleRunCostUsd } from "../lib/utils";
 import { InlineEditor } from "../components/InlineEditor";
 import { CommentThread } from "../components/CommentThread";
 import { IssueDocumentsSection } from "../components/IssueDocumentsSection";
@@ -417,9 +417,7 @@ export function IssueDetail() {
        "cached_input_tokens",
        "cache_read_input_tokens",
      );
-      const runCost =
-        usageNumber(usage, "costUsd", "cost_usd", "total_cost_usd") ||
-        usageNumber(result, "total_cost_usd", "cost_usd", "costUsd");
+      const runCost = visibleRunCostUsd(usage, result);
      if (runCost > 0) hasCost = true;
      if (runInput + runOutput + runCached > 0) hasTokens = true;
      input += runInput;
--- a/ui/src/pages/ProjectDetail.tsx
+++ b/ui/src/pages/ProjectDetail.tsx
@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useState, useRef } from "react";
 import { useParams, useNavigate, useLocation, Navigate } from "@/lib/router";
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { PROJECT_COLORS, isUuidLike } from "@paperclipai/shared";
+import { PROJECT_COLORS, isUuidLike, type BudgetPolicySummary } from "@paperclipai/shared";
+import { budgetsApi } from "../api/budgets";
 import { projectsApi } from "../api/projects";
 import { issuesApi } from "../api/issues";
 import { agentsApi } from "../api/agents";
@@ -14,6 +15,7 @@ import { queryKeys } from "../lib/queryKeys";
 import { ProjectProperties, type ProjectConfigFieldKey, type ProjectFieldSaveState } from "../components/ProjectProperties";
 import { InlineEditor } from "../components/InlineEditor";
 import { StatusBadge } from "../components/StatusBadge";
+import { BudgetPolicyCard } from "../components/BudgetPolicyCard";
 import { IssuesList } from "../components/IssuesList";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { PageTabBar } from "../components/PageTabBar";
@@ -296,6 +298,14 @@ export function ProjectDetail() {
    },
  });

+  const { data: budgetOverview } = useQuery({
+    queryKey: queryKeys.budgets.overview(resolvedCompanyId ?? "__none__"),
+    queryFn: () => budgetsApi.overview(resolvedCompanyId!),
+    enabled: !!resolvedCompanyId,
+    refetchInterval: 30_000,
+    staleTime: 5_000,
+  });
+
  useEffect(() => {
    setBreadcrumbs([
      { label: "Projects", href: "/projects" },
@@ -377,6 +387,53 @@ export function ProjectDetail() {
    }
  }, [invalidateProject, lookupCompanyId, projectLookupRef, resolvedCompanyId, scheduleFieldReset, setFieldState]);

+  const projectBudgetSummary = useMemo(() => {
+    const matched = budgetOverview?.policies.find(
+      (policy) => policy.scopeType === "project" && policy.scopeId === (project?.id ?? routeProjectRef),
+    );
+    if (matched) return matched;
+    return {
+      policyId: "",
+      companyId: resolvedCompanyId ?? "",
+      scopeType: "project",
+      scopeId: project?.id ?? routeProjectRef,
+      scopeName: project?.name ?? "Project",
+      metric: "billed_cents",
+      windowKind: "lifetime",
+      amount: 0,
+      observedAmount: 0,
+      remainingAmount: 0,
+      utilizationPercent: 0,
+      warnPercent: 80,
+      hardStopEnabled: true,
+      notifyEnabled: true,
+      isActive: false,
+      status: "ok",
+      paused: Boolean(project?.pausedAt),
+      pauseReason: project?.pauseReason ?? null,
+      windowStart: new Date(),
+      windowEnd: new Date(),
+    } satisfies BudgetPolicySummary;
+  }, [budgetOverview?.policies, project, resolvedCompanyId, routeProjectRef]);
+
+  const budgetMutation = useMutation({
+    mutationFn: (amount: number) =>
+      budgetsApi.upsertPolicy(resolvedCompanyId!, {
+        scopeType: "project",
+        scopeId: project?.id ?? routeProjectRef,
+        amount,
+        windowKind: "lifetime",
+      }),
+    onSuccess: () => {
+      if (!resolvedCompanyId) return;
+      queryClient.invalidateQueries({ queryKey: queryKeys.budgets.overview(resolvedCompanyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(routeProjectRef) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(projectLookupRef) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.list(resolvedCompanyId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.dashboard(resolvedCompanyId) });
+    },
+  });
+
  if (pluginTabFromSearch && !pluginDetailSlotsLoading && !activePluginTab) {
    return <Navigate to={`/projects/${canonicalProjectRef}/issues`} replace />;
  }
@@ -469,6 +526,15 @@ export function ProjectDetail() {
        />
      </Tabs>

+      {resolvedCompanyId ? (
+        <BudgetPolicyCard
+          summary={projectBudgetSummary}
+          compact
+          isSaving={budgetMutation.isPending}
+          onSave={(amount) => budgetMutation.mutate(amount)}
+        />
+      ) : null}
+
      {activeTab === "overview" && (
        <OverviewContent
          project={project}