fix: harden port listener detection

src/infra/ports-inspect.test.ts

@@ -0,0 +1,35 @@
+import net from "node:net";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const runCommandWithTimeoutMock = vi.fn();
+
+vi.mock("../process/exec.js", () => ({
+  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
+}));
+
+const describeUnix = process.platform === "win32" ? describe.skip : describe;
+
+describeUnix("inspectPortUsage", () => {
+  beforeEach(() => {
+    runCommandWithTimeoutMock.mockReset();
+  });
+
+  it("reports busy when lsof is missing but loopback listener exists", async () => {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = (server.address() as net.AddressInfo).port;
+
+    runCommandWithTimeoutMock.mockRejectedValueOnce(
+      Object.assign(new Error("spawn lsof ENOENT"), { code: "ENOENT" }),
+    );
+
+    try {
+      const { inspectPortUsage } = await import("./ports-inspect.js");
+      const result = await inspectPortUsage(port);
+      expect(result.status).toBe("busy");
+      expect(result.errors?.some((err) => err.includes("ENOENT"))).toBe(true);
+    } finally {
+      server.close();
+    }
+  });
+});

src/infra/ports-inspect.ts

@@ -1,5 +1,6 @@
 import net from "node:net";
 import { runCommandWithTimeout } from "../process/exec.js";
+import { resolveLsofCommand } from "./ports-lsof.js";
 import { buildPortHints } from "./ports-format.js";
 import type { PortListener, PortUsage, PortUsageStatus } from "./ports-types.js";
 
@@ -71,7 +72,8 @@ async function readUnixListeners(
   port: number,
 ): Promise<{ listeners: PortListener[]; detail?: string; errors: string[] }> {
   const errors: string[] = [];
-  const res = await runCommandSafe(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpFcn"]);
+  const lsof = await resolveLsofCommand();
+  const res = await runCommandSafe([lsof, "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpFcn"]);
   if (res.code === 0) {
     const listeners = parseLsofFieldOutput(res.stdout);
     await Promise.all(
@@ -87,11 +89,12 @@ async function readUnixListeners(
     );
     return { listeners, detail: res.stdout.trim() || undefined, errors };
   }
-  if (res.code === 1) {
+  const stderr = res.stderr.trim();
+  if (res.code === 1 && !res.error && !stderr) {
     return { listeners: [], detail: undefined, errors };
   }
   if (res.error) errors.push(res.error);
-  const detail = [res.stderr.trim(), res.stdout.trim()].filter(Boolean).join("\n");
+  const detail = [stderr, res.stdout.trim()].filter(Boolean).join("\n");
   if (detail) errors.push(detail);
   return { listeners: [], detail: undefined, errors };
 }
@@ -175,7 +178,7 @@ async function readWindowsListeners(
   return { listeners, detail: res.stdout.trim() || undefined, errors };
 }
 
-async function checkPortInUse(port: number): Promise<PortUsageStatus> {
+async function tryListenOnHost(port: number, host: string): Promise<PortUsageStatus | "skip"> {
   try {
     await new Promise<void>((resolve, reject) => {
       const tester = net
@@ -184,15 +187,29 @@ async function checkPortInUse(port: number): Promise<PortUsageStatus> {
         .once("listening", () => {
           tester.close(() => resolve());
         })
-        .listen(port);
+        .listen({ port, host, exclusive: true });
     });
     return "free";
   } catch (err) {
     if (isErrno(err) && err.code === "EADDRINUSE") return "busy";
+    if (isErrno(err) && (err.code === "EADDRNOTAVAIL" || err.code === "EAFNOSUPPORT")) {
+      return "skip";
+    }
     return "unknown";
   }
 }
 
+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) {
+    const result = await tryListenOnHost(port, host);
+    if (result === "busy") return "busy";
+    if (result === "unknown") sawUnknown = true;
+  }
+  return sawUnknown ? "unknown" : "free";
+}
+
 export async function inspectPortUsage(port: number): Promise<PortUsage> {
   const errors: string[] = [];
   const result =

src/infra/ports-lsof.ts

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+
+const LSOF_CANDIDATES =
+  process.platform === "darwin"
+    ? ["/usr/sbin/lsof", "/usr/bin/lsof"]
+    : ["/usr/bin/lsof", "/usr/sbin/lsof"];
+
+async function canExecute(path: string): Promise<boolean> {
+  try {
+    await fsPromises.access(path, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveLsofCommand(): Promise<string> {
+  for (const candidate of LSOF_CANDIDATES) {
+    if (await canExecute(candidate)) return candidate;
+  }
+  return "lsof";
+}
+
+export function resolveLsofCommandSync(): string {
+  for (const candidate of LSOF_CANDIDATES) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // keep trying
+    }
+  }
+  return "lsof";
+}