Files
PaperClipAI/server
DottaandClaude Opus 5.5 7a4a5bba8a test(server): advance the maintenance fake clock only after database connections finish startup (#22523)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The maintenance server tests boot the real server in a child process
with a fake clock. The test moves the clock forward (up to 30 s per
step) to reach deadlines fast.
> - The fake clock also replaces the timers of the PostgreSQL driver.
The driver starts a 30 s connect timer when it opens a connection, and
stops it at the first ReadyForQuery.
> - If the test moves the clock 30 s while a new database connection is
still in startup, the connect timer fires at once. The query fails with
`CONNECT_TIMEOUT`, the queue goes into retry, and the server does not
settle.
> - This race stopped the Release for 856f14e507 in `verify / Serialized
tests (2/5)`.
> - This pull request makes the child wait until every database
connection has finished startup before it moves the clock.
> - The benefit is that clock steps never fire a real-network timeout,
so these tests no longer depend on runner speed.

## Linked Issues or Issue Description

**What happened?**
The Cloud readiness run 44954319430 (Release for 856f14e507) failed in
`verify / Serialized tests (2/5)`. The failed test is
`maintenance-server-routes.test.ts > assembled maintenance server
production wiring > reacts to the first ordinary status-card source
write and accepts authorized controlled summarizer output`. The error is
"Maintenance did not settle". The child log shows `write CONNECT_TIMEOUT
127.0.0.1:<proxy>` from `connectTimedOut` in postgres.js, called from
`MockTimers.tick` at `server-child.ts:86`. That line is the `advance`
command. The same log shows a false 28.6 s "event loop stall" from the
same 30 s clock step.

**Expected behavior**
A fake clock step moves only the server's own deadlines. It must not
fire the driver's connect timeout for a connection that is still in
startup on the real network.

**Steps to reproduce**
1. Run `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/maintenance-clock-database-startup.test.ts`.
2. The first test starts a PostgreSQL connection against a server that
holds its startup reply, moves fake timers by 30 s, and then lets the
reply through. The query fails with `CONNECT_TIMEOUT`. This is the CI
failure in a deterministic form.
3. The second test waits with the new startup tracker before the same 30
s step. The query succeeds.

**Paperclip version or commit**
master at 856f14e507. The race exists since the fake-clock `advance`
command came in; the parent-side guard (`proxy.starting`) did not cover
a connection that opens after the guard check.

Classification: timing flake in the test harness (fake clock against a
real-network driver timer). It is not a product regression. The test
passed in every earlier Cloud readiness run on master.

## What Changed

- New helper
`server/src/__tests__/helpers/maintenance/database-startup.ts`. It uses
the `net.client.socket` diagnostics channel to track each client socket
from `connect()` until the first ReadyForQuery from the database (or
until it closes or is not a database socket). It reads only backend
frames with the existing protocol observer.
- `server-child.ts` waits for that tracker before each `advance`, and
then moves the clock in the same synchronous step. The driver starts its
connect timer in the same synchronous call that publishes
`net.client.socket`, so no connection can start its timer between the
check and the step.
- New test
`server/src/__tests__/maintenance-clock-database-startup.test.ts` with
the red case (unguarded step gives `CONNECT_TIMEOUT`) and the green case
(guarded step succeeds).
- No product code changes. No timeout changes.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/maintenance-clock-database-startup.test.ts`: 2 of 2 pass.
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/maintenance-server-routes.test.ts -t "first ordinary
status-card source write"`: passes locally.
- Full `maintenance-server-routes.test.ts`,
`maintenance-postgres-proxy.test.ts` and
`maintenance-harness-resources.test.ts`: pass locally.
- `node scripts/typecheck-test-projects.mjs
server/src/__tests__/helpers/maintenance`: passes.

## Risks

- Low risk. Test-harness change only. If a database connection never
finishes startup, `advance` now fails after 30 s with a clear message
instead of a later "did not settle".

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, GitHub CLI) for investigation, the
fix and local verification.

## 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
- [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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 21:25:19 -06:00
..