Merge public-gh/master into paperclip-company-import-export

server/src/__tests__/assets.test.ts

@@ -0,0 +1,250 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import express from "express";
+import request from "supertest";
+import { MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
+import { assetRoutes } from "../routes/assets.js";
+import type { StorageService } from "../storage/types.js";
+
+const { createAssetMock, getAssetByIdMock, logActivityMock } = vi.hoisted(() => ({
+  createAssetMock: vi.fn(),
+  getAssetByIdMock: vi.fn(),
+  logActivityMock: vi.fn(),
+}));
+
+vi.mock("../services/index.js", () => ({
+  assetService: vi.fn(() => ({
+    create: createAssetMock,
+    getById: getAssetByIdMock,
+  })),
+  logActivity: logActivityMock,
+}));
+
+function createAsset() {
+  const now = new Date("2026-01-01T00:00:00.000Z");
+  return {
+    id: "asset-1",
+    companyId: "company-1",
+    provider: "local",
+    objectKey: "assets/abc",
+    contentType: "image/png",
+    byteSize: 40,
+    sha256: "sha256-sample",
+    originalFilename: "logo.png",
+    createdByAgentId: null,
+    createdByUserId: "user-1",
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function createStorageService(contentType = "image/png"): StorageService {
+  const putFile: StorageService["putFile"] = vi.fn(async (input: {
+    companyId: string;
+    namespace: string;
+    originalFilename: string | null;
+    contentType: string;
+    body: Buffer;
+  }) => {
+    return {
+      provider: "local_disk" as const,
+      objectKey: `${input.namespace}/${input.originalFilename ?? "upload"}`,
+      contentType: contentType || input.contentType,
+      byteSize: input.body.length,
+      sha256: "sha256-sample",
+      originalFilename: input.originalFilename,
+    };
+  });
+
+  return {
+    provider: "local_disk" as const,
+    putFile,
+    getObject: vi.fn(),
+    headObject: vi.fn(),
+    deleteObject: vi.fn(),
+  };
+}
+
+function createApp(storage: ReturnType<typeof createStorageService>) {
+  const app = express();
+  app.use((req, _res, next) => {
+    req.actor = {
+      type: "board",
+      source: "local_implicit",
+      userId: "user-1",
+    };
+    next();
+  });
+  app.use("/api", assetRoutes({} as any, storage));
+  return app;
+}
+
+describe("POST /api/companies/:companyId/assets/images", () => {
+  afterEach(() => {
+    createAssetMock.mockReset();
+    getAssetByIdMock.mockReset();
+    logActivityMock.mockReset();
+  });
+
+  it("accepts PNG image uploads and returns an asset path", async () => {
+    const png = createStorageService("image/png");
+    const app = createApp(png);
+
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/assets/images")
+      .field("namespace", "goals")
+      .attach("file", Buffer.from("png"), "logo.png");
+
+    expect(res.status).toBe(201);
+    expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
+    expect(createAssetMock).toHaveBeenCalledTimes(1);
+    expect(png.putFile).toHaveBeenCalledWith({
+      companyId: "company-1",
+      namespace: "assets/goals",
+      originalFilename: "logo.png",
+      contentType: "image/png",
+      body: expect.any(Buffer),
+    });
+  });
+
+  it("allows supported non-image attachments outside the company logo flow", async () => {
+    const text = createStorageService("text/plain");
+    const app = createApp(text);
+
+    createAssetMock.mockResolvedValue({
+      ...createAsset(),
+      contentType: "text/plain",
+      originalFilename: "note.txt",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/company-1/assets/images")
+      .field("namespace", "issues/drafts")
+      .attach("file", Buffer.from("hello"), { filename: "note.txt", contentType: "text/plain" });
+
+    expect(res.status).toBe(201);
+    expect(text.putFile).toHaveBeenCalledWith({
+      companyId: "company-1",
+      namespace: "assets/issues/drafts",
+      originalFilename: "note.txt",
+      contentType: "text/plain",
+      body: expect.any(Buffer),
+    });
+  });
+});
+
+describe("POST /api/companies/:companyId/logo", () => {
+  afterEach(() => {
+    createAssetMock.mockReset();
+    getAssetByIdMock.mockReset();
+    logActivityMock.mockReset();
+  });
+
+  it("accepts PNG logo uploads and returns an asset path", async () => {
+    const png = createStorageService("image/png");
+    const app = createApp(png);
+
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", Buffer.from("png"), "logo.png");
+
+    expect(res.status).toBe(201);
+    expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
+    expect(createAssetMock).toHaveBeenCalledTimes(1);
+    expect(png.putFile).toHaveBeenCalledWith({
+      companyId: "company-1",
+      namespace: "assets/companies",
+      originalFilename: "logo.png",
+      contentType: "image/png",
+      body: expect.any(Buffer),
+    });
+  });
+
+  it("sanitizes SVG logo uploads before storing them", async () => {
+    const svg = createStorageService("image/svg+xml");
+    const app = createApp(svg);
+
+    createAssetMock.mockResolvedValue({
+      ...createAsset(),
+      contentType: "image/svg+xml",
+      originalFilename: "logo.svg",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach(
+        "file",
+        Buffer.from(
+          "<svg xmlns='http://www.w3.org/2000/svg' onload='alert(1)'><script>alert(1)</script><a href='https://evil.example/'><circle cx='12' cy='12' r='10'/></a></svg>",
+        ),
+        "logo.svg",
+      );
+
+    expect(res.status).toBe(201);
+    expect(svg.putFile).toHaveBeenCalledTimes(1);
+    const stored = (svg.putFile as ReturnType<typeof vi.fn>).mock.calls[0]?.[0];
+    expect(stored.contentType).toBe("image/svg+xml");
+    expect(stored.originalFilename).toBe("logo.svg");
+    const body = stored.body.toString("utf8");
+    expect(body).toContain("<svg");
+    expect(body).toContain("<circle");
+    expect(body).not.toContain("<script");
+    expect(body).not.toContain("onload=");
+    expect(body).not.toContain("https://evil.example/");
+  });
+
+  it("allows logo uploads within the general attachment limit", async () => {
+    const png = createStorageService("image/png");
+    const app = createApp(png);
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const file = Buffer.alloc(150 * 1024, "a");
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", file, "within-limit.png");
+
+    expect(res.status).toBe(201);
+  });
+
+  it("rejects logo files larger than the general attachment limit", async () => {
+    const app = createApp(createStorageService());
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const file = Buffer.alloc(MAX_ATTACHMENT_BYTES + 1, "a");
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", file, "too-large.png");
+
+    expect(res.status).toBe(422);
+    expect(res.body.error).toBe(`Image exceeds ${MAX_ATTACHMENT_BYTES} bytes`);
+  });
+
+  it("rejects unsupported image types", async () => {
+    const app = createApp(createStorageService("text/plain"));
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", Buffer.from("not an image"), "note.txt");
+
+    expect(res.status).toBe(422);
+    expect(res.body.error).toBe("Unsupported image type: text/plain");
+    expect(createAssetMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects SVG image uploads that cannot be sanitized", async () => {
+    const app = createApp(createStorageService("image/svg+xml"));
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", Buffer.from("not actually svg"), "logo.svg");
+
+    expect(res.status).toBe(422);
+    expect(res.body.error).toBe("SVG could not be sanitized");
+    expect(createAssetMock).not.toHaveBeenCalled();
+  });
+});

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),
+      }),
+    );
+  });
+});

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(),
 }));
 

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();
+  });
+});

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);
+  });
+});

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: [],
+      },
+    ]);
+  });
+});

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");
+  });
+});

