mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - After a server restart, the new server reattaches to the live runs
of the old server (the reattach phase)
> - In a restart-chaos release swap with a hard kill, six runs
authenticated in under 10 s but no run was reached
> - The whole API then stopped answering for about 480 s: plain GETs
timed out, CPU was idle, and no run events were saved
> - The process identity write of each run started and did not commit,
so the reattach phase ended at its 180 s cap with 0 of 6 reached
> - The wave kept no `pg_stat_activity` or `pg_locks` data, so the head
of the lock chain cannot be proven from the evidence
> - This pull request records that data on the server at the moment the
stall is detected
> - The benefit is that the next occurrence names the blocking session
and its query, so the real fix targets one proven holder
## Linked Issues or Issue Description
**What happened?**
In a restart-chaos K15 release swap, the outgoing server got SIGKILL.
The incoming server reattached six remote runs after their leases
expired. All six runs authenticated. None was reached. The reattach
phase ended at the cap. The server did not answer any API request from
about 22:35:24Z to 22:43:23Z. Then all buffered events arrived in the
same second. The task finished without help, but the runs were silent
for about 8 minutes.
**Expected behavior**
The runs are reached within seconds, as in the hand-off swap of the same
wave (6 of 6 reached in 13 s). If a stall occurs, the server log names
what holds the database.
**Steps to reproduce**
Run a release swap that kills the outgoing server with SIGKILL while six
remote runs are live. Wait for their controller leases to expire.
**Paperclip version or commit**
master at 3452639a81 (restart-chaos wave w-20261116T220803-s7105).
**Database mode**
External Postgres on loopback, owned outside the server process tree.
A follow-up check ruled out one cause: a SIGKILLed client's row lock on
this loopback path is released in 4 ms, so no orphaned session from the
killed server held the run rows.
## What Changed
- `reattach-phase.ts`: when the reattach phase ends at its cap and some
runs authenticated but were never reached, the server reads
`pg_stat_activity` with `pg_blocking_pids` on the private liveness pool.
It logs the waiting sessions, their blockers, long transactions, and the
dedicated connection stats.
- The read uses a 5 s statement timeout and a pool that a stalled main
pool cannot starve.
- Test: an embedded Postgres test holds a run row lock, starts a second
waiting transaction, ends the phase at the cap with an authenticated
run, and checks that the log names the holder and the waiter.
## Verification
- `cd server && npx vitest run
src/services/heartbeat/reattach-phase.test.ts` passes (36 tests).
- Red/green: with the source change reverted, the new test fails
(`expected false to be true`). With the change, it passes.
- `npx tsc --noEmit -p server` passes.
- `pnpm verify` asked for broader coverage (opaque setup dependency), so
required CI gives that coverage.
## Risks
- Low risk. The read runs only when a cap ends with authenticated but
unreached runs. It runs on the liveness pool with a 5 s timeout. A
failure is logged and ignored.
- Query text in the log is cut to 160 characters. Drizzle sends
parameters apart from the text, so values do not appear.
- This change does not remove the stall. It makes its cause visible for
the next fix.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in Claude Code.
## 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>