## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The heartbeat service runs agent work and resumes interrupted native
sessions on timers
> - `drainActiveRunExecutions()` lets a caller that tears down shared
state (a test cleanup) wait until no background run work is in flight
> - The drain cleared resume timers that had not fired yet, but it could
not see a timer that had already fired and was still reading and
claiming run state
> - That untracked work raced the `fresh-continuation-fallback.test.ts`
cleanup TRUNCATE and deadlocked it, which failed Cloud readiness and
held releases on 2026-11-13
> - This pull request makes the drain wait for fired resume dispatches
too, and removes the deadlock retry from that suite's cleanup
> - The benefit is a deterministic cleanup: nothing still writes run
tables when the drain returns, so the release gate no longer fails on
this test
## Linked Issues or Issue Description
No public issue exists. The bug is described here.
**What happened?**
Cloud readiness `verify / General tests (server (5/10))` failed on
master commits 18fb6ee571 and 5ede64f247. The `afterEach` TRUNCATE in
`fresh-continuation-fallback.test.ts` failed with `deadlock detected`
(40P01). Another backend held a lock on one run table and was waiting on
a table that the TRUNCATE had already locked. #21375 added a drain and
wrapped the TRUNCATE in `truncateTablesWithDeadlockRetry`. The retry
hides the race but does not remove it.
**Root cause**
`scheduleNativeSessionResumeDispatch` arms a timer. When it fires, its
async body calls `getSchedulingSuppression`, then
`recoverNativeRunsAfterRestart` or `dispatchNativeSessionResumptions`.
All of these read and claim run rows before any execution is registered.
Recovery arms an immediate timer (`new Date()`).
`drainActiveRunExecutions()` only cleared timers that had not fired. It
did not track the fired body, so it returned while that work still ran.
A failed dispatch could also re-arm a 30-second timer after the drain
had cleared the timers.
**Expected behavior**
When `drainActiveRunExecutions()` resolves, no heartbeat background work
writes to the database.
**Steps to reproduce**
The new test `heartbeat-drain-native-resume-dispatch.test.ts` holds an
ACCESS EXCLUSIVE lock on `instance_settings` and `heartbeat_runs`. It
arms an immediate resume dispatch and waits until a backend is blocked
behind that lock, which proves the timer fired. Then it starts the
drain. On the old code the drain resolves at once. The leaked query then
also outlives the test and fails at teardown with `CONNECTION_ENDED`.
## What Changed
- `heartbeat.ts`: the fired resume-dispatch body is tracked in a
module-level set, `activeNativeResumeDispatches`, shared by all service
instances like the other drain sets. `drainActiveRunExecutions()` awaits
that set. It still clears only the timers armed before it started. A
timer armed during the drain that is already due (for example the
immediate dispatch a run arms when its executor detaches) counts as
pending work: the drain yields so it fires, then drains what it starts.
Timers due later keep their deadline. A first version cleared timers on
every pass, and CI showed that this cancelled the self-detach takeover
in `heartbeat-native-restart-suspension.test.ts`.
- `heartbeatService` exposes `scheduleNativeSessionResumeDispatch` so
the regression test can drive it. Recovery already uses it.
- `fresh-continuation-fallback.test.ts` uses a plain TRUNCATE again. A
future leak fails the test instead of being retried away.
- New test `heartbeat-drain-native-resume-dispatch.test.ts`, described
above.
## Verification
- Red: the new drain test fails on the old `heartbeat.ts` (`expected
true to be false`: the drain returned while the dispatch was blocked).
- Green: the new drain test passes with the fix.
- Repeated runs with the fix and the plain TRUNCATE (no retry): 50/50
for "runs a person's Retry pressed before delivery…", 50/50 for "…old
lease is pending_cleanup", and 80 runs of "…old lease is active". No
deadlock occurred.
- In the loaded local runs, 11 of the 80 "active" repeats hit the 30 s
hook timeout. I logged `pg_stat_activity` every 5 s during cleanup. In
each case the drain had finished within 5.6 s. The TRUNCATE was `active`
with no lock wait and no other open backend: it was slow cascade I/O on
a host at load average 30 to 60. These were not leaks.
- `heartbeat-native-restart-suspension.test.ts`, the drain test and
`fresh-continuation-fallback.test.ts` together: 188/188 locally.
- `npx tsc --noEmit -p server`: no errors.
## Risks
- The drain now also waits for fired resume dispatches. These dispatches
are short. A slow one makes a test cleanup wait longer instead of racing
it.
- Production behavior does not change. Only callers of
`drainActiveRunExecutions()` see the difference.
- Follow-up, not in this PR: four other heartbeat suites still use
`truncateTablesWithDeadlockRetry`. They may no longer need it.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code 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
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Server tests that need a real PostgreSQL process must use
./helpers/embedded-postgres.ts instead of constructing embedded-postgres
directly.
The shared helper creates a throwaway data directory and a reserved-safe
loopback port for each test database. This protects the live Paperclip
control-plane Postgres from server vitest runs; see PAP-2033 for the incident
that introduced this guard.