server/src/adapters/registry.ts

@@ -5,6 +5,7 @@ import {
   syncClaudeSkills,
   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 {
@@ -13,6 +14,7 @@ import {
   syncCodexSkills,
   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 {
@@ -85,6 +87,7 @@ const claudeLocalAdapter: ServerAdapterModule = {
   models: claudeModels,
   supportsLocalAgentJwt: true,
   agentConfigurationDoc: claudeAgentConfigurationDoc,
+  getQuotaWindows: claudeGetQuotaWindows,
 };
 
 const codexLocalAdapter: ServerAdapterModule = {
@@ -98,6 +101,7 @@ const codexLocalAdapter: ServerAdapterModule = {
   listModels: listCodexModels,
   supportsLocalAgentJwt: true,
   agentConfigurationDoc: codexAgentConfigurationDoc,
+  getQuotaWindows: codexGetQuotaWindows,
 };
 
 const cursorLocalAdapter: ServerAdapterModule = {

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}`);

server/src/routes/agents.ts

@@ -30,6 +30,7 @@ import {
   accessService,
   approvalService,
   companySkillService,
+  budgetService,
   heartbeatService,
   issueApprovalService,
   issueService,
@@ -64,6 +65,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);
@@ -1094,6 +1096,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);
   });
 

server/src/routes/assets.ts

@@ -1,21 +1,104 @@
 import { Router, type Request, type Response } from "express";
 import multer from "multer";
+import createDOMPurify from "dompurify";
+import { JSDOM } from "jsdom";
 import type { Db } from "@paperclipai/db";
 import { createAssetImageMetadataSchema } from "@paperclipai/shared";
 import type { StorageService } from "../storage/types.js";
 import { assetService, logActivity } from "../services/index.js";
-import { assertCompanyAccess, getActorInfo } from "./authz.js";
 import { isAllowedContentType, MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
+import { assertCompanyAccess, getActorInfo } from "./authz.js";
+const SVG_CONTENT_TYPE = "image/svg+xml";
+const ALLOWED_COMPANY_LOGO_CONTENT_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/webp",
+  "image/gif",
+  SVG_CONTENT_TYPE,
+]);
+
+function sanitizeSvgBuffer(input: Buffer): Buffer | null {
+  const raw = input.toString("utf8").trim();
+  if (!raw) return null;
+
+  const baseDom = new JSDOM("");
+  const domPurify = createDOMPurify(
+    baseDom.window as unknown as Parameters<typeof createDOMPurify>[0],
+  );
+  domPurify.addHook("uponSanitizeAttribute", (_node, data) => {
+    const attrName = data.attrName.toLowerCase();
+    const attrValue = (data.attrValue ?? "").trim();
+
+    if (attrName.startsWith("on")) {
+      data.keepAttr = false;
+      return;
+    }
+
+    if ((attrName === "href" || attrName === "xlink:href") && attrValue && !attrValue.startsWith("#")) {
+      data.keepAttr = false;
+    }
+  });
+
+  let parsedDom: JSDOM | null = null;
+  try {
+    const sanitized = domPurify.sanitize(raw, {
+      USE_PROFILES: { svg: true, svgFilters: true, html: false },
+      FORBID_TAGS: ["script", "foreignObject"],
+      FORBID_CONTENTS: ["script", "foreignObject"],
+      RETURN_TRUSTED_TYPE: false,
+    });
+
+    parsedDom = new JSDOM(sanitized, { contentType: SVG_CONTENT_TYPE });
+    const document = parsedDom.window.document;
+    const root = document.documentElement;
+    if (!root || root.tagName.toLowerCase() !== "svg") return null;
+
+    for (const el of Array.from(root.querySelectorAll("script, foreignObject"))) {
+      el.remove();
+    }
+    for (const el of Array.from(root.querySelectorAll("*"))) {
+      for (const attr of Array.from(el.attributes)) {
+        const attrName = attr.name.toLowerCase();
+        const attrValue = attr.value.trim();
+        if (attrName.startsWith("on")) {
+          el.removeAttribute(attr.name);
+          continue;
+        }
+        if ((attrName === "href" || attrName === "xlink:href") && attrValue && !attrValue.startsWith("#")) {
+          el.removeAttribute(attr.name);
+        }
+      }
+    }
+
+    const output = root.outerHTML.trim();
+    if (!output || !/^<svg[\s>]/i.test(output)) return null;
+    return Buffer.from(output, "utf8");
+  } catch {
+    return null;
+  } finally {
+    parsedDom?.window.close();
+    baseDom.window.close();
+  }
+}
 
 export function assetRoutes(db: Db, storage: StorageService) {
   const router = Router();
   const svc = assetService(db);
-  const upload = multer({
+  const assetUpload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: MAX_ATTACHMENT_BYTES, files: 1 },
+  });
+  const companyLogoUpload = multer({
     storage: multer.memoryStorage(),
     limits: { fileSize: MAX_ATTACHMENT_BYTES, files: 1 },
   });
 
-  async function runSingleFileUpload(req: Request, res: Response) {
+  async function runSingleFileUpload(
+    upload: ReturnType<typeof multer>,
+    req: Request,
+    res: Response,
+  ) {
     await new Promise<void>((resolve, reject) => {
       upload.single("file")(req, res, (err: unknown) => {
         if (err) reject(err);
@@ -29,7 +112,7 @@ export function assetRoutes(db: Db, storage: StorageService) {
     assertCompanyAccess(req, companyId);
 
     try {
-      await runSingleFileUpload(req, res);
+      await runSingleFileUpload(assetUpload, req, res);
     } catch (err) {
       if (err instanceof multer.MulterError) {
         if (err.code === "LIMIT_FILE_SIZE") {
@@ -48,16 +131,6 @@ export function assetRoutes(db: Db, storage: StorageService) {
       return;
     }
 
-    const contentType = (file.mimetype || "").toLowerCase();
-    if (!isAllowedContentType(contentType)) {
-      res.status(422).json({ error: `Unsupported file type: ${contentType || "unknown"}` });
-      return;
-    }
-    if (file.buffer.length <= 0) {
-      res.status(422).json({ error: "Image is empty" });
-      return;
-    }
-
     const parsedMeta = createAssetImageMetadataSchema.safeParse(req.body ?? {});
     if (!parsedMeta.success) {
       res.status(400).json({ error: "Invalid image metadata", details: parsedMeta.error.issues });
@@ -65,13 +138,32 @@ export function assetRoutes(db: Db, storage: StorageService) {
     }
 
     const namespaceSuffix = parsedMeta.data.namespace ?? "general";
+    const contentType = (file.mimetype || "").toLowerCase();
+    if (contentType !== SVG_CONTENT_TYPE && !isAllowedContentType(contentType)) {
+      res.status(422).json({ error: `Unsupported file type: ${contentType || "unknown"}` });
+      return;
+    }
+    let fileBody = file.buffer;
+    if (contentType === SVG_CONTENT_TYPE) {
+      const sanitized = sanitizeSvgBuffer(file.buffer);
+      if (!sanitized || sanitized.length <= 0) {
+        res.status(422).json({ error: "SVG could not be sanitized" });
+        return;
+      }
+      fileBody = sanitized;
+    }
+    if (fileBody.length <= 0) {
+      res.status(422).json({ error: "Image is empty" });
+      return;
+    }
+
     const actor = getActorInfo(req);
     const stored = await storage.putFile({
       companyId,
       namespace: `assets/${namespaceSuffix}`,
       originalFilename: file.originalname || null,
       contentType,
-      body: file.buffer,
+      body: fileBody,
     });
 
     const asset = await svc.create(companyId, {
@@ -118,6 +210,105 @@ export function assetRoutes(db: Db, storage: StorageService) {
     });
   });
 
+  router.post("/companies/:companyId/logo", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+
+    try {
+      await runSingleFileUpload(companyLogoUpload, req, res);
+    } catch (err) {
+      if (err instanceof multer.MulterError) {
+        if (err.code === "LIMIT_FILE_SIZE") {
+          res.status(422).json({ error: `Image exceeds ${MAX_ATTACHMENT_BYTES} bytes` });
+          return;
+        }
+        res.status(400).json({ error: err.message });
+        return;
+      }
+      throw err;
+    }
+
+    const file = (req as Request & { file?: { mimetype: string; buffer: Buffer; originalname: string } }).file;
+    if (!file) {
+      res.status(400).json({ error: "Missing file field 'file'" });
+      return;
+    }
+
+    const contentType = (file.mimetype || "").toLowerCase();
+    if (!ALLOWED_COMPANY_LOGO_CONTENT_TYPES.has(contentType)) {
+      res.status(422).json({ error: `Unsupported image type: ${contentType || "unknown"}` });
+      return;
+    }
+
+    let fileBody = file.buffer;
+    if (contentType === SVG_CONTENT_TYPE) {
+      const sanitized = sanitizeSvgBuffer(file.buffer);
+      if (!sanitized || sanitized.length <= 0) {
+        res.status(422).json({ error: "SVG could not be sanitized" });
+        return;
+      }
+      fileBody = sanitized;
+    }
+
+    if (fileBody.length <= 0) {
+      res.status(422).json({ error: "Image is empty" });
+      return;
+    }
+
+    const actor = getActorInfo(req);
+    const stored = await storage.putFile({
+      companyId,
+      namespace: "assets/companies",
+      originalFilename: file.originalname || null,
+      contentType,
+      body: fileBody,
+    });
+
+    const asset = await svc.create(companyId, {
+      provider: stored.provider,
+      objectKey: stored.objectKey,
+      contentType: stored.contentType,
+      byteSize: stored.byteSize,
+      sha256: stored.sha256,
+      originalFilename: stored.originalFilename,
+      createdByAgentId: actor.agentId,
+      createdByUserId: actor.actorType === "user" ? actor.actorId : null,
+    });
+
+    await logActivity(db, {
+      companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "asset.created",
+      entityType: "asset",
+      entityId: asset.id,
+      details: {
+        originalFilename: asset.originalFilename,
+        contentType: asset.contentType,
+        byteSize: asset.byteSize,
+        namespace: "assets/companies",
+      },
+    });
+
+    res.status(201).json({
+      assetId: asset.id,
+      companyId: asset.companyId,
+      provider: asset.provider,
+      objectKey: asset.objectKey,
+      contentType: asset.contentType,
+      byteSize: asset.byteSize,
+      sha256: asset.sha256,
+      originalFilename: asset.originalFilename,
+      createdByAgentId: asset.createdByAgentId,
+      createdByUserId: asset.createdByUserId,
+      createdAt: asset.createdAt,
+      updatedAt: asset.updatedAt,
+      contentPath: `/api/assets/${asset.id}/content`,
+    });
+  });
+
   router.get("/assets/:assetId/content", async (req, res, next) => {
     const assetId = req.params.assetId as string;
     const asset = await svc.getById(assetId);
@@ -128,9 +319,14 @@ export function assetRoutes(db: Db, storage: StorageService) {
     assertCompanyAccess(req, asset.companyId);
 
     const object = await storage.getObject(asset.companyId, asset.objectKey);
-    res.setHeader("Content-Type", asset.contentType || object.contentType || "application/octet-stream");
+    const responseContentType = asset.contentType || object.contentType || "application/octet-stream";
+    res.setHeader("Content-Type", responseContentType);
     res.setHeader("Content-Length", String(asset.byteSize || object.contentLength || 0));
     res.setHeader("Cache-Control", "private, max-age=60");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    if (responseContentType === SVG_CONTENT_TYPE) {
+      res.setHeader("Content-Security-Policy", "sandbox; default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'");
+    }
     const filename = asset.originalFilename ?? "asset";
     res.setHeader("Content-Disposition", `inline; filename=\"${filename.replaceAll("\"", "")}\"`);
 
@@ -142,4 +338,3 @@ export function assetRoutes(db: Db, storage: StorageService) {
 
   return router;
 }
-

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);
   });
 

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);
   });
 

