fix: isPortBusy preflight misses IPv4-only occupant (same address-family flaw as #94379)

RichChen01 · claude · RichChen01 · commit e922970e51c6 · 2026-06-18T14:30:07.000+08:00
Route isPortBusy through checkPortInUse (from src/infra/ports-inspect.ts), which probes all four endpoints (127.0.0.1, 0.0.0.0, ::1, ::) instead of a bare tryListenOnPort that binds the IPv6 wildcard (::) on dual-stack hosts. An occupant listening only on 127.0.0.1 (IPv4-only) does not conflict with that bind, so isPortBusy returns false (free) when the port is actually taken. This is the same address-family flaw fixed for the CDP preflight in #94379 / #94415, now fixed for the gateway --force flow. Closes #94426. Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/src/cli/ports.ts b/src/cli/ports.ts
@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
 import { createServer } from "node:net";
 import { formatErrorMessage } from "../infra/errors.js";
 import { resolveLsofCommandSync } from "../infra/ports-lsof.js";
-import { tryListenOnPort } from "../infra/ports-probe.js";
+import { checkPortInUse } from "../infra/ports-inspect.js";
 import { resolvePositiveTimerTimeoutMs, resolveTimerTimeoutMs } from "../shared/number-coercion.js";
 import { sleep } from "../utils.js";
 
@@ -130,16 +130,11 @@ function killPortWithFuser(port: number, signal: "SIGTERM" | "SIGKILL"): PortPro
 }
 
 async function isPortBusy(port: number): Promise<boolean> {
-  try {
-    await tryListenOnPort({ port, exclusive: true });
-    return false;
-  } catch (err: unknown) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "EADDRINUSE") {
-      return true;
-    }
-    throw err instanceof Error ? err : new Error(String(err));
-  }
+  // Probes all four endpoints (127.0.0.1, 0.0.0.0, ::1, ::) instead of a bare
+  // tryListenOnPort which binds the IPv6 wildcard (::) and misses IPv4-only
+  // occupants. See #94379 / #94415 for the sibling fix.
+  const status = await checkPortInUse(port);
+  return status === "busy";
 }
 
 export function parseLsofOutput(output: string): PortProcess[] {
diff --git a/src/infra/ports-inspect.ts b/src/infra/ports-inspect.ts
@@ -634,7 +634,7 @@ async function tryListenOnHost(port: number, host: string): Promise<PortUsageSta
   }
 }
 
-async function checkPortInUse(port: number): Promise<PortUsageStatus> {
+export async function checkPortInUse(port: number): Promise<PortUsageStatus> {
   const hosts = ["127.0.0.1", "0.0.0.0", "::1", "::"];
   let sawUnknown = false;
   for (const host of hosts) {

Original file line number	Diff line number	Diff line change
`@@ -634,7 +634,7 @@ async function tryListenOnHost(port: number, host: string): Promise<PortUsageSta`
`634`	`634`	`}`
`635`	`635`	`}`
`636`	`636`
`637`		`-async function checkPortInUse(port: number): Promise<PortUsageStatus> {`
	`637`	`+export async function checkPortInUse(port: number): Promise<PortUsageStatus> {`
`638`	`638`	`const hosts = ["127.0.0.1", "0.0.0.0", "::1", "::"];`
`639`	`639`	`let sawUnknown = false;`
`640`	`640`	`for (const host of hosts) {`