Merge remote-tracking branch 'public-gh/master' into paperclip-subissues

* public-gh/master: Fix budget incident resolution edge cases Fix agent budget tab routing Fix budget auth and monthly spend rollups Harden budget enforcement and migration startup Add budget tabs and sidebar budget indicators feat(costs): add billing, quota, and budget control plane refactor(quota): move provider quota logic into adapter layer, add unit tests fix(costs): replace non-null map assertions with nullish coalescing, clarify weekData guard fix(costs): guard byProject against duplicate null keys, memoize ProviderQuotaCard row aggregations fix(costs): align byAgent run filter to startedAt, tighten providerTabItems memo deps, stabilize byProject row keys feat(costs): add agent model breakdown, harden date validation, sync CostByProject type, fix quota threshold and tab-gated queries fix(costs): harden company auth check, fix frozen date memo, hide empty quota rows fix(costs): guard routes, fix DST ranges, sync provider state, wire live updates feat(costs): consolidate /usage into /costs with Spend + Providers tabs feat(usage): add subscription quota windows per provider on /usage page address greptile review: per-provider deficit notch, startedAt filter, weekRange refresh, deduplicate providerDisplayName feat(ui): add resource and usage dashboard (/usage route) # Conflicts: # packages/db/src/migration-runtime.ts # packages/db/src/migrations/meta/0031_snapshot.json # packages/db/src/migrations/meta/_journal.json
2026-03-16 17:19:55 -05:00
parent 3d01217aef c578fb1575
commit bb7d1b2c71
112 changed files with 46441 additions and 2489 deletions
--- a/server/src/tests/budgets-service.test.ts
+++ b/server/src/tests/budgets-service.test.ts
@@ -0,0 +1,311 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { budgetService } from "../services/budgets.ts";
+
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/activity-log.js", () => ({
+  logActivity: mockLogActivity,
+}));
+
+type SelectResult = unknown[];
+
+function createDbStub(selectResults: SelectResult[]) {
+  const pendingSelects = [...selectResults];
+  const selectWhere = vi.fn(async () => pendingSelects.shift() ?? []);
+  const selectThen = vi.fn((resolve: (value: unknown[]) => unknown) => Promise.resolve(resolve(pendingSelects.shift() ?? [])));
+  const selectOrderBy = vi.fn(async () => pendingSelects.shift() ?? []);
+  const selectFrom = vi.fn(() => ({
+    where: selectWhere,
+    then: selectThen,
+    orderBy: selectOrderBy,
+  }));
+  const select = vi.fn(() => ({
+    from: selectFrom,
+  }));
+
+  const insertValues = vi.fn();
+  const insertReturning = vi.fn(async () => pendingInserts.shift() ?? []);
+  const insert = vi.fn(() => ({
+    values: insertValues.mockImplementation(() => ({
+      returning: insertReturning,
+    })),
+  }));
+
+  const updateSet = vi.fn();
+  const updateWhere = vi.fn(async () => pendingUpdates.shift() ?? []);
+  const update = vi.fn(() => ({
+    set: updateSet.mockImplementation(() => ({
+      where: updateWhere,
+    })),
+  }));
+
+  const pendingInserts: unknown[][] = [];
+  const pendingUpdates: unknown[][] = [];
+
+  return {
+    db: {
+      select,
+      insert,
+      update,
+    },
+    queueInsert: (rows: unknown[]) => {
+      pendingInserts.push(rows);
+    },
+    queueUpdate: (rows: unknown[] = []) => {
+      pendingUpdates.push(rows);
+    },
+    selectWhere,
+    insertValues,
+    updateSet,
+  };
+}
+
+describe("budgetService", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("creates a hard-stop incident and pauses an agent when spend exceeds a budget", async () => {
+    const policy = {
+      id: "policy-1",
+      companyId: "company-1",
+      scopeType: "agent",
+      scopeId: "agent-1",
+      metric: "billed_cents",
+      windowKind: "calendar_month_utc",
+      amount: 100,
+      warnPercent: 80,
+      hardStopEnabled: true,
+      notifyEnabled: false,
+      isActive: true,
+    };
+
+    const dbStub = createDbStub([
+      [policy],
+      [{ total: 150 }],
+      [],
+      [{
+        companyId: "company-1",
+        name: "Budget Agent",
+        status: "running",
+        pauseReason: null,
+      }],
+    ]);
+
+    dbStub.queueInsert([{
+      id: "approval-1",
+      companyId: "company-1",
+      status: "pending",
+    }]);
+    dbStub.queueInsert([{
+      id: "incident-1",
+      companyId: "company-1",
+      policyId: "policy-1",
+      approvalId: "approval-1",
+    }]);
+    dbStub.queueUpdate([]);
+    const cancelWorkForScope = vi.fn().mockResolvedValue(undefined);
+
+    const service = budgetService(dbStub.db as any, { cancelWorkForScope });
+    await service.evaluateCostEvent({
+      companyId: "company-1",
+      agentId: "agent-1",
+      projectId: null,
+    } as any);
+
+    expect(dbStub.insertValues).toHaveBeenCalledWith(
+      expect.objectContaining({
+        companyId: "company-1",
+        type: "budget_override_required",
+        status: "pending",
+      }),
+    );
+    expect(dbStub.insertValues).toHaveBeenCalledWith(
+      expect.objectContaining({
+        companyId: "company-1",
+        policyId: "policy-1",
+        thresholdType: "hard",
+        amountLimit: 100,
+        amountObserved: 150,
+        approvalId: "approval-1",
+      }),
+    );
+    expect(dbStub.updateSet).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: "paused",
+        pauseReason: "budget",
+        pausedAt: expect.any(Date),
+      }),
+    );
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        action: "budget.hard_threshold_crossed",
+        entityId: "incident-1",
+      }),
+    );
+    expect(cancelWorkForScope).toHaveBeenCalledWith({
+      companyId: "company-1",
+      scopeType: "agent",
+      scopeId: "agent-1",
+    });
+  });
+
+  it("blocks new work when an agent hard-stop remains exceeded even if the agent is not paused yet", async () => {
+    const agentPolicy = {
+      id: "policy-agent-1",
+      companyId: "company-1",
+      scopeType: "agent",
+      scopeId: "agent-1",
+      metric: "billed_cents",
+      windowKind: "calendar_month_utc",
+      amount: 100,
+      warnPercent: 80,
+      hardStopEnabled: true,
+      notifyEnabled: true,
+      isActive: true,
+    };
+
+    const dbStub = createDbStub([
+      [{
+        status: "running",
+        pauseReason: null,
+        companyId: "company-1",
+        name: "Budget Agent",
+      }],
+      [{
+        status: "active",
+        name: "Paperclip",
+      }],
+      [],
+      [agentPolicy],
+      [{ total: 120 }],
+    ]);
+
+    const service = budgetService(dbStub.db as any);
+    const block = await service.getInvocationBlock("company-1", "agent-1");
+
+    expect(block).toEqual({
+      scopeType: "agent",
+      scopeId: "agent-1",
+      scopeName: "Budget Agent",
+      reason: "Agent cannot start because its budget hard-stop is still exceeded.",
+    });
+  });
+
+  it("surfaces a budget-owned company pause distinctly from a manual pause", async () => {
+    const dbStub = createDbStub([
+      [{
+        status: "idle",
+        pauseReason: null,
+        companyId: "company-1",
+        name: "Budget Agent",
+      }],
+      [{
+        status: "paused",
+        pauseReason: "budget",
+        name: "Paperclip",
+      }],
+    ]);
+
+    const service = budgetService(dbStub.db as any);
+    const block = await service.getInvocationBlock("company-1", "agent-1");
+
+    expect(block).toEqual({
+      scopeType: "company",
+      scopeId: "company-1",
+      scopeName: "Paperclip",
+      reason: "Company is paused because its budget hard-stop was reached.",
+    });
+  });
+
+  it("uses live observed spend when raising a budget incident", async () => {
+    const dbStub = createDbStub([
+      [{
+        id: "incident-1",
+        companyId: "company-1",
+        policyId: "policy-1",
+        amountObserved: 120,
+        approvalId: "approval-1",
+      }],
+      [{
+        id: "policy-1",
+        companyId: "company-1",
+        scopeType: "company",
+        scopeId: "company-1",
+        metric: "billed_cents",
+        windowKind: "calendar_month_utc",
+      }],
+      [{ total: 150 }],
+    ]);
+
+    const service = budgetService(dbStub.db as any);
+
+    await expect(
+      service.resolveIncident(
+        "company-1",
+        "incident-1",
+        { action: "raise_budget_and_resume", amount: 140 },
+        "board-user",
+      ),
+    ).rejects.toThrow("New budget must exceed current observed spend");
+  });
+
+  it("syncs company monthly budget when raising and resuming a company incident", async () => {
+    const now = new Date();
+    const dbStub = createDbStub([
+      [{
+        id: "incident-1",
+        companyId: "company-1",
+        policyId: "policy-1",
+        scopeType: "company",
+        scopeId: "company-1",
+        metric: "billed_cents",
+        windowKind: "calendar_month_utc",
+        windowStart: now,
+        windowEnd: now,
+        thresholdType: "hard",
+        amountLimit: 100,
+        amountObserved: 120,
+        status: "open",
+        approvalId: "approval-1",
+        resolvedAt: null,
+        createdAt: now,
+        updatedAt: now,
+      }],
+      [{
+        id: "policy-1",
+        companyId: "company-1",
+        scopeType: "company",
+        scopeId: "company-1",
+        metric: "billed_cents",
+        windowKind: "calendar_month_utc",
+        amount: 100,
+      }],
+      [{ total: 120 }],
+      [{ id: "approval-1", status: "approved" }],
+      [{
+        companyId: "company-1",
+        name: "Paperclip",
+        status: "paused",
+        pauseReason: "budget",
+        pausedAt: now,
+      }],
+    ]);
+
+    const service = budgetService(dbStub.db as any);
+    await service.resolveIncident(
+      "company-1",
+      "incident-1",
+      { action: "raise_budget_and_resume", amount: 175 },
+      "board-user",
+    );
+
+    expect(dbStub.updateSet).toHaveBeenCalledWith(
+      expect.objectContaining({
+        budgetMonthlyCents: 175,
+        updatedAt: expect.any(Date),
+      }),
+    );
+  });
+});
--- a/server/src/tests/companies-route-path-guard.test.ts
+++ b/server/src/tests/companies-route-path-guard.test.ts
@@ -22,6 +22,9 @@ vi.mock("../services/index.js", () => ({
    canUser: vi.fn(),
    ensureMembership: vi.fn(),
  }),
+  budgetService: () => ({
+    upsertPolicy: vi.fn(),
+  }),
  logActivity: vi.fn(),
 }));

