test(server): flaky startServer port-retry assertion under concurrent test runs

[tomsen-ai]

Summary

packages/server/test/start.test.ts has a flaky test:

"retries on port+1 and updates the lock when the requested port is held by a third party"

It assumes that port + 1 remains free between the helper releasing it and startServer binding it. Under vitest's concurrent workers, another test can grab port + 1 in that window, causing startServer to bind to port + 2 or higher and the assertion to fail.

Reproduction

Run the packages/server suite repeatedly:

for i in {1..10}; do pnpm vitest run packages/server; done

In my environment this fails ~80% of the time with an error like:

Expected: "http://127.0.0.1:55398"
Received: "http://127.0.0.1:55399"

 ❯ test/start.test.ts:183:25
    expect(r.address).toBe(`http://127.0.0.1:${String(next)}`);

Running start.test.ts in isolation always passes, which confirms the failure is caused by concurrent port allocation from other vitest workers.

Root cause

allocateAdjacentFreePair() finds port and port + 1, then immediately releases both. The test occupies port to simulate a third-party listener, but leaves port + 1 unprotected. While the test prepares to start the server, another worker can bind port + 1, so startServer advances to port + 2 and the strict assertion fails.

Possible fixes

1. Relax the integration assertion (recommended)
   Verify that startServer binds to a port >= port + 1 and that the lock file records the actual bound port. Keep the exact port + 1 retry strategy covered by the existing listenWithPortRetry unit tests, which already use a fake gateway to assert 5000 -> 5001 -> 5002.

2. Hold port + 1 until right before binding
   Have allocateAdjacentFreePair() return a releaseNext() callback that is awaited immediately before startServer() runs. This shrinks the race window but does not fully eliminate it; in my testing it reduced the failure rate from ~80% to ~20%.

3. Run the test sequentially
   Mark the test or describe block as sequential so it does not race with other workers. This avoids the issue but slows down the suite and does not address the underlying fragility.

4. Introduce cross-process locking
   Use a file lock or similar mechanism so only one process allocates ports in this helper at a time. This is heavier and adds complexity.

I am happy to open a PR for whichever approach the maintainers prefer. I have already verified option 1 locally: after relaxing the assertion, 10 consecutive full packages/server runs passed for start.test.ts.

[tt-a1i]

I can take this. The unit test already pins the exact retry sequence, so I'll just make the startServer integration check assert the actual bound port + lock update instead of assuming port+1 stays free.

[tomsen-ai]

Hi @tt-a1i, thanks for picking this up so quickly! I had already diagnosed and fixed the same issue locally, so I went ahead and opened #942 with the same approach you described (relax the integration assertion while keeping the unit-test coverage for the exact retry sequence). Feel free to review and leave feedback.

[tomsen-ai]

Update: I see @tt-a1i already opened #941 with the same approach plus a couple of lint cleanups, so I've closed my #942 as a duplicate. Happy to review and help iterate on #941 instead.