server/src/routes/issues.ts

@@ -921,6 +921,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;

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

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,

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!;
+    },
+  };
+}

server/src/services/companies.ts

@@ -1,7 +1,9 @@
-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,
+  companyLogos,
+  assets,
   agents,
   agentApiKeys,
   agentRuntimeState,
@@ -14,6 +16,7 @@ import {
   heartbeatRuns,
   heartbeatRunEvents,
   costEvents,
+  financeEvents,
   approvalComments,
   approvals,
   activityLog,
@@ -23,10 +26,84 @@ import {
   principalPermissionGrants,
   companyMemberships,
 } from "@paperclipai/db";
+import { notFound, unprocessable } from "../errors.js";
 
 export function companyService(db: Db) {
   const ISSUE_PREFIX_FALLBACK = "CMP";
 
+  const companySelection = {
+    id: companies.id,
+    name: companies.name,
+    description: companies.description,
+    status: companies.status,
+    issuePrefix: companies.issuePrefix,
+    issueCounter: companies.issueCounter,
+    budgetMonthlyCents: companies.budgetMonthlyCents,
+    spentMonthlyCents: companies.spentMonthlyCents,
+    requireBoardApprovalForNewAgents: companies.requireBoardApprovalForNewAgents,
+    brandColor: companies.brandColor,
+    logoAssetId: companyLogos.assetId,
+    createdAt: companies.createdAt,
+    updatedAt: companies.updatedAt,
+  };
+
+  function enrichCompany<T extends { logoAssetId: string | null }>(company: T) {
+    return {
+      ...company,
+      logoUrl: company.logoAssetId ? `/api/assets/${company.logoAssetId}/content` : null,
+    };
+  }
+
+  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)
+      .from(companies)
+      .leftJoin(companyLogos, eq(companyLogos.companyId, companies.id));
+  }
+
   function deriveIssuePrefixBase(name: string) {
     const normalized = name.toUpperCase().replace(/[^A-Z]/g, "");
     return normalized.slice(0, 3) || ISSUE_PREFIX_FALLBACK;
@@ -70,32 +147,109 @@ export function companyService(db: Db) {
   }
 
   return {
-    list: () => db.select().from(companies),
+    list: async () => {
+      const rows = await getCompanyQuery(db);
+      const hydrated = await hydrateCompanySpend(rows);
+      return hydrated.map((row) => enrichCompany(row));
+    },
 
-    getById: (id: string) =>
-      db
-        .select()
-        .from(companies)
+    getById: async (id: string) => {
+      const row = await getCompanyQuery(db)
         .where(eq(companies.id, id))
-        .then((rows) => 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) => createCompanyWithUniquePrefix(data),
+    create: async (data: typeof companies.$inferInsert) => {
+      const created = await createCompanyWithUniquePrefix(data);
+      const row = await getCompanyQuery(db)
+        .where(eq(companies.id, created.id))
+        .then((rows) => rows[0] ?? null);
+      if (!row) throw notFound("Company not found after creation");
+      const [hydrated] = await hydrateCompanySpend([row], db);
+      return enrichCompany(hydrated);
+    },
 
-    update: (id: string, data: Partial<typeof companies.$inferInsert>) =>
-      db
-        .update(companies)
-        .set({ ...data, updatedAt: new Date() })
-        .where(eq(companies.id, id))
-        .returning()
-        .then((rows) => rows[0] ?? null),
+    update: (
+      id: string,
+      data: Partial<typeof companies.$inferInsert> & { logoAssetId?: string | null },
+    ) =>
+      db.transaction(async (tx) => {
+        const existing = await getCompanyQuery(tx)
+          .where(eq(companies.id, id))
+          .then((rows) => rows[0] ?? null);
+        if (!existing) return null;
+
+        const { logoAssetId, ...companyPatch } = data;
+
+        if (logoAssetId !== undefined && logoAssetId !== null) {
+          const nextLogoAsset = await tx
+            .select({ id: assets.id, companyId: assets.companyId })
+            .from(assets)
+            .where(eq(assets.id, logoAssetId))
+            .then((rows) => rows[0] ?? null);
+          if (!nextLogoAsset) throw notFound("Logo asset not found");
+          if (nextLogoAsset.companyId !== existing.id) {
+            throw unprocessable("Logo asset must belong to the same company");
+          }
+        }
+
+        const updated = await tx
+          .update(companies)
+          .set({ ...companyPatch, updatedAt: new Date() })
+          .where(eq(companies.id, id))
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        if (!updated) return null;
+
+        if (logoAssetId === null) {
+          await tx.delete(companyLogos).where(eq(companyLogos.companyId, id));
+        } else if (logoAssetId !== undefined) {
+          await tx
+            .insert(companyLogos)
+            .values({
+              companyId: id,
+              assetId: logoAssetId,
+            })
+            .onConflictDoUpdate({
+              target: companyLogos.companyId,
+              set: {
+                assetId: logoAssetId,
+                updatedAt: new Date(),
+              },
+            });
+        }
+
+        if (logoAssetId !== undefined && existing.logoAssetId && existing.logoAssetId !== logoAssetId) {
+          await tx.delete(assets).where(eq(assets.id, existing.logoAssetId));
+        }
+
+        const [hydrated] = await hydrateCompanySpend([{
+          ...updated,
+          logoAssetId: logoAssetId === undefined ? existing.logoAssetId : logoAssetId,
+        }], tx);
+
+        return enrichCompany(hydrated);
+      }),
 
     archive: (id: string) =>
-      db
-        .update(companies)
-        .set({ status: "archived", updatedAt: new Date() })
-        .where(eq(companies.id, id))
-        .returning()
-        .then((rows) => rows[0] ?? null),
+      db.transaction(async (tx) => {
+        const updated = await tx
+          .update(companies)
+          .set({ status: "archived", updatedAt: new Date() })
+          .where(eq(companies.id, id))
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        if (!updated) return null;
+        const row = await getCompanyQuery(tx)
+          .where(eq(companies.id, id))
+          .then((rows) => rows[0] ?? null);
+        if (!row) return null;
+        const [hydrated] = await hydrateCompanySpend([row], tx);
+        return enrichCompany(hydrated);
+      }),
 
     remove: (id: string) =>
       db.transaction(async (tx) => {
@@ -108,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));
@@ -116,6 +271,8 @@ export function companyService(db: Db) {
         await tx.delete(principalPermissionGrants).where(eq(principalPermissionGrants.companyId, id));
         await tx.delete(companyMemberships).where(eq(companyMemberships.companyId, id));
         await tx.delete(issues).where(eq(issues.companyId, id));
+        await tx.delete(companyLogos).where(eq(companyLogos.companyId, id));
+        await tx.delete(assets).where(eq(assets.companyId, id));
         await tx.delete(goals).where(eq(goals.companyId, id));
         await tx.delete(projects).where(eq(projects.companyId, id));
         await tx.delete(agents).where(eq(agents.companyId, id));

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));
     },
   };

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,
+        },
       };
     },
   };

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);
+    },
+  };
+}

