fix(server): preserve budget history for deleted resources (#18389)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Budget views show saved policies, incidents and spend for each
company.
> - A policy can remain after its agent or project has been deleted.
> - The overview currently stops when it cannot resolve that old
resource.
> - A current agent's budget then becomes unreadable during normal
setup.
> - This pull request preserves the historical row in display summaries.
> - Admission and policy changes still require a real company-owned
resource.

## Linked Issues or Issue Description

**What happened?**

The budget overview throws `Agent not found` when a saved policy
references a deleted agent. One old resource prevents the company from
reading its current budgets. The same problem affects historical project
policies and incident summaries.

**Expected behavior**

The overview should retain historical policy and incident IDs and spend.
It should display `Deleted agent` or `Deleted project` for a missing
resource. Read access must not grant permission to execute work or
change a budget for that resource.

**Steps to reproduce**

1. Create an agent and a budget policy for it.
2. Permanently delete the agent after its other dependencies have been
cleared.
3. Read the company's budget overview. The existing service throws
instead of returning its remaining current and historical rows.

**Paperclip version or commit**

The isolated repair starts from merged commit
`d9354bbfc35ef74333e90e596ce21dc8e59149b9` and integrates the exact
merged baseline test fix `8595efc20bda3ce20a9fbbf34a5d156a6fcf6d57`. It
also integrates the actual merged Antigravity auth fix
`18b1637b6371a6a6adade857e2a73654ee626fef` (#18254). The diff against
the selected merged parent remains two budget files.

**Related work**

Earlier reports and implementations: #11058 and #4333. This extracts the
product prerequisite from #18351 so it can qualify independently of that
journey's other dependencies. The change contains only the budget
service repair and four database regression cases.

## What Changed

- Resolve deleted agent and project scopes only when building display
summaries. Preserve their original IDs, policies, incidents and
accounting records.
- Reject a saved policy or incident that resolves to another company's
resource. Propagate other read failures.
- Keep missing-company resolution, work admission and policy changes
strict. Validate company, policy and incident scope bindings before
either incident action. A budget raise requires a live company-owned
resource. Historical dismissal may proceed only for a genuinely deleted
owned agent/project, and must reject live foreign or mismatched scopes.
- Add four canonical PostgreSQL regression cases: deleted agent history,
deleted project history, missing-scope admission and budget raises with
safe historical dismissal, and foreign/mismatched references. The
history cases also verify current ledger spend and unchanged stored
rows.

## Verification

- Real-service RED/GREEN against official PGlite with every canonical
migration: the original overview throws for deleted history; the repair
returns the historical IDs, incidents and spend while retaining current
budgets.
- Mutation regression RED/GREEN: missing-resource budget raises must
reject before writes; owned deleted-scope dismissal must reject its
linked pending approval, retain policy/agent/ledger data and incident
history, and remove the incident from the active list. Live foreign and
mismatched scopes reject both actions without mutations.
- Current integrated head `b3434f5ad05fd3067379352700c36bfe826179c4`:
all four canonical PostgreSQL regressions pass in [server
2/12](https://github.com/paperclipai/paperclip/actions/runs/41142588583/job/124361194077),
and all five existing budget-service tests pass in [server
7/12](https://github.com/paperclipai/paperclip/actions/runs/41142588583/job/124361194080).
Both use the CI merge against selected parent `18b1637`.
- Clean-build declaration typing passes in the current CI typecheck
gate. The earlier local source-alias no-emit check also passed,
including the canonical actor argument. The local worktree borrows
compiled dependencies from a sibling checkout; a later real-service
import was blocked by its stale `sandboxCreationOperations` export, so
clean-build CI is authoritative for the final integration. No production
workaround was made.
- `git diff --check` passes. Broad repository typecheck, tests and build
run in current-head CI rather than repeated locally. Native local
PostgreSQL could not start because this host exhausted its semaphore
pool; no global IPC settings or unrelated processes were changed.
- One unchanged Runner lane retry was authorized after a probable
intermittent close-settlement fixture failure. The [original
failure](https://github.com/paperclipai/paperclip/actions/runs/41142588583/job/124360234111)
occurred in `omitted-context` cleanup. A [fresh passing Linux
lane](https://github.com/paperclipai/paperclip/actions/runs/41142552195/job/124360110386)
passed the same case and all 1,998 tests with byte-identical entire
Runner and adapter-utils trees, lockfile, root package, scripts and
workflows, against the same merged base. The fixture has a five-second
close allowance with a 2.5-second suspension reserve; a host stall is
not proven. No budget path or changed close input was found. The [single
targeted
retry](https://github.com/paperclipai/paperclip/actions/runs/41142588583/job/124365812609)
passed the same case in 1,034 ms and all 1,998 lane tests; dependent
verification also passed. All 57 current PR checks are terminal and
green.
- The product helper requires all current CI and clean review before
merge. Actual QA budget-overview proof will run on the combined final
app before hiring qualification. No deployed success is claimed. The
older `b4863dd` artifact was never deployed; selected parent `18b1637`
adds sandbox/lifecycle changes and migration 0418, so whole-app identity
is not claimed. The budget module and relevant budget contracts remain
unchanged, and final hiring requires the combined final app with
explicit source identities.

## Risks

Budget summaries now return historical rows whose resources have been
deleted. These rows use explicit display names and preserve their
accounting data. They do not create a resource or relax work admission,
authorization or budget grants. Historical incident dismissal changes
only that incident and its linked approval; it does not resume work or
raise a budget. Cross-company references still fail closed. There is no
schema migration and no new background work.

## Model Used

OpenAI Codex, GPT-6 family. The session does not expose a more specific
backend model ID or fixed context window. Used reasoning, repository
tools, TypeScript and database test execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes (the
PR description documents the display-only history and strict-mutation
contract)
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

server/src/__tests__/budgets-history.test.ts

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { agents, approvals, budgetIncidents, budgetPolicies, companies, costEvents, createDb, projects, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS } from "@paperclipai/db";
+import { budgetService } from "../services/budgets.js";
+import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
+
+vi.mock("../services/activity-log.js", () => ({ logActivity: vi.fn() }));
+const support = await getEmbeddedPostgresTestSupport();
+
+describe.skipIf(!support.supported)("budget history for deleted scopes", () => {
+  let db: ReturnType<typeof createDb>;
+  let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
+  beforeAll(async () => {
+    database = await startEmbeddedPostgresTestDatabase("paperclip-budget-history-");
+    db = createDb(database.connectionString);
+  }, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS);
+  afterEach(async () => {
+    await db.delete(budgetIncidents); await db.delete(approvals); await db.delete(budgetPolicies); await db.delete(costEvents);
+    await db.delete(projects); await db.delete(agents); await db.delete(companies);
+  });
+  afterAll(async () => { await db?.$client.end({ timeout: 1 }); await database?.cleanup(); });
+
+  async function fixture() {
+    const companyId = randomUUID(), agentId = randomUUID();
+    await db.insert(companies).values({ id: companyId, name: "History company", issuePrefix: `B${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}` });
+    await db.insert(agents).values({ id: agentId, companyId, name: "Current agent", role: "engineer" });
+    const [policy] = await db.insert(budgetPolicies).values({ companyId, scopeType: "agent", scopeId: agentId,
+      metric: "billed_cents", windowKind: "calendar_month_utc", amount: 300 }).returning();
+    await db.insert(costEvents).values({ companyId, agentId, provider: "openai", model: "history-fixture", inputTokens: 1, outputTokens: 1, costCents: 17, occurredAt: new Date() });
+    return { companyId, agentId, policy: policy! };
+  }
+
+  it.each(["agent", "project"] as const)("keeps current budgets and deleted %s policy/incident history readable without changing stored rows", async scopeType => {
+    const { companyId, policy } = await fixture(), deletedId = randomUUID();
+    if (scopeType === "agent") await db.insert(agents).values({ id: deletedId, companyId, name: "Former agent", role: "engineer" });
+    else await db.insert(projects).values({ id: deletedId, companyId, name: "Former project" });
+    const [historical] = await db.insert(budgetPolicies).values({ companyId, scopeType, scopeId: deletedId,
+      metric: "billed_cents", windowKind: "calendar_month_utc", amount: 200 }).returning();
+    await db.insert(budgetIncidents).values({ companyId, policyId: historical!.id, scopeType, scopeId: deletedId,
+      metric: "billed_cents", windowKind: "calendar_month_utc", windowStart: new Date("2020-01-01"), windowEnd: new Date("2020-02-01"),
+      thresholdType: "hard", amountLimit: 200, amountObserved: 201 });
+    if (scopeType === "agent") await db.delete(agents).where(eq(agents.id, deletedId));
+    else await db.delete(projects).where(eq(projects.id, deletedId));
+    const policiesBefore = await db.select().from(budgetPolicies), incidentsBefore = await db.select().from(budgetIncidents), costsBefore = await db.select().from(costEvents);
+
+    const overview = await budgetService(db).overview(companyId);
+    expect(overview.policies).toHaveLength(2);
+    expect(overview.policies.find(row => row.policyId === policy.id)).toMatchObject({ companyId, scopeName: "Current agent", amount: 300, observedAmount: 17 });
+    expect(overview.policies.find(row => row.policyId === historical!.id)).toMatchObject({ companyId, scopeType, scopeId: deletedId, scopeName: `Deleted ${scopeType}`, amount: 200 });
+    expect(overview.activeIncidents).toMatchObject([{ companyId, policyId: historical!.id, scopeId: deletedId, scopeName: `Deleted ${scopeType}`, status: "open", amountObserved: 201 }]);
+    expect(await db.select().from(budgetPolicies)).toEqual(policiesBefore);
+    expect(await db.select().from(budgetIncidents)).toEqual(incidentsBefore);
+    expect(await db.select().from(costEvents)).toEqual(costsBefore);
+  });
+  it("rejects missing-scope budget grants but can dismiss their historical incidents", async () => {
+    const { companyId, agentId } = await fixture(), missingId = randomUUID(), service = budgetService(db);
+    await expect(service.evaluateAdmission(companyId, missingId)).rejects.toThrow("Agent not found");
+    await expect(service.evaluateAdmission(companyId, agentId, { projectId: missingId })).rejects.toThrow("Project not found");
+    for (const scopeType of ["agent", "project"] as const) {
+      await expect(service.upsertPolicy(companyId, { scopeType, scopeId: missingId, amount: 100 }, "board")).rejects.toThrow(`${scopeType === "agent" ? "Agent" : "Project"} not found`);
+      const [policy] = await db.insert(budgetPolicies).values({ companyId, scopeType, scopeId: missingId,
+        windowKind: "calendar_month_utc", amount: 100 }).returning();
+      const [approval] = await db.insert(approvals).values({ companyId, type: "budget_override_required", payload: {} }).returning();
+      const [incident] = await db.insert(budgetIncidents).values({ companyId, policyId: policy!.id, approvalId: approval!.id, scopeType, scopeId: missingId,
+        metric: "billed_cents", windowKind: "calendar_month_utc", windowStart: new Date("2020-01-01"), windowEnd: new Date("2020-02-01"),
+        thresholdType: "hard", amountLimit: 100, amountObserved: 101 }).returning();
+      const before = { policies: await db.select().from(budgetPolicies), incidents: await db.select().from(budgetIncidents),
+        agents: await db.select().from(agents), costs: await db.select().from(costEvents), approvals: await db.select().from(approvals) };
+      await expect(service.resolveIncident(companyId, incident!.id, { action: "raise_budget_and_resume", amount: 200 }, "board"))
+        .rejects.toThrow(`${scopeType === "agent" ? "Agent" : "Project"} not found`);
+      expect({ policies: await db.select().from(budgetPolicies), incidents: await db.select().from(budgetIncidents),
+        agents: await db.select().from(agents), costs: await db.select().from(costEvents), approvals: await db.select().from(approvals) }).toEqual(before);
+      const dismissed = await service.resolveIncident(companyId, incident!.id, { action: "keep_paused" }, "board");
+      expect(dismissed).toMatchObject({ companyId, policyId: policy!.id, scopeId: missingId, scopeName: `Deleted ${scopeType}`, status: "dismissed" });
+      const { status: _status, resolvedAt: _resolvedAt, updatedAt: _updatedAt, ...preserved } = incident!;
+      const [saved] = await db.select().from(budgetIncidents).where(eq(budgetIncidents.id, incident!.id));
+      expect(saved).toMatchObject({ ...preserved, status: "dismissed", resolvedAt: expect.any(Date) });
+      expect((await db.select().from(approvals).where(eq(approvals.id, approval!.id)))[0]).toMatchObject({ status: "rejected" });
+      expect(await db.select().from(budgetPolicies)).toEqual(before.policies);
+      expect(await db.select().from(agents)).toEqual(before.agents);
+      expect(await db.select().from(costEvents)).toEqual(before.costs);
+      expect((await service.overview(companyId)).activeIncidents.some(row => row.id === incident!.id)).toBe(false);
+    }
+  });
+
+  it("rejects a corrupted policy pointing to another company's scope instead of exposing its name", async () => {
+    const { companyId } = await fixture(), foreignCompanyId = randomUUID(), foreignAgentId = randomUUID();
+    await db.insert(companies).values({ id: foreignCompanyId, name: "Other company", issuePrefix: `F${foreignCompanyId.replace(/-/g, "").slice(0, 6).toUpperCase()}` });
+    await db.insert(agents).values({ id: foreignAgentId, companyId: foreignCompanyId, name: "Private other-company agent", role: "engineer" });
+    const [policy] = await db.insert(budgetPolicies).values({ companyId, scopeType: "agent", scopeId: foreignAgentId, windowKind: "calendar_month_utc", amount: 200 }).returning();
+    const [incident] = await db.insert(budgetIncidents).values({ companyId, policyId: policy!.id, scopeType: "agent", scopeId: foreignAgentId,
+      metric: "billed_cents", windowKind: "calendar_month_utc", windowStart: new Date("2020-01-01"), windowEnd: new Date("2020-02-01"),
+      thresholdType: "hard", amountLimit: 200, amountObserved: 201 }).returning();
+    const service = budgetService(db);
+    await expect(service.overview(companyId)).rejects.toThrow("Budget scope not found");
+    for (const scopeId of [foreignAgentId, randomUUID()]) {
+      await db.update(budgetIncidents).set({ scopeId }).where(eq(budgetIncidents.id, incident!.id));
+      const before = { policies: await db.select().from(budgetPolicies), incidents: await db.select().from(budgetIncidents),
+        agents: await db.select().from(agents), costs: await db.select().from(costEvents) };
+      for (const action of ["raise_budget_and_resume", "keep_paused"] as const) {
+        await expect(service.resolveIncident(companyId, incident!.id, { action, amount: 300 }, "board")).rejects.toThrow("Budget scope not found");
+        expect({ policies: await db.select().from(budgetPolicies), incidents: await db.select().from(budgetIncidents),
+          agents: await db.select().from(agents), costs: await db.select().from(costEvents) }).toEqual(before);
+      }
+    }
+  });
+
+});

server/src/services/budgets.ts

@@ -163,6 +163,19 @@ async function resolveScopeRecord(db: Db, scopeType: BudgetScopeType, scopeId: s
   };
 }
 
+async function resolveSummaryScopeRecord(db: Db, companyId: string, scopeType: BudgetScopeType, scopeId: string): Promise<ScopeRecord> {
+  let scope: ScopeRecord;
+  try {
+    scope = await resolveScopeRecord(db, scopeType, scopeId);
+  } catch (error) {
+    if (!(error instanceof HttpError) || error.status !== 404 || (scopeType !== "agent" && scopeType !== "project")) throw error;
+    return { companyId, name: scopeType === "agent" ? "Deleted agent" : "Deleted project",
+      paused: false, pauseReason: null, budgetHeld: false };
+  }
+  if (scope.companyId !== companyId) throw notFound("Budget scope not found");
+  return scope;
+}
+
 // Keep a large dashboard from filling the database pool with queued reads.
 async function mapBudgetReads<T, R>(rows: T[], read: (row: T) => Promise<R>): Promise<R[]> {
   const result: R[] = [];
@@ -395,7 +408,7 @@ export function budgetServiceInTransaction(db: Db, publications: ActivityPublica
   }
 
   async function buildPolicySummary(policy: PolicyRow): Promise<BudgetPolicySummary> {
-    const scope = await resolveScopeRecord(db, policy.scopeType as BudgetScopeType, policy.scopeId);
+    const scope = await resolveSummaryScopeRecord(db, policy.companyId, policy.scopeType as BudgetScopeType, policy.scopeId);
     const observed = await computeObservedSpend(db, policy);
     const { total: observedAmount, totalExact: observedAmountExact, unpricedEventCount, pendingRunCount } = observed;
     const { windowStart: start, windowEnd: end } = observed;
@@ -560,7 +573,7 @@ export function budgetServiceInTransaction(db: Db, publications: ActivityPublica
     const approvalStatusById = new Map(approvalRows.map((row) => [row.id, row.status]));
 
     return mapBudgetReads(rows, async (row) => {
-      const scope = await resolveScopeRecord(db, row.scopeType as BudgetScopeType, row.scopeId);
+      const scope = await resolveSummaryScopeRecord(db, row.companyId, row.scopeType as BudgetScopeType, row.scopeId);
       return {
         id: row.id,
         companyId: row.companyId,
@@ -925,6 +938,13 @@ export function budgetServiceInTransaction(db: Db, publications: ActivityPublica
       if (incident.companyId !== companyId) throw notFound("Budget incident not found");
 
       const policy = await getPolicyRow(incident.policyId);
+      if (policy.companyId !== companyId || policy.scopeType !== incident.scopeType || policy.scopeId !== incident.scopeId) {
+        throw notFound("Budget scope not found");
+      }
+      const scope = input.action === "keep_paused"
+        ? await resolveSummaryScopeRecord(db, companyId, policy.scopeType as BudgetScopeType, policy.scopeId)
+        : await resolveScopeRecord(db, policy.scopeType as BudgetScopeType, policy.scopeId);
+      if (scope.companyId !== companyId) throw notFound("Budget scope not found");
       if (input.action === "raise_budget_and_resume") {
         const nextAmount = Math.max(0, Math.floor(input.amount ?? 0));
         const observed = await computeObservedSpend(db, policy);