feat(server): surface external port conflicts on all platforms; single-worker default without SO_REUSEPORT

[kriszyp]

Summary

Stacked on #1603 (MQTT listeners share their port via SO_REUSEPORT on non-macOS). This makes external port conflicts detected and loudly logged on every platform, and aligns two related behaviors on platforms without working SO_REUSEPORT (macOS/Windows).

listenOnPorts() used to swallow every EADDRINUSE — a workaround for a Node <20.11.1 reusePort bug now outside Harper's supported range (^22.18 || >=24). So an unrelated process squatting a Harper port (the original symptom: a second Harper instance holding 8883) silently received Harper's MQTT traffic with no error logged anywhere.

Design

Every EADDRINUSE with a possible in-process explanation is structurally ruled out, so what remains is unambiguously external and gets logged (port + owning component + error):

Case	Why EADDRINUSE must be external
reusePort listener (Linux)	siblings share the port, never collide — even across overlapping restarts
main thread (HTTP/ops ports)	binds every port (awaited) before any worker starts; never restarts
dedicated listener's owner worker (MQTT via server.socket())	never bound by the main thread; now bound by a single owner worker (lowest eligible index) instead of every worker racing; restarts are non-overlapping without reusePort

The one remaining benign case — a worker's exclusive HTTP bind losing to the main thread on macOS/Windows — stays silently swallowed. Everything still resolves, so a squatted port never stalls boot.

Supporting changes:

• restartWorkers() no longer pre-starts replacements on macOS (canPreStartReplacement now excludes darwin, like Windows/Bun). This also fixes a latent bug: the pre-started replacement could never bind the exclusive ports the old worker still held, its EADDRINUSE was swallowed, and worker-owned listeners (MQTT) were left permanently unbound after every component-reload restart on macOS. The main thread keeps serving HTTP throughout, so only worker-owned listeners see the brief shutdown-first gap.
• threads.count defaults to 1 on macOS/Windows (setDefaultThreads): without SO_REUSEPORT, extra HTTP workers can never share the server ports — the CPU-based default just spawned workers that serve no direct TCP traffic. Explicit threads.count still overrides.

Where to look

• The ownership claims are the crux. Verified in code + empirically: main thread binds HTTP/ops before workers (socketRouter.ts awaits listenOnPorts() pre-spawn); component plugins don't run handleApplication on the main thread, so MQTT listeners exist only in workers.
• canPreStartReplacement on darwin: Multi-worker HTTP rolling restart produces ~0.6–1.2s whole-pool connection-refused gap #1417 (rolling-restart conn-refused) was a Linux SO_REUSEPORT-pool fix and Linux is unchanged. rolling-restart.test.ts fails identically on macOS on the base branch (pre-existing), so CI/Linux remains the gating signal.
• threadRange: the dedicated-listener owner is the lowest eligible index, not hardcoded 0.

Test

integrationTests/server/external-port-conflict.test.ts squats the MQTT secure port before boot and asserts the conflict is logged on every platform (skip removed) and Harper still starts. Plus platform-stubbed unit coverage for setDefaultThreads and the dedicatedListener marker.

---

🤖 Generated by Claude (Fable 5 / Opus 4.8 across revisions). Cross-model reviewed (Codex + Gemini) at each design iteration; earlier reviews drove the pivot from worker-gating → reusePort-only → this universal design.

[gemini-code-assist]

Code Review

This pull request introduces a regression test to verify external MQTT port-conflict detection and updates the thread server to log external bind conflicts when reusePort is enabled. The feedback recommends passing the caught error object to the logging function to ensure the root cause is preserved, in accordance with the repository's guidelines.

[Ethan-Arrowood]

LGTM — the ownership analysis is convincing. Branch is conflicting with main but the hunks look mechanical (drain-hook context drift); approving on that assumption — ping me if the rebase turns out to touch anything real.

_{sent with Claude Fable 5}

[claude]

Blocker — no-restricted-imports lint violation

node:assert/strict is banned by the root .oxlintrc.json (rule configured as "error"), so npm run lint (oxlint --deny-warnings .) will fail on this file. Every other integration test in this directory imports from plain node:assert (rolling-restart.test.ts, ops-port-isolation.test.ts, etc.).

Suggested change

	import { tmpdir } from 'node:os';
	import { ok } from 'node:assert';