fix(port-reservation): serve the port bound during provide instead of re-listening

[Upd4ting]

Summary

Problem. In 1.3.0 the server port is reserved from provide until start by a placeholder net.createServer() with no connection handler, then start closes the placeholder and calls listen() again on the real server. If a client connects during that window (for example a startup probe on /health), the accepted socket is never read nor closed, so the placeholder's close(cb) never calls back, listenServers() never reaches the real listen(), and the HTTP server never starts ("Server started" is never logged). In production this made a pod crash-loop until a boot happened to receive no connection during the window.

Fix: bind once, serve later. The reserve → close → re-listen handoff is replaced by a single listening socket, like Go's net.Listen followed by http.Serve:

• provide binds the definitive listening socket for each configured server (net.createServer({ pauseOnConnect: true })), with the existing rules — dev fallback up to 20 ports above then an OS-assigned port, strictPort, port: 0, PortReservationError with the strict hint — and publishes the port read back from that socket.
• start creates the http/https server with the existing factory and never calls listen() on it. Connections accepted before start are queued paused and unread; serve hands them, then every new connection, to the server with server.emit("connection", socket) (TLS wraps the socket for https). The server is also sent listening, which arms Node's connection tracking (request/headers timeouts, closing idle keep-alive connections on close()).
• Nothing is closed and re-bound between provide and start, so there is no race: no 503, no timeouts, no deadline log.
• stop closes the servers and the listening sockets. listenServers() binds lazily through the same code path when no matching socket is held (after a stop, when provide never ran, or when the configuration no longer names the bound address), so restart and autoListen: false + listenServers() keep working. A second start hands the bound socket to the new servers.
• Port fallback now lives in one place (src/port-listener.ts, renamed from port-reservation.ts); port-binding.ts keeps only the shared helpers. src/startup-deadline.ts, the 503 answer, the release timeout and the listen deadline log are removed.
• applyReservedPorts is kept: construct may receive a rebuilt config carrying the requested port again, and the config must keep carrying the bound port. getListeningEndpoints reports the bound socket's address.
• README: the port reservation section describes the bound-once socket; connections arriving before start are served once the server starts.

Public exports (provide, construct, start, stop, listenServers, getListeningEndpoints, applyReservedPorts) and config semantics are unchanged. No version bump or changelog edit: both are produced by the release workflow (release-it + changelogen).

Related issue

No issue: production incident on 2026-09-25 (startup probe hitting the reservation window prevented the server from ever listening).

Verification

• New src/test/early-connections.test.ts:
  • a client sends a request after provide and before start: it gets no answer until start, then a real HTTP response from the server (not a 503);
  • a silent client holding a connection does not block start;
  • port: 0 publishes and serves the same OS-assigned port;
  • stop then start binds the port again and serves it;
  • calling start twice hands the bound socket to the new servers;
  • stop does not wait on idle keep-alive connections.
• src/test/config-vars.test.ts: the reservation suite now exercises bindServerPorts (requested port, fallback, PortReservationError under strictPort, port: 0, cleanup on partial failure); the publication suite checks the published port equals the served one, including fallback.
• The first two tests fail on main ("The server never started serving").
• https hand-off (emit("connection") on an https server with queued and later connections) checked manually with a self-signed certificate; the repo has no TLS fixtures.
• pnpm prepack, pnpm lint, pnpm format:check, pnpm knip, pnpm test (206 passing).

Checklist

• The pull request title follows Conventional Commits.
• I added or updated tests when behavior changed.
• I updated documentation when users or contributors are affected.
• I documented breaking changes and migration steps. (N/A: no breaking change)
• I did not include credentials or unrelated changes.