fix(ports): fail fast when port availability cannot be verified

wanglu241 · wanglu241 · commit 07238df4bf83 · 2026-06-18T20:40:48.000+08:00
ensurePortAvailable routed through checkPortInUse only threw on "busy",
silently treating "unknown" (a bind probe that failed with something
other than EADDRINUSE, e.g. EACCES/EINVAL) as available. The original
bare-listen path rethrew such errors; restore that fail-fast and add an
unknown-path regression guard.
diff --git a/src/infra/ports.test.ts b/src/infra/ports.test.ts
@@ -110,6 +110,15 @@ describe("ports helpers", () => {
     }
   });
 
+  it("regression: #94415 — ensurePortAvailable fails fast when availability cannot be verified", async () => {
+    // An out-of-range port makes every bind probe reject with a non-EADDRINUSE
+    // error (ERR_SOCKET_BAD_PORT), so checkPortInUse reports "unknown". The
+    // preflight must rethrow rather than silently treat an unverifiable port as
+    // free (the pre-refactor bare-listen path rethrew non-EADDRINUSE errors).
+    await expect(ensurePortAvailable(99999)).rejects.toThrow();
+    await expect(ensurePortAvailable(99999)).rejects.not.toBeInstanceOf(PortInUseError);
+  });
+
   it("handlePortError exits nicely on EADDRINUSE", async () => {
     const runtime = {
       error: vi.fn(),
diff --git a/src/infra/ports.ts b/src/infra/ports.ts
@@ -39,9 +39,17 @@ export async function ensurePortAvailable(port: number): Promise<void> {
   // Probe every address family: a bare listen binds the IPv6 wildcard on
   // dual-stack hosts and misses an IPv4-only occupant, letting Chrome later
   // collide on 127.0.0.1 and surface a misleading CDP 401.
-  if ((await checkPortInUse(port)) === "busy") {
+  const status = await checkPortInUse(port);
+  if (status === "busy") {
     throw new PortInUseError(port);
   }
+  if (status === "unknown") {
+    // A bind probe failed with something other than EADDRINUSE (e.g. EACCES on
+    // a privileged port, EINVAL on an out-of-range port). The original
+    // bare-listen path rethrew here; preserve that fail-fast instead of
+    // silently treating an unverifiable port as available.
+    throw new Error(`Port ${port} availability could not be verified.`);
+  }
 }
 
 export async function handlePortError(
