Title: DELETE /api/agents/:id and DELETE /api/companies/:id fail with FK violation on cost_events

[kr8vkaos]

Summary

Hard-deleting an agent (or company) that has heartbeat_runs entries fails with HTTP 500 because cost_events.heartbeat_run_id has a foreign key into heartbeat_runs that the delete path doesn't clean up first.

Reproduction

1. Fresh onboard via pnpm paperclipai run (local_trusted mode)
2. Create a company and an agent
3. Run at least one heartbeat (pnpm paperclipai heartbeat run --agent-id <id>) so cost_events rows exist
4. curl -X DELETE http://localhost:3100/api/agents/<id>

Expected

HTTP 200, agent deleted.

Actual

HTTP 500. Server log:
update or delete on table "heartbeat_runs" violates foreign key constraint "cost_events_heartbeat_run_id_heartbeat_runs_id_fk" on table "cost_events"

Postgres detail: Key (id)=(<heartbeat-run-id>) is still referenced from table "cost_events".

Workaround

PATCH agent status to terminated and POST to /api/companies/:id/archive. Company remains in the default GET /api/companies list though — see separate issue about archived-company filtering.

Versions

• Paperclip: canary/v2026.416.1-canary.4 (CLI reports 0.3.1)
• Postgres: embedded (54329)
• Windows 11

[serenakeyitan]

null

[serenakeyitan]

🌱 gardener · ✅ ALIGNED · severity: medium

What is this? repo-gardener checks whether PRs and issues fit the project's product decisions, architecture, and roadmap — not code correctness. Think of it as a product-context review layer. For code review, see Greptile/CodeRabbit.

Context fit

Area	This Issue	Tree guidance	Fit
Data integrity on delete	FK violation when deleting agents/companies that have cost_events linked via heartbeat_runs	Tree requires governance-first design; all mutations must maintain consistent state	✅ Valid bug — fixing a broken delete path is squarely aligned
Heartbeat run lifecycle	cost_events reference heartbeat_runs; cascading delete or pre-delete cleanup needed	engineering/backend/heartbeat-run-orchestration — state transitions must be atomic; partial results from crashed executions are a known concern	✅ Fits within the orchestration hardening scope
Company-scoped isolation	Deleting a company entity must clean up all scoped entities	engineering/database/company-scoped-isolation.md — isolation bugs are application bugs; service code must treat company scoping as a first principle	✅ This is exactly the class of application-layer integrity issue the tree flags

Tree nodes referenced

• engineering/backend/heartbeat-run-orchestration/NODE.md — Run lifecycle, failure hardening, and partial-result handling
• engineering/database/company-scoped-isolation.md — Application-layer enforcement of scoping; isolation bugs are not auto-rescued by the DB

The fix likely belongs in the service layer: either cascade-delete cost_events (and potentially heartbeat_run_events) before deleting heartbeat_runs, or use a DB-level cascade. The tree's isolation model is a signal not to rely on the database to automatically rescue this — the service code owns the cleanup ordering.

---

_{Reviewed: issue@2026-04-17T21:30:51Z · Tree: ddfe6b6c · Commands: @gardener re-review · @gardener pause · @gardener ignore}

_{🌱 Posted by repo-gardener — reviews this repo against serenakeyitan/paperclip-tree. Not affiliated with this project's maintainers.}