server/src/services/heartbeat.ts

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 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,
@@ -23,6 +24,7 @@ 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 { companySkillService } from "./company-skills.js";
+import { budgetService, type BudgetEnforcementScope } from "./budgets.js";
 import { secretService } from "./secrets.js";
 import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js";
 import { summarizeHeartbeatRunResultJson } from "./heartbeat-run-summary.js";
@@ -171,6 +173,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 {
@@ -559,6 +622,10 @@ export function heartbeatService(db: Db) {
   const companySkills = companySkillService(db);
   const issuesSvc = issueService(db);
   const activeRunExecutions = new Set<string>();
+  const budgetHooks = {
+    cancelWorkForScope: cancelBudgetScopeWork,
+  };
+  const budgets = budgetService(db, budgetHooks);
 
   async function getAgent(agentId: string) {
     return db
@@ -1141,6 +1208,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)
@@ -1296,8 +1383,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)
@@ -1316,12 +1407,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(),
@@ -1333,6 +1430,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);
@@ -1882,8 +1982,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;
 
@@ -2233,6 +2336,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" ||
@@ -2242,21 +2382,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");
@@ -2666,6 +2791,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
@@ -2838,77 +3162,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

server/src/services/index.ts

@@ -9,8 +9,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";

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);
+  }
+}