--- a/server/src/tests/costs-service.test.ts
+++ b/server/src/tests/costs-service.test.ts
@@ -0,0 +1,226 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { costRoutes } from "../routes/costs.js";
+import { errorHandler } from "../middleware/index.js";
+
+function makeDb(overrides: Record<string, unknown> = {}) {
+  const selectChain = {
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    leftJoin: vi.fn().mockReturnThis(),
+    innerJoin: vi.fn().mockReturnThis(),
+    groupBy: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    then: vi.fn().mockResolvedValue([]),
+  };
+
+  const thenableChain = Object.assign(Promise.resolve([]), selectChain);
+
+  return {
+    select: vi.fn().mockReturnValue(thenableChain),
+    insert: vi.fn().mockReturnValue({
+      values: vi.fn().mockReturnValue({ returning: vi.fn().mockResolvedValue([]) }),
+    }),
+    update: vi.fn().mockReturnValue({
+      set: vi.fn().mockReturnValue({ where: vi.fn().mockResolvedValue([]) }),
+    }),
+    ...overrides,
+  };
+}
+
+const mockCompanyService = vi.hoisted(() => ({
+  getById: vi.fn(),
+  update: vi.fn(),
+}));
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+  update: vi.fn(),
+}));
+const mockHeartbeatService = vi.hoisted(() => ({
+  cancelBudgetScopeWork: vi.fn().mockResolvedValue(undefined),
+}));
+const mockLogActivity = vi.hoisted(() => vi.fn());
+const mockFetchAllQuotaWindows = vi.hoisted(() => vi.fn());
+const mockCostService = vi.hoisted(() => ({
+  createEvent: vi.fn(),
+  summary: vi.fn().mockResolvedValue({ spendCents: 0 }),
+  byAgent: vi.fn().mockResolvedValue([]),
+  byAgentModel: vi.fn().mockResolvedValue([]),
+  byProvider: vi.fn().mockResolvedValue([]),
+  byBiller: vi.fn().mockResolvedValue([]),
+  windowSpend: vi.fn().mockResolvedValue([]),
+  byProject: vi.fn().mockResolvedValue([]),
+}));
+const mockFinanceService = vi.hoisted(() => ({
+  createEvent: vi.fn(),
+  summary: vi.fn().mockResolvedValue({ debitCents: 0, creditCents: 0, netCents: 0, estimatedDebitCents: 0, eventCount: 0 }),
+  byBiller: vi.fn().mockResolvedValue([]),
+  byKind: vi.fn().mockResolvedValue([]),
+  list: vi.fn().mockResolvedValue([]),
+}));
+const mockBudgetService = vi.hoisted(() => ({
+  overview: vi.fn().mockResolvedValue({
+    companyId: "company-1",
+    policies: [],
+    activeIncidents: [],
+    pausedAgentCount: 0,
+    pausedProjectCount: 0,
+    pendingApprovalCount: 0,
+  }),
+  upsertPolicy: vi.fn(),
+  resolveIncident: vi.fn(),
+}));
+
+vi.mock("../services/index.js", () => ({
+  budgetService: () => mockBudgetService,
+  costService: () => mockCostService,
+  financeService: () => mockFinanceService,
+  companyService: () => mockCompanyService,
+  agentService: () => mockAgentService,
+  heartbeatService: () => mockHeartbeatService,
+  logActivity: mockLogActivity,
+}));
+
+vi.mock("../services/quota-windows.js", () => ({
+  fetchAllQuotaWindows: mockFetchAllQuotaWindows,
+}));
+
+function createApp() {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.actor = { type: "board", userId: "board-user", source: "local_implicit" };
+    next();
+  });
+  app.use("/api", costRoutes(makeDb() as any));
+  app.use(errorHandler);
+  return app;
+}
+
+function createAppWithActor(actor: any) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.actor = actor;
+    next();
+  });
+  app.use("/api", costRoutes(makeDb() as any));
+  app.use(errorHandler);
+  return app;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockCompanyService.update.mockResolvedValue({
+    id: "company-1",
+    name: "Paperclip",
+    budgetMonthlyCents: 100,
+    spentMonthlyCents: 0,
+  });
+  mockAgentService.update.mockResolvedValue({
+    id: "agent-1",
+    companyId: "company-1",
+    name: "Budget Agent",
+    budgetMonthlyCents: 100,
+    spentMonthlyCents: 0,
+  });
+  mockBudgetService.upsertPolicy.mockResolvedValue(undefined);
+});
+
+describe("cost routes", () => {
+  it("accepts valid ISO date strings and passes them to cost summary routes", async () => {
+    const app = createApp();
+    const res = await request(app)
+      .get("/api/companies/company-1/costs/summary")
+      .query({ from: "2026-01-01T00:00:00.000Z", to: "2026-01-31T23:59:59.999Z" });
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 400 for an invalid 'from' date string", async () => {
+    const app = createApp();
+    const res = await request(app)
+      .get("/api/companies/company-1/costs/summary")
+      .query({ from: "not-a-date" });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/invalid 'from' date/i);
+  });
+
+  it("returns 400 for an invalid 'to' date string", async () => {
+    const app = createApp();
+    const res = await request(app)
+      .get("/api/companies/company-1/costs/summary")
+      .query({ to: "banana" });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/invalid 'to' date/i);
+  });
+
+  it("returns finance summary rows for valid requests", async () => {
+    const app = createApp();
+    const res = await request(app)
+      .get("/api/companies/company-1/costs/finance-summary")
+      .query({ from: "2026-02-01T00:00:00.000Z", to: "2026-02-28T23:59:59.999Z" });
+    expect(res.status).toBe(200);
+    expect(mockFinanceService.summary).toHaveBeenCalled();
+  });
+
+  it("returns 400 for invalid finance event list limits", async () => {
+    const app = createApp();
+    const res = await request(app)
+      .get("/api/companies/company-1/costs/finance-events")
+      .query({ limit: "0" });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/invalid 'limit'/i);
+  });
+
+  it("accepts valid finance event list limits", async () => {
+    const app = createApp();
+    const res = await request(app)
+      .get("/api/companies/company-1/costs/finance-events")
+      .query({ limit: "25" });
+    expect(res.status).toBe(200);
+    expect(mockFinanceService.list).toHaveBeenCalledWith("company-1", undefined, 25);
+  });
+
+  it("rejects company budget updates for board users outside the company", async () => {
+    const app = createAppWithActor({
+      type: "board",
+      userId: "board-user",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: ["company-2"],
+    });
+
+    const res = await request(app)
+      .patch("/api/companies/company-1/budgets")
+      .send({ budgetMonthlyCents: 2500 });
+
+    expect(res.status).toBe(403);
+    expect(mockCompanyService.update).not.toHaveBeenCalled();
+  });
+
+  it("rejects agent budget updates for board users outside the agent company", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "company-1",
+      name: "Budget Agent",
+      budgetMonthlyCents: 100,
+      spentMonthlyCents: 0,
+    });
+    const app = createAppWithActor({
+      type: "board",
+      userId: "board-user",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: ["company-2"],
+    });
+
+    const res = await request(app)
+      .patch("/api/agents/agent-1/budgets")
+      .send({ budgetMonthlyCents: 2500 });
+
+    expect(res.status).toBe(403);
+    expect(mockAgentService.update).not.toHaveBeenCalled();
+  });
+});
--- a/server/src/tests/monthly-spend-service.test.ts
+++ b/server/src/tests/monthly-spend-service.test.ts
@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { companyService } from "../services/companies.ts";
+import { agentService } from "../services/agents.ts";
+
+function createSelectSequenceDb(results: unknown[]) {
+  const pending = [...results];
+  const chain = {
+    from: vi.fn(() => chain),
+    where: vi.fn(() => chain),
+    leftJoin: vi.fn(() => chain),
+    groupBy: vi.fn(() => chain),
+    then: vi.fn((resolve: (value: unknown[]) => unknown) => Promise.resolve(resolve(pending.shift() ?? []))),
+  };
+
+  return {
+    db: {
+      select: vi.fn(() => chain),
+    },
+  };
+}
+
+describe("monthly spend hydration", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("recomputes company spentMonthlyCents from the current utc month instead of returning stale stored values", async () => {
+    const dbStub = createSelectSequenceDb([
+      [{
+        id: "company-1",
+        name: "Paperclip",
+        description: null,
+        status: "active",
+        issuePrefix: "PAP",
+        issueCounter: 1,
+        budgetMonthlyCents: 5000,
+        spentMonthlyCents: 999999,
+        requireBoardApprovalForNewAgents: false,
+        brandColor: null,
+        logoAssetId: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }],
+      [{
+        companyId: "company-1",
+        spentMonthlyCents: 420,
+      }],
+    ]);
+
+    const companies = companyService(dbStub.db as any);
+    const [company] = await companies.list();
+
+    expect(company.spentMonthlyCents).toBe(420);
+  });
+
+  it("recomputes agent spentMonthlyCents from the current utc month instead of returning stale stored values", async () => {
+    const dbStub = createSelectSequenceDb([
+      [{
+        id: "agent-1",
+        companyId: "company-1",
+        name: "Budget Agent",
+        role: "general",
+        title: null,
+        reportsTo: null,
+        capabilities: null,
+        adapterType: "claude-local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        budgetMonthlyCents: 5000,
+        spentMonthlyCents: 999999,
+        metadata: null,
+        permissions: null,
+        status: "idle",
+        pauseReason: null,
+        pausedAt: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }],
+      [{
+        agentId: "agent-1",
+        spentMonthlyCents: 175,
+      }],
+    ]);
+
+    const agents = agentService(dbStub.db as any);
+    const agent = await agents.getById("agent-1");
+
+    expect(agent?.spentMonthlyCents).toBe(175);
+  });
+});
--- a/server/src/tests/quota-windows-service.test.ts
+++ b/server/src/tests/quota-windows-service.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../adapters/registry.js", () => ({
+  listServerAdapters: vi.fn(),
+}));
+
+import { listServerAdapters } from "../adapters/registry.js";
+import { fetchAllQuotaWindows } from "../services/quota-windows.js";
+
+describe("fetchAllQuotaWindows", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("returns adapter results without waiting for a slower provider to finish forever", async () => {
+    vi.mocked(listServerAdapters).mockReturnValue([
+      {
+        type: "codex_local",
+        getQuotaWindows: vi.fn().mockResolvedValue({
+          provider: "openai",
+          source: "codex-rpc",
+          ok: true,
+          windows: [{ label: "5h limit", usedPercent: 2, resetsAt: null, valueLabel: null, detail: null }],
+        }),
+      },
+      {
+        type: "claude_local",
+        getQuotaWindows: vi.fn(() => new Promise(() => {})),
+      },
+    ] as never);
+
+    const promise = fetchAllQuotaWindows();
+    await vi.advanceTimersByTimeAsync(20_001);
+    const results = await promise;
+
+    expect(results).toEqual([
+      {
+        provider: "openai",
+        source: "codex-rpc",
+        ok: true,
+        windows: [{ label: "5h limit", usedPercent: 2, resetsAt: null, valueLabel: null, detail: null }],
+      },
+      {
+        provider: "anthropic",
+        ok: false,
+        error: "quota polling timed out after 20s",
+        windows: [],
+      },
+    ]);
+  });
+});
--- a/server/src/tests/quota-windows.test.ts
+++ b/server/src/tests/quota-windows.test.ts
@@ -0,0 +1,812 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import os from "node:os";
+import path from "node:path";
+import type { QuotaWindow } from "@paperclipai/adapter-utils";
+
+// Pure utility functions — import directly from adapter source
+import {
+  toPercent,
+  fetchWithTimeout,
+  fetchClaudeQuota,
+  parseClaudeCliUsageText,
+  readClaudeToken,
+  claudeConfigDir,
+} from "@paperclipai/adapter-claude-local/server";
+
+import {
+  secondsToWindowLabel,
+  readCodexAuthInfo,
+  readCodexToken,
+  fetchCodexQuota,
+  mapCodexRpcQuota,
+  codexHomeDir,
+} from "@paperclipai/adapter-codex-local/server";
+
+// ---------------------------------------------------------------------------
+// toPercent
+// ---------------------------------------------------------------------------
+
+describe("toPercent", () => {
+  it("returns null for null input", () => {
+    expect(toPercent(null)).toBe(null);
+  });
+
+  it("returns null for undefined input", () => {
+    expect(toPercent(undefined)).toBe(null);
+  });
+
+  it("converts 0 to 0", () => {
+    expect(toPercent(0)).toBe(0);
+  });
+
+  it("converts 0.5 to 50", () => {
+    expect(toPercent(0.5)).toBe(50);
+  });
+
+  it("converts 1.0 to 100", () => {
+    expect(toPercent(1.0)).toBe(100);
+  });
+
+  it("clamps overshoot to 100", () => {
+    // floating-point utilization can slightly exceed 1.0
+    expect(toPercent(1.001)).toBe(100);
+    expect(toPercent(1.01)).toBe(100);
+  });
+
+  it("rounds to nearest integer", () => {
+    expect(toPercent(0.333)).toBe(33);
+    expect(toPercent(0.666)).toBe(67);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// secondsToWindowLabel
+// ---------------------------------------------------------------------------
+
+describe("secondsToWindowLabel", () => {
+  it("returns fallback for null seconds", () => {
+    expect(secondsToWindowLabel(null, "Primary")).toBe("Primary");
+  });
+
+  it("returns fallback for undefined seconds", () => {
+    expect(secondsToWindowLabel(undefined, "Secondary")).toBe("Secondary");
+  });
+
+  it("labels windows under 6 hours as '5h'", () => {
+    expect(secondsToWindowLabel(3600, "fallback")).toBe("5h");   // 1h
+    expect(secondsToWindowLabel(18000, "fallback")).toBe("5h");  // 5h exactly
+  });
+
+  it("labels windows up to 24 hours as '24h'", () => {
+    expect(secondsToWindowLabel(21600, "fallback")).toBe("24h"); // 6h (≥6h boundary)
+    expect(secondsToWindowLabel(86400, "fallback")).toBe("24h"); // 24h exactly
+  });
+
+  it("labels windows up to 7 days as '7d'", () => {
+    expect(secondsToWindowLabel(86401, "fallback")).toBe("7d");   // just over 24h
+    expect(secondsToWindowLabel(604800, "fallback")).toBe("7d"); // 7d exactly
+  });
+
+  it("labels windows beyond 7 days with actual day count", () => {
+    expect(secondsToWindowLabel(1209600, "fallback")).toBe("14d"); // 14d
+    expect(secondsToWindowLabel(2592000, "fallback")).toBe("30d"); // 30d
+  });
+});
+
+// ---------------------------------------------------------------------------
+// WHAM used_percent normalization (codex / openai)
+// ---------------------------------------------------------------------------
+
+describe("WHAM used_percent normalization via fetchCodexQuota", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown) {
+    (fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => body,
+    } as Response);
+  }
+
+  it("treats values >= 1 as already-percentage (50 → 50%)", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 50,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(50);
+  });
+
+  it("treats values < 1 as fraction and multiplies by 100 (0.5 → 50%)", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 0.5,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(50);
+  });
+
+  it("treats value exactly 1.0 as 1% (not 100%) — the < 1 heuristic boundary", async () => {
+    // 1.0 is NOT < 1, so it is treated as already-percentage → 1%
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 1.0,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(1);
+  });
+
+  it("treats value 0 as 0%", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 0,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(0);
+  });
+
+  it("clamps 100% to 100 (no overshoot)", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 105,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(100);
+  });
+
+  it("sets usedPercent to null when used_percent is absent", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(null);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readClaudeToken — filesystem paths
+// ---------------------------------------------------------------------------
+
+describe("readClaudeToken", () => {
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    } else {
+      process.env.CLAUDE_CONFIG_DIR = savedEnv;
+    }
+    vi.restoreAllMocks();
+  });
+
+  it("returns null when credentials.json does not exist", async () => {
+    // Point to a directory that does not have credentials.json
+    process.env.CLAUDE_CONFIG_DIR = "/tmp/__no_such_paperclip_dir__";
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+  });
+
+  it("returns null for malformed JSON", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), "not-json"),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns null when claudeAiOauth key is missing", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), JSON.stringify({ other: "data" })),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns null when accessToken is an empty string", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    const creds = { claudeAiOauth: { accessToken: "" } };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), JSON.stringify(creds)),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns the token when credentials file is well-formed", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    const creds = { claudeAiOauth: { accessToken: "my-test-token" } };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), JSON.stringify(creds)),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe("my-test-token");
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("reads the token from .credentials.json when that is the available Claude auth file", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    const creds = { claudeAiOauth: { accessToken: "dotfile-token" } };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, ".credentials.json"), JSON.stringify(creds)),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe("dotfile-token");
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+});
+
+describe("parseClaudeCliUsageText", () => {
+  it("parses the Claude usage panel layout into quota windows", () => {
+    const raw = `
+      Settings:  Status   Config   Usage
+      Current session
+      2% used
+      Resets 5pm (America/Chicago)
+
+      Current week (all models)
+      47% used
+      Resets Mar 18 at 7:59am (America/Chicago)
+
+      Current week (Sonnet only)
+      0% used
+      Resets Mar 18 at 8:59am (America/Chicago)
+
+      Extra usage
+      Extra usage not enabled • /extra-usage to enable
+    `;
+
+    expect(parseClaudeCliUsageText(raw)).toEqual([
+      {
+        label: "Current session",
+        usedPercent: 2,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Resets 5pm (America/Chicago)",
+      },
+      {
+        label: "Current week (all models)",
+        usedPercent: 47,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Resets Mar 18 at 7:59am (America/Chicago)",
+      },
+      {
+        label: "Current week (Sonnet only)",
+        usedPercent: 0,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Resets Mar 18 at 8:59am (America/Chicago)",
+      },
+      {
+        label: "Extra usage",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Extra usage not enabled • /extra-usage to enable",
+      },
+    ]);
+  });
+
+  it("throws a useful error when the Claude CLI panel reports a usage load failure", () => {
+    expect(() => parseClaudeCliUsageText("Failed to load usage data")).toThrow(
+      "Claude CLI could not load usage data. Open the CLI and retry `/usage`.",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readCodexAuthInfo / readCodexToken — filesystem paths
+// ---------------------------------------------------------------------------
+
+describe("readCodexAuthInfo", () => {
+  const savedEnv = process.env.CODEX_HOME;
+
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env.CODEX_HOME;
+    } else {
+      process.env.CODEX_HOME = savedEnv;
+    }
+  });
+
+  it("returns null when auth.json does not exist", async () => {
+    process.env.CODEX_HOME = "/tmp/__no_such_paperclip_codex_dir__";
+    const result = await readCodexAuthInfo();
+    expect(result).toBe(null);
+  });
+
+  it("returns null for malformed JSON", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), "{bad json"),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns null when accessToken is absent", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify({ accountId: "acc-1" })),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("reads the legacy flat auth shape", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    const auth = { accessToken: "codex-token", accountId: "acc-123" };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify(auth)),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toMatchObject({
+      accessToken: "codex-token",
+      accountId: "acc-123",
+      email: null,
+      planType: null,
+    });
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("reads the modern nested auth shape", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    const jwtPayload = Buffer.from(
+      JSON.stringify({
+        email: "codex@example.com",
+        "https://api.openai.com/auth": {
+          chatgpt_plan_type: "pro",
+          chatgpt_user_email: "codex@example.com",
+        },
+      }),
+    ).toString("base64url");
+    const auth = {
+      tokens: {
+        access_token: `header.${jwtPayload}.sig`,
+        account_id: "acc-modern",
+        refresh_token: "refresh-me",
+        id_token: `header.${jwtPayload}.sig`,
+      },
+      last_refresh: "2026-03-14T12:00:00Z",
+    };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify(auth)),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toMatchObject({
+      accessToken: `header.${jwtPayload}.sig`,
+      accountId: "acc-modern",
+      refreshToken: "refresh-me",
+      email: "codex@example.com",
+      planType: "pro",
+      lastRefresh: "2026-03-14T12:00:00Z",
+    });
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+});
+
+describe("readCodexToken", () => {
+  const savedEnv = process.env.CODEX_HOME;
+
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env.CODEX_HOME;
+    } else {
+      process.env.CODEX_HOME = savedEnv;
+    }
+  });
+
+  it("returns token and accountId from the nested auth shape", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify({
+          tokens: {
+            access_token: "nested-token",
+            account_id: "acc-nested",
+          },
+        })),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexToken();
+    expect(result).toEqual({ token: "nested-token", accountId: "acc-nested" });
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchClaudeQuota — response parsing
+// ---------------------------------------------------------------------------
+
+describe("fetchClaudeQuota", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown, ok = true, status = 200) {
+    (fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok,
+      status,
+      json: async () => body,
+    } as Response);
+  }
+
+  it("throws when the API returns a non-200 status", async () => {
+    mockFetch({}, false, 401);
+    await expect(fetchClaudeQuota("token")).rejects.toThrow("anthropic usage api returned 401");
+  });
+
+  it("returns an empty array when all window fields are absent", async () => {
+    mockFetch({});
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toEqual([]);
+  });
+
+  it("parses five_hour window", async () => {
+    mockFetch({ five_hour: { utilization: 0.4, resets_at: "2026-01-01T00:00:00Z" } });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({
+      label: "Current session",
+      usedPercent: 40,
+      resetsAt: "2026-01-01T00:00:00Z",
+    });
+  });
+
+  it("parses seven_day window", async () => {
+    mockFetch({ seven_day: { utilization: 0.75, resets_at: null } });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({
+      label: "Current week (all models)",
+      usedPercent: 75,
+      resetsAt: null,
+    });
+  });
+
+  it("parses seven_day_sonnet and seven_day_opus windows", async () => {
+    mockFetch({
+      seven_day_sonnet: { utilization: 0.2, resets_at: null },
+      seven_day_opus: { utilization: 0.9, resets_at: null },
+    });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(2);
+    expect(windows[0]!.label).toBe("Current week (Sonnet only)");
+    expect(windows[1]!.label).toBe("Current week (Opus only)");
+  });
+
+  it("sets usedPercent to null when utilization is absent", async () => {
+    mockFetch({ five_hour: { resets_at: null } });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows[0]!.usedPercent).toBe(null);
+  });
+
+  it("includes all four windows when all are present", async () => {
+    mockFetch({
+      five_hour: { utilization: 0.1, resets_at: null },
+      seven_day: { utilization: 0.2, resets_at: null },
+      seven_day_sonnet: { utilization: 0.3, resets_at: null },
+      seven_day_opus: { utilization: 0.4, resets_at: null },
+    });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(4);
+    const labels = windows.map((w: QuotaWindow) => w.label);
+    expect(labels).toEqual([
+      "Current session",
+      "Current week (all models)",
+      "Current week (Sonnet only)",
+      "Current week (Opus only)",
+    ]);
+  });
+
+  it("parses extra usage when the OAuth response includes it", async () => {
+    mockFetch({
+      extra_usage: {
+        is_enabled: false,
+        utilization: null,
+      },
+    });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toEqual([
+      {
+        label: "Extra usage",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: "Not enabled",
+        detail: "Extra usage not enabled",
+      },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchCodexQuota — response parsing (credits, windows)
+// ---------------------------------------------------------------------------
+
+describe("fetchCodexQuota", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown, ok = true, status = 200) {
+    (fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok,
+      status,
+      json: async () => body,
+    } as Response);
+  }
+
+  it("throws when the WHAM API returns a non-200 status", async () => {
+    mockFetch({}, false, 403);
+    await expect(fetchCodexQuota("token", null)).rejects.toThrow("chatgpt wham api returned 403");
+  });
+
+  it("passes ChatGPT-Account-Id header when accountId is provided", async () => {
+    mockFetch({});
+    await fetchCodexQuota("token", "acc-xyz");
+    const callInit = (fetch as ReturnType<typeof vi.fn>).mock.calls[0][1] as RequestInit;
+    expect((callInit.headers as Record<string, string>)["ChatGPT-Account-Id"]).toBe("acc-xyz");
+  });
+
+  it("omits ChatGPT-Account-Id header when accountId is null", async () => {
+    mockFetch({});
+    await fetchCodexQuota("token", null);
+    const callInit = (fetch as ReturnType<typeof vi.fn>).mock.calls[0][1] as RequestInit;
+    expect((callInit.headers as Record<string, string>)["ChatGPT-Account-Id"]).toBeUndefined();
+  });
+
+  it("returns empty array when response body is empty", async () => {
+    mockFetch({});
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toEqual([]);
+  });
+
+  it("normalizes numeric reset timestamps from WHAM", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: { used_percent: 30, limit_window_seconds: 86400, reset_at: 1_767_312_000 },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({ label: "5h limit", usedPercent: 30, resetsAt: "2026-01-02T00:00:00.000Z" });
+  });
+
+  it("parses secondary_window alongside primary_window", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: { used_percent: 10, limit_window_seconds: 18000 },
+        secondary_window: { used_percent: 60, limit_window_seconds: 604800 },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toHaveLength(2);
+    expect(windows[0]!.label).toBe("5h limit");
+    expect(windows[1]!.label).toBe("Weekly limit");
+  });
+
+  it("includes Credits window when credits present and not unlimited", async () => {
+    mockFetch({
+      credits: { balance: 420, unlimited: false },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({ label: "Credits", valueLabel: "$4.20 remaining", usedPercent: null });
+  });
+
+  it("omits Credits window when unlimited is true", async () => {
+    mockFetch({
+      credits: { balance: 9999, unlimited: true },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toEqual([]);
+  });
+
+  it("shows 'N/A' valueLabel when credits balance is null", async () => {
+    mockFetch({
+      credits: { balance: null, unlimited: false },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.valueLabel).toBe("N/A");
+  });
+});
+
+describe("mapCodexRpcQuota", () => {
+  it("maps account and model-specific Codex limits into quota windows", () => {
+    const snapshot = mapCodexRpcQuota(
+      {
+        rateLimits: {
+          limitId: "codex",
+          primary: { usedPercent: 1, windowDurationMins: 300, resetsAt: 1_763_500_000 },
+          secondary: { usedPercent: 27, windowDurationMins: 10_080 },
+          planType: "pro",
+        },
+        rateLimitsByLimitId: {
+          codex_bengalfox: {
+            limitId: "codex_bengalfox",
+            limitName: "GPT-5.3-Codex-Spark",
+            primary: { usedPercent: 8, windowDurationMins: 300 },
+            secondary: { usedPercent: 20, windowDurationMins: 10_080 },
+          },
+        },
+      },
+      {
+        account: {
+          email: "codex@example.com",
+          planType: "pro",
+        },
+      },
+    );
+
+    expect(snapshot.email).toBe("codex@example.com");
+    expect(snapshot.planType).toBe("pro");
+    expect(snapshot.windows).toEqual([
+      {
+        label: "5h limit",
+        usedPercent: 1,
+        resetsAt: "2025-11-18T21:06:40.000Z",
+        valueLabel: null,
+        detail: null,
+      },
+      {
+        label: "Weekly limit",
+        usedPercent: 27,
+        resetsAt: null,
+        valueLabel: null,
+        detail: null,
+      },
+      {
+        label: "GPT-5.3-Codex-Spark · 5h limit",
+        usedPercent: 8,
+        resetsAt: null,
+        valueLabel: null,
+        detail: null,
+      },
+      {
+        label: "GPT-5.3-Codex-Spark · Weekly limit",
+        usedPercent: 20,
+        resetsAt: null,
+        valueLabel: null,
+        detail: null,
+      },
+    ]);
+  });
+
+  it("includes a credits row when the root Codex limit reports finite credits", () => {
+    const snapshot = mapCodexRpcQuota({
+      rateLimits: {
+        limitId: "codex",
+        credits: {
+          unlimited: false,
+          balance: "12.34",
+        },
+      },
+    });
+
+    expect(snapshot.windows).toEqual([
+      {
+        label: "Credits",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: "$12.34 remaining",
+        detail: null,
+      },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchWithTimeout — abort on timeout
+// ---------------------------------------------------------------------------
+
+describe("fetchWithTimeout", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("resolves normally when fetch completes before timeout", async () => {
+    const mockResponse = { ok: true, status: 200, json: async () => ({}) } as Response;
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(mockResponse));
+
+    const result = await fetchWithTimeout("https://example.com", {}, 5000);
+    expect(result.ok).toBe(true);
+  });
+
+  it("rejects with abort error when fetch takes too long", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(
+        (_url: string, init: RequestInit) =>
+          new Promise((_resolve, reject) => {
+            init.signal?.addEventListener("abort", () => {
+              reject(new DOMException("The operation was aborted.", "AbortError"));
+            });
+          }),
+      ),
+    );
+
+    const promise = fetchWithTimeout("https://example.com", {}, 1000);
+    vi.advanceTimersByTime(1001);
+    await expect(promise).rejects.toThrow("aborted");
+  });
+});
--- a/server/src/adapters/registry.ts
+++ b/server/src/adapters/registry.ts
@@ -3,12 +3,14 @@ import {
  execute as claudeExecute,
  testEnvironment as claudeTestEnvironment,
  sessionCodec as claudeSessionCodec,
+  getQuotaWindows as claudeGetQuotaWindows,
 } from "@paperclipai/adapter-claude-local/server";
 import { agentConfigurationDoc as claudeAgentConfigurationDoc, models as claudeModels } from "@paperclipai/adapter-claude-local";
 import {
  execute as codexExecute,
  testEnvironment as codexTestEnvironment,
  sessionCodec as codexSessionCodec,
+  getQuotaWindows as codexGetQuotaWindows,
 } from "@paperclipai/adapter-codex-local/server";
 import { agentConfigurationDoc as codexAgentConfigurationDoc, models as codexModels } from "@paperclipai/adapter-codex-local";
 import {
@@ -71,6 +73,7 @@ const claudeLocalAdapter: ServerAdapterModule = {
  models: claudeModels,
  supportsLocalAgentJwt: true,
  agentConfigurationDoc: claudeAgentConfigurationDoc,
+  getQuotaWindows: claudeGetQuotaWindows,
 };

 const codexLocalAdapter: ServerAdapterModule = {
@@ -82,6 +85,7 @@ const codexLocalAdapter: ServerAdapterModule = {
  listModels: listCodexModels,
  supportsLocalAgentJwt: true,
  agentConfigurationDoc: codexAgentConfigurationDoc,
+  getQuotaWindows: codexGetQuotaWindows,
 };

 const cursorLocalAdapter: ServerAdapterModule = {
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -83,8 +83,7 @@ export async function startServer(): Promise<StartedServer> {
    | "skipped"
    | "already applied"
    | "applied (empty database)"
-    | "applied (pending migrations)"
-    | "pending migrations skipped";
+    | "applied (pending migrations)";
  
  function formatPendingMigrationSummary(migrations: string[]): string {
    if (migrations.length === 0) return "none";
@@ -139,11 +138,10 @@ export async function startServer(): Promise<StartedServer> {
      );
      const apply = autoApply ? true : await promptApplyMigrations(state.pendingMigrations);
      if (!apply) {
-        logger.warn(
-          { pendingMigrations: state.pendingMigrations },
-          `${label} has pending migrations; continuing without applying. Run pnpm db:migrate to apply before startup.`,
+        throw new Error(
+          `${label} has pending migrations (${formatPendingMigrationSummary(state.pendingMigrations)}). ` +
+            "Refusing to start against a stale schema. Run pnpm db:migrate or set PAPERCLIP_MIGRATION_AUTO_APPLY=true.",
        );
-        return "pending migrations skipped";
      }
  
      logger.info({ pendingMigrations: state.pendingMigrations }, `Applying ${state.pendingMigrations.length} pending migrations for ${label}`);
@@ -153,11 +151,10 @@ export async function startServer(): Promise<StartedServer> {
  
    const apply = autoApply ? true : await promptApplyMigrations(state.pendingMigrations);
    if (!apply) {
-      logger.warn(
-        { pendingMigrations: state.pendingMigrations },
-        `${label} has pending migrations; continuing without applying. Run pnpm db:migrate to apply before startup.`,
+      throw new Error(
+        `${label} has pending migrations (${formatPendingMigrationSummary(state.pendingMigrations)}). ` +
+          "Refusing to start against a stale schema. Run pnpm db:migrate or set PAPERCLIP_MIGRATION_AUTO_APPLY=true.",
      );
-      return "pending migrations skipped";
    }
  
    logger.info({ pendingMigrations: state.pendingMigrations }, `Applying ${state.pendingMigrations.length} pending migrations for ${label}`);
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -23,6 +23,7 @@ import {
  agentService,
  accessService,
  approvalService,
+  budgetService,
  heartbeatService,
  issueApprovalService,
  issueService,
@@ -57,6 +58,7 @@ export function agentRoutes(db: Db) {
  const svc = agentService(db);
  const access = accessService(db);
  const approvalsSvc = approvalService(db);
+  const budgets = budgetService(db);
  const heartbeat = heartbeatService(db);
  const issueApprovalsSvc = issueApprovalService(db);
  const secretsSvc = secretService(db);
@@ -941,6 +943,19 @@ export function agentRoutes(db: Db) {
      details: { name: agent.name, role: agent.role },
    });

+    if (agent.budgetMonthlyCents > 0) {
+      await budgets.upsertPolicy(
+        companyId,
+        {
+          scopeType: "agent",
+          scopeId: agent.id,
+          amount: agent.budgetMonthlyCents,
+          windowKind: "calendar_month_utc",
+        },
+        actor.actorType === "user" ? actor.actorId : null,
+      );
+    }
+
    res.status(201).json(agent);
  });

--- a/server/src/routes/companies.ts
+++ b/server/src/routes/companies.ts
@@ -9,7 +9,13 @@ import {
 } from "@paperclipai/shared";
 import { forbidden } from "../errors.js";
 import { validate } from "../middleware/validate.js";
-import { accessService, companyPortabilityService, companyService, logActivity } from "../services/index.js";
+import {
+  accessService,
+  budgetService,
+  companyPortabilityService,
+  companyService,
+  logActivity,
+} from "../services/index.js";
 import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";

 export function companyRoutes(db: Db) {
@@ -17,6 +23,7 @@ export function companyRoutes(db: Db) {
  const svc = companyService(db);
  const portability = companyPortabilityService(db);
  const access = accessService(db);
+  const budgets = budgetService(db);

  router.get("/", async (req, res) => {
    assertBoard(req);
@@ -122,6 +129,18 @@ export function companyRoutes(db: Db) {
      entityId: company.id,
      details: { name: company.name },
    });
+    if (company.budgetMonthlyCents > 0) {
+      await budgets.upsertPolicy(
+        company.id,
+        {
+          scopeType: "company",
+          scopeId: company.id,
+          amount: company.budgetMonthlyCents,
+          windowKind: "calendar_month_utc",
+        },
+        req.actor.userId ?? "board",
+      );
+    }
    res.status(201).json(company);
  });

--- a/server/src/routes/costs.ts
+++ b/server/src/routes/costs.ts
@@ -1,13 +1,35 @@
 import { Router } from "express";
 import type { Db } from "@paperclipai/db";
-import { createCostEventSchema, updateBudgetSchema } from "@paperclipai/shared";
+import {
+  createCostEventSchema,
+  createFinanceEventSchema,
+  resolveBudgetIncidentSchema,
+  updateBudgetSchema,
+  upsertBudgetPolicySchema,
+} from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
-import { costService, companyService, agentService, logActivity } from "../services/index.js";
+import {
+  budgetService,
+  costService,
+  financeService,
+  companyService,
+  agentService,
+  heartbeatService,
+  logActivity,
+} from "../services/index.js";
 import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
+import { fetchAllQuotaWindows } from "../services/quota-windows.js";
+import { badRequest } from "../errors.js";

 export function costRoutes(db: Db) {
  const router = Router();
-  const costs = costService(db);
+  const heartbeat = heartbeatService(db);
+  const budgetHooks = {
+    cancelWorkForScope: heartbeat.cancelBudgetScopeWork,
+  };
+  const costs = costService(db, budgetHooks);
+  const finance = financeService(db);
+  const budgets = budgetService(db, budgetHooks);
  const companies = companyService(db);
  const agents = agentService(db);

@@ -40,12 +62,56 @@ export function costRoutes(db: Db) {
    res.status(201).json(event);
  });

+  router.post("/companies/:companyId/finance-events", validate(createFinanceEventSchema), async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    assertBoard(req);
+
+    const event = await finance.createEvent(companyId, {
+      ...req.body,
+      occurredAt: new Date(req.body.occurredAt),
+    });
+
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      action: "finance_event.reported",
+      entityType: "finance_event",
+      entityId: event.id,
+      details: {
+        amountCents: event.amountCents,
+        biller: event.biller,
+        eventKind: event.eventKind,
+        direction: event.direction,
+      },
+    });
+
+    res.status(201).json(event);
+  });
+
  function parseDateRange(query: Record<string, unknown>) {
-    const from = query.from ? new Date(query.from as string) : undefined;
-    const to = query.to ? new Date(query.to as string) : undefined;
+    const fromRaw = query.from as string | undefined;
+    const toRaw = query.to as string | undefined;
+    const from = fromRaw ? new Date(fromRaw) : undefined;
+    const to = toRaw ? new Date(toRaw) : undefined;
+    if (from && isNaN(from.getTime())) throw badRequest("invalid 'from' date");
+    if (to && isNaN(to.getTime())) throw badRequest("invalid 'to' date");
    return (from || to) ? { from, to } : undefined;
  }

+  function parseLimit(query: Record<string, unknown>) {
+    const raw = query.limit as string | undefined;
+    if (!raw) return 100;
+    const limit = Number.parseInt(raw, 10);
+    if (!Number.isFinite(limit) || limit <= 0 || limit > 500) {
+      throw badRequest("invalid 'limit' value");
+    }
+    return limit;
+  }
+
  router.get("/companies/:companyId/costs/summary", async (req, res) => {
    const companyId = req.params.companyId as string;
    assertCompanyAccess(req, companyId);
@@ -62,6 +128,117 @@ export function costRoutes(db: Db) {
    res.json(rows);
  });

+  router.get("/companies/:companyId/costs/by-agent-model", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const rows = await costs.byAgentModel(companyId, range);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/by-provider", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const rows = await costs.byProvider(companyId, range);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/by-biller", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const rows = await costs.byBiller(companyId, range);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/finance-summary", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const summary = await finance.summary(companyId, range);
+    res.json(summary);
+  });
+
+  router.get("/companies/:companyId/costs/finance-by-biller", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const rows = await finance.byBiller(companyId, range);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/finance-by-kind", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const rows = await finance.byKind(companyId, range);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/finance-events", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const range = parseDateRange(req.query);
+    const limit = parseLimit(req.query);
+    const rows = await finance.list(companyId, range, limit);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/window-spend", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const rows = await costs.windowSpend(companyId);
+    res.json(rows);
+  });
+
+  router.get("/companies/:companyId/costs/quota-windows", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    assertBoard(req);
+    // validate companyId resolves to a real company so the "__none__" sentinel
+    // and any forged ids are rejected before we touch provider credentials
+    const company = await companies.getById(companyId);
+    if (!company) {
+      res.status(404).json({ error: "Company not found" });
+      return;
+    }
+    const results = await fetchAllQuotaWindows();
+    res.json(results);
+  });
+
+  router.get("/companies/:companyId/budgets/overview", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const overview = await budgets.overview(companyId);
+    res.json(overview);
+  });
+
+  router.post(
+    "/companies/:companyId/budgets/policies",
+    validate(upsertBudgetPolicySchema),
+    async (req, res) => {
+      assertBoard(req);
+      const companyId = req.params.companyId as string;
+      assertCompanyAccess(req, companyId);
+      const summary = await budgets.upsertPolicy(companyId, req.body, req.actor.userId ?? "board");
+      res.json(summary);
+    },
+  );
+
+  router.post(
+    "/companies/:companyId/budget-incidents/:incidentId/resolve",
+    validate(resolveBudgetIncidentSchema),
+    async (req, res) => {
+      assertBoard(req);
+      const companyId = req.params.companyId as string;
+      const incidentId = req.params.incidentId as string;
+      assertCompanyAccess(req, companyId);
+      const incident = await budgets.resolveIncident(companyId, incidentId, req.body, req.actor.userId ?? "board");
+      res.json(incident);
+    },
+  );
+
  router.get("/companies/:companyId/costs/by-project", async (req, res) => {
    const companyId = req.params.companyId as string;
    assertCompanyAccess(req, companyId);
@@ -73,6 +250,7 @@ export function costRoutes(db: Db) {
  router.patch("/companies/:companyId/budgets", validate(updateBudgetSchema), async (req, res) => {
    assertBoard(req);
    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
    const company = await companies.update(companyId, { budgetMonthlyCents: req.body.budgetMonthlyCents });
    if (!company) {
      res.status(404).json({ error: "Company not found" });
@@ -89,6 +267,17 @@ export function costRoutes(db: Db) {
      details: { budgetMonthlyCents: req.body.budgetMonthlyCents },
    });

+    await budgets.upsertPolicy(
+      companyId,
+      {
+        scopeType: "company",
+        scopeId: companyId,
+        amount: req.body.budgetMonthlyCents,
+        windowKind: "calendar_month_utc",
+      },
+      req.actor.userId ?? "board",
+    );
+
    res.json(company);
  });

@@ -100,6 +289,8 @@ export function costRoutes(db: Db) {
      return;
    }

+    assertCompanyAccess(req, agent.companyId);
+
    if (req.actor.type === "agent") {
      if (req.actor.agentId !== agentId) {
        res.status(403).json({ error: "Agent can only change its own budget" });
@@ -125,6 +316,17 @@ export function costRoutes(db: Db) {
      details: { budgetMonthlyCents: updated.budgetMonthlyCents },
    });

+    await budgets.upsertPolicy(
+      updated.companyId,
+      {
+        scopeType: "agent",
+        scopeId: updated.id,
+        amount: updated.budgetMonthlyCents,
+        windowKind: "calendar_month_utc",
+      },
+      req.actor.type === "board" ? req.actor.userId ?? "board" : null,
+    );
+
    res.json(updated);
  });

--- a/server/src/routes/issues.ts
+++ b/server/src/routes/issues.ts
@@ -1032,6 +1032,19 @@ export function issueRoutes(db: Db, storage: StorageService) {
    }
    assertCompanyAccess(req, issue.companyId);

+    if (issue.projectId) {
+      const project = await projectsSvc.getById(issue.projectId);
+      if (project?.pausedAt) {
+        res.status(409).json({
+          error:
+            project.pauseReason === "budget"
+              ? "Project is paused because its budget hard-stop was reached"
+              : "Project is paused",
+        });
+        return;
+      }
+    }
+
    if (req.actor.type === "agent" && req.actor.agentId !== req.body.agentId) {
      res.status(403).json({ error: "Agent can only checkout as itself" });
      return;
--- a/server/src/services/agents.ts
+++ b/server/src/services/agents.ts
@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from "node:crypto";
-import { and, desc, eq, inArray, ne } from "drizzle-orm";
+import { and, desc, eq, gte, inArray, lt, ne, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
  agents,
@@ -8,6 +8,7 @@ import {
  agentRuntimeState,
  agentTaskSessions,
  agentWakeupRequests,
+  costEvents,
  heartbeatRunEvents,
  heartbeatRuns,
 } from "@paperclipai/db";
@@ -182,6 +183,15 @@ export function deduplicateAgentName(
 }

 export function agentService(db: Db) {
+  function currentUtcMonthWindow(now = new Date()) {
+    const year = now.getUTCFullYear();
+    const month = now.getUTCMonth();
+    return {
+      start: new Date(Date.UTC(year, month, 1, 0, 0, 0, 0)),
+      end: new Date(Date.UTC(year, month + 1, 1, 0, 0, 0, 0)),
+    };
+  }
+
  function withUrlKey<T extends { id: string; name: string }>(row: T) {
    return {
      ...row,
@@ -196,13 +206,47 @@ export function agentService(db: Db) {
    });
  }

+  async function getMonthlySpendByAgentIds(companyId: string, agentIds: string[]) {
+    if (agentIds.length === 0) return new Map<string, number>();
+    const { start, end } = currentUtcMonthWindow();
+    const rows = await db
+      .select({
+        agentId: costEvents.agentId,
+        spentMonthlyCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+      })
+      .from(costEvents)
+      .where(
+        and(
+          eq(costEvents.companyId, companyId),
+          inArray(costEvents.agentId, agentIds),
+          gte(costEvents.occurredAt, start),
+          lt(costEvents.occurredAt, end),
+        ),
+      )
+      .groupBy(costEvents.agentId);
+    return new Map(rows.map((row) => [row.agentId, Number(row.spentMonthlyCents ?? 0)]));
+  }
+
+  async function hydrateAgentSpend<T extends { id: string; companyId: string; spentMonthlyCents: number }>(rows: T[]) {
+    const agentIds = rows.map((row) => row.id);
+    const companyId = rows[0]?.companyId;
+    if (!companyId || agentIds.length === 0) return rows;
+    const spendByAgentId = await getMonthlySpendByAgentIds(companyId, agentIds);
+    return rows.map((row) => ({
+      ...row,
+      spentMonthlyCents: spendByAgentId.get(row.id) ?? 0,
+    }));
+  }
+
  async function getById(id: string) {
    const row = await db
      .select()
      .from(agents)
      .where(eq(agents.id, id))
      .then((rows) => rows[0] ?? null);
-    return row ? normalizeAgentRow(row) : null;
+    if (!row) return null;
+    const [hydrated] = await hydrateAgentSpend([row]);
+    return normalizeAgentRow(hydrated);
  }

  async function ensureManager(companyId: string, managerId: string) {
@@ -331,7 +375,8 @@ export function agentService(db: Db) {
        conditions.push(ne(agents.status, "terminated"));
      }
      const rows = await db.select().from(agents).where(and(...conditions));
-      return rows.map(normalizeAgentRow);
+      const hydrated = await hydrateAgentSpend(rows);
+      return hydrated.map(normalizeAgentRow);
    },

    getById,
@@ -360,14 +405,19 @@ export function agentService(db: Db) {

    update: updateAgent,

-    pause: async (id: string) => {
+    pause: async (id: string, reason: "manual" | "budget" | "system" = "manual") => {
      const existing = await getById(id);
      if (!existing) return null;
      if (existing.status === "terminated") throw conflict("Cannot pause terminated agent");

      const updated = await db
        .update(agents)
-        .set({ status: "paused", updatedAt: new Date() })
+        .set({
+          status: "paused",
+          pauseReason: reason,
+          pausedAt: new Date(),
+          updatedAt: new Date(),
+        })
        .where(eq(agents.id, id))
        .returning()
        .then((rows) => rows[0] ?? null);
@@ -384,7 +434,12 @@ export function agentService(db: Db) {

      const updated = await db
        .update(agents)
-        .set({ status: "idle", updatedAt: new Date() })
+        .set({
+          status: "idle",
+          pauseReason: null,
+          pausedAt: null,
+          updatedAt: new Date(),
+        })
        .where(eq(agents.id, id))
        .returning()
        .then((rows) => rows[0] ?? null);
@@ -397,7 +452,12 @@ export function agentService(db: Db) {

      await db
        .update(agents)
-        .set({ status: "terminated", updatedAt: new Date() })
+        .set({
+          status: "terminated",
+          pauseReason: null,
+          pausedAt: null,
+          updatedAt: new Date(),
+        })
        .where(eq(agents.id, id));

      await db
--- a/server/src/services/approvals.ts
+++ b/server/src/services/approvals.ts
@@ -4,6 +4,7 @@ import { approvalComments, approvals } from "@paperclipai/db";
 import { notFound, unprocessable } from "../errors.js";
 import { redactCurrentUserText } from "../log-redaction.js";
 import { agentService } from "./agents.js";
+import { budgetService } from "./budgets.js";
 import { notifyHireApproved } from "./hire-hook.js";

 function redactApprovalComment<T extends { body: string }>(comment: T): T {
@@ -15,6 +16,7 @@ function redactApprovalComment<T extends { body: string }>(comment: T): T {

 export function approvalService(db: Db) {
  const agentsSvc = agentService(db);
+  const budgets = budgetService(db);
  const canResolveStatuses = new Set(["pending", "revision_requested"]);
  const resolvableStatuses = Array.from(canResolveStatuses);
  type ApprovalRecord = typeof approvals.$inferSelect;
@@ -137,6 +139,20 @@ export function approvalService(db: Db) {
          hireApprovedAgentId = created?.id ?? null;
        }
        if (hireApprovedAgentId) {
+          const budgetMonthlyCents =
+            typeof payload.budgetMonthlyCents === "number" ? payload.budgetMonthlyCents : 0;
+          if (budgetMonthlyCents > 0) {
+            await budgets.upsertPolicy(
+              updated.companyId,
+              {
+                scopeType: "agent",
+                scopeId: hireApprovedAgentId,
+                amount: budgetMonthlyCents,
+                windowKind: "calendar_month_utc",
+              },
+              decidedByUserId,
+            );
+          }
          void notifyHireApproved(db, {
            companyId: updated.companyId,
            agentId: hireApprovedAgentId,
--- a/server/src/services/budgets.ts
+++ b/server/src/services/budgets.ts
@@ -0,0 +1,958 @@
+import { and, desc, eq, gte, inArray, lt, ne, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  agents,
+  approvals,
+  budgetIncidents,
+  budgetPolicies,
+  companies,
+  costEvents,
+  projects,
+} from "@paperclipai/db";
+import type {
+  BudgetIncident,
+  BudgetIncidentResolutionInput,
+  BudgetMetric,
+  BudgetOverview,
+  BudgetPolicy,
+  BudgetPolicySummary,
+  BudgetPolicyUpsertInput,
+  BudgetScopeType,
+  BudgetThresholdType,
+  BudgetWindowKind,
+} from "@paperclipai/shared";
+import { notFound, unprocessable } from "../errors.js";
+import { logActivity } from "./activity-log.js";
+
+type ScopeRecord = {
+  companyId: string;
+  name: string;
+  paused: boolean;
+  pauseReason: "manual" | "budget" | "system" | null;
+};
+
+type PolicyRow = typeof budgetPolicies.$inferSelect;
+type IncidentRow = typeof budgetIncidents.$inferSelect;
+
+export type BudgetEnforcementScope = {
+  companyId: string;
+  scopeType: BudgetScopeType;
+  scopeId: string;
+};
+
+export type BudgetServiceHooks = {
+  cancelWorkForScope?: (scope: BudgetEnforcementScope) => Promise<void>;
+};
+
+function currentUtcMonthWindow(now = new Date()) {
+  const year = now.getUTCFullYear();
+  const month = now.getUTCMonth();
+  const start = new Date(Date.UTC(year, month, 1, 0, 0, 0, 0));
+  const end = new Date(Date.UTC(year, month + 1, 1, 0, 0, 0, 0));
+  return { start, end };
+}
+
+function resolveWindow(windowKind: BudgetWindowKind, now = new Date()) {
+  if (windowKind === "lifetime") {
+    return {
+      start: new Date(Date.UTC(1970, 0, 1, 0, 0, 0, 0)),
+      end: new Date(Date.UTC(9999, 0, 1, 0, 0, 0, 0)),
+    };
+  }
+  return currentUtcMonthWindow(now);
+}
+
+function budgetStatusFromObserved(
+  observedAmount: number,
+  amount: number,
+  warnPercent: number,
+): BudgetPolicySummary["status"] {
+  if (amount <= 0) return "ok";
+  if (observedAmount >= amount) return "hard_stop";
+  if (observedAmount >= Math.ceil((amount * warnPercent) / 100)) return "warning";
+  return "ok";
+}
+
+function normalizeScopeName(scopeType: BudgetScopeType, name: string) {
+  if (scopeType === "company") return name;
+  return name.trim().length > 0 ? name : scopeType;
+}
+
+async function resolveScopeRecord(db: Db, scopeType: BudgetScopeType, scopeId: string): Promise<ScopeRecord> {
+  if (scopeType === "company") {
+    const row = await db
+      .select({
+        companyId: companies.id,
+        name: companies.name,
+        status: companies.status,
+        pauseReason: companies.pauseReason,
+        pausedAt: companies.pausedAt,
+      })
+      .from(companies)
+      .where(eq(companies.id, scopeId))
+      .then((rows) => rows[0] ?? null);
+    if (!row) throw notFound("Company not found");
+    return {
+      companyId: row.companyId,
+      name: row.name,
+      paused: row.status === "paused" || Boolean(row.pausedAt),
+      pauseReason: (row.pauseReason as ScopeRecord["pauseReason"]) ?? null,
+    };
+  }
+
+  if (scopeType === "agent") {
+    const row = await db
+      .select({
+        companyId: agents.companyId,
+        name: agents.name,
+        status: agents.status,
+        pauseReason: agents.pauseReason,
+      })
+      .from(agents)
+      .where(eq(agents.id, scopeId))
+      .then((rows) => rows[0] ?? null);
+    if (!row) throw notFound("Agent not found");
+    return {
+      companyId: row.companyId,
+      name: row.name,
+      paused: row.status === "paused",
+      pauseReason: (row.pauseReason as ScopeRecord["pauseReason"]) ?? null,
+    };
+  }
+
+  const row = await db
+    .select({
+      companyId: projects.companyId,
+      name: projects.name,
+      pauseReason: projects.pauseReason,
+      pausedAt: projects.pausedAt,
+    })
+    .from(projects)
+    .where(eq(projects.id, scopeId))
+    .then((rows) => rows[0] ?? null);
+  if (!row) throw notFound("Project not found");
+  return {
+    companyId: row.companyId,
+    name: row.name,
+    paused: Boolean(row.pausedAt),
+    pauseReason: (row.pauseReason as ScopeRecord["pauseReason"]) ?? null,
+  };
+}
+
+async function computeObservedAmount(
+  db: Db,
+  policy: Pick<PolicyRow, "companyId" | "scopeType" | "scopeId" | "windowKind" | "metric">,
+) {
+  if (policy.metric !== "billed_cents") return 0;
+
+  const conditions = [eq(costEvents.companyId, policy.companyId)];
+  if (policy.scopeType === "agent") conditions.push(eq(costEvents.agentId, policy.scopeId));
+  if (policy.scopeType === "project") conditions.push(eq(costEvents.projectId, policy.scopeId));
+  const { start, end } = resolveWindow(policy.windowKind as BudgetWindowKind);
+  if (policy.windowKind === "calendar_month_utc") {
+    conditions.push(gte(costEvents.occurredAt, start));
+    conditions.push(lt(costEvents.occurredAt, end));
+  }
+
+  const [row] = await db
+    .select({
+      total: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+    })
+    .from(costEvents)
+    .where(and(...conditions));
+
+  return Number(row?.total ?? 0);
+}
+
+function buildApprovalPayload(input: {
+  policy: PolicyRow;
+  scopeName: string;
+  thresholdType: BudgetThresholdType;
+  amountObserved: number;
+  windowStart: Date;
+  windowEnd: Date;
+}) {
+  return {
+    scopeType: input.policy.scopeType,
+    scopeId: input.policy.scopeId,
+    scopeName: input.scopeName,
+    metric: input.policy.metric,
+    windowKind: input.policy.windowKind,
+    thresholdType: input.thresholdType,
+    budgetAmount: input.policy.amount,
+    observedAmount: input.amountObserved,
+    warnPercent: input.policy.warnPercent,
+    windowStart: input.windowStart.toISOString(),
+    windowEnd: input.windowEnd.toISOString(),
+    policyId: input.policy.id,
+    guidance: "Raise the budget and resume the scope, or keep the scope paused.",
+  };
+}
+
+async function markApprovalStatus(
+  db: Db,
+  approvalId: string | null,
+  status: "approved" | "rejected",
+  decisionNote: string | null | undefined,
+  decidedByUserId: string,
+) {
+  if (!approvalId) return;
+  await db
+    .update(approvals)
+    .set({
+      status,
+      decisionNote: decisionNote ?? null,
+      decidedByUserId,
+      decidedAt: new Date(),
+      updatedAt: new Date(),
+    })
+    .where(eq(approvals.id, approvalId));
+}
+
+export function budgetService(db: Db, hooks: BudgetServiceHooks = {}) {
+  async function pauseScopeForBudget(policy: PolicyRow) {
+    const now = new Date();
+    if (policy.scopeType === "agent") {
+      await db
+        .update(agents)
+        .set({
+          status: "paused",
+          pauseReason: "budget",
+          pausedAt: now,
+          updatedAt: now,
+        })
+        .where(and(eq(agents.id, policy.scopeId), inArray(agents.status, ["active", "idle", "running", "error"])));
+      return;
+    }
+
+    if (policy.scopeType === "project") {
+      await db
+        .update(projects)
+        .set({
+          pauseReason: "budget",
+          pausedAt: now,
+          updatedAt: now,
+        })
+        .where(eq(projects.id, policy.scopeId));
+      return;
+    }
+
+    await db
+      .update(companies)
+      .set({
+        status: "paused",
+        pauseReason: "budget",
+        pausedAt: now,
+        updatedAt: now,
+      })
+      .where(eq(companies.id, policy.scopeId));
+  }
+
+  async function pauseAndCancelScopeForBudget(policy: PolicyRow) {
+    await pauseScopeForBudget(policy);
+    await hooks.cancelWorkForScope?.({
+      companyId: policy.companyId,
+      scopeType: policy.scopeType as BudgetScopeType,
+      scopeId: policy.scopeId,
+    });
+  }
+
+  async function resumeScopeFromBudget(policy: PolicyRow) {
+    const now = new Date();
+    if (policy.scopeType === "agent") {
+      await db
+        .update(agents)
+        .set({
+          status: "idle",
+          pauseReason: null,
+          pausedAt: null,
+          updatedAt: now,
+        })
+        .where(and(eq(agents.id, policy.scopeId), eq(agents.pauseReason, "budget")));
+      return;
+    }
+
+    if (policy.scopeType === "project") {
+      await db
+        .update(projects)
+        .set({
+          pauseReason: null,
+          pausedAt: null,
+          updatedAt: now,
+        })
+        .where(and(eq(projects.id, policy.scopeId), eq(projects.pauseReason, "budget")));
+      return;
+    }
+
+    await db
+      .update(companies)
+      .set({
+        status: "active",
+        pauseReason: null,
+        pausedAt: null,
+        updatedAt: now,
+      })
+      .where(and(eq(companies.id, policy.scopeId), eq(companies.pauseReason, "budget")));
+  }
+
+  async function getPolicyRow(policyId: string) {
+    const policy = await db
+      .select()
+      .from(budgetPolicies)
+      .where(eq(budgetPolicies.id, policyId))
+      .then((rows) => rows[0] ?? null);
+    if (!policy) throw notFound("Budget policy not found");
+    return policy;
+  }
+
+  async function listPolicyRows(companyId: string) {
+    return db
+      .select()
+      .from(budgetPolicies)
+      .where(eq(budgetPolicies.companyId, companyId))
+      .orderBy(desc(budgetPolicies.updatedAt));
+  }
+
+  async function buildPolicySummary(policy: PolicyRow): Promise<BudgetPolicySummary> {
+    const scope = await resolveScopeRecord(db, policy.scopeType as BudgetScopeType, policy.scopeId);
+    const observedAmount = await computeObservedAmount(db, policy);
+    const { start, end } = resolveWindow(policy.windowKind as BudgetWindowKind);
+    const amount = policy.isActive ? policy.amount : 0;
+    const utilizationPercent =
+      amount > 0 ? Number(((observedAmount / amount) * 100).toFixed(2)) : 0;
+    return {
+      policyId: policy.id,
+      companyId: policy.companyId,
+      scopeType: policy.scopeType as BudgetScopeType,
+      scopeId: policy.scopeId,
+      scopeName: normalizeScopeName(policy.scopeType as BudgetScopeType, scope.name),
+      metric: policy.metric as BudgetMetric,
+      windowKind: policy.windowKind as BudgetWindowKind,
+      amount,
+      observedAmount,
+      remainingAmount: amount > 0 ? Math.max(0, amount - observedAmount) : 0,
+      utilizationPercent,
+      warnPercent: policy.warnPercent,
+      hardStopEnabled: policy.hardStopEnabled,
+      notifyEnabled: policy.notifyEnabled,
+      isActive: policy.isActive,
+      status: policy.isActive
+        ? budgetStatusFromObserved(observedAmount, amount, policy.warnPercent)
+        : "ok",
+      paused: scope.paused,
+      pauseReason: scope.pauseReason,
+      windowStart: start,
+      windowEnd: end,
+    };
+  }
+
+  async function createIncidentIfNeeded(
+    policy: PolicyRow,
+    thresholdType: BudgetThresholdType,
+    amountObserved: number,
+  ) {
+    const { start, end } = resolveWindow(policy.windowKind as BudgetWindowKind);
+    const existing = await db
+      .select()
+      .from(budgetIncidents)
+      .where(
+        and(
+          eq(budgetIncidents.policyId, policy.id),
+          eq(budgetIncidents.windowStart, start),
+          eq(budgetIncidents.thresholdType, thresholdType),
+          ne(budgetIncidents.status, "dismissed"),
+        ),
+      )
+      .then((rows) => rows[0] ?? null);
+    if (existing) return existing;
+
+    const scope = await resolveScopeRecord(db, policy.scopeType as BudgetScopeType, policy.scopeId);
+    const payload = buildApprovalPayload({
+      policy,
+      scopeName: normalizeScopeName(policy.scopeType as BudgetScopeType, scope.name),
+      thresholdType,
+      amountObserved,
+      windowStart: start,
+      windowEnd: end,
+    });
+
+    const approval = thresholdType === "hard"
+      ? await db
+        .insert(approvals)
+        .values({
+          companyId: policy.companyId,
+          type: "budget_override_required",
+          requestedByUserId: null,
+          requestedByAgentId: null,
+          status: "pending",
+          payload,
+        })
+        .returning()
+        .then((rows) => rows[0] ?? null)
+      : null;
+
+    return db
+      .insert(budgetIncidents)
+      .values({
+        companyId: policy.companyId,
+        policyId: policy.id,
+        scopeType: policy.scopeType,
+        scopeId: policy.scopeId,
+        metric: policy.metric,
+        windowKind: policy.windowKind,
+        windowStart: start,
+        windowEnd: end,
+        thresholdType,
+        amountLimit: policy.amount,
+        amountObserved,
+        status: "open",
+        approvalId: approval?.id ?? null,
+      })
+      .returning()
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function resolveOpenSoftIncidents(policyId: string) {
+    await db
+      .update(budgetIncidents)
+      .set({
+        status: "resolved",
+        resolvedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(budgetIncidents.policyId, policyId),
+          eq(budgetIncidents.thresholdType, "soft"),
+          eq(budgetIncidents.status, "open"),
+        ),
+      );
+  }
+
+  async function resolveOpenIncidentsForPolicy(
+    policyId: string,
+    approvalStatus: "approved" | "rejected" | null,
+    decidedByUserId: string | null,
+  ) {
+    const openRows = await db
+      .select()
+      .from(budgetIncidents)
+      .where(and(eq(budgetIncidents.policyId, policyId), eq(budgetIncidents.status, "open")));
+
+    await db
+      .update(budgetIncidents)
+      .set({
+        status: "resolved",
+        resolvedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(and(eq(budgetIncidents.policyId, policyId), eq(budgetIncidents.status, "open")));
+
+    if (!approvalStatus || !decidedByUserId) return;
+    for (const row of openRows) {
+      await markApprovalStatus(db, row.approvalId ?? null, approvalStatus, "Resolved via budget update", decidedByUserId);
+    }
+  }
+
+  async function hydrateIncidentRows(rows: IncidentRow[]): Promise<BudgetIncident[]> {
+    const approvalIds = rows.map((row) => row.approvalId).filter((value): value is string => Boolean(value));
+    const approvalRows = approvalIds.length > 0
+      ? await db
+        .select({ id: approvals.id, status: approvals.status })
+        .from(approvals)
+        .where(inArray(approvals.id, approvalIds))
+      : [];
+    const approvalStatusById = new Map(approvalRows.map((row) => [row.id, row.status]));
+
+    return Promise.all(
+      rows.map(async (row) => {
+        const scope = await resolveScopeRecord(db, row.scopeType as BudgetScopeType, row.scopeId);
+        return {
+          id: row.id,
+          companyId: row.companyId,
+          policyId: row.policyId,
+          scopeType: row.scopeType as BudgetScopeType,
+          scopeId: row.scopeId,
+          scopeName: normalizeScopeName(row.scopeType as BudgetScopeType, scope.name),
+          metric: row.metric as BudgetMetric,
+          windowKind: row.windowKind as BudgetWindowKind,
+          windowStart: row.windowStart,
+          windowEnd: row.windowEnd,
+          thresholdType: row.thresholdType as BudgetThresholdType,
+          amountLimit: row.amountLimit,
+          amountObserved: row.amountObserved,
+          status: row.status as BudgetIncident["status"],
+          approvalId: row.approvalId ?? null,
+          approvalStatus: row.approvalId ? approvalStatusById.get(row.approvalId) ?? null : null,
+          resolvedAt: row.resolvedAt ?? null,
+          createdAt: row.createdAt,
+          updatedAt: row.updatedAt,
+        };
+      }),
+    );
+  }
+
+  return {
+    listPolicies: async (companyId: string): Promise<BudgetPolicy[]> => {
+      const rows = await listPolicyRows(companyId);
+      return rows.map((row) => ({
+        ...row,
+        scopeType: row.scopeType as BudgetScopeType,
+        metric: row.metric as BudgetMetric,
+        windowKind: row.windowKind as BudgetWindowKind,
+      }));
+    },
+
+    upsertPolicy: async (
+      companyId: string,
+      input: BudgetPolicyUpsertInput,
+      actorUserId: string | null,
+    ): Promise<BudgetPolicySummary> => {
+      const scope = await resolveScopeRecord(db, input.scopeType, input.scopeId);
+      if (scope.companyId !== companyId) {
+        throw unprocessable("Budget scope does not belong to company");
+      }
+
+      const metric = input.metric ?? "billed_cents";
+      const windowKind = input.windowKind ?? (input.scopeType === "project" ? "lifetime" : "calendar_month_utc");
+      const amount = Math.max(0, Math.floor(input.amount));
+      const nextIsActive = amount > 0 && (input.isActive ?? true);
+      const existing = await db
+        .select()
+        .from(budgetPolicies)
+        .where(
+          and(
+            eq(budgetPolicies.companyId, companyId),
+            eq(budgetPolicies.scopeType, input.scopeType),
+            eq(budgetPolicies.scopeId, input.scopeId),
+            eq(budgetPolicies.metric, metric),
+            eq(budgetPolicies.windowKind, windowKind),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+
+      const now = new Date();
+      const row = existing
+        ? await db
+          .update(budgetPolicies)
+          .set({
+            amount,
+            warnPercent: input.warnPercent ?? existing.warnPercent,
+            hardStopEnabled: input.hardStopEnabled ?? existing.hardStopEnabled,
+            notifyEnabled: input.notifyEnabled ?? existing.notifyEnabled,
+            isActive: nextIsActive,
+            updatedByUserId: actorUserId,
+            updatedAt: now,
+          })
+          .where(eq(budgetPolicies.id, existing.id))
+          .returning()
+          .then((rows) => rows[0])
+        : await db
+          .insert(budgetPolicies)
+          .values({
+            companyId,
+            scopeType: input.scopeType,
+            scopeId: input.scopeId,
+            metric,
+            windowKind,
+            amount,
+            warnPercent: input.warnPercent ?? 80,
+            hardStopEnabled: input.hardStopEnabled ?? true,
+            notifyEnabled: input.notifyEnabled ?? true,
+            isActive: nextIsActive,
+            createdByUserId: actorUserId,
+            updatedByUserId: actorUserId,
+          })
+          .returning()
+          .then((rows) => rows[0]);
+
+      if (input.scopeType === "company" && windowKind === "calendar_month_utc") {
+        await db
+          .update(companies)
+          .set({
+            budgetMonthlyCents: amount,
+            updatedAt: now,
+          })
+          .where(eq(companies.id, input.scopeId));
+      }
+
+      if (input.scopeType === "agent" && windowKind === "calendar_month_utc") {
+        await db
+          .update(agents)
+          .set({
+            budgetMonthlyCents: amount,
+            updatedAt: now,
+          })
+          .where(eq(agents.id, input.scopeId));
+      }
+
+      if (amount > 0) {
+        const observedAmount = await computeObservedAmount(db, row);
+        if (observedAmount < amount) {
+          await resumeScopeFromBudget(row);
+          await resolveOpenIncidentsForPolicy(row.id, actorUserId ? "approved" : null, actorUserId);
+        } else {
+          const softThreshold = Math.ceil((row.amount * row.warnPercent) / 100);
+          if (row.notifyEnabled && observedAmount >= softThreshold) {
+            await createIncidentIfNeeded(row, "soft", observedAmount);
+          }
+          if (row.hardStopEnabled && observedAmount >= row.amount) {
+            await resolveOpenSoftIncidents(row.id);
+            await createIncidentIfNeeded(row, "hard", observedAmount);
+            await pauseAndCancelScopeForBudget(row);
+          }
+        }
+      } else {
+        await resumeScopeFromBudget(row);
+        await resolveOpenIncidentsForPolicy(row.id, actorUserId ? "approved" : null, actorUserId);
+      }
+
+      await logActivity(db, {
+        companyId,
+        actorType: "user",
+        actorId: actorUserId ?? "board",
+        action: "budget.policy_upserted",
+        entityType: "budget_policy",
+        entityId: row.id,
+        details: {
+          scopeType: row.scopeType,
+          scopeId: row.scopeId,
+          amount: row.amount,
+          windowKind: row.windowKind,
+        },
+      });
+
+      return buildPolicySummary(row);
+    },
+
+    overview: async (companyId: string): Promise<BudgetOverview> => {
+      const rows = await listPolicyRows(companyId);
+      const policies = await Promise.all(rows.map((row) => buildPolicySummary(row)));
+      const activeIncidentRows = await db
+        .select()
+        .from(budgetIncidents)
+        .where(and(eq(budgetIncidents.companyId, companyId), eq(budgetIncidents.status, "open")))
+        .orderBy(desc(budgetIncidents.createdAt));
+      const activeIncidents = await hydrateIncidentRows(activeIncidentRows);
+      return {
+        companyId,
+        policies,
+        activeIncidents,
+        pausedAgentCount: policies.filter((policy) => policy.scopeType === "agent" && policy.paused).length,
+        pausedProjectCount: policies.filter((policy) => policy.scopeType === "project" && policy.paused).length,
+        pendingApprovalCount: activeIncidents.filter((incident) => incident.approvalStatus === "pending").length,
+      };
+    },
+
+    evaluateCostEvent: async (event: typeof costEvents.$inferSelect) => {
+      const candidatePolicies = await db
+        .select()
+        .from(budgetPolicies)
+        .where(
+          and(
+            eq(budgetPolicies.companyId, event.companyId),
+            eq(budgetPolicies.isActive, true),
+            inArray(budgetPolicies.scopeType, ["company", "agent", "project"]),
+          ),
+        );
+
+      const relevantPolicies = candidatePolicies.filter((policy) => {
+        if (policy.scopeType === "company") return policy.scopeId === event.companyId;
+        if (policy.scopeType === "agent") return policy.scopeId === event.agentId;
+        if (policy.scopeType === "project") return Boolean(event.projectId) && policy.scopeId === event.projectId;
+        return false;
+      });
+
+      for (const policy of relevantPolicies) {
+        if (policy.metric !== "billed_cents" || policy.amount <= 0) continue;
+        const observedAmount = await computeObservedAmount(db, policy);
+        const softThreshold = Math.ceil((policy.amount * policy.warnPercent) / 100);
+
+        if (policy.notifyEnabled && observedAmount >= softThreshold) {
+          const softIncident = await createIncidentIfNeeded(policy, "soft", observedAmount);
+          if (softIncident) {
+            await logActivity(db, {
+              companyId: policy.companyId,
+              actorType: "system",
+              actorId: "budget_service",
+              action: "budget.soft_threshold_crossed",
+              entityType: "budget_incident",
+              entityId: softIncident.id,
+              details: {
+                scopeType: policy.scopeType,
+                scopeId: policy.scopeId,
+                amountObserved: observedAmount,
+                amountLimit: policy.amount,
+              },
+            });
+          }
+        }
+
+        if (policy.hardStopEnabled && observedAmount >= policy.amount) {
+          await resolveOpenSoftIncidents(policy.id);
+          const hardIncident = await createIncidentIfNeeded(policy, "hard", observedAmount);
+          await pauseAndCancelScopeForBudget(policy);
+          if (hardIncident) {
+            await logActivity(db, {
+              companyId: policy.companyId,
+              actorType: "system",
+              actorId: "budget_service",
+              action: "budget.hard_threshold_crossed",
+              entityType: "budget_incident",
+              entityId: hardIncident.id,
+              details: {
+                scopeType: policy.scopeType,
+                scopeId: policy.scopeId,
+                amountObserved: observedAmount,
+                amountLimit: policy.amount,
+                approvalId: hardIncident.approvalId ?? null,
+              },
+            });
+          }
+        }
+      }
+    },
+
+    getInvocationBlock: async (
+      companyId: string,
+      agentId: string,
+      context?: { issueId?: string | null; projectId?: string | null },
+    ) => {
+      const agent = await db
+        .select({
+          status: agents.status,
+          pauseReason: agents.pauseReason,
+          companyId: agents.companyId,
+          name: agents.name,
+        })
+        .from(agents)
+        .where(eq(agents.id, agentId))
+        .then((rows) => rows[0] ?? null);
+      if (!agent || agent.companyId !== companyId) throw notFound("Agent not found");
+
+      const company = await db
+        .select({
+          status: companies.status,
+          pauseReason: companies.pauseReason,
+          name: companies.name,
+        })
+        .from(companies)
+        .where(eq(companies.id, companyId))
+        .then((rows) => rows[0] ?? null);
+      if (!company) throw notFound("Company not found");
+      if (company.status === "paused") {
+        return {
+          scopeType: "company" as const,
+          scopeId: companyId,
+          scopeName: company.name,
+          reason:
+            company.pauseReason === "budget"
+              ? "Company is paused because its budget hard-stop was reached."
+              : "Company is paused and cannot start new work.",
+        };
+      }
+
+      const companyPolicy = await db
+        .select()
+        .from(budgetPolicies)
+        .where(
+          and(
+            eq(budgetPolicies.companyId, companyId),
+            eq(budgetPolicies.scopeType, "company"),
+            eq(budgetPolicies.scopeId, companyId),
+            eq(budgetPolicies.isActive, true),
+            eq(budgetPolicies.metric, "billed_cents"),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+      if (companyPolicy && companyPolicy.hardStopEnabled && companyPolicy.amount > 0) {
+        const observed = await computeObservedAmount(db, companyPolicy);
+        if (observed >= companyPolicy.amount) {
+          return {
+            scopeType: "company" as const,
+            scopeId: companyId,
+            scopeName: company.name,
+            reason: "Company cannot start new work because its budget hard-stop is exceeded.",
+          };
+        }
+      }
+
+      if (agent.status === "paused" && agent.pauseReason === "budget") {
+        return {
+          scopeType: "agent" as const,
+          scopeId: agentId,
+          scopeName: agent.name,
+          reason: "Agent is paused because its budget hard-stop was reached.",
+        };
+      }
+
+      const agentPolicy = await db
+        .select()
+        .from(budgetPolicies)
+        .where(
+          and(
+            eq(budgetPolicies.companyId, companyId),
+            eq(budgetPolicies.scopeType, "agent"),
+            eq(budgetPolicies.scopeId, agentId),
+            eq(budgetPolicies.isActive, true),
+            eq(budgetPolicies.metric, "billed_cents"),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+      if (agentPolicy && agentPolicy.hardStopEnabled && agentPolicy.amount > 0) {
+        const observed = await computeObservedAmount(db, agentPolicy);
+        if (observed >= agentPolicy.amount) {
+          return {
+            scopeType: "agent" as const,
+            scopeId: agentId,
+            scopeName: agent.name,
+            reason: "Agent cannot start because its budget hard-stop is still exceeded.",
+          };
+        }
+      }
+
+      const candidateProjectId = context?.projectId ?? null;
+      if (!candidateProjectId) return null;
+
+      const project = await db
+        .select({
+          id: projects.id,
+          name: projects.name,
+          companyId: projects.companyId,
+          pauseReason: projects.pauseReason,
+          pausedAt: projects.pausedAt,
+        })
+        .from(projects)
+        .where(eq(projects.id, candidateProjectId))
+        .then((rows) => rows[0] ?? null);
+
+      if (!project || project.companyId !== companyId) return null;
+      const projectPolicy = await db
+        .select()
+        .from(budgetPolicies)
+        .where(
+          and(
+            eq(budgetPolicies.companyId, companyId),
+            eq(budgetPolicies.scopeType, "project"),
+            eq(budgetPolicies.scopeId, project.id),
+            eq(budgetPolicies.isActive, true),
+            eq(budgetPolicies.metric, "billed_cents"),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+      if (projectPolicy && projectPolicy.hardStopEnabled && projectPolicy.amount > 0) {
+        const observed = await computeObservedAmount(db, projectPolicy);
+        if (observed >= projectPolicy.amount) {
+          return {
+            scopeType: "project" as const,
+            scopeId: project.id,
+            scopeName: project.name,
+            reason: "Project cannot start work because its budget hard-stop is still exceeded.",
+          };
+        }
+      }
+
+      if (!project.pausedAt || project.pauseReason !== "budget") return null;
+      return {
+        scopeType: "project" as const,
+        scopeId: project.id,
+        scopeName: project.name,
+        reason: "Project is paused because its budget hard-stop was reached.",
+      };
+    },
+
+    resolveIncident: async (
+      companyId: string,
+      incidentId: string,
+      input: BudgetIncidentResolutionInput,
+      actorUserId: string,
+    ): Promise<BudgetIncident> => {
+      const incident = await db
+        .select()
+        .from(budgetIncidents)
+        .where(eq(budgetIncidents.id, incidentId))
+        .then((rows) => rows[0] ?? null);
+      if (!incident) throw notFound("Budget incident not found");
+      if (incident.companyId !== companyId) throw notFound("Budget incident not found");
+
+      const policy = await getPolicyRow(incident.policyId);
+      if (input.action === "raise_budget_and_resume") {
+        const nextAmount = Math.max(0, Math.floor(input.amount ?? 0));
+        const currentObserved = await computeObservedAmount(db, policy);
+        if (nextAmount <= currentObserved) {
+          throw unprocessable("New budget must exceed current observed spend");
+        }
+
+        const now = new Date();
+        await db
+          .update(budgetPolicies)
+          .set({
+            amount: nextAmount,
+            isActive: true,
+            updatedByUserId: actorUserId,
+            updatedAt: now,
+          })
+          .where(eq(budgetPolicies.id, policy.id));
+
+        if (policy.scopeType === "company" && policy.windowKind === "calendar_month_utc") {
+          await db
+            .update(companies)
+            .set({ budgetMonthlyCents: nextAmount, updatedAt: now })
+            .where(eq(companies.id, policy.scopeId));
+        }
+
+        if (policy.scopeType === "agent" && policy.windowKind === "calendar_month_utc") {
+          await db
+            .update(agents)
+            .set({ budgetMonthlyCents: nextAmount, updatedAt: now })
+            .where(eq(agents.id, policy.scopeId));
+        }
+
+        await resumeScopeFromBudget(policy);
+        await db
+          .update(budgetIncidents)
+          .set({
+            status: "resolved",
+            resolvedAt: now,
+            updatedAt: now,
+          })
+          .where(and(eq(budgetIncidents.policyId, policy.id), eq(budgetIncidents.status, "open")));
+
+        await markApprovalStatus(db, incident.approvalId ?? null, "approved", input.decisionNote, actorUserId);
+      } else {
+        await db
+          .update(budgetIncidents)
+          .set({
+            status: "dismissed",
+            resolvedAt: new Date(),
+            updatedAt: new Date(),
+          })
+          .where(eq(budgetIncidents.id, incident.id));
+        await markApprovalStatus(db, incident.approvalId ?? null, "rejected", input.decisionNote, actorUserId);
+      }
+
+      await logActivity(db, {
+        companyId: incident.companyId,
+        actorType: "user",
+        actorId: actorUserId,
+        action: "budget.incident_resolved",
+        entityType: "budget_incident",
+        entityId: incident.id,
+        details: {
+          action: input.action,
+          amount: input.amount ?? null,
+          scopeType: incident.scopeType,
+          scopeId: incident.scopeId,
+        },
+      });
+
+      const [updated] = await hydrateIncidentRows([{
+        ...incident,
+        status: input.action === "raise_budget_and_resume" ? "resolved" : "dismissed",
+        resolvedAt: new Date(),
+        updatedAt: new Date(),
+      }]);
+      return updated!;
+    },
+  };
+}
--- a/server/src/services/companies.ts
+++ b/server/src/services/companies.ts
@@ -1,4 +1,4 @@
-import { eq, count } from "drizzle-orm";
+import { and, count, eq, gte, inArray, lt, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
  companies,
@@ -16,6 +16,7 @@ import {
  heartbeatRuns,
  heartbeatRunEvents,
  costEvents,
+  financeEvents,
  approvalComments,
  approvals,
  activityLog,
@@ -53,6 +54,49 @@ export function companyService(db: Db) {
    };
  }

+  function currentUtcMonthWindow(now = new Date()) {
+    const year = now.getUTCFullYear();
+    const month = now.getUTCMonth();
+    return {
+      start: new Date(Date.UTC(year, month, 1, 0, 0, 0, 0)),
+      end: new Date(Date.UTC(year, month + 1, 1, 0, 0, 0, 0)),
+    };
+  }
+
+  async function getMonthlySpendByCompanyIds(
+    companyIds: string[],
+    database: Pick<Db, "select"> = db,
+  ) {
+    if (companyIds.length === 0) return new Map<string, number>();
+    const { start, end } = currentUtcMonthWindow();
+    const rows = await database
+      .select({
+        companyId: costEvents.companyId,
+        spentMonthlyCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+      })
+      .from(costEvents)
+      .where(
+        and(
+          inArray(costEvents.companyId, companyIds),
+          gte(costEvents.occurredAt, start),
+          lt(costEvents.occurredAt, end),
+        ),
+      )
+      .groupBy(costEvents.companyId);
+    return new Map(rows.map((row) => [row.companyId, Number(row.spentMonthlyCents ?? 0)]));
+  }
+
+  async function hydrateCompanySpend<T extends { id: string; spentMonthlyCents: number }>(
+    rows: T[],
+    database: Pick<Db, "select"> = db,
+  ) {
+    const spendByCompanyId = await getMonthlySpendByCompanyIds(rows.map((row) => row.id), database);
+    return rows.map((row) => ({
+      ...row,
+      spentMonthlyCents: spendByCompanyId.get(row.id) ?? 0,
+    }));
+  }
+
  function getCompanyQuery(database: Pick<Db, "select">) {
    return database
      .select(companySelection)
@@ -103,13 +147,20 @@ export function companyService(db: Db) {
  }

  return {
-    list: () =>
-      getCompanyQuery(db).then((rows) => rows.map((row) => enrichCompany(row))),
+    list: async () => {
+      const rows = await getCompanyQuery(db);
+      const hydrated = await hydrateCompanySpend(rows);
+      return hydrated.map((row) => enrichCompany(row));
+    },

-    getById: (id: string) =>
-      getCompanyQuery(db)
+    getById: async (id: string) => {
+      const row = await getCompanyQuery(db)
        .where(eq(companies.id, id))
-        .then((rows) => (rows[0] ? enrichCompany(rows[0]) : null)),
+        .then((rows) => rows[0] ?? null);
+      if (!row) return null;
+      const [hydrated] = await hydrateCompanySpend([row], db);
+      return enrichCompany(hydrated);
+    },

    create: async (data: typeof companies.$inferInsert) => {
      const created = await createCompanyWithUniquePrefix(data);
@@ -117,7 +168,8 @@ export function companyService(db: Db) {
        .where(eq(companies.id, created.id))
        .then((rows) => rows[0] ?? null);
      if (!row) throw notFound("Company not found after creation");
-      return enrichCompany(row);
+      const [hydrated] = await hydrateCompanySpend([row], db);
+      return enrichCompany(hydrated);
    },

    update: (
@@ -174,10 +226,12 @@ export function companyService(db: Db) {
          await tx.delete(assets).where(eq(assets.id, existing.logoAssetId));
        }

-        return enrichCompany({
+        const [hydrated] = await hydrateCompanySpend([{
          ...updated,
          logoAssetId: logoAssetId === undefined ? existing.logoAssetId : logoAssetId,
-        });
+        }], tx);
+
+        return enrichCompany(hydrated);
      }),

    archive: (id: string) =>
@@ -192,7 +246,9 @@ export function companyService(db: Db) {
        const row = await getCompanyQuery(tx)
          .where(eq(companies.id, id))
          .then((rows) => rows[0] ?? null);
-        return row ? enrichCompany(row) : null;
+        if (!row) return null;
+        const [hydrated] = await hydrateCompanySpend([row], tx);
+        return enrichCompany(hydrated);
      }),

    remove: (id: string) =>
@@ -206,6 +262,7 @@ export function companyService(db: Db) {
        await tx.delete(agentRuntimeState).where(eq(agentRuntimeState.companyId, id));
        await tx.delete(issueComments).where(eq(issueComments.companyId, id));
        await tx.delete(costEvents).where(eq(costEvents.companyId, id));
+        await tx.delete(financeEvents).where(eq(financeEvents.companyId, id));
        await tx.delete(approvalComments).where(eq(approvalComments.companyId, id));
        await tx.delete(approvals).where(eq(approvals.companyId, id));
        await tx.delete(companySecrets).where(eq(companySecrets.companyId, id));
--- a/server/src/services/costs.ts
+++ b/server/src/services/costs.ts
@@ -1,14 +1,50 @@
-import { and, desc, eq, gte, isNotNull, lte, sql } from "drizzle-orm";
+import { and, desc, eq, gte, isNotNull, lt, lte, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import { activityLog, agents, companies, costEvents, heartbeatRuns, issues, projects } from "@paperclipai/db";
+import { activityLog, agents, companies, costEvents, issues, projects } from "@paperclipai/db";
 import { notFound, unprocessable } from "../errors.js";
+import { budgetService, type BudgetServiceHooks } from "./budgets.js";

 export interface CostDateRange {
  from?: Date;
  to?: Date;
 }

-export function costService(db: Db) {
+const METERED_BILLING_TYPE = "metered_api";
+const SUBSCRIPTION_BILLING_TYPES = ["subscription_included", "subscription_overage"] as const;
+
+function currentUtcMonthWindow(now = new Date()) {
+  const year = now.getUTCFullYear();
+  const month = now.getUTCMonth();
+  return {
+    start: new Date(Date.UTC(year, month, 1, 0, 0, 0, 0)),
+    end: new Date(Date.UTC(year, month + 1, 1, 0, 0, 0, 0)),
+  };
+}
+
+async function getMonthlySpendTotal(
+  db: Db,
+  scope: { companyId: string; agentId?: string | null },
+) {
+  const { start, end } = currentUtcMonthWindow();
+  const conditions = [
+    eq(costEvents.companyId, scope.companyId),
+    gte(costEvents.occurredAt, start),
+    lt(costEvents.occurredAt, end),
+  ];
+  if (scope.agentId) {
+    conditions.push(eq(costEvents.agentId, scope.agentId));
+  }
+  const [row] = await db
+    .select({
+      total: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+    })
+    .from(costEvents)
+    .where(and(...conditions));
+  return Number(row?.total ?? 0);
+}
+
+export function costService(db: Db, budgetHooks: BudgetServiceHooks = {}) {
+  const budgets = budgetService(db, budgetHooks);
  return {
    createEvent: async (companyId: string, data: Omit<typeof costEvents.$inferInsert, "companyId">) => {
      const agent = await db
@@ -24,14 +60,25 @@ export function costService(db: Db) {

      const event = await db
        .insert(costEvents)
-        .values({ ...data, companyId })
+        .values({
+          ...data,
+          companyId,
+          biller: data.biller ?? data.provider,
+          billingType: data.billingType ?? "unknown",
+          cachedInputTokens: data.cachedInputTokens ?? 0,
+        })
        .returning()
        .then((rows) => rows[0]);

+      const [agentMonthSpend, companyMonthSpend] = await Promise.all([
+        getMonthlySpendTotal(db, { companyId, agentId: event.agentId }),
+        getMonthlySpendTotal(db, { companyId }),
+      ]);
+
      await db
        .update(agents)
        .set({
-          spentMonthlyCents: sql`${agents.spentMonthlyCents} + ${event.costCents}`,
+          spentMonthlyCents: agentMonthSpend,
          updatedAt: new Date(),
        })
        .where(eq(agents.id, event.agentId));
@@ -39,29 +86,12 @@ export function costService(db: Db) {
      await db
        .update(companies)
        .set({
-          spentMonthlyCents: sql`${companies.spentMonthlyCents} + ${event.costCents}`,
+          spentMonthlyCents: companyMonthSpend,
          updatedAt: new Date(),
        })
        .where(eq(companies.id, companyId));

-      const updatedAgent = await db
-        .select()
-        .from(agents)
-        .where(eq(agents.id, event.agentId))
-        .then((rows) => rows[0] ?? null);
-
-      if (
-        updatedAgent &&
-        updatedAgent.budgetMonthlyCents > 0 &&
-        updatedAgent.spentMonthlyCents >= updatedAgent.budgetMonthlyCents &&
-        updatedAgent.status !== "paused" &&
-        updatedAgent.status !== "terminated"
-      ) {
-        await db
-          .update(agents)
-          .set({ status: "paused", updatedAt: new Date() })
-          .where(eq(agents.id, updatedAgent.id));
-      }
+      await budgets.evaluateCostEvent(event);

      return event;
    },
@@ -105,52 +135,180 @@ export function costService(db: Db) {
      if (range?.from) conditions.push(gte(costEvents.occurredAt, range.from));
      if (range?.to) conditions.push(lte(costEvents.occurredAt, range.to));

-      const costRows = await db
+      return db
        .select({
          agentId: costEvents.agentId,
          agentName: agents.name,
          agentStatus: agents.status,
          costCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
          inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::int`,
+          cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::int`,
          outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::int`,
+          apiRunCount:
+            sql<number>`count(distinct case when ${costEvents.billingType} = ${METERED_BILLING_TYPE} then ${costEvents.heartbeatRunId} end)::int`,
+          subscriptionRunCount:
+            sql<number>`count(distinct case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.heartbeatRunId} end)::int`,
+          subscriptionCachedInputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.cachedInputTokens} else 0 end), 0)::int`,
+          subscriptionInputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.inputTokens} else 0 end), 0)::int`,
+          subscriptionOutputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.outputTokens} else 0 end), 0)::int`,
        })
        .from(costEvents)
        .leftJoin(agents, eq(costEvents.agentId, agents.id))
        .where(and(...conditions))
        .groupBy(costEvents.agentId, agents.name, agents.status)
        .orderBy(desc(sql`coalesce(sum(${costEvents.costCents}), 0)::int`));
+    },

-      const runConditions: ReturnType<typeof eq>[] = [eq(heartbeatRuns.companyId, companyId)];
-      if (range?.from) runConditions.push(gte(heartbeatRuns.finishedAt, range.from));
-      if (range?.to) runConditions.push(lte(heartbeatRuns.finishedAt, range.to));
+    byProvider: async (companyId: string, range?: CostDateRange) => {
+      const conditions: ReturnType<typeof eq>[] = [eq(costEvents.companyId, companyId)];
+      if (range?.from) conditions.push(gte(costEvents.occurredAt, range.from));
+      if (range?.to) conditions.push(lte(costEvents.occurredAt, range.to));

-      const runRows = await db
+      return db
        .select({
-          agentId: heartbeatRuns.agentId,
+          provider: costEvents.provider,
+          biller: costEvents.biller,
+          billingType: costEvents.billingType,
+          model: costEvents.model,
+          costCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+          inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::int`,
+          cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::int`,
+          outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::int`,
          apiRunCount:
-            sql<number>`coalesce(sum(case when coalesce((${heartbeatRuns.usageJson} ->> 'billingType'), 'unknown') = 'api' then 1 else 0 end), 0)::int`,
+            sql<number>`count(distinct case when ${costEvents.billingType} = ${METERED_BILLING_TYPE} then ${costEvents.heartbeatRunId} end)::int`,
          subscriptionRunCount:
-            sql<number>`coalesce(sum(case when coalesce((${heartbeatRuns.usageJson} ->> 'billingType'), 'unknown') = 'subscription' then 1 else 0 end), 0)::int`,
+            sql<number>`count(distinct case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.heartbeatRunId} end)::int`,
+          subscriptionCachedInputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.cachedInputTokens} else 0 end), 0)::int`,
          subscriptionInputTokens:
-            sql<number>`coalesce(sum(case when coalesce((${heartbeatRuns.usageJson} ->> 'billingType'), 'unknown') = 'subscription' then coalesce((${heartbeatRuns.usageJson} ->> 'inputTokens')::int, 0) else 0 end), 0)::int`,
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.inputTokens} else 0 end), 0)::int`,
          subscriptionOutputTokens:
-            sql<number>`coalesce(sum(case when coalesce((${heartbeatRuns.usageJson} ->> 'billingType'), 'unknown') = 'subscription' then coalesce((${heartbeatRuns.usageJson} ->> 'outputTokens')::int, 0) else 0 end), 0)::int`,
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.outputTokens} else 0 end), 0)::int`,
        })
-        .from(heartbeatRuns)
-        .where(and(...runConditions))
-        .groupBy(heartbeatRuns.agentId);
+        .from(costEvents)
+        .where(and(...conditions))
+        .groupBy(costEvents.provider, costEvents.biller, costEvents.billingType, costEvents.model)
+        .orderBy(desc(sql`coalesce(sum(${costEvents.costCents}), 0)::int`));
+    },

-      const runRowsByAgent = new Map(runRows.map((row) => [row.agentId, row]));
-      return costRows.map((row) => {
-        const runRow = runRowsByAgent.get(row.agentId);
-        return {
-          ...row,
-          apiRunCount: runRow?.apiRunCount ?? 0,
-          subscriptionRunCount: runRow?.subscriptionRunCount ?? 0,
-          subscriptionInputTokens: runRow?.subscriptionInputTokens ?? 0,
-          subscriptionOutputTokens: runRow?.subscriptionOutputTokens ?? 0,
-        };
-      });
+    byBiller: async (companyId: string, range?: CostDateRange) => {
+      const conditions: ReturnType<typeof eq>[] = [eq(costEvents.companyId, companyId)];
+      if (range?.from) conditions.push(gte(costEvents.occurredAt, range.from));
+      if (range?.to) conditions.push(lte(costEvents.occurredAt, range.to));
+
+      return db
+        .select({
+          biller: costEvents.biller,
+          costCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+          inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::int`,
+          cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::int`,
+          outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::int`,
+          apiRunCount:
+            sql<number>`count(distinct case when ${costEvents.billingType} = ${METERED_BILLING_TYPE} then ${costEvents.heartbeatRunId} end)::int`,
+          subscriptionRunCount:
+            sql<number>`count(distinct case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.heartbeatRunId} end)::int`,
+          subscriptionCachedInputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.cachedInputTokens} else 0 end), 0)::int`,
+          subscriptionInputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.inputTokens} else 0 end), 0)::int`,
+          subscriptionOutputTokens:
+            sql<number>`coalesce(sum(case when ${costEvents.billingType} in (${sql.join(SUBSCRIPTION_BILLING_TYPES.map((value) => sql`${value}`), sql`, `)}) then ${costEvents.outputTokens} else 0 end), 0)::int`,
+          providerCount: sql<number>`count(distinct ${costEvents.provider})::int`,
+          modelCount: sql<number>`count(distinct ${costEvents.model})::int`,
+        })
+        .from(costEvents)
+        .where(and(...conditions))
+        .groupBy(costEvents.biller)
+        .orderBy(desc(sql`coalesce(sum(${costEvents.costCents}), 0)::int`));
+    },
+
+    /**
+     * aggregates cost_events by provider for each of three rolling windows:
+     * last 5 hours, last 24 hours, last 7 days.
+     * purely internal consumption data, no external rate-limit sources.
+     */
+    windowSpend: async (companyId: string) => {
+      const windows = [
+        { label: "5h", hours: 5 },
+        { label: "24h", hours: 24 },
+        { label: "7d", hours: 168 },
+      ] as const;
+
+      const results = await Promise.all(
+        windows.map(async ({ label, hours }) => {
+          const since = new Date(Date.now() - hours * 60 * 60 * 1000);
+          const rows = await db
+            .select({
+              provider: costEvents.provider,
+              biller: sql<string>`case when count(distinct ${costEvents.biller}) = 1 then min(${costEvents.biller}) else 'mixed' end`,
+              costCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+              inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::int`,
+              cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::int`,
+              outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::int`,
+            })
+            .from(costEvents)
+            .where(
+              and(
+                eq(costEvents.companyId, companyId),
+                gte(costEvents.occurredAt, since),
+              ),
+            )
+            .groupBy(costEvents.provider)
+            .orderBy(desc(sql`coalesce(sum(${costEvents.costCents}), 0)::int`));
+
+          return rows.map((row) => ({
+            provider: row.provider,
+            biller: row.biller,
+            window: label as string,
+            windowHours: hours,
+            costCents: row.costCents,
+            inputTokens: row.inputTokens,
+            cachedInputTokens: row.cachedInputTokens,
+            outputTokens: row.outputTokens,
+          }));
+        }),
+      );
+
+      return results.flat();
+    },
+
+    byAgentModel: async (companyId: string, range?: CostDateRange) => {
+      const conditions: ReturnType<typeof eq>[] = [eq(costEvents.companyId, companyId)];
+      if (range?.from) conditions.push(gte(costEvents.occurredAt, range.from));
+      if (range?.to) conditions.push(lte(costEvents.occurredAt, range.to));
+
+      // single query: group by agent + provider + model.
+      // the (companyId, agentId, occurredAt) composite index covers this well.
+      // order by provider + model for stable db-level ordering; cost-desc sort
+      // within each agent's sub-rows is done client-side in the ui memo.
+      return db
+        .select({
+          agentId: costEvents.agentId,
+          agentName: agents.name,
+          provider: costEvents.provider,
+          biller: costEvents.biller,
+          billingType: costEvents.billingType,
+          model: costEvents.model,
+          costCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`,
+          inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::int`,
+          cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::int`,
+          outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::int`,
+        })
+        .from(costEvents)
+        .leftJoin(agents, eq(costEvents.agentId, agents.id))
+        .where(and(...conditions))
+        .groupBy(
+          costEvents.agentId,
+          agents.name,
+          costEvents.provider,
+          costEvents.biller,
+          costEvents.billingType,
+          costEvents.model,
+        )
+        .orderBy(costEvents.provider, costEvents.biller, costEvents.billingType, costEvents.model);
    },

    byProject: async (companyId: string, range?: CostDateRange) => {
@@ -179,25 +337,27 @@ export function costService(db: Db) {
        .orderBy(activityLog.runId, issues.projectId, desc(activityLog.createdAt))
        .as("run_project_links");

-      const conditions: ReturnType<typeof eq>[] = [eq(heartbeatRuns.companyId, companyId)];
-      if (range?.from) conditions.push(gte(heartbeatRuns.finishedAt, range.from));
-      if (range?.to) conditions.push(lte(heartbeatRuns.finishedAt, range.to));
+      const effectiveProjectId = sql<string | null>`coalesce(${costEvents.projectId}, ${runProjectLinks.projectId})`;
+      const conditions: ReturnType<typeof eq>[] = [eq(costEvents.companyId, companyId)];
+      if (range?.from) conditions.push(gte(costEvents.occurredAt, range.from));
+      if (range?.to) conditions.push(lte(costEvents.occurredAt, range.to));

-      const costCentsExpr = sql<number>`coalesce(sum(round(coalesce((${heartbeatRuns.usageJson} ->> 'costUsd')::numeric, 0) * 100)), 0)::int`;
+      const costCentsExpr = sql<number>`coalesce(sum(${costEvents.costCents}), 0)::int`;

      return db
        .select({
-          projectId: runProjectLinks.projectId,
+          projectId: effectiveProjectId,
          projectName: projects.name,
          costCents: costCentsExpr,
-          inputTokens: sql<number>`coalesce(sum(coalesce((${heartbeatRuns.usageJson} ->> 'inputTokens')::int, 0)), 0)::int`,
-          outputTokens: sql<number>`coalesce(sum(coalesce((${heartbeatRuns.usageJson} ->> 'outputTokens')::int, 0)), 0)::int`,
+          inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::int`,
+          cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::int`,
+          outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::int`,
        })
-        .from(runProjectLinks)
-        .innerJoin(heartbeatRuns, eq(runProjectLinks.runId, heartbeatRuns.id))
-        .innerJoin(projects, eq(runProjectLinks.projectId, projects.id))
-        .where(and(...conditions))
-        .groupBy(runProjectLinks.projectId, projects.name)
+        .from(costEvents)
+        .leftJoin(runProjectLinks, eq(costEvents.heartbeatRunId, runProjectLinks.runId))
+        .innerJoin(projects, sql`${projects.id} = ${effectiveProjectId}`)
+        .where(and(...conditions, sql`${effectiveProjectId} is not null`))
+        .groupBy(effectiveProjectId, projects.name)
        .orderBy(desc(costCentsExpr));
    },
  };
--- a/server/src/services/dashboard.ts
+++ b/server/src/services/dashboard.ts
@@ -2,8 +2,10 @@ import { and, eq, gte, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import { agents, approvals, companies, costEvents, issues } from "@paperclipai/db";
 import { notFound } from "../errors.js";
+import { budgetService } from "./budgets.js";

 export function dashboardService(db: Db) {
+  const budgets = budgetService(db);
  return {
    summary: async (companyId: string) => {
      const company = await db
@@ -78,6 +80,7 @@ export function dashboardService(db: Db) {
        company.budgetMonthlyCents > 0
          ? (monthSpendCents / company.budgetMonthlyCents) * 100
          : 0;
+      const budgetOverview = await budgets.overview(companyId);

      return {
        companyId,
@@ -94,6 +97,12 @@ export function dashboardService(db: Db) {
          monthUtilizationPercent: Number(utilization.toFixed(2)),
        },
        pendingApprovals,
+        budgets: {
+          activeIncidents: budgetOverview.activeIncidents.length,
+          pendingApprovals: budgetOverview.pendingApprovalCount,
+          pausedAgents: budgetOverview.pausedAgentCount,
+          pausedProjects: budgetOverview.pausedProjectCount,
+        },
      };
    },
  };
--- a/server/src/services/finance.ts
+++ b/server/src/services/finance.ts
@@ -0,0 +1,134 @@
+import { and, desc, eq, gte, lte, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { agents, costEvents, financeEvents, goals, heartbeatRuns, issues, projects } from "@paperclipai/db";
+import { notFound, unprocessable } from "../errors.js";
+
+export interface FinanceDateRange {
+  from?: Date;
+  to?: Date;
+}
+
+async function assertBelongsToCompany(
+  db: Db,
+  table: any,
+  id: string,
+  companyId: string,
+  label: string,
+) {
+  const row = await db
+    .select()
+    .from(table)
+    .where(eq(table.id, id))
+    .then((rows) => rows[0] ?? null);
+
+  if (!row) throw notFound(`${label} not found`);
+  if ((row as unknown as { companyId: string }).companyId !== companyId) {
+    throw unprocessable(`${label} does not belong to company`);
+  }
+}
+
+function rangeConditions(companyId: string, range?: FinanceDateRange) {
+  const conditions: ReturnType<typeof eq>[] = [eq(financeEvents.companyId, companyId)];
+  if (range?.from) conditions.push(gte(financeEvents.occurredAt, range.from));
+  if (range?.to) conditions.push(lte(financeEvents.occurredAt, range.to));
+  return conditions;
+}
+
+export function financeService(db: Db) {
+  const debitExpr = sql<number>`coalesce(sum(case when ${financeEvents.direction} = 'debit' then ${financeEvents.amountCents} else 0 end), 0)::int`;
+  const creditExpr = sql<number>`coalesce(sum(case when ${financeEvents.direction} = 'credit' then ${financeEvents.amountCents} else 0 end), 0)::int`;
+  const estimatedDebitExpr = sql<number>`coalesce(sum(case when ${financeEvents.direction} = 'debit' and ${financeEvents.estimated} = true then ${financeEvents.amountCents} else 0 end), 0)::int`;
+
+  return {
+    createEvent: async (companyId: string, data: Omit<typeof financeEvents.$inferInsert, "companyId">) => {
+      if (data.agentId) await assertBelongsToCompany(db, agents, data.agentId, companyId, "Agent");
+      if (data.issueId) await assertBelongsToCompany(db, issues, data.issueId, companyId, "Issue");
+      if (data.projectId) await assertBelongsToCompany(db, projects, data.projectId, companyId, "Project");
+      if (data.goalId) await assertBelongsToCompany(db, goals, data.goalId, companyId, "Goal");
+      if (data.heartbeatRunId) await assertBelongsToCompany(db, heartbeatRuns, data.heartbeatRunId, companyId, "Heartbeat run");
+      if (data.costEventId) await assertBelongsToCompany(db, costEvents, data.costEventId, companyId, "Cost event");
+
+      const event = await db
+        .insert(financeEvents)
+        .values({
+          ...data,
+          companyId,
+          currency: data.currency ?? "USD",
+          direction: data.direction ?? "debit",
+          estimated: data.estimated ?? false,
+        })
+        .returning()
+        .then((rows) => rows[0]);
+
+      return event;
+    },
+
+    summary: async (companyId: string, range?: FinanceDateRange) => {
+      const conditions = rangeConditions(companyId, range);
+      const [row] = await db
+        .select({
+          debitCents: debitExpr,
+          creditCents: creditExpr,
+          estimatedDebitCents: estimatedDebitExpr,
+          eventCount: sql<number>`count(*)::int`,
+        })
+        .from(financeEvents)
+        .where(and(...conditions));
+
+      return {
+        companyId,
+        debitCents: Number(row?.debitCents ?? 0),
+        creditCents: Number(row?.creditCents ?? 0),
+        netCents: Number(row?.debitCents ?? 0) - Number(row?.creditCents ?? 0),
+        estimatedDebitCents: Number(row?.estimatedDebitCents ?? 0),
+        eventCount: Number(row?.eventCount ?? 0),
+      };
+    },
+
+    byBiller: async (companyId: string, range?: FinanceDateRange) => {
+      const conditions = rangeConditions(companyId, range);
+      return db
+        .select({
+          biller: financeEvents.biller,
+          debitCents: debitExpr,
+          creditCents: creditExpr,
+          estimatedDebitCents: estimatedDebitExpr,
+          eventCount: sql<number>`count(*)::int`,
+          kindCount: sql<number>`count(distinct ${financeEvents.eventKind})::int`,
+          netCents: sql<number>`(${debitExpr} - ${creditExpr})::int`,
+        })
+        .from(financeEvents)
+        .where(and(...conditions))
+        .groupBy(financeEvents.biller)
+        .orderBy(desc(sql`(${debitExpr} - ${creditExpr})::int`), financeEvents.biller);
+    },
+
+    byKind: async (companyId: string, range?: FinanceDateRange) => {
+      const conditions = rangeConditions(companyId, range);
+      return db
+        .select({
+          eventKind: financeEvents.eventKind,
+          debitCents: debitExpr,
+          creditCents: creditExpr,
+          estimatedDebitCents: estimatedDebitExpr,
+          eventCount: sql<number>`count(*)::int`,
+          billerCount: sql<number>`count(distinct ${financeEvents.biller})::int`,
+          netCents: sql<number>`(${debitExpr} - ${creditExpr})::int`,
+        })
+        .from(financeEvents)
+        .where(and(...conditions))
+        .groupBy(financeEvents.eventKind)
+        .orderBy(desc(sql`(${debitExpr} - ${creditExpr})::int`), financeEvents.eventKind);
+    },
+
+    list: async (companyId: string, range?: FinanceDateRange, limit: number = 100) => {
+      const conditions = rangeConditions(companyId, range);
+      return db
+        .select()
+        .from(financeEvents)
+        .where(and(...conditions))
+        .orderBy(desc(financeEvents.occurredAt), desc(financeEvents.createdAt))
+        .limit(limit);
+    },
+  };
+}
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -4,6 +4,7 @@ import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { and, asc, desc, eq, gt, inArray, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
+import type { BillingType } from "@paperclipai/shared";
 import {
  agents,
  agentRuntimeState,
@@ -24,6 +25,7 @@ import type { AdapterExecutionResult, AdapterInvocationMeta, AdapterSessionCodec
 import { createLocalAgentJwt } from "../agent-auth-jwt.js";
 import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js";
 import { costService } from "./costs.js";
+import { budgetService, type BudgetEnforcementScope } from "./budgets.js";
 import { secretService } from "./secrets.js";
 import { resolveDefaultAgentWorkspaceDir, resolveManagedProjectWorkspaceDir } from "../home-paths.js";
 import { summarizeHeartbeatRunResultJson } from "./heartbeat-run-summary.js";
@@ -251,6 +253,67 @@ function readNonEmptyString(value: unknown): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value : null;
 }

+function normalizeLedgerBillingType(value: unknown): BillingType {
+  const raw = readNonEmptyString(value);
+  switch (raw) {
+    case "api":
+    case "metered_api":
+      return "metered_api";
+    case "subscription":
+    case "subscription_included":
+      return "subscription_included";
+    case "subscription_overage":
+      return "subscription_overage";
+    case "credits":
+      return "credits";
+    case "fixed":
+      return "fixed";
+    default:
+      return "unknown";
+  }
+}
+
+function resolveLedgerBiller(result: AdapterExecutionResult): string {
+  return readNonEmptyString(result.biller) ?? readNonEmptyString(result.provider) ?? "unknown";
+}
+
+function normalizeBilledCostCents(costUsd: number | null | undefined, billingType: BillingType): number {
+  if (billingType === "subscription_included") return 0;
+  if (typeof costUsd !== "number" || !Number.isFinite(costUsd)) return 0;
+  return Math.max(0, Math.round(costUsd * 100));
+}
+
+async function resolveLedgerScopeForRun(
+  db: Db,
+  companyId: string,
+  run: typeof heartbeatRuns.$inferSelect,
+) {
+  const context = parseObject(run.contextSnapshot);
+  const contextIssueId = readNonEmptyString(context.issueId);
+  const contextProjectId = readNonEmptyString(context.projectId);
+
+  if (!contextIssueId) {
+    return {
+      issueId: null,
+      projectId: contextProjectId,
+    };
+  }
+
+  const issue = await db
+    .select({
+      id: issues.id,
+      projectId: issues.projectId,
+    })
+    .from(issues)
+    .where(and(eq(issues.id, contextIssueId), eq(issues.companyId, companyId)))
+    .then((rows) => rows[0] ?? null);
+
+  return {
+    issueId: issue?.id ?? null,
+    projectId: issue?.projectId ?? contextProjectId,
+  };
+}
+
 function normalizeUsageTotals(usage: UsageSummary | null | undefined): UsageTotals | null {
  if (!usage) return null;
  return {
@@ -639,6 +702,10 @@ export function heartbeatService(db: Db) {
  const issuesSvc = issueService(db);
  const executionWorkspacesSvc = executionWorkspaceService(db);
  const activeRunExecutions = new Set<string>();
+  const budgetHooks = {
+    cancelWorkForScope: cancelBudgetScopeWork,
+  };
+  const budgets = budgetService(db, budgetHooks);

  async function getAgent(agentId: string) {
    return db
@@ -1281,6 +1348,26 @@ export function heartbeatService(db: Db) {

  async function claimQueuedRun(run: typeof heartbeatRuns.$inferSelect) {
    if (run.status !== "queued") return run;
+    const agent = await getAgent(run.agentId);
+    if (!agent) {
+      await cancelRunInternal(run.id, "Cancelled because the agent no longer exists");
+      return null;
+    }
+    if (agent.status === "paused" || agent.status === "terminated" || agent.status === "pending_approval") {
+      await cancelRunInternal(run.id, "Cancelled because the agent is not invokable");
+      return null;
+    }
+
+    const context = parseObject(run.contextSnapshot);
+    const budgetBlock = await budgets.getInvocationBlock(run.companyId, run.agentId, {
+      issueId: readNonEmptyString(context.issueId),
+      projectId: readNonEmptyString(context.projectId),
+    });
+    if (budgetBlock) {
+      await cancelRunInternal(run.id, budgetBlock.reason);
+      return null;
+    }
+
    const claimedAt = new Date();
    const claimed = await db
      .update(heartbeatRuns)
@@ -1436,8 +1523,12 @@ export function heartbeatService(db: Db) {
    const inputTokens = usage?.inputTokens ?? 0;
    const outputTokens = usage?.outputTokens ?? 0;
    const cachedInputTokens = usage?.cachedInputTokens ?? 0;
-    const additionalCostCents = Math.max(0, Math.round((result.costUsd ?? 0) * 100));
+    const billingType = normalizeLedgerBillingType(result.billingType);
+    const additionalCostCents = normalizeBilledCostCents(result.costUsd, billingType);
    const hasTokenUsage = inputTokens > 0 || outputTokens > 0 || cachedInputTokens > 0;
+    const provider = result.provider ?? "unknown";
+    const biller = resolveLedgerBiller(result);
+    const ledgerScope = await resolveLedgerScopeForRun(db, agent.companyId, run);

    await db
      .update(agentRuntimeState)
@@ -1456,12 +1547,18 @@ export function heartbeatService(db: Db) {
      .where(eq(agentRuntimeState.agentId, agent.id));

    if (additionalCostCents > 0 || hasTokenUsage) {
-      const costs = costService(db);
+      const costs = costService(db, budgetHooks);
      await costs.createEvent(agent.companyId, {
+        heartbeatRunId: run.id,
        agentId: agent.id,
-        provider: result.provider ?? "unknown",
+        issueId: ledgerScope.issueId,
+        projectId: ledgerScope.projectId,
+        provider,
+        biller,
+        billingType,
        model: result.model ?? "unknown",
        inputTokens,
+        cachedInputTokens,
        outputTokens,
        costCents: additionalCostCents,
        occurredAt: new Date(),
@@ -1473,6 +1570,9 @@ export function heartbeatService(db: Db) {
    return withAgentStartLock(agentId, async () => {
      const agent = await getAgent(agentId);
      if (!agent) return [];
+      if (agent.status === "paused" || agent.status === "terminated" || agent.status === "pending_approval") {
+        return [];
+      }
      const policy = parseHeartbeatPolicy(agent);
      const runningCount = await countRunningRunsForAgent(agentId);
      const availableSlots = Math.max(0, policy.maxConcurrentRuns - runningCount);
@@ -2086,8 +2186,11 @@ export function heartbeatService(db: Db) {
              freshSession: runtimeForAdapter.sessionId == null && runtimeForAdapter.sessionDisplayId == null,
              sessionRotated: sessionCompaction.rotate,
              sessionRotationReason: sessionCompaction.reason,
+              provider: readNonEmptyString(adapterResult.provider) ?? "unknown",
+              biller: resolveLedgerBiller(adapterResult),
+              model: readNonEmptyString(adapterResult.model) ?? "unknown",
              ...(adapterResult.costUsd != null ? { costUsd: adapterResult.costUsd } : {}),
-              ...(adapterResult.billingType ? { billingType: adapterResult.billingType } : {}),
+              billingType: normalizeLedgerBillingType(adapterResult.billingType),
            } as Record<string, unknown>)
          : null;

@@ -2437,6 +2540,43 @@ export function heartbeatService(db: Db) {
    const agent = await getAgent(agentId);
    if (!agent) throw notFound("Agent not found");

+    const writeSkippedRequest = async (skipReason: string) => {
+      await db.insert(agentWakeupRequests).values({
+        companyId: agent.companyId,
+        agentId,
+        source,
+        triggerDetail,
+        reason: skipReason,
+        payload,
+        status: "skipped",
+        requestedByActorType: opts.requestedByActorType ?? null,
+        requestedByActorId: opts.requestedByActorId ?? null,
+        idempotencyKey: opts.idempotencyKey ?? null,
+        finishedAt: new Date(),
+      });
+    };
+
+    let projectId = readNonEmptyString(enrichedContextSnapshot.projectId);
+    if (!projectId && issueId) {
+      projectId = await db
+        .select({ projectId: issues.projectId })
+        .from(issues)
+        .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
+        .then((rows) => rows[0]?.projectId ?? null);
+    }
+
+    const budgetBlock = await budgets.getInvocationBlock(agent.companyId, agentId, {
+      issueId,
+      projectId,
+    });
+    if (budgetBlock) {
+      await writeSkippedRequest("budget.blocked");
+      throw conflict(budgetBlock.reason, {
+        scopeType: budgetBlock.scopeType,
+        scopeId: budgetBlock.scopeId,
+      });
+    }
+
    if (
      agent.status === "paused" ||
      agent.status === "terminated" ||
@@ -2446,21 +2586,6 @@ export function heartbeatService(db: Db) {
    }

    const policy = parseHeartbeatPolicy(agent);
-    const writeSkippedRequest = async (reason: string) => {
-      await db.insert(agentWakeupRequests).values({
-        companyId: agent.companyId,
-        agentId,
-        source,
-        triggerDetail,
-        reason,
-        payload,
-        status: "skipped",
-        requestedByActorType: opts.requestedByActorType ?? null,
-        requestedByActorId: opts.requestedByActorId ?? null,
-        idempotencyKey: opts.idempotencyKey ?? null,
-        finishedAt: new Date(),
-      });
-    };

    if (source === "timer" && !policy.enabled) {
      await writeSkippedRequest("heartbeat.disabled");
@@ -2870,6 +2995,205 @@ export function heartbeatService(db: Db) {
    return newRun;
  }

+  async function listProjectScopedRunIds(companyId: string, projectId: string) {
+    const runIssueId = sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`;
+    const effectiveProjectId = sql<string | null>`coalesce(${heartbeatRuns.contextSnapshot} ->> 'projectId', ${issues.projectId}::text)`;
+
+    const rows = await db
+      .selectDistinctOn([heartbeatRuns.id], { id: heartbeatRuns.id })
+      .from(heartbeatRuns)
+      .leftJoin(
+        issues,
+        and(
+          eq(issues.companyId, companyId),
+          sql`${issues.id}::text = ${runIssueId}`,
+        ),
+      )
+      .where(
+        and(
+          eq(heartbeatRuns.companyId, companyId),
+          inArray(heartbeatRuns.status, ["queued", "running"]),
+          sql`${effectiveProjectId} = ${projectId}`,
+        ),
+      );
+
+    return rows.map((row) => row.id);
+  }
+
+  async function listProjectScopedWakeupIds(companyId: string, projectId: string) {
+    const wakeIssueId = sql<string | null>`${agentWakeupRequests.payload} ->> 'issueId'`;
+    const effectiveProjectId = sql<string | null>`coalesce(${agentWakeupRequests.payload} ->> 'projectId', ${issues.projectId}::text)`;
+
+    const rows = await db
+      .selectDistinctOn([agentWakeupRequests.id], { id: agentWakeupRequests.id })
+      .from(agentWakeupRequests)
+      .leftJoin(
+        issues,
+        and(
+          eq(issues.companyId, companyId),
+          sql`${issues.id}::text = ${wakeIssueId}`,
+        ),
+      )
+      .where(
+        and(
+          eq(agentWakeupRequests.companyId, companyId),
+          inArray(agentWakeupRequests.status, ["queued", "deferred_issue_execution"]),
+          sql`${agentWakeupRequests.runId} is null`,
+          sql`${effectiveProjectId} = ${projectId}`,
+        ),
+      );
+
+    return rows.map((row) => row.id);
+  }
+
+  async function cancelPendingWakeupsForBudgetScope(scope: BudgetEnforcementScope) {
+    const now = new Date();
+    let wakeupIds: string[] = [];
+
+    if (scope.scopeType === "company") {
+      wakeupIds = await db
+        .select({ id: agentWakeupRequests.id })
+        .from(agentWakeupRequests)
+        .where(
+          and(
+            eq(agentWakeupRequests.companyId, scope.companyId),
+            inArray(agentWakeupRequests.status, ["queued", "deferred_issue_execution"]),
+            sql`${agentWakeupRequests.runId} is null`,
+          ),
+        )
+        .then((rows) => rows.map((row) => row.id));
+    } else if (scope.scopeType === "agent") {
+      wakeupIds = await db
+        .select({ id: agentWakeupRequests.id })
+        .from(agentWakeupRequests)
+        .where(
+          and(
+            eq(agentWakeupRequests.companyId, scope.companyId),
+            eq(agentWakeupRequests.agentId, scope.scopeId),
+            inArray(agentWakeupRequests.status, ["queued", "deferred_issue_execution"]),
+            sql`${agentWakeupRequests.runId} is null`,
+          ),
+        )
+        .then((rows) => rows.map((row) => row.id));
+    } else {
+      wakeupIds = await listProjectScopedWakeupIds(scope.companyId, scope.scopeId);
+    }
+
+    if (wakeupIds.length === 0) return 0;
+
+    await db
+      .update(agentWakeupRequests)
+      .set({
+        status: "cancelled",
+        finishedAt: now,
+        error: "Cancelled due to budget pause",
+        updatedAt: now,
+      })
+      .where(inArray(agentWakeupRequests.id, wakeupIds));
+
+    return wakeupIds.length;
+  }
+
+  async function cancelRunInternal(runId: string, reason = "Cancelled by control plane") {
+    const run = await getRun(runId);
+    if (!run) throw notFound("Heartbeat run not found");
+    if (run.status !== "running" && run.status !== "queued") return run;
+
+    const running = runningProcesses.get(run.id);
+    if (running) {
+      running.child.kill("SIGTERM");
+      const graceMs = Math.max(1, running.graceSec) * 1000;
+      setTimeout(() => {
+        if (!running.child.killed) {
+          running.child.kill("SIGKILL");
+        }
+      }, graceMs);
+    }
+
+    const cancelled = await setRunStatus(run.id, "cancelled", {
+      finishedAt: new Date(),
+      error: reason,
+      errorCode: "cancelled",
+    });
+
+    await setWakeupStatus(run.wakeupRequestId, "cancelled", {
+      finishedAt: new Date(),
+      error: reason,
+    });
+
+    if (cancelled) {
+      await appendRunEvent(cancelled, 1, {
+        eventType: "lifecycle",
+        stream: "system",
+        level: "warn",
+        message: "run cancelled",
+      });
+      await releaseIssueExecutionAndPromote(cancelled);
+    }
+
+    runningProcesses.delete(run.id);
+    await finalizeAgentStatus(run.agentId, "cancelled");
+    await startNextQueuedRunForAgent(run.agentId);
+    return cancelled;
+  }
+
+  async function cancelActiveForAgentInternal(agentId: string, reason = "Cancelled due to agent pause") {
+    const runs = await db
+      .select()
+      .from(heartbeatRuns)
+      .where(and(eq(heartbeatRuns.agentId, agentId), inArray(heartbeatRuns.status, ["queued", "running"])));
+
+    for (const run of runs) {
+      await setRunStatus(run.id, "cancelled", {
+        finishedAt: new Date(),
+        error: reason,
+        errorCode: "cancelled",
+      });
+
+      await setWakeupStatus(run.wakeupRequestId, "cancelled", {
+        finishedAt: new Date(),
+        error: reason,
+      });
+
+      const running = runningProcesses.get(run.id);
+      if (running) {
+        running.child.kill("SIGTERM");
+        runningProcesses.delete(run.id);
+      }
+      await releaseIssueExecutionAndPromote(run);
+    }
+
+    return runs.length;
+  }
+
+  async function cancelBudgetScopeWork(scope: BudgetEnforcementScope) {
+    if (scope.scopeType === "agent") {
+      await cancelActiveForAgentInternal(scope.scopeId, "Cancelled due to budget pause");
+      await cancelPendingWakeupsForBudgetScope(scope);
+      return;
+    }
+
+    const runIds =
+      scope.scopeType === "company"
+        ? await db
+          .select({ id: heartbeatRuns.id })
+          .from(heartbeatRuns)
+          .where(
+            and(
+              eq(heartbeatRuns.companyId, scope.companyId),
+              inArray(heartbeatRuns.status, ["queued", "running"]),
+            ),
+          )
+          .then((rows) => rows.map((row) => row.id))
+        : await listProjectScopedRunIds(scope.companyId, scope.scopeId);
+
+    for (const runId of runIds) {
+      await cancelRunInternal(runId, "Cancelled due to budget pause");
+    }
+
+    await cancelPendingWakeupsForBudgetScope(scope);
+  }
+
  return {
    list: async (companyId: string, agentId?: string, limit?: number) => {
      const query = db
@@ -3042,77 +3366,11 @@ export function heartbeatService(db: Db) {
      return { checked, enqueued, skipped };
    },

-    cancelRun: async (runId: string) => {
-      const run = await getRun(runId);
-      if (!run) throw notFound("Heartbeat run not found");
-      if (run.status !== "running" && run.status !== "queued") return run;
+    cancelRun: (runId: string) => cancelRunInternal(runId),

-      const running = runningProcesses.get(run.id);
-      if (running) {
-        running.child.kill("SIGTERM");
-        const graceMs = Math.max(1, running.graceSec) * 1000;
-        setTimeout(() => {
-          if (!running.child.killed) {
-            running.child.kill("SIGKILL");
-          }
-        }, graceMs);
-      }
+    cancelActiveForAgent: (agentId: string) => cancelActiveForAgentInternal(agentId),

-      const cancelled = await setRunStatus(run.id, "cancelled", {
-        finishedAt: new Date(),
-        error: "Cancelled by control plane",
-        errorCode: "cancelled",
-      });
-
-      await setWakeupStatus(run.wakeupRequestId, "cancelled", {
-        finishedAt: new Date(),
-        error: "Cancelled by control plane",
-      });
-
-      if (cancelled) {
-        await appendRunEvent(cancelled, 1, {
-          eventType: "lifecycle",
-          stream: "system",
-          level: "warn",
-          message: "run cancelled",
-        });
-        await releaseIssueExecutionAndPromote(cancelled);
-      }
-
-      runningProcesses.delete(run.id);
-      await finalizeAgentStatus(run.agentId, "cancelled");
-      await startNextQueuedRunForAgent(run.agentId);
-      return cancelled;
-    },
-
-    cancelActiveForAgent: async (agentId: string) => {
-      const runs = await db
-        .select()
-        .from(heartbeatRuns)
-        .where(and(eq(heartbeatRuns.agentId, agentId), inArray(heartbeatRuns.status, ["queued", "running"])));
-
-      for (const run of runs) {
-        await setRunStatus(run.id, "cancelled", {
-          finishedAt: new Date(),
-          error: "Cancelled due to agent pause",
-          errorCode: "cancelled",
-        });
-
-        await setWakeupStatus(run.wakeupRequestId, "cancelled", {
-          finishedAt: new Date(),
-          error: "Cancelled due to agent pause",
-        });
-
-        const running = runningProcesses.get(run.id);
-        if (running) {
-          running.child.kill("SIGTERM");
-          runningProcesses.delete(run.id);
-        }
-        await releaseIssueExecutionAndPromote(run);
-      }
-
-      return runs.length;
-    },
+    cancelBudgetScopeWork,

    getActiveRunForAgent: async (agentId: string) => {
      const [run] = await db
--- a/server/src/services/index.ts
+++ b/server/src/services/index.ts
@@ -8,8 +8,10 @@ export { issueApprovalService } from "./issue-approvals.js";
 export { goalService } from "./goals.js";
 export { activityService, type ActivityFilters } from "./activity.js";
 export { approvalService } from "./approvals.js";
+export { budgetService } from "./budgets.js";
 export { secretService } from "./secrets.js";
 export { costService } from "./costs.js";
+export { financeService } from "./finance.js";
 export { heartbeatService } from "./heartbeat.js";
 export { dashboardService } from "./dashboard.js";
 export { sidebarBadgeService } from "./sidebar-badges.js";
--- a/server/src/services/quota-windows.ts
+++ b/server/src/services/quota-windows.ts
@@ -0,0 +1,64 @@
+import type { ProviderQuotaResult } from "@paperclipai/shared";
+import { listServerAdapters } from "../adapters/registry.js";
+
+const QUOTA_PROVIDER_TIMEOUT_MS = 20_000;
+
+function providerSlugForAdapterType(type: string): string {
+  switch (type) {
+    case "claude_local":
+      return "anthropic";
+    case "codex_local":
+      return "openai";
+    default:
+      return type;
+  }
+}
+
+/**
+ * Asks each registered adapter for its provider quota windows and aggregates the results.
+ * Adapters that don't implement getQuotaWindows() are silently skipped.
+ * Individual adapter failures are caught and returned as error results rather than
+ * letting one provider's outage block the entire response.
+ */
+export async function fetchAllQuotaWindows(): Promise<ProviderQuotaResult[]> {
+  const adapters = listServerAdapters().filter((a) => a.getQuotaWindows != null);
+
+  const settled = await Promise.allSettled(
+    adapters.map((adapter) => withQuotaTimeout(adapter.type, adapter.getQuotaWindows!())),
+  );
+
+  return settled.map((result, i) => {
+    if (result.status === "fulfilled") return result.value;
+    const adapterType = adapters[i]!.type;
+    return {
+      provider: providerSlugForAdapterType(adapterType),
+      ok: false,
+      error: String(result.reason),
+      windows: [],
+    };
+  });
+}
+
+async function withQuotaTimeout(
+  adapterType: string,
+  task: Promise<ProviderQuotaResult>,
+): Promise<ProviderQuotaResult> {
+  let timeoutId: NodeJS.Timeout | null = null;
+  try {
+    return await Promise.race([
+      task,
+      new Promise<ProviderQuotaResult>((resolve) => {
+        timeoutId = setTimeout(() => {
+          resolve({
+            provider: providerSlugForAdapterType(adapterType),
+            ok: false,
+            error: `quota polling timed out after ${Math.round(QUOTA_PROVIDER_TIMEOUT_MS / 1000)}s`,
+            windows: [],
+          });
+        }, QUOTA_PROVIDER_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}